Pseudolife Memory

Pseudolife-MCP

简体中文 · 日本語 · 한국어 · Português (BR) · Español

Persistent long-term memory for Claude Code, Codex, and other MCP clients.

An MCP server that gives coding agents a long-term memory that persists across sessions — surviving context compactions and fresh tasks. Your coding agent is the intelligence; this server is its memory on disk.

What you get:

• Associative memory with honest forgetting — a flat similarity store ranked by hybrid dense-plus-lexical retrieval, with conflict detection that admits potential updates while preserving earlier source notes; whole-note replacement is explicit. (The measured verdict: a preregistered ablation campaign found the previous 8-band continuum tied a flat store on every gate, so the simpler structure ships; the continuum remains one config line away.)
• Canonical facts, not vibes — one *current* value per entity.attribute slot (or a member set, for slots that hold many concurrent values); corrections supersede rather than silently overwrite, and the full version history survives.
• Dreams — a bundled local extractor, or any OpenAI-compatible endpoint (a Claude model on your Max plan, a GPT-5.6 model on a ChatGPT plan, LM Studio, Ollama, vLLM), consolidates the memory stream into facts and a knowledge graph while you're not looking.
• Lessons from its own work — successes, dead-ends, and your corrections become do/avoid guidance surfaced at the start of every session.
• A web console to watch it think — the Cortex Console above, plus cited world facts, session episodes, and document RAG.

Measured, with receipts — the full 500-question LongMemEval sweep, all six question types, and every number ships with its committed run artifact:

Equal accuracy to naive RAG across the whole benchmark on ~73% of the context, and better calibrated about what it does not know: on BEAM-100K's abstention questions the fact spine scores 0.950 against naive RAG's 0.775, unchanged under two independent judges. Read that as calibration, not recall — in the budget-matched five-arm run of 2026-09-02 (rag 0.725 there; one replicate, local judge) an arm served no memory at all scores 1.000 on the same questions, because refusing is the right answer there and an empty context always refuses. The fact spine loses where an answer has to be aggregated across sessions. The second claim to survive a judge swap is a win rather than a wash: re-run on 2026-09-04 with the hybrid arm budget-matched to the control at 6 turns, the same 500 questions give hybrid 0.730 against naive RAG's 0.690 under the local judge and 0.736 against 0.694 under claude-opus-5 — paired +0.040 / +0.042, p 0.015 / 0.013 — bought with *more* context, ~1229 tokens against the control's ~1124, not less, and carried mostly by temporal-reasoning questions. Graded by a local, byte-reproducible judge (the cross-judge check names its second judge) — compare within rows, never against GPT-judged leaderboards.

