Pseudolife MCP

Pseudolife-MCP

[](https://pypi.org/project/pseudolife-mcp/) [](https://github.com/Pseudogiant-xr/Pseudolife-MCP/actions/workflows/ci.yml) [](LICENSE) [](https://pypi.org/project/pseudolife-mcp/)

[简体中文](docs/i18n/README.zh.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [Português (BR)](docs/i18n/README.pt-br.md) · [Español](docs/i18n/README.es.md)

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 that ages like memory should — an 8-band recency

continuum from working to forever, ranked by cosine similarity, with contradiction detection and supersession.

• Canonical facts, not vibes — one current value per entity.attribute

slot; corrections supersede rather than silently overwrite, and the full version history survives.

• Dreams — a bundled extractor (or Claude Sonnet via your Max plan)

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.

Quickstart

Requires Docker and Claude Code, Codex, or both. One command from clone to first memory (Claude remains the compatibility default):

git clone https://github.com/Pseudogiant-xr/Pseudolife-MCP.git
cd Pseudolife-MCP
ops/install.sh          # Linux / macOS
ops\install.ps1         # Windows (pwsh 7+)
# Codex: add --client codex / -Client codex
# Both:  add --client both  / -Client both

The installer runs the preflight (one exact fix line per missing prerequisite), asks which dream extractor should consolidate memories —

• sonnet-only — the lightest install: Claude Sonnet via a CLI shim

(needs a logged-in Max-plan claude CLI); the sidecar image is never built or pulled (~9 GB lighter; dreams pause while the shim is down);

• sonnet-fallback — Sonnet primary, the bundled sidecar as automatic

fallback (Max-plan CLI plus the ~9 GB image);

• sidecar — the bundled local CPU model; no Claude plan needed, works

for everyone (~9 GB image) —

then brings the stack up, installs the selected clients' session hooks, offers to append the memory-loop block to ~/.claude/CLAUDE.md and/or ~/.codex/AGENTS.md, registers the HTTP MCP server, and health-checks the daemon. The server also advertises the core loop through MCP instructions, so the standing file reinforces the protocol guidance. Idempotent — re-run any time; --extractor switches extractor setups. Non-interactive example: ops/install.sh --extractor sidecar --client codex --instructions append. Linux (Docker Engine): your user must be in the docker group — sudo usermod -aG docker $USER, then log out/in (the preflight checks this).

Manual install (the steps the installer automates)

ops/preflight.sh --client codex    # or ops\preflight.ps1 -Client codex
docker volume create pseudolife-mcp-bank
docker volume create pseudolife-mcp-state
docker compose -f ops/docker-compose.yml up -d --build   # first build, once

# Verify, then wire into one or both clients:
curl http://127.0.0.1:8765/health
claude mcp add --transport http --scope user pseudolife-memory http://127.0.0.1:8765/mcp
codex mcp add pseudolife-memory --url http://127.0.0.1:8765/mcp

# Reinforce the protocol-level memory loop with a global standing instruction:
cat examples/CLAUDE.memory.md >> ~/.claude/CLAUDE.md
cat examples/CLAUDE.memory.md >> ~/.codex/AGENTS.md
# (PowerShell: Add-Content "$env:USERPROFILE\.claude\CLAUDE.md" (Get-Content examples\CLAUDE.memory.md -Raw))

Optional knobs live in ops/.env (cp ops/.env.example ops/.env — the install/update scripts scaffold it too; every value is commented, a missing file runs entirely on defaults).

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: .

What this is

A memory engine exposed over MCP. There's no chat UI and no LLM doing the thinking — your coding agent is the intelligence; these are tools it calls to store and recall what matters. (Models are bundled as plumbing: baked embedding weights for retrieval, and the optional CPU extractor sidecar that consolidates memories into facts while you sleep.)

It layers several complementary stores: the associative continuum (an 8-tier recency-tiered embedding store, working → forever, ranked by cosine similarity with novelty-gated storage, contradiction detection, and supersession); the cortex (slot-keyed canonical facts — one current value per entity.attribute — with provenance tiers and contender parking instead of silent overwrites); a typed knowledge graph over those facts with a closed relation vocabulary and on-read inference; the world cortex (durable cited facts about external reality, age-decayed trust); procedural lessons learned from the agent's own work; and a ChromaDB reference bank for document RAG. The canonical layers in depth: [the memory model](docs/guide/memory-model.md); the graph and multi-hop recall: [retrieval](docs/guide/retrieval.md).

State lives in Postgres (the durable source of truth) behind a single long-lived daemon; every session attaches over HTTP (or, for host-process installs, a thin stdio shim). The result: Claude can pick up where it left off, correct itself when facts change, and reason over relationships — without you re-explaining context each session.

Documentation

This README is the front door — install, wiring, and the basic loop. The deep material lives in the user guide:

| Page | What's in it | |---|---| | [Configuration](docs/guide/configuration.md) | Env vars, tuned defaults, toolset tiers, stdio shim, LAN sharing, data layout, backups, schema history | | [Retrieval](docs/guide/retrieval.md) | Reranker, BM25 hybrid, abstention floors, ranking-trace debugging, memory_recall, the knowledge graph | | [Dreaming](docs/guide/dreaming.md) | Extractor tiers, the bundled sidecar, upgrading the extractor, Sonnet-fallback, cadence, deep dream, consolidation | | [Episodes & sessions](docs/guide/episodes.md) | Daemon-owned session episodes, the briefing hook, nested sub-episodes, tags | | [The memory model](docs/guide/memory-model.md) | Cortex slots, provenance contenders, world cortex, lessons, temporal/HLC stamps | | [Benchmarks](docs/guide/benchmarks.md) | LongMemEval results; why extraction quality dominates |

Plus [evals/README.md](evals/README.md) (full benchmark methodology) and [CONTRIBUTING](CONTRIBUTING.md).

Tools exposed

The surface was consolidated 2026-07-02 (55 → 32 tools; now 33 with memory_toolset): lifecycle families became verb-dispatched tools (memory_dream, memory_forget, memory_graph_review), and dump/introspection views moved to the Cortex Console (REST) — the manifest is agent context every session, so it stays lean.

| Tool | Purpose | |------|---------| | memory_store(text, source?, tags?, origin?) | Remember one durable fact / decision / observation (canonical facts reach the cortex via the dream pass or memory_fact_set) | | memory_search(query, top_k?, filters..., rerank?, bm25?, explain?, verbose?) | Associative retrieval; canonical cortex facts surface ahead of recall hits; explain=True attaches a ranking trace | | memory_recent(n?, sources?, episodes?, tags?, verbose?) | Newest stores, timestamp-ordered (debug + session catch-up) | | memory_supersede(old_text, new_text) | Explicit correction — mark a memory obsolete, keep it as history | | memory_forget(scope, ...) | Hard-delete from one store: memory (by text/substring/source/episode/tag), fact, world, or lesson (by entity/attribute) | | memory_stats() | Per-band sizes, hit rates, totals | | memory_get(entry_id) / memory_reinforce(entry_id) | Dereference a memory id to its full episode (+ consolidated_into); reinforce it after finding it useful | | memory_fact_get(entity, attribute) | The one CURRENT canonical value at a slot (+ parked contenders); on an empty slot returns ranked candidates (same-entity, then similar slots) | | memory_fact_set(entity, attribute, value, origin?, confidence?) | Assert a canonical fact deliberately (insert / confirm / supersede / contest) | | memory_fact_resolve(entity, attribute, accept) | Settle a contested slot — adopt (true) or discard (false) the contender | | memory_history(entity, attribute?) | With attribute: version timeline at a slot, with writer/temporal stamps. Without: the entity's causal chain — dated fact/entry/edge/lesson events ("what led to X") | | memory_world_set(entity, attribute, value, source_url?, ...) | Assert a cited WORLD fact (external knowledge; age-decayed trust by freshness class) | | memory_world_search(query, top_k?, verbose?) | Search world facts — each carries effective_confidence, a stale flag, and its citation | | memory_outcome(task, outcome, about?, detail?, polarity?) | Record a procedural outcome signal (success/failure/correction); the dream distils signals into lessons | | memory_lesson_search(query, top_k?, verbose?) | Recall learned lessons for the task at hand — heed polarity - dead-ends; re_verify flags lessons whose subject facts changed since | | memory_dream(action, limit?, cursor?, apply?, snippets?) | Drive the dream: status / pull / commit / run (server-side extractor) / deep (full-corpus graph consolidation; dry-run unless apply, which snapshots the graph tables first; snippets=false omits candidate evidence; responses carry evidence-enriched merge_proposals for near-duplicate triage) | | memory_graph_review(action, proposal_id?, proposals?, scope?, src?, dst?) | Work the review queue: list / propose / dismiss_pair / accept_link / reject_link / accept_merge / accept_junk / reject_entity (merge/entity decisions are audit-stamped decided_by=agent over MCP, human via Console) | | memory_session_title(title) | Name THIS session's auto-opened episode (default titles are generic) | | memory_episode_start(title, hint?) / memory_episode_end() | Open/close a nested sub-episode for a substantial task; entries stored while open carry its id | | memory_episode_summary(id) | Stats + tag/source distribution + recent entries within an episode | | memory_consolidation_candidates(query?, episode?, ...) | Cluster near-duplicate memories ripe for consolidation | | memory_consolidate(replaces, new_text, source?, tags?) | Atomic supersede + store — replace a cluster with one canonical note | | memory_graph_relate(src, relation, dst, ...) | Assert a typed edge (closed relation vocabulary; re-assertion bumps confidence) | | memory_graph_unrelate(src, relation, dst) | Retract an edge (superseded, kept for audit) | | memory_alias(entity, alias) | Bind an alternative name — lookups resolve aliases first | | memory_graph(entity, depth?, include_facts?, to?, relation_filter?) | Entity neighborhood (≤3 hops) with derived transitive/inverse edges and per-edge EXTRACTED/INFERRED/AMBIGUOUS provenance tags; to returns the shortest path between two entities | | memory_recall(query, hops?, top_k?, verbose?) | Multi-hop retrieval for relational questions; low_confidence: true → fall back to memory_search | | memory_relation_define(name, description, ...) | Grow the closed relation vocabulary (deliberate, rare act) | | document_ingest(path, source?) | Index a file (txt/md/pdf) in the reference bank | | document_search(query, top_k?) | RAG search over the reference bank only | | memory_toolset(action) | Check or change this session's visibility tier: status / expand / collapse |

Each tool returns plain JSON. See pseudolife_memory/mcp_server.py for docstrings — those are what Claude reads to decide when to call which tool. The five recall-path tools return compact entries by default (result payloads are agent context on every retrieval); pass verbose=true for full metadata. Full-table dumps and topology views live in the Cortex Console (/api/*) and the pseudolife-mcp briefing CLI.

Toolset tiers. Three visibility tiers — minimal (7 tools), core (20, the shipped default), full (33) — filtered per session at tools/list; a session steps its own tier up or down with memory_toolset before calling a hidden tool. Defaults, per-client mapping, and weak-model deployments: [Configuration — toolset tiers](docs/guide/configuration.md#toolset-tiers).

Architecture

One memory daemon owns the bank and serves MCP over streamable HTTP at /mcp; every Claude Code session (and any LAN agent) attaches to it. Postgres 16 + pgvector (in Docker) is the durable source of truth — the in-memory MIRAS bands are a write-through cache hydrated at startup (a small weights.pt persists only band counters — there are no MLP weights).

The daemon runs either containerized (recommended — portable, no host Python) or as a host process. Claude Code attaches either directly over HTTP (recommended) or through a thin torch-free stdio shim:

Claude session A ─┐  HTTP (recommended)
Claude session B ─┼───────────────────► pseudolife-mcp daemon ─► Postgres (Docker)
LAN agent ────────┘  or stdio shim         (single writer)        pgvector
                     (per session)         host proc OR Docker

This kills two v0.1 hazards by construction: a single writer means concurrent sessions can't clobber each other, and entries are transactional so a crash can't wipe the bank. On top of the associative bands sit the canonical layers — cortex, world facts, lessons, temporal/HLC stamps ([the memory model](docs/guide/memory-model.md)) — joined to a typed knowledge graph walkable via memory_graph and multi-hop memory_recall ([retrieval & the graph](docs/guide/retrieval.md)).

Install — containerized (recommended, any OS)

The whole stack — Postgres and the memory daemon — runs in Docker. No host Python, no torch install, no version skew; the daemon image bakes in CPU-only torch and the all-MiniLM-L6-v2 weights, so it runs identically on Windows / macOS / Linux. Requires only Docker; built once: ~3 GB daemon image + ~0.6 GB Postgres + ~9 GB extractor sidecar (skip the sidecar entirely with the installer's sonnet-only mode).

git clone https://github.com/Pseudogiant-xr/Pseudolife-MCP.git
cd Pseudolife-MCP

# 1. One-time: create the two persistent volumes (bank + daemon state).
docker volume create pseudolife-mcp-bank
docker volume create pseudolife-mcp-state

# 2. Build + start all three services (Postgres, extractor, then the daemon).
docker compose -f ops/docker-compose.yml up -d --build

> Upgrading from a pre-rename install (volumes ops_pseudolife_pgdata / > ops_pseudolife_data)? Don't rename those volumes — keep pointing at them by > creating ops/.env with PSEUDOLIFE_BANK_VOLUME=ops_pseudolife_pgdata and > PSEUDOLIFE_STATE_VOLUME=ops_pseudolife_data before up. See the compose header.

> Windows: Docker Desktop's WSL2 VM claims up to ~50% of host RAM by > default; the stack needs ~6–7 GB under dream load with the default sidecar > (~1 GB in sonnet-only mode) — cap the VM via ops/wslconfig.example > (see [Troubleshooting](#troubleshooting)).

The daemon serves MCP at http://127.0.0.1:8765/mcp and restarts with Docker — no logon task needed. First build downloads the model into the image (once); every container start after that is offline a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Pseudogiant-xr
• Source: Pseudogiant-xr/Pseudolife-MCP
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.