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.

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.

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)