Retired 2026-08-25 (#188): the 0.936 knowledge-update headline. It was

measured on the 2026-07-30 bench stack (Qwen3.6-27B answerer and judge).

Re-running the same 78 questions after the 2026-08-17 migration to

Qwen3.8-27B puts the cascade at 0.846, below the naive-RAG control —

which lands on 0.859 on both stacks. The cascade serves the fact-spine

answer unless that channel says "I don't know", so it measures the

*answerer's* abstention behaviour as much as the memory: 32/78 abstentions

at 46/46 commit precision on the old stack, 22/78 at 0.839 on the new one.

The 500-question table above is on the older judge and has not been

re-judged, so read its cascade row as an upper bound.

Full tables, the per-type breakdown, both stacks side by side, and every artifact: Benchmarks.

Quickstart

Install and register the lite tier. No Docker, no database to set up, no container runtime:

pip install "pseudolife-mcp[lite]"

claude mcp add --scope user pseudolife-memory -- pseudolife-mcp

Codex instead of Claude Code — same shape:

pip install "pseudolife-mcp[lite]"

codex mcp add pseudolife-memory --env PSEUDOLIFE_WRITER_ID=codex -- pseudolife-mcp

For Codex, finish setup before starting a fresh task. In the existing [mcp_servers.pseudolife-memory] table in ~/.codex/config.toml, add startup_timeout_sec = 240, tool_timeout_sec = 240, and required = true. The shim can wait up to 180 seconds for a cold daemon; Codex's default startup budget is 10 seconds. required makes missing memory visible at startup and waits for its initial catalog. These are starting budgets, not a promise that a first model download fits. The tool budget leaves time for the shim's 180-second deadline to report a failure before the host cancels it; prewarm with pseudolife-mcp serve in a terminal if needed.

Approve memory_message in that table's tool configuration ([mcp_servers.pseudolife-memory.tools.memory_message] approval_mode = "approve", or allow it once and keep the approval); Codex hook setup (python ops/setup-codex-hooks.py) sets it when you approve the hooks, and keeps any value you chose. Board mail can wake an idle Codex task by default, and the woken task reads its mail with that tool: without the approval it stalls on a prompt until someone answers it. Set PSEUDOLIFE_CODEX_DOORBELL = "0" in the same env table to keep the task from being woken (see Codex doorbell).

The agent board (peer awareness and addressed mail between sessions) is on by default, behind bearer authentication. Without coordination.allowed_principals in the daemon's config.yaml, only the singular PSEUDOLIFE_MCP_TOKEN principal is admitted. A Codex bearer from a PSEUDOLIFE_MCP_TOKENS map stays off the board until an operator lists it (allowed_principals: [default, codex]). Until then a shim on the default setting leaves coordination off without an error; one pinned with --enable shows an attach-unavailable hint instead. python ops/setup-codex-coordination.py --check reports ready (default-on) or names the cause. See Codex CLI and desktop.

The MCP handshake delivers compact recall/capture/reflection instructions. For the complete standing guidance, copy the bundled memory block into your project AGENTS.md or ~/.codex/AGENTS.md. For session briefings and per-turn reminders, follow Codex hooks and verification. Use one MCP registration and one hook source; an installed plugin may already provide either. After the daemon is running, execute pseudolife-mcp doctor from the same environment as the registered command. It checks the handshake and annotations without calling bank tools. When the shell has no PSEUDOLIFE_MCP_TOKEN or PSEUDOLIFE_MCP_TOKEN_FILE, doctor takes the token from the Claude Code registration (~/.claude.json, or under CLAUDE_CONFIG_DIR), else from the Codex one, and names where it came from in credential_source; with none and a daemon that requires a token, it reports BearerMissing.

Then in either coding agent: *"remember that my staging box is haze-02"* → the agent calls memory_store; next session, *"which box is staging?"* → memory_search finds it. Browse everything at the Cortex Console: http://127.0.0.1:8765/ui/.

The first session auto-starts the daemon, which provisions an embedded PostgreSQL 18 (pgvector included, via pg0-embedded) under a stable per-user data dir and downloads the embedding model (~1.2 GB, one-time). It is a real Postgres bank, not a cut-down one: pseudolife-mcp backup writes a standard owner-free pg_dump archive (plus a state archive, 7-day rotation) that restores into any PostgreSQL 18 target regardless of role — the Docker tier included — so outgrowing lite is a dump/restore, not a migration project (backups). For a tier- and Postgres-version-independent copy, pseudolife-mcp export / import move the whole bank as portable JSONL (logical export / import). Windows needs an ASCII-only data path (PSEUDOLIFE_MCP_DATA_DIR).

What lite gives you, and the one thing it doesn't

The gap, stated plainly. Lite ships no extractor, so the dream pass still runs, prunes, and acknowledges its input batch, but writes no canonical facts: on this path memory_fact_set is the only cortex writer. Everything else above works. Nothing about this is silent — curl http://127.0.0.1:8765/health reports "extractor": "none", and the stdio shim says the same on stderr at session start.

Any OpenAI-compatible endpoint closes it. The daemon inherits the environment it starts from, so two variables are the whole fix — with a local Ollama:

export PSEUDOLIFE_DREAM_BASE_URL=http://localhost:11434/v1

export PSEUDOLIFE_DREAM_MODEL=qwen2.5:7b pseudolife-mcp serve

$env:PSEUDOLIFE_DREAM_BASE_URL = "http://localhost:11434/v1"

$env:PSEUDOLIFE_DREAM_MODEL = "qwen2.5:7b" pseudolife-mcp serve

/health then reports "extractor": "configured". One gotcha: a daemon that is already running keeps the environment it started with, and the shim reattaches to it rather than spawning a new one — stop the old daemon first. A hosted endpoint works too, and costs you the zero-egress property: memory text leaves the machine. Extractor tiers, quality, and the trade-offs: Dreaming.

Durable tier — Docker (recommended for a long-lived bank)

Everything above plus the bundled extractor, external volumes, health-checked services, and backup/rollback tooling. Requires Docker (with the compose v2 and buildx plugins) and at least one MCP-capable coding agent — Claude Code, Codex, and Gemini CLI are wired end-to-end; anything else gets paste-ready config (provider matrix). For Portainer, Dockge, Komodo or a plain compose folder, use the supported external-stack path; never hand-flatten the source compose. One command from clone to first memory:

git clon