Pseudolife-MCP

# Pseudolife-MCP — full documentation

> Persistent long-term memory for Claude Code, Codex, and other MCP clients: an associative store that ages and supersedes, a slot-keyed canonical-fact cortex, dream consolidation into facts and a knowledge graph, procedural lessons, and cited world facts — served by a local daemon your coding agent calls over MCP.

<!-- source: README.md -->

# Pseudolife-MCP

<!-- mcp-name: io.github.Pseudogiant-xr/pseudolife-mcp -->

[![PyPI](https://img.shields.io/pypi/v/pseudolife-mcp)](https://pypi.org/project/pseudolife-mcp/)
[![CI](https://github.com/Pseudogiant-xr/Pseudolife-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Pseudogiant-xr/Pseudolife-MCP/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/pseudolife-mcp)](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.

![Cortex Console — Observatory view](https://raw.githubusercontent.com/Pseudogiant-xr/Pseudolife-MCP/master/docs/images/cortex-console-observatory.png)

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:

| LongMemEval oracle, 500 questions | naive RAG | commit-gated cascade |
|---|---:|---:|
| accuracy, all six question types | 0.688 | 0.690 |
| context tokens per question | ~1210 | **~883** |
| knowledge-update slice (78 of the 500) | 0.859 | ~~0.936~~ (retired — see below) |

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](docs/guide/benchmarks.md).

## Quickstart

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

```bash
pip install "pseudolife-mcp[lite]"
claude mcp add --scope user pseudolife-memory -- pseudolife-mcp
```

Codex instead of Claude Code — same shape:

```bash
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). 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](docs/guide/configuration.md#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](docs/guide/configuration.md#codex-cli-and-desktop).

The MCP handshake delivers compact recall/capture/reflection instructions.
For the complete standing guidance, copy the
[bundled memory block](examples/CLAUDE.memory.md) into your project
`AGENTS.md` or `~/.codex/AGENTS.md`. For session briefings and per-turn
reminders, follow [Codex hooks and verification](docs/guide/providers.md#codex-specifics).
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](docs/guide/configuration.md#backups)). For a
tier- and Postgres-version-independent copy, `pseudolife-mcp export` /
`import` move the whole bank as portable JSONL
([logical export / import](docs/guide/configuration.md#logical-export--import)).
Windows needs an ASCII-only data path
([`PSEUDOLIFE_MCP_DATA_DIR`](docs/guide/configuration.md#connection--deployment-env-vars)).

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

| | lite (pip) | durable (Docker) |
|---|---|---|
| Associative store, hybrid search, supersession, version history | yes | yes |
| Cortex facts, knowledge graph, lessons, world facts, episodes | yes | yes |
| Cortex Console, document RAG, `pseudolife-mcp backup` | yes | yes |
| **Dream consolidation filling the cortex on its own** | **no extractor ships** | yes — bundled local CPU sidecar |
| External volumes, health-checked services, deploy/rollback tooling | no | yes |

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

```bash
export PSEUDOLIFE_DREAM_BASE_URL=http://localhost:11434/v1
export PSEUDOLIFE_DREAM_MODEL=qwen2.5:7b
pseudolife-mcp serve
```

```powershell
$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](docs/guide/dreaming.md).

## 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 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](docs/guide/providers.md)). One command from clone to
first memory:

```bash
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
# Codex defaults to automatic hook-source detection and asks once for approval.
# Unattended hook approval: --codex-hook-trust yes / -CodexHookTrust yes
# Instructions only: --codex-hooks skip --instructions append
# PowerShell equivalent: -CodexHooks skip -Instructions append
# Both:  add --client both  / -Client both
# Gemini: add --client gemini — or several: --client claude,codex,gemini
# Other MCP agents (Cursor, Windsurf, Zed, ...): --client generic
```

The installer asks which agents to wire (multi-select, with a capability
matrix showing exactly what each one gets — session briefing, per-turn
discipline, standing file), runs the preflight (one exact fix line per
missing prerequisite), then asks which **dream extractor** should
consolidate memories —

- **sidecar** — the bundled local CPU model; no Claude plan needed, works
  for everyone, and keeps every memory on the box (~11.8 GB image);
- **sonnet-only** — the lightest install: a Claude model via a CLI shim
  (`claude-opus-5` by default; the mode name is historical. Needs a
  logged-in Max-plan `claude` CLI); the sidecar image is **never built or
  pulled** (~11.8 GB lighter; dreams pause while the shim is down);
- **sonnet-fallback** — the Claude shim primary, the bundled sidecar as
  automatic fallback (Max-plan CLI plus the ~11.8 GB image);
- **codex-only / codex-fallback** — the same two shapes on an OpenAI
  subscription: a GPT-5.6 model (Sol / Terra / Luna) via the Codex CLI
  shim on a signed-in ChatGPT plan (extraction quality unmeasured — see
  the [dreaming guide](docs/guide/dreaming.md)) —

then brings the stack up, installs the selected clients' session hooks
(where the client has a hook system), registers the MCP transport (the
stdio shim by default, with a per-provider writer id; direct HTTP via
`--transport http`), and health-checks the daemon — finishing with a
per-agent ladder of what got wired and what that agent's platform cannot
support. Codex setup offers one choice to enable automatic memory briefings,
reminders, and session cleanup (plus, where the agent board is on, a board
check-in at session start and a new-mail hint per prompt), use standing
instructions only, or skip.
Automatic setup reuses an enabled PseudoLife plugin or installs the three
lifecycle hooks, backs up configuration, approves only their exact current
definitions, and verifies execution. If verification fails, the same approval
allows the standing memory block as a fallback; setup reports the remaining
repair step. Hook-less providers (Gemini CLI and generic agents) are offered
the standing block. `--instructions
append` always writes the block from `examples/CLAUDE.memory.md` into
`~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.gemini/GEMINI.md`
(useful for subagent visibility even with hooks).
Idempotent — re-run any time; `--extractor <mode>` switches extractor
setups. Non-interactive example:
`ops/install.sh --extractor sidecar --client codex --codex-hook-trust yes`.
Without explicit hook approval, unattended setup does not grant trust; use
`--codex-hooks skip --instructions append` for instructions only. Explicit
`--instructions skip` prevents fallback edits.
The installer also turns the agent board on: it mints a bearer token in
`ops/.env` (owner-only, never printed) and gives each shim client it wires an
owner-only token file. Re-running it on an existing install adds that file to
the Claude Code registration in place. The ladder's last line, and
`pseudolife-mcp doctor`, say whether the board is on or why it is off.
`--no-token` / `-NoToken` keeps an open-loopback install with the board
dormant ([Turning the board on](docs/guide/configuration.md#turning-the-board-on)).
Linux (Docker Engine): your user must be in the `docker` group —
`sudo usermod -aG docker $USER`, then log out/in (the preflight checks this).

Image sizes, the Windows WSL2 memory cap, and what the installer automates:
[the containerized install](#install--containerized-any-os) below.

<details>
<summary>Manual install (the steps the installer automates)</summary>

```bash
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

# ...or pull the prebuilt images instead of building (releases >= 0.14.0):
docker compose -f ops/docker-compose.yml -f ops/docker-compose.ghcr.yml pull pseudolife-pg pseudolife-daemon
docker compose -f ops/docker-compose.yml -f ops/docker-compose.ghcr.yml up -d

# Verify, then wire the transport into one or both clients.
curl http://127.0.0.1:8765/health

# Stdio shim (the installer's default — per-session episode identity).
# PSEUDOLIFE_MCP_NO_SPAWN=1 makes the shim wait for the container instead
# of spawning a host fallback that can shadow the Docker bank after a
# reboot; set it on Docker-tier registrations like these.
pip install pseudolife-mcp
claude mcp add --scope user pseudolife-memory --env PSEUDOLIFE_MCP_NO_SPAWN=1 -- pseudolife-mcp
codex mcp add pseudolife-memory --env PSEUDOLIFE_MCP_NO_SPAWN=1 -- pseudolife-mcp

# ...or direct HTTP (no pip package needed; fine for single-session setups):
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).
</details>

## 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.)

Where it sits among the common approaches to agent memory — each column
is a fair tool for what it's for; this table is about *what question each
one answers*, not who's wrong:

| | notes file (`CLAUDE.md`) | auto-journaling plugin | plain vector store | Pseudolife-MCP |
|---|---|---|---|---|
| Survives sessions and compactions | yes | yes | yes | yes |
| "What is X *now*?" has one current answer | if you curate it | no — replays what happened | no — every stored version competes at recall | yes — slot-keyed cortex |
| A canonical-fact correction replaces the old value | you edit the file | appended beside it | old and new both retrievable, unranked by recency of truth | cortex supersedes, with full version history kept |
| Facts know their age and go stale | no | no | no | dated, freshness-decayed, quarantined when stale |
| Distils do/avoid lessons from its own outcomes | no | no | no | yes |
| Benchmark numbers ship with their raw run artifacts | — | typically no | typically no | every published number, test-enforced |

Auto-journaling records what the agent *did*; Pseudolife curates what it
*learned*. Both are useful — they answer different questions. Named
alternatives — Mem0, Zep/Graphiti, Letta, Cognee, memU, Memori — and the
cases where one of them is the better pick:
[Comparison](docs/guide/comparison.md).

It layers several complementary stores: the **associative store** (a flat
embedding store ranked by cosine similarity fused with a BM25 lexical pool
(on by default), with conflict-aware admission and explicit source-note
replacement; an 8-tier
banded layout is available as an opt-in preset); the **cortex** (slot-keyed canonical facts — one *current*
value per `entity.attribute`, or a member set for set-valued slots — 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 through a thin stdio shim
(installer default — per-session identity) or directly over HTTP
(single-session setups). 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 |
| [Providers](docs/guide/providers.md) | Capability matrix per coding agent, memory instruction layers, AGENTS.md standard, Codex hook setup and verification, writer ids |
| [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 |
| [Comparison](docs/guide/comparison.md) | Mem0, Zep/Graphiti, Letta, Cognee, memU, Memori — the axes, and when to use something else |
| [Security posture](docs/guide/security-posture.md) | Memory poisoning (ASI06): every shipped mitigation, and what is not defended |

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 38 with
`memory_toolset`, the set-slot pair and coordination): 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?, episode?, authority?, distortion_tolerance?)` | Remember one durable fact / decision / observation (canonical facts reach the cortex via the dream pass or `memory_fact_set`); `authority`/`distortion_tolerance` label the speech act and how exactly it must survive — `auto` (default) is a deterministic form heuristic, no model call, and both labels are inherited through supersession unless restated |
| `memory_search(query, top_k?, filters..., rerank?, bm25?, explain?, verbose?)` | Associative retrieval; canonical `cortex` facts surface ahead of recall hits, each dated (`asserted_at` / `last_confirmed` / human `age`, plus `stale` when it has rotted); `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, entry_id?)` | Correct the selected entry by ID, or one unique exact-text match; ambiguous/missing targets fail closed. Keep the old entry as history; `derived_flagged` names canonical facts built on it (flagged, never rewritten) |
| `memory_reinstate(entry_id, operation_id, expected_..., evidence_packet_sha256, reviewer_ids, reason)` | Reinstate one independently reviewed retired entry under its durable ID; Postgres-only, named-principal, exact-preimage, append-only and idempotent. Refuses any trace invalidation and never confirms derived cortex facts |
| `memory_forget(scope, ...)` | Forget from one store: `memory` (by text/substring/source/episode/tag) and `fact` hard-delete; `world` and `lesson` (by entity/attribute) retire the slot with an audit row — reversible via `memory_graph_review(action="restore_slot")` |
| `memory_stats()` | Store occupancy, hit rates, totals |
| `memory_agents(action, project?, task?, status?, lease?, expect?, children?, park_reason?, park_needs?, park_clear_by?, park_resume?, park_expires?)` | Experimental peer awareness or update of the caller's registered context, on by default for authenticated installs ([coordination](docs/guide/configuration.md#experimental-agent-coordination)); lists peers active within the hour (three hours while holding a lease), each status with its age and a stale flag past two hours, and counts the rest as `idle_omitted`; `update` sets project, task, status, `expect` (seconds until the status is overdue), `children` (the labels of subagents working under the caller's address, which only read the board) and the park record (why the session stopped, what clears it, who can, what to do then; a plain status clears it), which every listed row carries; `claim`/`release` take or free an advisory `lease`; unknown episode scope stays unknown, and activity is not a resource reservation |
| `memory_message(action, to?, text?, request_id?, reply_to?, after?, message_id?, clears?, urgent?)` | Experimental addressed mail: `send` to one agent (its id, or a unique prefix of 8+ hex characters), to `project:<name>` or to `all` (every attached, non-idle peer, at most 50, one request id for the burst, per-recipient receipts), non-destructive `receive`, or explicit recipient `ack` (one id or several comma-separated, ids or prefixes); requires authenticated adapter binding, remains outside memory retrieval, and never grants user approval. Each receipt carries the daemon's `wake` decision (`hinted`, `not_needed`, `rung`, `withheld` with the parked need, `nudged`, `no_path`, `capped`): a parked peer rings only for mail that clears what it declared it needs ([park records and wake](docs/guide/configuration.md#park-records-and-the-wake-decision)) |
| `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); aged/contested facts carry a ready-made `correct_with` call (as do `memory_search` / `memory_world_search` hits) |
| `memory_fact_set(entity, attribute, value, origin?, confidence?, episode?, freshness_class?, authority?, distortion_tolerance?)` | Assert a canonical fact deliberately (insert / confirm / supersede / contest); `freshness_class` (`auto` default) says how fast the slot rots — `auto` infers it from the entity's kind; `authority`/`distortion_tolerance` (`auto` = deterministic form heuristic, no model call) inherit the slot's labels unless restated |
| `memory_fact_resolve(entity, attribute, accept)` | Settle a contested slot — adopt (`true`) or discard (`false`) the contender |
| `memory_set_add(entity, attribute, member)` / `memory_set_remove(entity, attribute, member)` | Add/confirm or retract one member of a set-valued slot (many concurrent values, e.g. tags — not one NOW value); a scalar there converts to a set one-way on first `memory_set_add`, except a number-led aggregate scalar ("32", "$1,500"), which is protected — the add parks as a contender instead. Read with `memory_fact_get`, which returns `{kind: "set", members, removed}` for these slots |
| `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?, episode?, used_ids?)` | Record a procedural outcome signal (`success`/`failure`/`correction`); the dream distils signals into lessons. `used_ids` names the search hits the work actually turned on — each credits every `retrieval_events` row in the session window that served it with a `retrieval_uses` label (`used_via=outcome`), the relevance signal a learned reranker trains on; same session, within `use_window_seconds`, or nothing is credited |
| `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?, commit_token?, apply?, snippets?, run_id?)` | Drive the dream: `status` / `pull` / `commit` / `run` (server-side extractor) / `runs` (audit trail of recent passes) / `rollback` (revert the latest committed pass from its pre-image journal) / `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, with long lists capped and their full counts under `truncated`) |
| `memory_graph_review(action, proposal_id?, proposal_ids?, proposals?, scope?, src?, dst?, relation?, store?)` | Work the review queue: `list` / `propose` / `relate` (link a pair *and* dismiss its duplicate proposal in one call) / `dismiss_pair` / `dismiss_slot_pair` / `restore_slot` / `accept_link` / `reject_link` / `accept_merge` / `accept_junk` / `reject_entity` (merge/entity decisions are audit-stamped `decided_by=agent` over MCP, `human` via Console); `list` takes `scope=<memory source>` (the Atlas project scope) to keep only analyzer findings whose entities carry that source — queued proposals (`proposed_link` / `merge_candidate` / `junk_candidate`) always list; omit or `"all"` for everything; it is not a finding-kind filter; `proposal_ids` settles many id-actions in one call; `restore_slot` undoes a `memory_forget(scope="lesson"/"world")` retirement — `store` + the retired `entity|attribute` key in `src` (or a bare entity to restore every retired aspect) |
| `memory_session_title(title, episode?)` | Name THIS session's auto-opened episode (default titles are generic); `episode` is your session handle from the briefing — concurrent sessions share one HTTP connection, so pass it to land the rename on your own episode |
| `memory_episode_start(title, hint?, episode?)` / `memory_episode_end(episode?)` | Open/close a nested sub-episode for a substantial task; entries stored while open carry its id; `episode` is your session handle so the nest/pop lands in your own tree when several sessions run concurrently |
| `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?, entry_ids?)` | Replace selected entries with one canonical note; validate every ID (or unique exact text) before any changes |
| `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/html) verbatim in the reference bank — the lossless complement to agent-side distillation ([division of labor](docs/guide/memory-model.md#background-documents--the-reference-bank)) |
| `document_search(query, top_k?)` | RAG search over the reference bank only |
| `memory_toolset(action)` | Check or change this principal'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; search and recent entries
keep their write `date`); 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` (9 tools), `core`
(24), `full` (38) — filtered per principal at
`tools/list`; a principal (the named bearer-token identity, or the writer
id for single-token installs) 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 18 + pgvector** (in Docker on the durable tier; the lite tier
runs the same Postgres embedded, no container) is the durable source of
truth —
the in-memory store is a write-through cache hydrated at startup
(a small `weights.pt` persists only counters — there are no MLP weights).

The daemon runs **either** containerized (recommended — portable, no host
Python) **or** as a host process. Claude Code attaches through a thin
torch-free stdio **shim** (the installer default — per-session identity,
needed for concurrent sessions) **or** directly over **HTTP** (simpler for
a single session):

```
Claude session A ─┐  stdio shim (installer default) or HTTP
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. The single writer is enforced: the daemon
holds a Postgres advisory-lock *writer lease* on its bank. A second daemon,
or a script or eval that opens the live bank through the service, refuses
to start and names the process that holds it. Stop the daemon before
offline maintenance such as `ops/dedup_cortex.py`. If the bank fails to
load at startup, the daemon serves nothing rather than a partly loaded
bank, and `/health` reports `degraded` with the reason until a retry
succeeds. On top of the associative store 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 (any OS)

What [the durable tier](#durable-tier--docker-recommended-for-a-long-lived-bank)
installer above does, by hand. 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 embedding weights — `Qwen/Qwen3-Embedding-0.6B`
(the default retrieval backbone since schema v25) plus `all-MiniLM-L6-v2`
(kept baked for the ONNX-parity test path) — so it runs identically on
Windows / macOS / Linux. Requires only Docker; built once: ~5.0 GB daemon
image (measured 2026-07-29 on the deployed build) + ~0.6 GB Postgres +
~11.8 GB extractor sidecar (measured 2026-08-20 with the v3 multi-task
bake; skip the sidecar entirely with the installer's `sonnet-only` mode).
The ~12.6 GB and ~10.4 GB figures published before
2026-07-29 are retired: both were inflated by a CUDA torch build that a
dependency-resolution bug pulled into the image (see the CHANGELOG); the
daemon has always been CPU-only.

```bash
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
```

Or skip the ~5 GB daemon build entirely and **pull the prebuilt images**
(releases ≥ 0.14.0):

```bash
docker compose -f ops/docker-compose.yml -f ops/docker-compose.ghcr.yml pull pseudolife-pg pseudolife-daemon
docker compose -f ops/docker-compose.yml -f ops/docker-compose.ghcr.yml up -d
```

The extractor sidecar is not published and still builds locally; updates on
the pull path are `pull` + `up -d`, not `ops/update.ps1`.

> **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:** cap Docker Desktop's WSL2 VM, which otherwise claims up to
> ~50% of host RAM — how much the stack actually needs, the
> `ops/wslconfig.example` template, and the daemon container's own memory
> cap: [Configuration — Windows / WSL2 memory](docs/guide/configuration.md#windows--wsl2-memory-docker-tier).

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 and fast. Wire
Claude Code in via the stdio shim (installer default) or directly over
HTTP (both below). Where the data actually lives, and
how to back it up:
[Configuration — data layout](docs/guide/configuration.md#data-layout).

**Host-process install (Windows, for GPU / dev):** run Postgres in Docker
but the daemon on host Python — for hacking on the daemon or running the
embedder on a local GPU. Steps, the `pseudolife-mcp` CLI modes, and the
logon autostart task:
[Configuration — host-process install](docs/guide/configuration.md#host-process-install-windows-for-gpu--dev).

## Updating

**Upgrading from before the agent board (no bearer token yet):** this
migration step applies to installer-managed Docker installations. Rerun
`ops/install.ps1` (Windows) or `ops/install.sh` (Linux / macOS) with the
same client selection (close sessions first on Windows, as below).
The installer creates a bearer token for the default shim install and
migrates the environment of the installer-managed `pseudolife-memory`
stdio registration for Claude Code in place. Custom registrations are
preserved; follow the installer's printed credential warnings for Gemini
or custom registrations. `-All` / `--all` and `ops/update_clients.py` do not
create the token or migrate the registration environment. Then refresh clients
with the **Everything at once** recipe below and restart them.

**Lite tier:** one command, bank untouched:

```bash
pip install -U "pseudolife-mcp[lite]"
```

On Windows, first close every Claude Code, Codex and Claude Desktop
session using the shim (quit Desktop from the tray): upgrading a shim
that is running can leave it half-removed.

**Docker tier:** after a `git pull` (or local code change), redeploy the
**daemon only** — safely, without touching Postgres or the extractor:

```powershell
.\ops\update.ps1        # Windows
```
```bash
./ops/update.sh         # Linux / macOS
```

It backs up the bank (`pg_dump` + a state-volume tar), tags a rollback
image (when a previous one exists — it says so loudly when there isn't),
rebuilds + recreates **only** the daemon, and waits for `/health`.
It never runs `down -v`. (Host-process install: just restart the daemon —
`pip install -e .` is editable.) Build cache is pruned automatically after
every healthy deploy; see
[Docker disk retention](docs/runbooks/docker-disk-retention.md) for the
weekly Scheduled Task and the manual `.vhdx` compact. Never run
`docker system prune --volumes`, which deletes volumes.

The image records the commit it was built from, and `/health` reports it
as `build` (`git_sha`, `dirty`, `built_at`). So the script refuses a tree
with uncommitted or untracked files, and lists them. It also refuses a
tree git cannot describe (no git, not a clone, or git's `safe.directory`
refusal, which it quotes). Commit or clean up first, or pass
`-AllowDirty` / `--allow-dirty` to deploy the tree as it is: stamped
`dirty: true`, or `unknown` when git cannot describe it. Each deploy
builds a new image, so the daemon container is recreated even when the
commit has not changed.

**Everything at once:** the daemon is one of three installs. The **shim**
your clients launch and the **Claude Code plugin** are separate and do not
move with it. `-All` / `--all` moves them in the same run, after the
daemon is healthy:

On Windows, close every Claude Code, Codex and Claude Desktop session
using the shim first (quit Desktop from the tray). If an in-use shim was
skipped, the daemon deploy has already succeeded; after closing those
sessions, retry only the shim: `python ops/update_clients.py --only shim`.

```powershell
.\ops\update.ps1 -All   # Windows
```
```bash
./ops/update.sh --all   # Linux / macOS
```

It reinstalls the shim behind each Claude Code / Codex registration where
that is safe (pipx, or the registered interpreter's pip; a shim running
straight from this checkout is already live and is named instead, since
its metadata refresh needs every session closed; on Windows a shim whose
virtualenv or launcher a session is running from is skipped, with the
sessions counted and the rerun named, because pip or pipx would leave it
half-removed), refreshes the plugin
cache by comparing bytes against the marketplace clone (the plugin's
version string only moves with a release, so `/plugin update` alone would
say "already latest"), and reports whether Codex's hook copy matches the
checkout (that refresh is a consent step: `python ops/setup-codex-hooks.py`).
It ends with a ladder of what moved and which clients need a restart; a
client-side step that fails is reported, never a failed deploy. The same
helper runs on its own: `python ops/update_clients.py`. Custom
registrations are preserved and named; upgrade those in their own
interpreter. A daemon-side credential change with an old shim leaves the
two out of step: the Claude Desktop registrar refuses a shim that cannot
read the selected token file (exit 4), and names the upgrade.

- **Upgrading past 2026-09-28: board mail starts waking idle sessions.**
  Once the plugin cache and the shim move (`-All`, then a client restart),
  a Claude Code session and a Codex task with a `codex` CLI are woken when
  mail arrives that clears the need they parked on; before this both wake
  paths were opt-in. Nothing rings for chatter, and rings are capped. To
  keep the old behaviour, set `PSEUDOLIFE_AGENT_WAKE_HOOK=0` in the `env`
  block of `~/.claude/settings.json` and `PSEUDOLIFE_CODEX_DOORBELL = "0"`
  in the Codex server's `env` table (`PSEUDOLIFE_AGENT_COORDINATION=0` in
  either place turns off the board for that client). `pseudolife-mcp
  doctor` shows each client's wake path under `wake`.

The three tell on each other: `/health` reports the daemon's `version`
and a digest of the hook scripts it shipped with; the session briefing
opens with a one-line notice when the plugin's version differs from the
daemon's (naming `/plugin marketplace update pseudolife-mcp` then
`/plugin update pseudolife-memory@pseudolife-mcp`, or the daemon redeploy,
whichever side is behind), or when the version matches but the hooks do
not (naming the `--all` command above); the shim says so on stderr and
ahead of its instructions; and `pseudolife-mcp doctor` reports
`version_mismatch`.

> **Two upgrades are not automatic**, because neither can be done safely
> in place. Both have a step-by-step runbook — backup, dry run, apply,
> verify, roll back — and a fresh install needs neither:
>
> - **A bank older than 0.11.0 (schema v25)**: every embedding column moved
>   from `vector(384)` to `vector(1024)`, so the daemon refuses to start
>   rather than half-migrate. Re-embed offline with
>   `ops/migrate_embeddings.py` —
>   [the v25 migration runbook](docs/runbooks/embedding-v25-migration.md).
> - **A Docker-tier bank created before 2026-08-14 (PostgreSQL 16 → 18)**:
>   a Postgres major bump cannot reuse the old data volume. Run
>   `pwsh ops/migrate-pg18.ps1` —
>   [the PostgreSQL 18 migration runbook](docs/runbooks/postgres-18-migration.md).

## Wire into your coding agent

**Plugin (hooks + commands).** The installer adds it whenever Claude Code
is a selected client (`--claude-plugin skip` / `-ClaudePlugin skip` opts
out; an installed plugin is left alone). It wires the session hooks
(briefing + episode identity), the memory-loop instructions, and the
`/dream` + `/memory-status` commands. By hand, the same two commands inside
Claude Code do it:

```
/plugin marketplace add Pseudogiant-xr/Pseudolife-MCP
/plugin install pseudolife-memory@pseudolife-mcp
```

The plugin replaces the settings.json hook, and the daemon serves a compact
memory core and a live briefing as session context. The full CLAUDE.md block
below is not served; append it if you want the complete guidance.
It deliberately does **not** bundle the MCP server: Claude Code loads a
plugin server alongside any user-registered one with no deduplication, which
doubled every session's tool namespace next to the installer's registration
— so the transport is registered exactly once, by `ops/install.*` (stdio
shim by default — per-session episode identity) or the one-liner below.
Hooks an earlier install wrote to `~/.claude/settings.json` would duplicate
the plugin's; the installer offers to remove them once the plugin runs
(`--claude-legacy-hooks remove` / `-ClaudeLegacyHooks remove` unattended).
Details, non-default ports/tokens, and migration:
[plugin/README.md](plugin/README.md).

**Manual transport registration.** The installer's default (shim mode)
registers a thin stdio shim — one shim process per session, so every
session carries its own tier-1 identity. The same wiring by hand:

```bash
pip install pseudolife-mcp    # daemon in Docker; add [lite] for the pip tier
claude mcp add --scope user pseudolife-memory --env PSEUDOLIFE_MCP_NO_SPAWN=1 -- pseudolife-mcp
```

`PSEUDOLIFE_MCP_NO_SPAWN=1` belongs on Docker-tier registrations: the shim
then waits for the container instead of spawning a host-side fallback whose
port bind can race a still-booting Docker and shadow the real bank. On the
`[lite]` pip tier drop the `--env` — there the spawn fallback *is* the
zero-config path.

Direct HTTP works too — the daemon serves MCP over HTTP natively (no shim,
no host command, nothing OS-specific; concurrent sessions then share one
episode identity, so it fits single-session setups best):

```bash
claude mcp add --transport http --scope user pseudolife-memory http://127.0.0.1:8765/mcp
```

(`--scope user` registers it for every project; drop it to register for the
current project only.) Or write the equivalent JSON yourself — into
`~/.claude.json` under the top-level `mcpServers` key for user scope, or into
a `.mcp.json` at a project root for project scope:

```json
{
  "mcpServers": {
    "pseudolife-memory": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}
```

For a token-protected daemon, add a `headers` key to that Claude JSON entry:
`"headers": { "Authorization": "Bearer <your-token>" }`.

**Claude Desktop** (the app, including its Cowork and Code sessions) — the
installer writes the entry for you:

```bash
ops/install.sh --client claude-desktop      # Windows: ops\install.ps1 -Client claude-desktop
```

Desktop has no `mcp add`; its servers live in `claude_desktop_config.json`
(macOS `~/Library/Application Support/Claude/`, Linux `~/.config/Claude/`,
Windows `%APPDATA%\Claude\` — except the Store/MSIX build, whose real file
is under `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\`; the
installer prefers that path when it exists). The equivalent entry by hand:

```json
{
  "mcpServers": {
    "pseudolife-desktop": {
      "command": "/absolute/path/to/pseudolife-mcp",
      "env": {
        "PSEUDOLIFE_WRITER_ID": "claude-desktop",
        "PSEUDOLIFE_MCP_NO_SPAWN": "1",
        "PSEUDOLIFE_MCP_DAEMON_URL": "http://127.0.0.1:8765"
      }
    }
  }
}
```

The entry is named `pseudolife-desktop` on purpose. Desktop's Code tab runs
Claude Code, which starts its own per-session `pseudolife-memory` server; when
an app-level entry has the same name, Desktop sends the session's
`mcp__pseudolife-memory__*` calls to the app-level entry and the session's own
server gets none. Re-running the installer renames an entry it wrote under the
old name (its `env` sets `PSEUDOLIFE_WRITER_ID` to `claude-desktop`), keeping
any `env` keys you added and backing the config up first. It leaves any other
`pseudolife-memory` entry alone and warns about it. Chat and Cowork then list
the tools as `mcp__pseudolife-desktop__*`.

Two things differ from the CLI clients. Desktop launches MCP servers with a
**sanitized environment** — PATH plus a few system variables, none of your
shell's exports — so `command` must be the shim's absolute path (`which
pseudolife-mcp` / `Get-Command pseudolife-mcp`), and a token-protected
daemon needs `"PSEUDOLIFE_MCP_TOKEN_FILE": "/absolute/path/to/a/private/file"`
in that `env` block: a bearer exported in your OS environment never reaches
the shim. The symptom of forgetting it is every session failing with
*"Couldn't start for Cowork and Code sessions. Error: unhandled errors in a
TaskGroup (1 sub-exception)"* — a 401 under the SDK's wrapper, which the
shim now names plainly on stderr at startup. When the daemon is
token-gated the installer writes that file (owner-only) from
`PSEUDOLIFE_MCP_TOKEN` in its environment or `ops/.env`, or migrates a
literal token already in the entry into it; with no token to write it
says so and exits 3. The shim must also be able to *read* that file:
releases through 0.15.0 only read the literal `PSEUDOLIFE_MCP_TOKEN`, so
the registrar probes `<command> --help` for the file form first and
refuses an older shim (exit 4, nothing written) rather than register an
entry that would fail with the same TaskGroup error — upgrade the shim
(`pipx upgrade pseudolife-mcp`, or `pipx install --force .` from the checkout) and
re-run. On Windows, run that upgrade with every session using the shim
closed (Desktop fully quit from the tray), or it can leave the shim
half-removed. After any edit, fully quit Desktop from the tray or
menu-bar icon and relaunch — closing the window does not reload the
config.

Codex — the installer's default (shim mode) wires the same stdio shim, so a
Codex session gets its own tier-1 identity instead of inheriting a
concurrent Claude session's episode:

```bash
pip install pseudolife-mcp
codex mcp add pseudolife-memory --env PSEUDOLIFE_MCP_NO_SPAWN=1 -- pseudolife-mcp
```

(Same Docker-tier note as the Claude wiring above: keep
`PSEUDOLIFE_MCP_NO_SPAWN=1` when the daemon runs in Docker; drop it on the
`[lite]` pip tier.)

The HTTP one-liner works too (no pip package needed):

```bash
codex mcp add pseudolife-memory --url http://127.0.0.1:8765/mcp
```

Or add the equivalent user-level entry to `~/.codex/config.toml`:

```toml
[mcp_servers.pseudolife-memory]
url = "http://127.0.0.1:8765/mcp"
bearer_token_env_var = "PSEUDOLIFE_MCP_TOKEN"
```

For that Codex HTTP configuration, export `PSEUDOLIFE_MCP_TOKEN` in the
environment that launches Codex. The token stays out of `config.toml`, and
Codex reads it when connecting. This is unnecessary for the default stdio shim.

Gemini CLI — same shape (`-s user` matters: Gemini defaults to project
scope; the `-e` env gives Gemini sessions their own write attribution, and
the same Docker-tier `PSEUDOLIFE_MCP_NO_SPAWN=1` note as above applies):

```bash
pip install pseudolife-mcp
gemini mcp add -s user -e PSEUDOLIFE_WRITER_ID=gemini -e PSEUDOLIFE_MCP_NO_SPAWN=1 pseudolife-memory pseudolife-mcp
```

Or HTTP, no pip package needed:

```bash
gemini mcp add -s user -t http pseudolife-memory http://127.0.0.1:8765/mcp
```

Note: since 2026-06-18 Google no longer serves individual-tier accounts
(free, AI Pro, AI Ultra) through Gemini CLI — OAuth sign-in fails and
points at Antigravity. The wiring above stays correct, but individual
accounts need API-key auth (`GEMINI_API_KEY`) to actually run sessions —
or use Google Antigravity itself, which connects to the same bank via
`~/.gemini/config/mcp_config.json`; both are covered in
[the providers guide](docs/guide/providers.md#gemini-cli).

**Any other MCP-capable agent** (Cursor, Windsurf, Zed, Copilot CLI, …) —
add the generic `mcpServers` entry to that tool's MCP config (`ops/install.sh
--client generic` prints both shapes ready to paste):

```json
{
  "mcpServers": {
    "pseudolife-memory": {
      "command": "pseudolife-mcp",
      "env": {
        "PSEUDOLIFE_WRITER_ID": "mcp-client",
        "PSEUDOLIFE_MCP_NO_SPAWN": "1"
      }
    }
  }
}
```

What each agent gets — and what its platform can't support (hooks,
per-turn discipline): [the provider matrix](docs/guide/providers.md).

**Verify:** run `claude mcp list`, `codex mcp list`, or `gemini mcp list`
(the server should report connected), then ask the agent to *"store a memory
that this install works"* and check it
appears in the Stream tab of the Console at <http://127.0.0.1:8765/ui/>.

Preferring stdio (this is what the installer wires by default, for
per-session identity)? A thin torch-free **shim** proxies stdio to the
daemon:
[stdio shim](docs/guide/configuration.md#stdio-shim-per-session-identity)
· [LAN sharing](docs/guide/configuration.md#sharing-memory-on-the-lan)
· [backups & restore rehearsal](docs/guide/configuration.md#backups)
· [agent mailbox recovery](docs/guide/coordination-recovery.md).

## Recommended agent setup (CLAUDE.md / AGENTS.md)

The server's value depends on the agent using it. The MCP server advertises
the core loop through protocol-level `instructions`; the shim adds the
messageboard check-in when its coordination adapter is up.
The plugin's memory SessionStart hook (also used by verified Codex hooks)
delivers a short operating guide and a bounded briefing; without the plugin,
the installer's Claude Code `settings.json` hook
(`pseudolife-mcp briefing --hook-json`) delivers the same two.
A separate coordination hook asks the agent to set its project,
task and status, discover peers, and read pending messages, but only where
the board is on for that credential (it is on by default behind bearer
authentication, so an open install or a disabled board adds no check-in).
Detailed memory
guidance remains in the bundled standing block. Hooks add per-prompt reminders
and session bookkeeping; neither delivery method
guarantees that the model performs every requested memory operation.

Hooks serve at most that short guide; the detailed block reaches an agent
only as a standing copy. For the complete guidance, for subagent
visibility (subagents read `CLAUDE.md` but not hook output), or in place of
hooks, append it to Claude's global `~/.claude/CLAUDE.md`, Codex's
global `~/.codex/AGENTS.md`, Gemini's global `~/.gemini/GEMINI.md`, or a
per-project `CLAUDE.md` / `AGENTS.md`:

```bash
cat examples/CLAUDE.memory.md >> ~/.claude/CLAUDE.md
cat examples/CLAUDE.memory.md >> ~/.codex/AGENTS.md
cat examples/CLAUDE.memory.md >> ~/.gemini/GEMINI.md
```

```powershell
Add-Content "$env:USERPROFILE\.claude\CLAUDE.md" (Get-Content examples\CLAUDE.memory.md -Raw)
Add-Content "$env:USERPROFILE\.codex\AGENTS.md" (Get-Content examples\CLAUDE.memory.md -Raw)
```

For hook-less providers this standing block supplies the full memory policy,
but it cannot provide a live briefing or run session cleanup. `AGENTS.md` is the cross-vendor standard for standing
agent instructions (Linux Foundation-governed; read by Codex, Copilot,
Cursor, Gemini CLI, Zed, and 30+ others), so a per-project `AGENTS.md`
carrying the block reaches almost every agent at once. Claude Code is the
holdout — it reads `CLAUDE.md` — but a `CLAUDE.md` whose first line is
`@AGENTS.md` imports the shared file, so one copy serves every tool.

The block ([`examples/CLAUDE.memory.md`](examples/CLAUDE.memory.md)) teaches
the loop: **RECALL at the start** (`memory_search` / `memory_lesson_search` /
`memory_fact_get` / `memory_world_search`), **CAPTURE as you go**
(`memory_store` with an honest `origin`, `memory_fact_set` for canonical
facts, `memory_world_set` for cited external facts, `source="status"` for
verbose logs so they stay out of the dream), **REFLECT at the end**
(`memory_outcome`, with `used_ids` naming the hits you actually used — the
dream distils these signals into the lessons surfaced at your next session
start).

For an existing Codex installation, run `python ops/setup-codex-hooks.py`.
The helper asks once, detects the hook source, backs up changed configuration,
persists scoped trust through Codex, and verifies startup briefing, prompt
reminder, and session cleanup, plus the agent-board check-in where the board
is on. The Docker installer runs this step for you.
See [Codex setup options and fallback](docs/guide/providers.md#codex-specifics).

For Claude Code, use the [plugin](plugin/README.md), or the legacy
`ops/install-hook.ps1 -Client claude` / `ops/install-hook.sh --client claude`
for briefing and reminder hooks. The legacy `--client codex` path remains
available but only writes hook definitions; it does not complete trust and
verification. Session episodes also work without hooks through the daemon:
[Episodes & sessions](docs/guide/episodes.md).

**Current Codex runtimes enable hooks by default, including Windows.**
Availability depends on the application/runtime and policy, not the model.
If `[features] hooks = false` is intentional, keep it and use the standing
`AGENTS.md` block. Codex runs the plugin's Windows hooks as native
PowerShell 7 commands; Claude Code runs their Bash commands through Git
Bash, so it needs Git for Windows installed (see
[plugin/README.md](plugin/README.md#windows)).
See the [official hook protocol](https://learn.chatgpt.com/docs/hooks).

**Codex hook trust:** setup approval is limited to PseudoLife's current hook
definitions: the memory and coordination SessionStart and UserPromptSubmit
handlers and SessionEnd, plus the plugin's `Stop` entry (Claude Code's wake
hook, on by default; in Codex it runs only the park gate). It does not approve other plugins or bypass
future trust checks. Changed definitions need approval again, and so does a
handler a plugin update adds; Codex skips an unapproved one silently in the
desktop app, which `ops/update.ps1 -All` (or `ops/update_clients.py`) now
reports as `needs-approval`. If automatic setup cannot
use the installed runtime's trust interface, it reports the problem and
asks you to open `/hooks` to review and trust the definitions. Approved standing
instructions remain available as fallback. Installed files alone do not
establish that hooks are working.

## Usage patterns

**At session start** — loads what you've worked on before, persistent
across compactions:
```
memory_search("project context for X")
```

**During work** — store real decisions; skip fleeting chatter (the shipped
store gate is permissive, so deliberate, durable claims only):
```
memory_store("Decided to use stdio transport for the MCP because no port conflicts", source="pseudolife")
```

**When corrected** — marks the old fact superseded *and* stores the
correction; both surface in future retrieval, the new one ranked higher.
Select the entry by the `id` carried on the search or recent hit:
```
memory_supersede(
  entry_id=417,
  new_text="Provider interface uses async calls — sync version was the v0.7 prototype only"
)
```
`old_text=` still selects by the full stored text when that text is exactly
unique among live entries; it is the legacy selector and the only one file
mode has. Ambiguous or missing targets change nothing.

**Hygiene** — `memory` and `fact` scopes hard-delete (at least one filter
is required for scope `memory`, preventing accidental wholesale deletion);
`lesson` and `world` scopes retire the slot with an audit row and are
reversible with `memory_graph_review(action="restore_slot", store=...,
src="entity|attribute")`; for "keep the history but mark it wrong" use
`memory_supersede` instead:
```
memory_forget(scope="memory", source="test-noise")
memory_forget(scope="fact", entity="test-entity")
```

**Discovering what's in the bank:** open the Cortex Console — sources, tags,
episodes, and full-table views all live there. Going deeper:
[reranking, BM25, abstention, and trace debugging](docs/guide/retrieval.md)
· [episodes + tags](docs/guide/episodes.md#episodes--tags)
· [canonical facts, contenders, world facts, lessons](docs/guide/memory-model.md)
· [the consolidation workflow](docs/guide/dreaming.md#consolidation-workflow-agent-driven-dedup).

## Dreaming — consolidating memories into facts

A **dream** distils the recent associative stream into canonical cortex
facts while you're not looking: pull unconsolidated memories → extract
`(entity, attribute, value)` → acknowledge those exact entries durably.
New entries remain pending regardless of their timestamps; failed acknowledgement
can replay claim application. Manual commits use the token returned by `pull`.
Extraction is pluggable:

| Tier | How it runs | Needs | Quality |
|------|-------------|-------|---------|
| **0 — none** | no extractor configured — the dream still runs, prunes, and acknowledges input batches, but writes no canonical facts | nothing | none (`memory_fact_set` is your only cortex writer) |
| **1 — agent-driven** | the **agent itself** is the gateway: the `/dream` judgment session (its manual-extraction branch fires only when no endpoint is configured) | the agent you already run | highest |
| **2 — shipped default** | daemon auto-sweep → the bundled CPU sidecar, or any OpenAI-compatible endpoint | nothing (sidecar) | high; free if local |

The stack ships tier 2 preconfigured (the bespoke Gemma 4 E4B extractor
fine-tune in a llama.cpp sidecar, internal-only). The sweep cadence,
pointing dreams at a bigger local model or at Claude Sonnet with automatic
sidecar fallback, the full-corpus **deep dream** graph pass, and the
privacy/cost trade-offs: [Dreaming](docs/guide/dreaming.md).

## Benchmarks

The headline is the **whole benchmark, not a slice**: all six
[LongMemEval](https://arxiv.org/abs/2410.10813) question types, 500
questions, oracle variant, run end to end through the memory (qwen-27b
extraction under the v25 embedding backbone, BM25-on turn retrieval).
Single pass, graded by the local Qwen3.6-27B bench judge (2026-08-03):

| arm | accuracy | context tokens/question |
|-----|----------|------------------------|
| naive RAG (top-6 turns) | 0.688 | ~1210 |
| cortex facts only | 0.416 | **~158** |
| hybrid (facts + top-3 turns) | 0.664 | ~842 |
| **commit-gated cascade** | **0.690** | ~883 |

The **cascade** is a serving policy, not a fourth pipeline: answer from
the consolidated facts when that channel *commits*, fall back to raw-turn
RAG when it abstains. Overall this is **a wash on accuracy at ~73% of the
context** — 0.690 vs 0.688 is one question in 500 on a single pass, and
nobody should read it as a win. The fact spine alone answers at ~13% of
RAG's token budget, at a large accuracy cost outside the types it is built
for. The structure is per type:

| question type | n | naive RAG | commit-gated cascade |
|---|---:|---:|---:|
| knowledge-update (facts change) | 78 | 0.859 | ~~0.936~~ (retired — [why](docs/guide/benchmarks.md#the-knowledge-update-slice-78-of-the-500)) |
| single-session-user | 70 | 0.929 | 0.943 |
| single-session-assistant | 56 | 0.911 | 0.929 |
| single-session-preference | 30 | 0.800 | 0.700 |
| temporal-reasoning | 133 | 0.526 | 0.526 |
| multi-session | 133 | 0.504 | 0.474 |

The consolidated spine helps where a fact changes and where the answer
sits inside one session; it loses where the answer must be aggregated
across sessions or ordered in time, because per-fact consolidation is
exactly what discards that structure. BEAM-100K reproduces the same shape
independently. Its abstention questions are where the spine looks best —
the fact-spine arm scores 0.950 against naive RAG's 0.775, identical under
the local judge and under an independent Opus-class judge — but the
2026-09-02 five-arm run bounds that reading: a no-memory arm scores 1.000
there, so the edge is calibration (a small fact context refuses where raw
turns confabulate), not evidence that the memory recalled anything. Setup, caveats,
both bench stacks side by side, and the evidence that extraction quality is
the dominant factor: [Benchmarks](docs/guide/benchmarks.md); full
methodology: [`evals/README.md`](evals/README.md).

Retrieval itself was re-measured on the same corpus before the v25 backbone
swap (150 questions, 74,183 haystack turns, 299 gold turns; pure recall — no
reader, no judge): `Qwen/Qwen3-Embedding-0.6B` reaches **R@10 0.809** against
`bge-base-en-v1.5`'s 0.742 and the previously-shipped `all-MiniLM-L6-v2`'s
0.572, and beats bge-base head-to-head **+32/−12 at k=10 (p=0.004)**.
Artifacts: [`embedder-recall-shootout-20260727.json`](evals/results/embedder-recall-shootout-20260727.json),
[`embedder-recall-qwen-vs-bge-20260728.json`](evals/results/embedder-recall-qwen-vs-bge-20260728.json).

## Cortex Console (web UI)

An operator dashboard served by the daemon itself — point a browser at
**`http://127.0.0.1:8765/ui/`** (the `/health` and `/mcp` endpoints are
unchanged; the console is additive). It's a read-mostly instrument panel for
seeing and steering the memory a human otherwise can't observe:
**Observatory** (health, per-layer counts, the memory store's capacity meter, dream
gauges), **Cortex** (canonical facts with provenance, version-history
timelines, inline Accept/Discard for contested slots), **World / Lessons /
Episodes**, **Stream** (live search with rerank/BM25 toggles and a
ranking-trace debugger), **Graph** (interactive force-directed visualiser, with a review drawer that
can Accept/Reject merges or — for a source file and its own bare concept,
`band.py` ↔ `band` — record an `implements` edge instead of forcing
merge-or-dismiss; proposals a background dream has already judged carry a
verdict chip — accept/reject/leave with confidence, the model's reason in
the tooltip — as a lead, never a decision), and **Console** (every safe `config.yaml` scalar with live-vs-restart
badges, diff-preview, and atomic save).

**Auth** mirrors `/mcp`: `/ui` (static shell) and `/health` are open; `/api/*`
requires the same `PSEUDOLIFE_MCP_TOKEN` bearer when one is set (the console
prompts for it and stores it locally). No build step, no CDN, fully offline —
vanilla ES modules + vendored OFL fonts served straight from the daemon.
Developing the UI? A fixture-backed dev server (no Postgres, no torch)
renders the real frontend against canned data:
`python -m pseudolife_memory.web.devserver` → `http://127.0.0.1:8770/ui/`.
Its payloads self-announce (`"fixtures": true` on `/health`), and the
topbar shows a "DEMO DATA — fixture server, not a real bank" chip in
place of the live chip, so a fixture run is never mistaken for a real
bank.

## Capabilities at a glance

| Capability | Status |
|---|---|
| Transport | Streamable-HTTP MCP daemon (`/mcp`); stdio shim is the installer default (per-session identity) — HTTP remains for single-session setups |
| Storage | Postgres 18 + pgvector (source of truth); ChromaDB for the reference bank |
| Associative store | Flat similarity store (default since the 2026-08-15 measured verdict; the 8-tier banded preset remains opt-in); hybrid dense + BM25 ranking (BM25 on by default); contradiction detection admits potential updates, including a deterministic slot-identity path regardless of embedding similarity, while retaining earlier source notes; whole-note supersession requires an explicit replacement operation |
| Canonical-fact cortex | Single-writer: LLM dream pass + `memory_fact_*` (regex auto-promote opt-in, default off) |
| Set-valued slots | `memory_set_add` / `memory_set_remove` for many-current-value slots; one-way scalar→set conversion, aggregate scalars guarded (park as contender); an `assistant`-origin add cannot convert or join another tier's set, and cannot retract another tier's member |
| Provenance contenders | Tier-rank guard `user > action > agent > assistant`; `memory_fact_resolve` |
| Fact currency | Every cortex fact is dated (`asserted_at` / `age`); `freshness_class` (`evergreen` / `slow` / `volatile`) decays `effective_confidence` and flags `stale`. Left `auto`, the class is inferred from the entity's kind (schema v24 `entity_kinds`) — only `system` entities can rot; artifacts and concepts stay evergreen |
| Write-time labels | `authority` (`directive` / `observation` / `quoted` — the speech act, orthogonal to the `origin` tier) and `distortion_tolerance` (`constraint` / `procedural` / `belief` / `preference` / `episodic`) on entries and facts, set at write time (explicit, or a deterministic heuristic under `auto`) and inherited through supersession unless restated. A `constraint` source is carried verbatim through the dream (with a post-dream guard) and pinned ahead of cosine in `memory_search`'s cortex block and `memory_recall` when the query names its entity; a `quoted` source is low-trust for the two-man rule (schema v35) |
| Knowledge graph | Typed entities/edges, closed relation vocab, on-read closure (Postgres + NetworkX, no AGE/Cypher) |
| World cortex | `memory_world_*` — cited external facts + age-decayed freshness (manual ingest) |
| Procedural memory | `memory_outcome` (signals) → dream-synthesised lessons via `memory_lesson_search`; `prefers`/`avoids` graph edges; single-writer |
| Sense of time + multi-writer | Per-write stamp (tx/valid time, HLC ordering, writer/session); `memory_history`; relative `age` on reads; `write_mode` seam (snapshot live, occ Phase-2) |
| Episodes + tags | Session episodes daemon-owned, keyed by a resolved five-tier session identity; hook eager-open or lazy-open on first store + idle reaper + prune-empty + resume-after-reap; nested sub-episodes with subtree-expanded recall; multi-valued `tags=[...]` |
| Session briefing | SessionStart hook injects lessons + verified world facts + last-session recap once per conversation (resume/compact get the episode handle only); the plugin's per-turn note speaks only when lessons or other sessions' status notes changed (`pseudolife-mcp briefing` adds the unsure-graph section) |
| Consolidation | `memory_consolidation_candidates` + `memory_consolidate` |
| Optional components | Cross-encoder reranker (`rerank=True`, ~80 MB); ONNX embedding backend (`pip install .[onnx]` — load-only, and auto-selected when installed and the configured model's artifact is already on disk, ~3x faster CPU encode on MiniLM. The configured artifact must already exist locally: the daemon image provisions MiniLM's while building, while a pip install stays on torch until you provision it yourself. Models whose Transformer module loads from a subfolder use torch on native Windows, and the default Qwen3-Embedding-0.6B has no ONNX export at all); NLI contradiction scorer (`pip install .[nli]`, ~278 MB) |
| Web console | Cortex Console at `/ui/` — health/stats, fact review + history, graph visualiser, search/trace, config editor (read-mostly, token-gated like `/mcp`) |
| Schema version | v49 (Postgres meta version) — additive `ADD COLUMN IF NOT EXISTS` migrations on daemon start, **except v25**: the `vector(384)`→`vector(1024)` move is not additive, so the daemon refuses to start against an older-dimensioned bank until you run [`ops/migrate_embeddings.py`](docs/runbooks/embedding-v25-migration.md); legacy file-mode `.pt` banks auto-migrate into Postgres; [full version history](docs/guide/configuration.md#schema-version-history) |

## Troubleshooting

Start with `curl http://127.0.0.1:8765/health` — it reports the daemon's
package `version`, the schema version, storage backend, auth state, and
`persist_errors` (non-zero means
writes are failing to reach Postgres; check `docker logs
pseudolife-mcp-daemon`).

- **The cortex stays empty** (canonical facts never appear on their own).
  `/health` reporting `"extractor": "none"` means no extractor is
  configured, so the dream writes no facts and `memory_fact_set` is the
  only cortex writer — expected on the lite tier. Point the daemon at an
  OpenAI-compatible endpoint
  ([Quickstart](#what-lite-gives-you-and-the-one-thing-it-doesnt)) or use
  the Docker tier's bundled sidecar. `"extractor": "disabled"` instead
  means dreaming itself is switched off in config.
- **Lite daemon refuses to start on Windows** with a message about the data
  path: the embedded Postgres runtime needs an **ASCII-only** data
  directory. Set `PSEUDOLIFE_MCP_DATA_DIR` to one (e.g.
  `C:\pseudolife-data`) —
  [Configuration](docs/guide/configuration.md#connection--deployment-env-vars).
- **First build is slow / big.** The daemon image (~5.0 GB, several
  minutes to build) bakes in CPU torch and the embedding weights (Qwen3-Embedding-0.6B
  plus MiniLM); the extractor sidecar
  adds a ~5.3 GB model download on its first build. Every start after that is
  offline and fast — if a *rebuild* is re-downloading models, the Docker
  layer cache was pruned.
- **Daemon unreachable after `wsl --shutdown`** (Windows): the host port
  forward is gone — `docker restart pseudolife-mcp-daemon` re-establishes it.
- **Docker eating RAM** (Windows): the WSL2 VM (`Vmmem`) claims up to ~50% of
  host memory by default. Copy `ops/wslconfig.example` to
  `%USERPROFILE%\.wslconfig`, tune `memory=`, then `wsl --shutdown`.
- **Port already in use**: the stack binds `127.0.0.1:8765` (daemon) and
  `127.0.0.1:5433` (Postgres). Change the host side in
  `ops/docker-compose.yml` if either collides.
- **Console shows "offline" / Unauthorized**: "offline" means the daemon
  isn't reachable (see above); a 401 prompt means it runs with
  `PSEUDOLIFE_MCP_TOKEN` — paste that token into the Console's Token dialog.
- **The coding agent doesn't see the tools**: `claude mcp list` or
  `codex mcp list` should show
  `pseudolife-memory` ✓ connected. If not, re-check the URL
  (`http://127.0.0.1:8765/mcp` — the `/mcp` path matters) and the bearer
  header when a token is set. The daemon preloads the embedder on a warmup
  thread at start (~5–10 s); a very early first call can race it and take a
  few seconds.
- **Tools vanish after an upgrade / the client log says "Connection
  closed"**: the shim's registered command can live outside the repo venv,
  and the MCP SDK v2 migration set an `mcp>=2.1` floor — an older SDK in
  that environment crashes the shim on start. The shim detects this and
  prints the interpreter path and the exact fix on stderr: `pip install -U
  "mcp>=2.1,<3"` in that interpreter, or re-run the installer (which
  registers the project venv's shim).
- **Claude Desktop says "Couldn't start for Cowork and Code sessions. Error:
  unhandled errors in a TaskGroup (1 sub-exception)"**: the real exception
  is at the bottom of `mcp-server-pseudolife-desktop.log`
  (`mcp-server-pseudolife-memory.log` for an entry not yet renamed) in the app's log
  folder (`%LOCALAPPDATA%\Claude\Logs` on Windows, `~/Library/Logs/Claude`
  on macOS). If it is a 401, the daemon is token-gated and the
  Desktop-launched shim holds no credential: Desktop sanitizes the
  environment, so put `PSEUDOLIFE_MCP_TOKEN_FILE` in the entry's `env` (see
  Claude Desktop under [Wire into your coding
  agent](#wire-into-your-coding-agent)) or re-run `ops/install.* --client
  claude-desktop`, then fully quit and relaunch. On the Windows Store build
  the file lives under
  `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\`. If the
  entry already carries `PSEUDOLIFE_MCP_TOKEN_FILE` and still 401s, the
  shim predates token-file support (PyPI releases through 0.15.0 read only
  the literal token): `pseudolife-mcp --help` from a capable shim lists
  `PSEUDOLIFE_MCP_TOKEN_FILE`; upgrade the shim and re-run the installer,
  which now refuses to register an older one against a token file. On
  Windows, upgrade with every session using the shim closed (Desktop
  fully quit from the tray), or it can leave the shim half-removed.
- **A harness "removed tools" notice is not an outage.** A resumed session
  can carry a larger tool roster in its transcript than the current
  [toolset tier](docs/guide/configuration.md#toolset-tiers) serves —
  that's a visibility filter, not a disconnect. Make one `memory_search`
  call before concluding the MCP is down.

## Uninstall

**Lite tier:** remove the MCP registration (`claude mcp remove
pseudolife-memory` / `codex mcp remove pseudolife-memory`), then
`pip uninstall pseudolife-mcp`. If you also want the bank gone, delete
the per-user data directory (`%LOCALAPPDATA%\pseudolife-mcp` on Windows,
`~/.local/share/pseudolife-mcp` on Linux, `~/Library/Application
Support/pseudolife-mcp` on macOS — or wherever `PSEUDOLIFE_MCP_DATA_DIR`
points). Back it up first: `pseudolife-mcp backup` works on lite too.

**Docker tier** — deletion is deliberate at every step:

```bash
# 1. Optional: take a final backup first (ops/backup.ps1 or ops/backup.sh).
# 2. Stop and remove the containers (volumes survive this).
docker compose -f ops/docker-compose.yml down
# 3. Remove the MCP registration.
claude mcp remove pseudolife-memory
codex mcp remove pseudolife-memory
gemini mcp remove pseudolife-memory -s user
# 4. Only when you're sure: delete the data volumes (THIS is the memory).
docker volume rm pseudolife-mcp-bank pseudolife-mcp-state
```

Host-process installs: also unregister the logon task
(`Unregister-ScheduledTask -TaskName "Pseudolife-MCP Daemon"`) and remove
the SessionStart briefing hook — plus the UserPromptSubmit memory-change
hook (`pseudolife-mcp prompt-hook`; older installs: the discipline echo) — from `~/.claude/settings.json` and/or
`~/.codex/hooks.json` (a timestamped `.bak-*` sits next to each edited file).

## Testing

`pip install -e .[dev]`, then `pytest tests/`. The suite covers every
layer, from the MemoryService surface to the Cortex Console REST API;
model-heavy pieces are stubbed so it stays fast and offline. The PG-backed
suites each target a throwaway per-run `pseudolife_memory_test_<pid>`
database on the bundled dev container (never your real bank; concurrent
runs can't collide), dropped on exit, and skip cleanly without Postgres.
The container's password is read from `ops/.env` (override with
`PSEUDOLIFE_TEST_DATABASE_URL` or `PSEUDOLIFE_TEST_PG_PASSWORD`); a
server that is reachable but rejects the credentials *errors* the PG-backed
tests rather than skipping them, so a rotated password can never produce a
green run by accident. Full dev setup: [CONTRIBUTING](CONTRIBUTING.md).

## What's not built yet

- **Reflection via MCP sampling** — would let the dream borrow *Claude
  itself* as the extractor;
  [Claude Code doesn't yet support it](https://github.com/anthropics/claude-code/issues/1785).
- **Cross-machine sync** — memory lives on one PC's disk; syncing via
  rclone / syncthing is left as an exercise.
- **Automated world-knowledge ingestion** — populating the world cortex
  from the live web needs a web-fetch tool the standalone server doesn't
  ship; an agent with web access can automate the fetch+cite step today
  via `memory_world_set`.

## Support

**Solo-maintained, best-effort.** One person builds, tests, and runs this;
there is no support contract and no response-time commitment. That said,
issues are read and most get an answer.

- **Something is broken** → open a
  [bug report](https://github.com/Pseudogiant-xr/Pseudolife-MCP/issues/new?template=bug_report.yml).
  The form asks for your `/health` output, schema version, install tier,
  and client, because those four answer most questions before any
  back-and-forth.
- **Something is missing** → open a
  [feature request](https://github.com/Pseudogiant-xr/Pseudolife-MCP/issues/new?template=feature_request.yml).
  Say what you were trying to do, not only what to add.
- **A security problem** → do **not** open a public issue. Use GitHub's
  private vulnerability reporting — [SECURITY.md](SECURITY.md). Memory
  integrity specifically: [security posture](docs/guide/security-posture.md).
- **Sending a patch** → [CONTRIBUTING](CONTRIBUTING.md) and
  [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md). The bar is "surgical, tested, and
  explained", not "big".

If you need someone to call, [Comparison — use something else
if](docs/guide/comparison.md#use-something-else-if) names vendors who sell
support.

## License

Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

---

<!-- source: docs/guide/memory-model.md -->

# The memory model — cortex, world facts, lessons, and time

The canonical-fact layers in depth: the slot-keyed cortex, provenance
contenders, the cited world cortex, procedural lessons, the reference bank
for background documents, and the temporal / multi-writer stamp. Part of
the [user guide](../../README.md#documentation).

## Canonical facts — the cortex (schema v8)

Alongside the associative store (a flat similarity-ranked pool since
2026-08-15; an 8-band layout remains an opt-in preset) sits the
**cortex**: a slot-keyed canonical-fact store. Where the associative
store is similarity-ranked, the cortex is **identity-not-similarity,
supersession-not-decay, currency-not-frequency** — one *current* value per
`(entity, attribute)` slot (or a member set, for [set-valued
slots](#set-valued-slots)), retrievable out of the context window.

- **Single-writer capture.** The LLM **dream** pass (the extractor sidecar)
  is the sole *automatic* writer of canonical facts, plus deliberate
  `memory_fact_set` calls. The deterministic regex auto-promote on `store`
  is now **opt-in** (`memory.cortex.auto_promote`, default **off**): it
  mis-splits compound entity names (`"payments database host"` →
  `payments` / `database host`) and fragments slots, so it ships off — see
  [the single-writer cortex design](../specs/2026-06-19-single-writer-cortex-design.md).
  (When enabled it still uses the precision-first dev lexicon:
  `<entity> <attr> is <value>` with the attribute drawn from a closed set —
  port / version / host / branch / default timeout / … — plus
  `my <attr> is <value>`, `<Entity>'s <attr> is <value>`,
  `the <attr> of <entity> is <value>`, and single-line
  `<entity> <attr>: <value>`.) A one-time `ops/dedup_cortex.py`
  (dry-run-first, reversible; run it with the daemon stopped, since it
  opens the bank as its writer) collapses sibling slots left by past
  auto-promotes.
- **Documented vs enacted.** A fact stated by a *document* you shared (a
  spec, policy, protocol, runbook) is captured under that document's
  subject, distinct from a fact about what was actually done — the rule and
  the practice occupy different slots and can disagree without either
  overwriting the other. See [what the extractor
  captures](dreaming.md#what-the-extractor-captures).
- **Deterministic read.** `memory_fact_get("project", "language")` returns
  the one current value — no ranking, no stale duplicates. `memory_search`
  also surfaces matching facts ahead of associative hits (a `"cortex"`
  block) — the hybrid shape that outperforms either channel alone (see
  [Benchmarks](benchmarks.md)).
- **Deliberate write / correction.** `memory_fact_set(entity, attribute,
  value, origin="user")` asserts a fact at higher confidence; setting a new
  value at an existing slot supersedes the old (kept as audit history).

### How current is this fact?

A cortex fact is the *last thing asserted* at a slot, which is not the same
as a *true* thing now. Two fields make that gap visible rather than leaving
a reader to assume the value is live:

- **Every fact carries its dates.** Reads project `asserted_at` and
  `last_confirmed` (ISO-8601, second resolution) plus a human `age`
  (`"3d ago"`). A value with no other signal is still judgeable: a
  "currently deployed" fact last confirmed nine months ago is worth
  re-checking against the source before acting on it.
- **`freshness_class` says how fast the slot rots** — `evergreen`
  (never decays), `slow` (~9 months), `volatile` (~3 weeks). Non-evergreen
  facts report an `effective_confidence` that decays toward a per-class
  floor with time since `last_confirmed`, and are flagged `stale: true`
  past twice their TTL. Re-asserting the same value confirms it and
  restores full confidence.
- **`stance` records how the source *held* the value** (schema v29) —
  a dream claim extracted from hedged or negated text ("probably X",
  "no longer Y") carries that epistemic stance onto the fact, visible in
  `memory_fact_get`, recall cortex blocks, and `history` when set. It
  follows the latest asserting write (a plain restatement clears it), is
  never an input to confidence, ranking, or supersession, and is not
  settable via `memory_fact_set` — it exists so a hedge survives
  consolidation instead of hardening into a flat assertion.

Set it explicitly at write time: `memory_fact_set("pseudolife-mcp",
"extractor-prompt-version", "v2", freshness_class="volatile")` — an
explicit value always wins, and since v23 `POST /api/facts/set` threads it
too, so the Console and the REST fallback (the documented workaround for
clients that stringify MCP list params) no longer pin every fact they
write to `evergreen`. Left unset (the default is the sentinel
`"auto"`), the class is instead **inferred from the entity's kind**
(schema v24, `entity_kinds`): a `system` entity (live, mutable — the sort
of thing with a "currently deployed" answer) can resolve to `volatile`; an
`artifact` (frozen at a point in time, like a tagged release) or a
`concept` (abstract/definitional) always resolves `evergreen`, whatever
the attribute name. `0-9-0-release / schema-version` is permanently true;
`daemon / schema-version` rots — same attribute, opposite class, because
the entities differ.

The attribute still gets a vote, but only on a `system` entity and only in
one direction: a short, deliberately dumb list of state-shaped names
(`status`, `state`, `health`, `live`, `running`, `current`,
`deployment`/`deployed`, `url`, `version`) resolves `volatile`, everything
else stays `evergreen`, and event-shaped names (`…-date`, `…-at`,
`…-hash`, `…-commit`, `…-count`) are forced `evergreen` first, so a
recorded deployment *date* never inherits the volatility of the deployment
it describes.

An entity with no recorded kind — which is every entity until the offline
classifier assigns one — resolves `evergreen`, not `volatile`: personal
cortex facts are mostly durable, and defaulting the other way would
re-rank every existing bank on an assumption nothing has measured. Facts
already in the bank before schema v23, and any entity the classifier
hasn't reached, read back exactly as before, so nothing changes until an
entity is deliberately classified.

Both fields are descriptive, not enforcement — a stale fact is still
returned, marked. Nothing is auto-deleted or auto-superseded on age.
The read surface does nudge, though: once a fact has aged past a third
of its TTL (or sits contested), `memory_search`, `memory_fact_get`, and
`memory_world_search` attach a ready-made `correct_with` call to it — a
filled-in `memory_fact_set(...)` the reading agent can run the moment it
verifies the value, re-asserting or correcting at the same slot. The
`stale: true` flag is the louder, later signal (twice the TTL);
`correct_with` fires earlier so drift gets fixed at first contact.

**`re_verify` / `re_verify_reason`** is a third, independent signal — a
*retract-direction* read of the engram cross-index (schema v13;
`memory.traces.enabled`, on by default — see
[Built-in defaults](configuration.md#built-in-defaults-tuned-for-claudes-use-case)).
Where the fields above say a fact is old, `re_verify` says a fact's
*evidence* moved: a served fact whose source memories were superseded
(corrected) *after* the fact was last confirmed carries `re_verify: true`
plus a `re_verify_reason` naming how many source memories were corrected
since. It surfaces on `memory_fact_get`, `memory_search`'s cortex block,
and `memory_recall`; on a set-valued slot the comparison is against the
newest member's confirmation stamp, since a set is served as one grouped
answer — falling back to a member's assertion time when that member carries
no confirmation stamp, so one legacy member cannot drag the slot's clock to
zero and warn on every source it ever had corrected.

It is a flag, never a cascade, and deliberately excluded from the
`correct_with` affordance: correcting a source note does not establish that
every fact derived from that note is wrong, and the signal is broad. Measured
on the live bank on 2026-09-11 with `ops/measure_reverify_population.py`
(read-only): 1668 of 6015 current facts, 27.7%, stood on a source memory
corrected since they were last confirmed. Routing that into a call whose
served note says to run a correction *now* would be a standing instruction to
rewrite a quarter of the cortex every session. Re-asserting or re-confirming
the slot moves `last_confirmed` forward and clears the flag.

The **active** affordance for retracted evidence lives on the correction
itself: `memory_supersede`'s result carries `derived_flagged` — the
canonical facts (slots) the dream built on the memories just corrected.
They are named, not touched: nothing is rewritten, the caller decides
whether each derivation still holds. Each row carries `has_current_value`
(a slot with no live value is still blast radius worth seeing, just
nothing to go re-check), the list is capped at 50 entries with live slots
first, and `derived_flagged_truncated` / `derived_flagged_total` say
whether a correction reached further than the cap.

PostgreSQL schema v39 preserves the correction event separately from the
evictable source and its trace. A corrected source can later disappear from
`source_entries` while its fact's `re_verify` warning remains, until the fact
is confirmed again. The event holds a normalized slot, opaque source entry ID
and correction time, without source text or a foreign key to the entry or fact
row. Cortex snapshots and fact compaction therefore retain it. Ordinary
eviction or deletion of an uncorrected source does not establish a correction
and creates no warning.

**What the upgrade does to an existing bank.** The first start on v39
materialises one durable event for every surviving `memory_traces` row whose
source entry is already superseded — 2077 pairs on the reference bank on
2026-09-11, which is what the same script reports as
`trace_supersession_pairs`. That reproduces the warnings the bank was already
serving; it does not invent new ones, and history already lost to deletion
cannot be recovered. The difference afterwards is that these warnings no
longer drain when their source is evicted. Each one clears only when its slot
is confirmed again: a `memory_fact_set` at the slot with the same or a new
value, or accepting a contender there. An operator who wants to clear a
population deliberately re-asserts those slots — the flag is per slot, so
there is no bulk switch, and there is deliberately no way to dismiss a warning
without confirming the value it stands on. `re_verify` stays passive
throughout: it is never rendered into `correct_with`, so a large flagged
population never becomes a large instruction list.

Both served signals are gated on `memory.traces.enabled`. Turning tracing off
silences them and stops new trace formation; corrections still preserve events
for trace relationships that already exist, so turning it back on does not
erase known provenance. Upgrades and older logical imports can reconstruct
events only from surviving superseded sources and traces. History already
lost to deletion cannot be recovered. These warnings remain passive: they
request scrutiny without changing or deleting a fact.

**Source notes retain their evidence when a potential conflict is stored.**
The contradiction detector runs before the surprise gate: a different
value or polarity at the same normalised `(entity, attribute)` slot, or a
match from its similarity-gated heuristics, lets a potential update pass
even when it is too similar to existing text to meet a positive surprise
threshold. A conflict about one detail does not establish that the whole
earlier note is invalid. Ordinary `memory_store` therefore does not decay
that note or stamp a supersession mark on it.

Old and new source notes can both compete in retrieval. Use
`memory_supersede` or `memory_consolidate` when deliberately replacing a
whole note or cluster; the cortex still supersedes canonical slot values
under its existing rules. Existing source-note supersession marks and
history are preserved, with no automatic repair or backfill. Their
retrieval treatment is described under
[superseded entries](retrieval.md#superseded-entries).

For an explicit correction, carry the selected entry's `id` from search or
recent results into `memory_supersede(entry_id=..., new_text=...)`. Use
`entry_ids=[...]` for `memory_consolidate`. IDs identify entries in the same
bank and survive ordinary PostgreSQL hydration; they are not portable across
bank replacement or arbitrary imports. The Console sends selected IDs too.

Use exactly one selector mode. Legacy `old_text` and `replaces` calls still
work when each full text identifies exactly one live entry; a retired
duplicate is history rather than a rival target, so text that was corrected
and later restated stays selectable. There is no paraphrase fallback or
replace-all behavior. Missing, ambiguous, already-superseded or unavailable
targets return `new_memory_stored: false` with `reason`, `error` and
`target_errors`; none of the selected entries change on target-validation
failure. Search again and resubmit IDs. Success results include
`superseded_ids`, which is empty in file mode: file-mode entries have no
durable row ID and therefore require unique exact text.

Whole-selection validation does not provide transactional rollback for later
encoding or storage failures. Operational failure recovery remains a separate
limitation of explicit corrections.

### Who said it, and how exactly must it survive? (schema v35)

Two labels ride on every entry and every fact, set at write time and
inherited through supersession unless a later write restates them:

- **`authority`** is the *speech act* of the text — `directive` (an
  instruction to the agent), `observation` (a plain statement; the
  default, stored as NULL and served as nothing), `quoted` (reported
  speech: a document, a paper, a third person). It is deliberately a
  separate axis from `origin`: `origin` says *who wrote* and is a tier
  that drives supersession arithmetic (the provenance guard, the two-man
  rule), while directive-vs-observation is not a tier ordering at all —
  and the failure this closes (arXiv 2608.01679, *authority collapse*)
  is exactly a third party's offhand remark consolidating into what reads
  as a standing user instruction. The pair `(origin, authority)` is what
  the paper calls authority. A `quoted` source is low-trust for the
  [consolidation quarantine](dreaming.md#consolidation-quarantine--the-two-man-rule-opt-in).
- **`distortion_tolerance`** is how exactly the text must survive
  consolidation (arXiv 2608.22752, *the compaction cliff*): `constraint`
  (zero — verbatim), `procedural`, `belief`, `preference`, `episodic`.
  Only `constraint` has consumers today: the dream copies a constraint
  entry's text verbatim onto a derived fact and a post-dream guard reports
  any constraint left without a carrier ([dreaming](dreaming.md#constraint-entries-survive-verbatim--typecompact--guard-schema-v35)),
  and in-scope constraint facts — in scope meaning the query names the
  fact's entity (a seed of the walk, in `memory_recall`) — are served
  *ahead of* the cosine ranking
  ([retrieval](retrieval.md#constraint-pinning-schema-v35), which also
  says what that scope test means for how a rule should be named and
  where a rule that must always hold belongs).

Both are explicit parameters on `memory_store` and `memory_fact_set`;
the `auto` default is a deterministic form heuristic (no model call on
the store path) that asserts `constraint` only for rule-sized deontic or
imperative text (`must`, `shall`, `forbidden`, `rule:`, or an opener like
`Never run …`), `quoted` on an explicit reporting construction
(`according to`, `per the`, `the docs say`), and `directive` on an
instruction addressed to the reader — measured on the live bank before
shipping (`evals/results/label-heuristic-audit-20260902.json`) and
re-measured on 2026-09-03 after `must` as a noun or adjective ("a
must-read series") stopped counting as a deontic
(`label-heuristic-audit-20260903.json`, plus the chat-text replay in
`label-heuristic-audit-20260903-beam-chip5.json`). The other four
fidelity classes are accepted explicitly and carried.
Neither label ever feeds confidence or supersession routing; a
`constraint` label is the one label retrieval *ranks* on. Served only
when set, so an unlabelled record's payload is byte-identical to before.

## Set-valued slots (schema v26)

A cortex slot is scalar by default — one *current* value, corrected by
supersession. Some facts aren't a single current value at all: restaurants
you've tried, bikes you own, PRs pending review. Forcing a collection through
the scalar model destroys information — the second `memory_fact_set` call
supersedes the first, so "tried: Ramen-ya" then "tried: Pho Anh" leaves only
Pho Anh current. A **set-valued slot** holds many members concurrently
current instead of one.

- **Use a set** when the fact is naturally plural and members are added and
  retracted independently of each other — tags, memberships, an inventory,
  a pending-items list.
- **Keep scalar supersession** when there is one true value that changes over
  time (a job title, a deployed version, a phone number) — the existing
  `memory_fact_set` behaviour, unchanged.

### Lifecycle

`memory_set_add(entity, attribute, member)` adds a member or, if the same
value (exact match or near-duplicate by embedding) is already current,
*confirms* it — bumping `last_confirmed` and, if higher, confidence, rather
than inserting a duplicate. `memory_set_remove(entity, attribute, member)`
retracts one current member. Neither call touches any other member of the
slot. As with scalar supersession, nothing is hard-deleted: a removed member's
row survives with `status: "removed"`, so re-adding the same value later is a
fresh add, not an undo, and the full history (added, confirmed, removed,
re-added) stays inspectable via `memory_history` / the store's
`members(..., include_removed=True)` audit view.

Members are never *contested* — there is no provenance-tier dispute path for
a set the way there is for a scalar (see [Provenance
contenders](#provenance-contenders--never-silently-overwrite-a-user-fact)
below). A second value landing on an already-populated set slot is just a
second member, not a conflict to resolve. (The one exception: an *add*
against a slot that still holds a protected aggregate scalar — see
[Conversion rules](#conversion-rules) below — parks as a scalar contender.
Once a slot has actually converted to a set, this still holds: members
themselves are never contested.) A set slot also caps at 100 concurrent
members; further adds beyond the cap are dropped (`"member_capped"`) rather
than silently applied or queued.

### Conversion rules

Conversion between scalar and set is deliberately **one-way in both
directions of the story**:

- **Scalar → set**: the first `memory_set_add` call against a slot that
  currently holds a scalar value converts it. The scalar row is superseded
  (kept as audit history, same as any other supersession) and reinserted as
  the set's first member. From that point, `memory_fact_set` against the
  same slot raises an actionable error naming `memory_set_add` /
  `memory_set_remove` instead of the store's own `add_member`/`remove_member`
  vocabulary — there is no path back to scalar while any member is current.
- **Set → scalar**: only once *every* member has been removed. With no
  current record of either kind at the slot, `memory_fact_set`'s own guard
  (which checks for current members, not history) allows a fresh scalar
  write there. This is a byproduct of removing the last member, not a
  dedicated "revert" call — and the removed member rows stay as audit, they
  just no longer make the slot read as a set.

Set members are **evergreen-only, by design**: there is no way to give a
member a `freshness_class`, and the scalar → set conversion **drops** a
non-evergreen scalar's class rather than carrying it onto the member (a
`volatile` "deploy status: pending" that gets a second status added
becomes an ordinary evergreen membership). Three reasons, weighed
deliberately rather than left implicit:

- staleness decay exists to age scalar values that change without anyone
  saying so; a set already has an explicit "no longer true" channel —
  `memory_set_remove`, with removal tombstones — and decay layered on top
  would be a second, competing invalidation mechanism;
- there is no group-level staleness that honours the `stale_policy`
  contract: quarantining or demoting a whole set entry because one member
  aged would transform *fresh* members' payloads (the no-harm gate the
  policy eval preregistered), while per-member transforms would still leak
  raw stale text through the composed group `value`;
- the serving change would re-rank deployed banks on an unmeasured
  assumption — the same reason `freshness_class` itself defaulted personal
  facts to `evergreen` at v23.

The drop is audit-visible, not silent: the conversion's supersession-log
entry carries `dropped_freshness_class` (e.g. `"volatile"`) whenever the
converted scalar was non-evergreen, and the superseded scalar row keeps
its own class for history. If a fact's staleness matters, keep it scalar.

The scalar → set conversion carries one guard: if the current scalar is a
**number-led aggregate value** — a value with an optional leading currency
symbol (`$` `€` `£`), then an optional leading `+`/`-` sign, then a required
digit (`^[$€£]?[+-]?\d`; e.g. "32", "27 species", "$1,500") —
`memory_set_add` does not convert it.
Converting would destroy a stated total that no enumeration of members
recovers, which is exactly what a paired eval gate measured as a
net-negative effect on knowledge-update questions
(`evals/results/c2op-gate-verdict.json`). Instead the incoming member is
parked as a contender against the scalar (audit reason
`member_add_blocked_aggregate`), the same provenance-contender machinery
described below; the scalar stays current, and `memory_fact_resolve(...,
accept=True)` remains the explicit human path to overwrite the total. If
the incoming member equals the current scalar, it confirms the scalar
instead of parking a contender identical to itself. The guard applies
unconditionally — regardless of `memory.cortex.protect_provenance` —
because protecting a stated total isn't a provenance-tier concern.
Accepted v1 limitation: on content that enumerates members after stating a
count ("I own 3 bikes" then "picked up a gravel bike"), the guard likewise
suppresses set formation and leaves the latest add sitting as a contender —
correct for stated-total content, a measured trade-off for enumerating
content.

### Reading a set slot

`memory_fact_get(entity, attribute)` returns the scalar shape
(`{record, contenders}`) for a scalar slot, but a set-valued slot returns a
different shape instead: `{kind: "set", entity, attribute, members: [...],
removed: [...]}`. **`members: []` (every member removed) reads as EMPTY** —
the same signal a scalar miss gives a caller — not as "found, zero members."

`memory_search` and `cortex_search` surface a set slot's whole current
membership as **one entry**, not one hit per member: `{"kind": "set",
"value": "m1; m2 (2 members)", "members": [...], "score": <top member's
score>, "contested": false, ...}`. The composed value lists whichever members
individually ranked highest first, then any current member that didn't rank
on its own — so the full membership is always visible even when the query
only matched one member by name. A set entry carries `last_confirmed`,
`asserted_at`, and `age`, all anchored to the most recent add/confirm
activity across its members — **removing a member never moves these dates**.
It carries no `freshness_class` at all (it renders as `evergreen`, same as
any unclassified scalar); age-based decay is a scalar-only affordance, by
the deliberate evergreen-only rule under [Conversion
rules](#conversion-rules) above.

### Dream extraction

A dream claim may carry `"op": "add" | "remove"` to target set membership
instead of the scalar supersede path. `op` is for membership changes only —
a plain value update ("moved to Seattle") is still an ordinary scalar claim
with no `op`. A scalar claim (no `op`) landing on a slot that already holds
current members is dropped and logged, not routed or silently applied — the
only way to touch a set slot is an explicit `op` or the two MCP tools
themselves. A malformed `op` value degrades to the scalar path with a
warning rather than failing the dream. **Since 2026-08-01 the shipped
extraction prompt solicits `op`**, paired with a counts-are-never-members
rule: the bare op block measured net-negative on knowledge-update content
(the model re-routed count *updates* into `op:"add"` claims, freezing
stated totals — `evals/results/c2op-gate-verdict.json`), and the count
rule is what repaired it — the gated run landed the commit-gated cascade
exactly at the op-less control while genuine sets still formed
(`evals/results/c2op-count-verdict.json`, with sidecar-adoption and
ladder-rung validation in the same artifact). The base of the shipped
prompt is byte-pinned to the measured artifact
(`evals/prompts/ku_op_prompt_v12_count_source_example.txt`, pinned by
`test_op_prompt_artifact.py`; the shipped prompt itself — that base plus
the assistant-facts blocks — is pinned to
`evals/prompts/assistant_facts_provenance.txt` by
`test_assistant_provenance.py`); the op block was introduced at v5 and the
pin has since moved through the v10 update-anchored stance revision to
the v12 example re-cut of 2026-09-07, which replaced the two worked
examples that had been paraphrased from the benchmark corpus.
The aggregate-conversion guard (see [Conversion rules](#conversion-rules)
above) remains the apply-time backstop: an `op:"add"` that does land on a
stated-total scalar parks as a contender rather than converting, whether
it came from a live `memory_set_add` call or a dream claim.

## Provenance contenders — never silently overwrite a user fact

Every cortex fact carries a provenance tier: **`user` > `action` >
`agent` > `assistant`** (set via `origin=`, or defaulted from `source`). A
write may only *supersede* a slot whose current value is backed by an
equal-or-weaker tier. A **weaker-tier** write (e.g. an `agent` value
conflicting with a `user`-stated fact), or one below the confidence margin,
is **not applied** — it's parked as a *contender*:

```python
memory_fact_set("db", "host", "10.0.0.5", origin="user")   # current
memory_fact_set("db", "host", "10.0.0.9", origin="agent")  # -> action="contested"
# current stays 10.0.0.5; "10.0.0.9" is parked. memory_fact_get shows both;
# memory_search flags the fact "contested": true.
memory_fact_resolve("db", "host", accept=True)   # human said yes -> adopt (user-confirmed)
# or accept=False -> discard the contender, current unchanged.
```

If the slot has since become a **set** (see [Conversion
rules](#conversion-rules)), `accept=True` is refused with
`reason: "slot_holds_set"` — a scalar contender cannot replace a member set,
so adopt the value with `memory_set_add` instead — while `accept=False`
always works and is how an operator dismisses such a contender.

`assistant` is the floor tier: a fact the **assistant** stated in a turn.
The shipped extraction prompt asks for a `speaker` label since 2026-09-05
— where the note makes the speaker knowable; see
[dreaming](dreaming.md#what-the-extractor-captures) — so this tier is
**reachable on the default path**
(`memory.dream.assistant_claims`, default `contender`). It may fill an empty
slot, but against a current value of any other origin it always parks as a
contender — that rule is not gated on `protect_provenance` below — and it
ranks after user-origin facts at equal similarity. The same rule covers
**scalar and set-valued slots**: an assistant claim cannot trigger the
one-way scalar→set conversion, cannot join a member set that carries any
non-assistant member (it parks as a contender), and cannot retract a
member another tier added (the retraction is dropped, `action:
"member_remove_refused"`). It may fill an empty slot, extend a set it
alone built, and retract its own members. Nothing supersedes *it*
in return: an assistant-origin value is replaced by any later write.
Measured 2026-09-05 on the LongMemEval oracle slice: asking the extractor
for assistant-stated facts lifts the fact-only arm on
`single-session-assistant` from 0.054 to 0.536 while the knowledge-update
pollution check stays flat-to-up, and the guard costs nothing measurable
against an unguarded variant of the same prompt — tables, paired tests and
the adoption gate are in `evals/README.md` (the published run is the clean
re-run `assist-prov2`; the first run's contaminated worked example and its
retired numbers are retained in the same section). That prompt then passed
the extraction ladder on the primary rung and **shipped on 2026-09-05**, so
a dream on stock settings now writes assistant-origin facts: they fill
empty slots and park as contenders against anything else. A claim carrying
no `speaker` label — a note with no role marker to read it from, an older
prompt, or an extractor shim launched with `--system-prompt-file` — still
writes exactly as it did before, and on a bank of unmarked notes that is
the common case.

This catches the case where the agent *decides* to update something and the
human only said "yes/proceed": the discrepancy surfaces (at the write, in
search, and in `memory_fact_get`) so the agent can check in rather than
overwrite. Set `memory.cortex.protect_provenance: false` in `config.yaml`
to disable and restore pure newer-wins — for scalar-vs-scalar conflicts;
the aggregate conversion guard's contender parking (see [Conversion
rules](#conversion-rules) above) applies regardless of this setting, since
protecting a stated total isn't a provenance-tier concern.

## World knowledge — the world cortex (schema v9)

A third layer sits beside the personal cortex: the **world cortex**, for
durable facts about *external* reality that a frozen training cut-off may
have wrong or stale — a current model version, a price, who holds a role, a
research finding. It's a separate slot-keyed store (its own `world_facts`
table, `origin=source`), so external claims never mingle with the
user/project facts.

```
memory_world_set("anthropic", "latest-model", "opus-4.8",
                 source_url="https://...", source_quote="Opus 4.8 is the latest...",
                 freshness_class="volatile")   # weeks | "slow" months | "evergreen" never
memory_world_search("which Claude model is current")
# → entries with effective_confidence (age-decayed), a `stale` flag, and the citation
```

Each fact carries a **citation** (`source_url` + the 1–2 sentence
`source_quote`, not the whole page) and a `freshness_class` that drives
**age-decayed trust** at read time: past 2×TTL a fact is flagged `stale`
(a lead to re-verify, not truth). The trust contract: prefer a fresh,
*cited* world fact over frozen training intuition when they conflict — but
cite it ("as of <date>, per <source>") rather than presenting it as your
own knowledge; your own cortex/episodic facts stay the highest-trust ground
truth. `memory_search` surfaces matching world facts in a separate block,
and the Console's world view (`/api/world`) lists them all for audit.

**Retiring a world fact is reversible (schema v37).**
`memory_forget(scope="world", ...)` retires the slot rather than deleting
it: the row's `status` becomes `retired` and an FK-free `store_decisions`
row records who, why, and the verbatim record. The undo is
`memory_graph_review(action="restore_slot", store="world",
src="entity|attribute")` — restoring from the retired row while it still
exists, or from the audit snapshot once compaction has purged it; a bare
entity in `src` (no `|attribute`) restores every retired aspect of that
entity. `GET /api/curation/retired` lists what's currently retired across
both stores, and the Console's undo route is `POST /api/world/restore`.
Only `scope="memory"` and `scope="fact"` still hard-delete.

> The world cortex here is populated **manually** via `memory_world_set`.
> The live-web `research_ingest` action (fetch + distil cited world facts
> automatically) is an agent-side capability that depends on the agent's
> web tool — it is not part of the standalone MCP server.

## Procedural memory — the lessons store (schema v10)

A fourth layer learns from the agent's *own work*. Where the cortex stores
*declarative* facts ("X is Y"), the lessons store is *procedural*: keyed by
a **task-type** and an **aspect** (`approach` / `pitfall` / `tool-choice` /
`correction`), each lesson carries an **outcome** (`success` / `failure` /
`correction`) and a **polarity** (`+` do-this / `-` avoid). Its own
`lessons` table keeps it isolated from the personal and world cortex.

Capture is cheap and in-session; synthesis is single-writer (the dream):

```
# during a task, log what happened — this writes a SIGNAL, not a lesson:
memory_outcome("deploy engine to host", "failure",
               about="tar --same-owner", detail="chown errors aborted the extract")
memory_outcome("deploy engine to host", "success", about="tar --no-same-owner",
               used_ids=[1421, 903])   # the search hits the work turned on
# user corrections are auto-captured when a user-tier memory_fact_set supersedes a value.

# the dream later distils accumulated signals into durable lessons; recall them at task start:
memory_lesson_search("how do I deploy the engine to a host")
# → [{task, aspect, lesson, about, polarity:"-"|"+", outcome, confidence, score}, ...]
```

Not every synthesized lesson is written: one that near-matches an existing
*current* lesson at a different key with the same polarity is skipped as a
duplicate and counted (`lessons_deduped` in the dream-run row;
`memory.lessons.synthesis_dedup_min_similarity`, default `0.88`, `0`
disables). Opposite-polarity near-matches always write — a dead-end and a
success about the same thing are both worth keeping — and explicit
`lesson_write` calls are never gated. The comparison covers the lessons the
same batch has already staged, so two near-identical claims in one batch
write once.

In PostgreSQL, synthesis stages lesson changes in memory and commits the
lessons, their graph updates, and the handled signals' acknowledgements in one
transaction. Each claim writes inside its own savepoint: a claim that cannot be
written rolls back both halves of itself and is counted as `write_errors`,
while the rest of the batch commits. A fully deduplicated group is acknowledged
only with its supporting lesson state durable. Extraction happens outside the
service lock; changed or already consumed inputs invalidate the extracted batch
before it writes anything. One sweep drains at most
`memory.lessons.synthesis_max_signals` signals (default 200), which bounds a
single lock hold rather than the total work; the rest waits for the next sweep.

An empty or failed extraction route leaves its signals pending for a later
sweep, while they are younger than `memory.lessons.signal_retry_days`
(default 30 days, counted from when the signal was recorded). Older pending
signals are kept as evidence but no longer offered. A rule signal whose own claim
failed stays pending too; the clustering route, whose claims do not map to
single signals, is acknowledged once any of its claims lands. This is a
persistence guarantee, not evidence that every extracted lesson is correct or
complete. A lost commit response triggers a durable-state check before retrying
or saving; if that check is unavailable, the service latches until it succeeds
or the daemon restarts.

While latched, lesson reads and the lesson half of a save fail; `/health`
reports `lesson_reconciliation_required` (status stays `ok`, so the container
healthcheck does not restart the daemon by itself) and the daemon logs the
latch at ERROR. Everything else still persists: the autosave and exit flush
write weights, access counts, and dirty cortex and world slots, then report the
lesson failure. That split matters because restarting is the operator's
recovery: it rehydrates the durable bank and clears the latch, and it discards
anything that was still only in memory. If selected signal rows have been
removed or retargeted during an extended outage, their state may no longer
prove the commit outcome: the service remains blocked for operator recovery
instead of claiming a successful retry. This protocol does not repair
historical losses or recover prior unsaved changes. It assumes the existing
single-daemon writer. File-mode synthesis still returns `skipped: no-storage`.

Lessons are also **traversable in the graph**: a task-type becomes an
`etype='task-type'` entity, and each lesson adds a `prefers` (positive) or
`avoids` (negative / dead-end) edge to the tool/source it concerns — so
`memory_graph("deploy engine to host")` shows what to reach for and what to
avoid. Retrieval is embedding-on-query (mirrors `memory_world_search`); the
graph edges power structured traversal.

**Retiring a lesson is reversible (schema v37).**
`memory_forget(scope="lesson", ...)` retires the slot rather than deleting
it: the row's `status` becomes `retired` and an FK-free `store_decisions`
row records who, why, and the verbatim record. The undo is
`memory_graph_review(action="restore_slot", store="lesson",
src="entity|attribute")` — restoring from the retired row while it still
exists, or from the audit snapshot once compaction has purged it; a bare
entity in `src` (no `|attribute`) restores every retired aspect of that
entity. `GET /api/curation/retired` lists what's currently retired across
both stores, and the Console's undo route is `POST /api/lessons/restore`.
Only `scope="memory"` and `scope="fact"` still hard-delete.

`used_ids` is a second, unrelated payload riding the same call: the ids of
the `memory_search` hits the work actually turned on. Each one credits
**every** `retrieval_events` row in the session window that served it with a
`retrieval_uses` label (`used_via="outcome"`) — the relevance signal a
learned reranker trains on, which otherwise only `memory_get` /
`memory_reinforce` produce (those credit only the most recent serving
search: a dereference follows one query, an outcome follows a session, and
the agent names ids, not queries — under most-recent-wins an entry served by
two searches left the earlier one unlabelled, which the replay dropped or,
when that event carried another label, scored as a miss). With no session
identity at all the most-recent rule stays: "same session" would otherwise
mean every other session-less search in the window.
No foreign key links a signal to the labels it caused: the labels stand on
their own. Since schema v44 the signal row's `used_ids` column keeps what
the ids became, as id lists: `{"credited", "unmatched",
"served_elsewhere"}`, or `{"unchecked", "reason"}` when the label write
failed. So the share of named ids that matched a search can be measured
from the bank. It stays `NULL` when the outcome named no ids or the
retrieval log is off, and also when this best-effort write itself failed
(counted in `memory_stats` `retrieval_log.write_errors`), so a match rate
over non-`NULL` rows skips those outcomes. Like the retrieval log, the
column stays out of portable exports.

`memory_lesson_search` calls are logged too (schema v44), in their own
`lesson_search_events` table: the query, the caller's session, and the
lessons served by `(task, aspect)` slot key (stored as `entity_norm` /
`attribute_norm`) with rank and score. A search
that found nothing gets a row as well. They are kept out of
`retrieval_events` because the retrieval replay and telemetry harnesses
re-run every row there as a `memory_search`. The log shares the retrieval
log's switch and retention, and `memory_stats` counts it under
`retrieval_log.lesson_searches`. Lessons shown in the session-start
briefing are not counted.

Two invariants a harness must keep, because the label silently credits
nothing otherwise: the outcome must be logged under the **same session
identity** as the searches (one session per episode), and **within
`memory.retrieval_log.use_window_seconds`** of them (default 1 h — an
end-of-episode outcome cannot credit a search older than that). The result
reports `used_ids_recorded` (ids credited to at least one search),
`used_ids_unmatched` (nothing in the window served it),
`used_ids_served_elsewhere` (a search in the window served it, but under
another session id — not "never served", so the two are kept apart) and
`used_ids_errors` (labels the storage layer refused, which is not the same
answer as a miss); at most 50 ids are taken per call, any beyond that
reported as `used_ids_truncated`. The label is **positive-only**: `used_ids=[]`
is the same as omitting it (the result says so under `used_ids_reason`), and
an outcome without `used_ids` says nothing about what was used — an
unlabelled session is not a zero-use session.

**Rule mode (2026-09-08).** The shipped synthesis clusters signals into one
abstract lesson per `(task-type, aspect)` slot and paraphrases freely. A
protocol that distils one situation-specific rule per episode with its
decision-critical values intact (the "Learning on the Job" setting,
`docs/specs/2026-09-08-learning-on-the-job.md`) opts a signal in by giving
`memory_outcome` an `about` that starts with `rule:` — or sets
`memory.lessons.rule_mode: true` to treat every signal that way. Rule
signals are synthesised one call per signal under a separate prompt: the
lesson is one `WHEN <situation> THEN <exact action>` (or `WHEN … do NOT …`
for a failure with no known solution) sentence, `aspect` is `rule`, the
slot key is the situation, and rules are exempt from the cross-key dedup
gate, so look-alike situations with different actions coexist. The
`detail` may carry a fixed block the prompt reads — `SITUATION:`,
`VERDICT:`, `ACTIONS TAKEN:`, `CORRECT SOLUTION:`, `ACTION DIFF:`,
`MUST INCLUDE: a; b` — and a rule that drops a `MUST INCLUDE` value is
retried once before being accepted. Default off; an extractor without the
rule path synthesises such signals under the shipped prompt instead and
the dream report says so (`rules_fallback`).

Failed rule calls and valid-but-empty rule responses stay pending individually
(`rules_failed` and `rules_empty` in the synthesis report). Plain and rule
extraction failures do not prevent a successful route from committing. A custom
rule extractor must return one rule per handled input and identify failed or
empty input IDs through `last_rule_failed_ids` / `last_rule_empty_ids`; if its
counts do not establish coverage, that route is left pending without writing
its unmatched outputs.

> Single-writer: `memory_outcome` only ever logs a signal — the dream's LLM
> extractor is the sole writer of lessons. With no extractor configured,
> signals accumulate (pruned by retention) and no lessons are synthesised,
> exactly as the cortex behaves without an extractor. The synthesised
> lessons are **auto-injected at session start** by the
> `pseudolife-mcp briefing` SessionStart hook (the "lessons from past work"
> block) — see [Episodes & session lifecycle](episodes.md).

## Background documents — the reference bank

A fifth layer holds *source material* rather than memories: the **reference
bank**, a ChromaDB chunk store for background documents (papers, manuals,
specs, codebases). `document_ingest(path)` extracts the text of a `.txt` /
`.md` / `.pdf` / `.html` file, chunks it, and indexes it;
`document_search(query)` retrieves chunks by pure cosine similarity.
It is deliberately kept apart from conversational memory — nothing ingested
here feeds the cortex, the graph, or the dream pass, and `memory_search`
surfaces document chunks alongside memories without mixing the stores.

**Division of labor: agents extract meaning; the reference bank preserves
the verbatim source.** These are complementary, not competing paths:

- **Understanding is the agent's job.** A capable agent reading a PDF
  through its own harness (vision, layout, tables, OCR of scanned pages,
  judgment about what matters) will always beat the server's text-layer
  extraction. The intended pattern is that the *agent* reads the document
  and writes the load-bearing conclusions into memory — `memory_store` for
  context, `memory_fact_set` for canonical values, `memory_world_set` for
  cited external facts. That distillate is what future retrieval reasons
  over.
- **Verbatim recall is the reference bank's job.** Distillation is lossy at
  ingest time: the agent keeps what looked relevant *that day*, and
  everything else is gone. Ingesting the raw file as well means
  `document_search` can still answer questions nobody anticipated — a
  one-time local embedding pass instead of re-reading the document through
  an agent's context window on every question.

For an important document, do both: distil the key facts into memory *and*
`document_ingest` the file itself.

> **Scope of the server-side parser.** Extraction is intentionally minimal:
> the embedded text layer only, via `pypdf` (always available) or
> `pypdfium2` (the optional `pdf` extra — better quality, still
> copyleft-free). There is **no OCR** — a scanned, image-only PDF ingests
> as empty text; have the agent read it and store the distillate instead.
> Paths resolve on the **server's** filesystem: with the Docker daemon,
> `document_ingest` needs a path visible inside the container (a mounted
> volume), not a host path.

## Sense of time + multi-writer attribution (schema v11)

Every canonical write (cortex, world, lessons) carries a **temporal /
provenance stamp** so the agent has a real sense of *when* a fact held and
*who* set it — and so concurrent writers can't silently clobber each other:

- **`tx_time`** — when this version was *written* (wall-clock display).
- **`valid_time`** — when the fact became *true* (event time). A lesson
  synthesised from an outcome signal inherits the signal's observation
  time, not the dream's write time, so the two clocks stay honest
  (bitemporal).
- **`(hlc_phys, hlc_logical)`** — a **Hybrid Logical Clock** that is the
  *ordering authority* for supersession. Wall clocks can jump backwards
  (NTP steps, clock skew across sessions); the HLC is monotonic, so "newer
  wins" is jitter-proof — a later write always supersedes, even if its wall
  time reads earlier. Wall time is display-only.
- **`writer_id` / `session_id`** — which writer/session made the change.
  The daemon reads an `X-PL-Writer` header per request (the stdio shim
  forwards `PSEUDOLIFE_WRITER_ID`) and resolves the session id through the
  five-tier [session-identity](configuration.md#session-identity) contract
  (the shim's `X-PL-Session` header preferred), so a Codex session, a second
  Claude session, and the dream are all distinguishable.

Reads surface this: a serialised fact includes the stamp plus a human `age`
("3 days ago"), and **`memory_history(entity, attribute)`** returns the
full version timeline — current + superseded, oldest→newest, each
attributed. The supersession log records the writer/session too. Since
2026-09-04 the *stamp itself* — `tx_time`, `valid_time`, `writer_id`,
`session_id` — is served by `memory_fact_get(..., verbose=True)`; the
default record carries `asserted_at`/`age`, `last_confirmed` and the
freshness flags, which is what a caller acts on. The REST/Console reads
(`service.*`) are unchanged.

> **Writer topology.** The live path is a single daemon with a coarse lock
> (`write_mode=snapshot`) — correct by construction. The schema also lays a
> dormant `write_mode=occ` seam (a `version` column + per-row
> compare-and-swap) for a future multi-process writer; selecting it raises
> `NotImplementedError` until that Phase-2 path is built.
>
> **Collision fix (v0.4) + AGE removal.** The DB role is `pseudolife`; the
> old Apache AGE graph was also named `pseudolife`, which made AGE create a
> `pseudolife` schema that shadowed the real `public` bank. AGE has since
> been removed entirely — edges live in the relational `edges` table (the
> source of truth), so the collision can no longer recur.
> `ops/migrate_drop_age.py` drops the AGE graph + extension from an
> existing bank (back up first), and every connection still pins
> `search_path` to `public` (asserted on startup).
> `ops/retire_by_writer.py` supersedes a rogue writer's rows in one shot.

---

<!-- source: docs/guide/retrieval.md -->

# Retrieval — search, recall, and the knowledge graph

How `memory_search` ranks, the optional reranker and BM25 channels,
abstention, ranking-trace debugging, multi-hop `memory_recall`, and the
knowledge graph it walks. Part of the [user guide](../../README.md#documentation).

## Asymmetric query and document encoding

Since schema v25, the default embedding backbone (`Qwen/Qwen3-Embedding-0.6B`)
is instruction-asymmetric: `memory_search` and every other retrieval probe
(cortex/world/lesson search, recall seed queries) encode the query text with
an instruction prefix (`EmbeddingConfig.query_prefix`) that stored documents
never carry — entries, fact/world/lesson claim text, and slot/entity-name
embeddings are all encoded bare, and every stored-to-stored comparison
(dedup, curation, alias candidates, the surprise gate) stays bare on BOTH
ends. Two distinct threshold effects follow, and they should not be
conflated. The `min_score` 0.2/0.25 recall floors gate a prefixed-query-to-document
cosine rather than a doc-to-doc one — their *semantics* shifted, not just
their scale, and they read somewhat more conservative at the shipped
defaults. By contrast, `alias_candidate_min_cosine`,
`curation_min_similarity` and the surprise gate remain doc-to-doc
comparisons whose cosine *distributions* merely shift with the new model.
All are left unrecalibrated pending live data. See
[Configuration](configuration.md#built-in-defaults-tuned-for-claudes-use-case)
for the config fields and the [schema version history](configuration.md#schema-version-history)
for the v25 cutover itself.

Explicit corrections do not use a similarity threshold: `memory_supersede`
and `memory_consolidate` select entry IDs, or unique exact text for legacy
calls. The earlier embedding fallback has been removed so a failed lookup
cannot redirect a correction to a different note.

## Cross-encoder reranking

```
memory_search("which python testing framework do we use", rerank=True)
```

After the bi-encoder retrieval builds the top-N candidate set, run
`cross-encoder/ms-marco-MiniLM-L-6-v2` over each `(query, candidate)`
pair and fuse the resulting relevance score with the bi-encoder score:

```
final = fusion_weight * sigmoid(ce_score) + (1 - fusion_weight) * original
```

The default `fusion_weight = 0.7` leans on the cross-encoder but
preserves enough of the bi-encoder signal that recency / source /
supersession multipliers still nudge order on near-ties. Off by
default — enable per call with `rerank=True`, or globally via:

```yaml
memory:
  reranker:
    enabled: true
    model_name: cross-encoder/ms-marco-MiniLM-L-6-v2
    top_n: 20            # maximum combined pool size for reranking
    fusion_weight: 0.7   # 1.0 = pure CE, 0.0 = pure bi-encoder
```

Reranking scores the whole combined memory/reference pool or skips it.
If the pool exceeds `top_n`, search preserves its original scores and order
and reports `candidate_budget_exceeded` in the reranker parameters and trace.
This bounds model work without treating fused scores and unscored originals
as comparable. A widened candidate pool or large `top_k` can trigger this
fallback; increase `top_n` deliberately if that additional work is wanted.
Reserved reference slots remain available in either case. The parameters
also record `candidate_count`, `scored_candidates`, and the
`complete_pool_or_skip` scoring policy.

First call lazy-loads the ~80 MB model from the HuggingFace Hub; later
calls cost ~10 ms per reranked candidate on CPU (≈ 200 ms wall-clock
added to a top-20 search). A `reranker.skip_margin` skips the pass when
the top-2 bi-encoder gap is decisive. If the model fails to load, the
reranker disables itself silently and retrieval falls back to bi-encoder
ranking — search never breaks because of an optional component.

`memory_search(..., rerank=True, explain=True)` surfaces the per-candidate
`original_score`, `ce_score`, and `fused_score` under `trace.reranker`
so you can see exactly how the cross-encoder reshuffled the
bi-encoder ordering.

## BM25 hybrid retrieval

**On by default since 2026-07-25** — pass `bm25=False` to opt out of a
single call. It shipped disabled for a year, which meant every published
retrieval number measured the dense pool alone.

```
memory_search("process_chunk_v2")
memory_search("ship blocker for v9.42.0")
```

Dense embeddings (Qwen3-Embedding-0.6B by default) are great for *semantic*
similarity but can underweight tokens with no real semantic neighbours — function
names, version strings, error codes, hex hashes. BM25 is the classic
sparse-lexical scorer (Okapi BM25 with Lucene-style IDF) that weights
tokens by inverse document frequency, so rare-but-exact tokens count
for a lot. The BM25 pool runs in parallel with dense retrieval and
fuses with weighted score-sum:

```
final = dense_score + weight * normalized_bm25_score
```

Entries already in the dense pool get *boosted*; entries only BM25
found enter at `weight * normalized_bm25` (intentionally below a
typical dense hit so semantic recall still drives ordering). The
tokenizer keeps underscored identifiers and dotted version strings
whole, lowercases everything, and filters a tiny stop list.

Since 2026-07-30 the same channel is also *available* for **cortex fact
retrieval** (`cortex_search`), but ships **opt-in**
(`memory.bm25.cortex_enabled = false`, or per-call `bm25=True`) — unlike
the turn pool. The pre-registered A/B that decided this
(`evals/results/bm25-ab-confirmation.json`, `_s` haystacks, reproducible
server, rag arm as byte-identical control): the fusion changed 56/78
served fact contexts yet moved **nothing end to end** — cortex accuracy
0.179 and cascade 0.423 in both arms — and cost ~1 question on the
oracle regression-gate slice. Lexical gaps in fact retrieval are real
but the abstentions trace to fact *coverage*, not ranking, so the
default stays honest to the measurement. When enabled, the fusion is
identical to the turn pool's, run over each fact record's composed
`entity — attribute: value` text — per member record for set-valued
slots, so an exact member name can rank on its own; grouping into one
set entry happens after fusion — with one deliberate difference:
lexical fact hits gate on the normalised `bm25.min_score`, *not* the
caller's dense `min_score` floor, so an exact-name query can rescue a
fact the embedder under-scores (useful on identifier-heavy corpora —
agent-trajectory content is where this channel earned its keep in the
LME-V2 smoke).
Configure globally with:

```yaml
memory:
  bm25:
    enabled: true
    k1: 1.5       # term-frequency saturation
    b: 0.75       # length-normalisation
    weight: 0.3   # contribution to the fused score
    top_n: 20     # how many BM25 hits to consider
    min_score: 0.1  # floor on normalised BM25 (drops noise)
```

No new dependencies — pure stdlib. Cost is one O(N tokens) index
rebuild per query, ≈ 20-50ms on a 40K-entry bank.

`memory_search(..., bm25=True, explain=True)` records per-hit `raw_bm25`,
`normalized`, and any BM25-only injections under `trace.bm25`.

## Abstention & confidence floors

`low_confidence: true` means **nothing matched**: search served no entry
and no cortex fact cleared `memory.cortex.guard_min_score`.
It is not an answerability signal. Over 1,072 real agent searches
(2026-09-06 to 2026-09-25) it fired on none of them: all but one served
entries, and that one served cortex facts. A question whose answer is not
in the bank still returns close-scoring hits. The 2026-09-23
review's four in-domain absent-answer probes topped out at dense cosine
0.43-0.64, inside the range of real hits (median top cosine 0.61 across
those agent searches). Judge the hits; do not read a served result as a
found answer.

`memory.search_confidence_floor` (default `0.0`, off) adds a score test:
above zero, `memory_search` also returns `low_confidence: true` when the
top served score (the fused score, not the raw cosine) is below the floor
**and** no cortex fact clears the guard. **No value is calibrated for the
current embedder.** Until 2026-09-25 this page recommended
`guard_min_score = 0.65` + `search_confidence_floor = 0.70`, a pair
measured on the MiniLM embedder (2026-06-19). On the agent searches above
that pair would flag 26% of searches, including 20% of the searches whose
hits the agent then reported using, and it caught 3 of the 4 absent-answer
probes (`evals/serving_policy_replay.py`, artifact
`evals/results/serving-policy-replay-20260925-r3.json`). Leave both knobs at
their defaults until a real answerability signal exists.

`memory.cortex.guard_min_score` (default `0.2`) decides which cortex facts
are served at all (a LongMemEval retrieval replay showed the old `0.3`
floor served *zero* facts for 60% of questions, because terse fact
embeddings rarely score 0.3 against a natural-language query even when
they are the answer, while going below 0.2 measurably hurt by diluting the
context with weak facts). Any served fact suppresses `low_confidence`.

The dense relevance floor, `memory.search.min_score` (default `0.25`), is a
different knob: a dense candidate below it never enters the pool. On the
same agent searches the weakest served dense hit was at cosine 0.39 at
the 1st percentile, and below 0.30 in one search of 1,064, so today the
floor rarely binds on a real search. Raising it is not a way to abstain.

## Superseded entries

An explicitly superseded entry, or one carrying a mark from an earlier
version, is **still retrieved**, with its score multiplied by `0.55`.
This favors current entries while keeping history accessible for answers
such as "you used to have X, then you changed it to Y". Ordinary
`memory_store` preserves earlier source notes when a potential conflict
is detected; that detection alone does not mark or downrank them as
superseded. Whole-note replacement remains available through
`memory_supersede` and `memory_consolidate`.

```yaml
memory:
  hide_superseded: true   # restore the pre-v0.7.3 hard filter
```

The filter is opt-in for a reason: hard-dropping superseded entries once
made a category query miss the only entry that named the category (the
entry had been superseded on an unrelated detail), and superseded rows
carry knowledge-update recall on LongMemEval. Use it for debugging and
audit, not as a deployment default. When on, it applies to both pools —
including BM25-only injections, which otherwise bypass the dense pool's
filters. `explain=True` reports dropped entries with
`drop_reason: "superseded"`.

## Debugging a retrieval miss

```
memory_search("why didn't X come back?", sources=["pseudolife"], explain=True)
```

Returns the normal search result plus a `trace` dict: every tier's
candidates with raw_score, recency boost, source/supersession multipliers,
and the `drop_reason` (or `kept=True`) for each. The `final_topk` block
shows exactly which entries reached the result set and what score they
carried.

Also useful for state-probe queries where recency bias is unwelcome:

```
memory_search("current Python version", disable_recency_boost=True)
```

Beyond one call, every `memory_search` also appends a row to the retrieval
event log (query, the ranked served list, the ranking components and the
knobs in force) and bumps a per-slot read counter, which `memory_stats`'
`read_audit` section summarises — see
[Configuration](configuration.md#built-in-defaults-tuned-for-claudes-use-case)
for both kill switches.

## Knowledge graph (ontology-lite)

The cortex's canonical facts are joined to a typed entity graph
(Postgres mode only). Edges use a **closed relation vocabulary** —
builtins `depends-on`*, `part-of`*, `runs-on`↔`hosts`, `uses`,
`configures`, `stores-data-in`, `related-to` (* = transitive) — so a
weak model can't fragment the graph with `depends_on`/`dependsOn`
variants: common forms normalize automatically, true unknowns are
rejected *with suggestions*. Soft type hints warn but never reject.
Transitive closure and inverse mirroring are computed **on read** by
NetworkX inside `memory_graph`; derived edges arrive marked
`derived: true` with rule provenance, so multi-hop conclusions read as
plain facts — the server reasons, the model reads.

The graph store is Postgres `entities` hub as source of truth, with a
NetworkX derived read-model built on demand — behind a swappable
`GraphStore` interface. There is no AGE/Cypher dependency; `memory_graph`
serves multi-hop queries (neighborhood + derived/inverse edges + shortest
path).

A merge folds the absorbed node's canonical into the survivor's aliases
without rewriting the cortex records written under it. Since 2026-09-02
both directions resolve: `memory_graph`, `memory_recall` and the dossier
attach an alias-keyed fact to the surviving node, and `memory_fact_get` /
`memory_history`'s chain view reach a record under the node's canonical or
any of its aliases. An alias that is also another entity's canonical is
skipped — that record belongs to the other entity. Slot-mode
`memory_history(entity, attribute)` is the one surface that still does no
alias resolution.

## memory_recall (multi-hop retrieval)

`memory_recall(query, hops=3, top_k=5)` answers **relational questions**
by iteratively following the knowledge graph — things `memory_search`
can't do with a single flat similarity pass.

**`top_k` bounds the seed search only, not the result.** It caps how many
initial hits name the entities the graph walk starts from; graph expansion
then fans out from those seeds with no bound of its own. The response is
kept bounded separately — see Return shape below.

**When to use it vs `memory_search`:**

- Use `memory_recall` for chain-of-links questions: "what does X ultimately
  run on?", "where does Y's data end up?", "how does A reach C?".
- Use `memory_search` for direct lookups: "what is X's port?", "what did I
  decide about Y?" — those are flat similarity queries and `memory_search`
  is faster and simpler.

**How it works.** `memory_recall` searches for a seed entity in the query,
then walks its graph neighbourhood one hop per iteration (up to `hops`,
capped at 5), accumulating bridging entities, facts, edges, and paths. It
never creates or modifies a memory, fact or edge — the only writes on the
path are telemetry: its seed searches append to the retrieval event log
(`memory.retrieval_log.enabled`) like any other `memory_search`. The facts
it attaches to a neighbourhood are deliberately *not* counted as slot
reads: they are context, not a direct answer.

### Constraint pinning (schema v35)

TypeRetrieve (arXiv 2608.22752):
a fact whose `distortion_tolerance` is `constraint` is served *ahead of*
the cosine ranking, marked `pinned: true`, when it is **in scope** — and
scope is defined cheaply and precisely, with no second embedding pass:
in `memory_search`'s cortex block, the query *names the fact's entity*
(both sides go through the cortex's slot normalisation, so `payments db`
matches `payments-db`, and the entity must occur as a word-bounded run
with no letter, digit or combining mark touching it, so `db` does not
match `payments-database` while `bench server?`, `bench server,` and
`bench server's` all name `bench server`; an apostrophe inside a word
binds it, so `don't` does not name `Don`; a raw-string test — it
does not resolve graph aliases, so a constraint written under an alias
later folded into another name is pinned by `memory_recall` but not by
the cortex block, a known open follow-up now that
`graph.alias_canonical_map` exists); in `memory_recall`, the
fact's entity is a **seed** of the walk (hop 0 — the entities the query
itself resolved to; hop-discovered entities are context, not scope, and
keep record order). Pinning is exemption from ranking, not from
relevance: a pin must clear the caller's `min_score` floor (the cortex
block's `guard_min_score`), pins take at most half of `top_k` so the
ranked answer always keeps the rest, and among pins the best cosine wins
the slots. A pin displaces the weakest ranked fact rather than growing
the payload, and
a pinned fact that never made the ranked list is served in the identical
shape with its true cosine as `score`, so a reader can see it was pinned,
not ranked. In recall the pin also guarantees the rule survives the
per-entity fact cap below. An unlabelled bank is served byte-identically;
`memory.cortex.pin_constraints = false` restores plain ranking. Under
`stale_policy = demote` a stale (`slow` / `volatile`) constraint still
sinks below the fresh ranked facts — staleness is a trust decision and
outranks the pin. The labels themselves are described in
[memory-model](memory-model.md#who-said-it-and-how-exactly-must-it-survive-schema-v35).

**What the scope test means for rules.** In `memory_search` the pin's
scope is *entity naming*, and a working session describes the moment a
rule matters by the task, not by the rule's name. "About to start the
bench server on the 4090" does not name `GPU pre-flight rule`, so that
constraint is not pinned and is ranked only if cosine happens to favour
it; "GPU pre-flight rule before a bench run" names it and pins it, floor
and cap permitting (probed on the live bank, 2026-09-27, while checking a
client's local memory files against it — the same held for a subagent
model rule and a main-checkout rule). `memory_recall` scopes by seed
instead: the mechanical driver seeds the vocabulary entities the query
names, and falls back to entities mentioned in the seed hits only when
the query names none, so a task-phrased recall can pin a rule the query
never names — but once the query names any known entity, that fallback
does not run. Two consequences. When you store a rule, name its entity
the way the task would say it (`bench server`, not `GPU pre-flight
rule`). The bounded match ends at whitespace, punctuation or a
possessive `'s`, so "should I start the bench server?" and "the bench
server's config" name it as well; in `memory_recall`, whose seeds come
from a raw-text match over entity names, a `.` straight after the name
does not end it. And a rule that must hold *however* the task is
phrased — a safety rule, a "never do X" — belongs in the agent's
standing-instruction surface too (the CLAUDE.md / AGENTS.md block, or
the client's own always-loaded memory), with the bank holding its why,
its history and its corrections: an always-loaded line fires without a
query; a bank entry fires only when the query reaches it.

**Return shape:** `seeds`, `entities` (each with current canonical facts),
`edges` (with a `derived` flag for inferred transitive/inverse links),
`paths`, supporting `texts`, and `iterations`. A served fact that stands on
a memory corrected since the fact was last confirmed carries `re_verify:
true` plus `re_verify_reason` — see below.

**Re-verify: a flag, not a cascade.** The `re_verify` marker above appears
on `memory_search`'s cortex block, `memory_fact_get`, and `memory_recall`
(the default `verbose=False` projection carries it too). PostgreSQL preserves
source correction events independently of evictable traces, so later removal
of a corrected source does not clear the warning. Re-confirming the fact does;
ordinary deletion of an uncorrected source creates no warning. Full
contract: [memory model](memory-model.md#how-current-is-this-fact).

**Output caps (issue #186).** A plain 3-hop query on a hub entity can
return dozens of entities/edges and every matched entry's full text —
issue #186's live audit (2026-08-21, real daemon) measured one such query
at 93.7 KB, enough that the calling client refused it. `entities` /
`edges` / `texts` are each capped (10 / 15 / 6 by default), and each
entity's `facts` list is separately capped (5). These are NOT flat prefix
slices — `entities`/`edges` reserve a minimum quota per graph hop so a
hub seed's own crowded 1-hop ring can't silently push the deeper,
harder-to-reach hops (the actual reason to call `memory_recall` over
`memory_search`) out of the response; `edges` also prefers connections
between two entities that both survived the entity cap; `texts` reserves
budget for hop-discovered support so it isn't purely a copy of the flat
seed search. With `verbose=False` (the default), `texts` are also
truncated to a preview length; `verbose=True` returns full text (though
the same entity/edge/text counts and per-entity fact cap still apply).
A reproducible in-tree probe (`evals/recall_cap_probe.py`, no DB/daemon
needed) exercises this same capping path on a synthetic 41-entity/40-edge
fixture graph and recorded a 24.5 KB → 3.8 KB (84.4%) reduction with
deep-hop entities still present in the result
(`evals/results/recall-cap-186-payload-probe.json`) — a different, smaller
graph than the live audit's, so the two byte counts aren't comparable
to each other, only each to its own before/after.

**Search fan-out caps (2026-09-04).** The output caps above bound what
comes *back*; these bound what the walk *spends*. Each hop re-queried every
newly discovered entity by name, so on a star-shaped graph one hub's ring
set the price of the whole call — measured on a restored copy of the live
bank at a mean of 89.15 searches and 25.25 s per call (max 205 and
57.67 s), enough that two live calls timed out at the MCP layer that
morning. Three knobs bound it, all in the Console's Recall group:
`memory.recall.max_searches_per_hop` (default 6) re-queries only the top N
newly discovered entities per hop — ranked by mentions in the seed hits,
then by lowest degree — while still returning the rest as entities with
their facts; `max_total_searches` (default 31) and `time_budget_seconds`
(default 20.0) are hard ceilings over the whole call including the seed
search. 31 is deliberately a backstop, not a working limit: `hops` is
clamped to 1..5, so the most the per-hop cap can spend is
1 + 6 x 5 = 31 and no request the tool accepts is cut by the ceiling —
only a raised `max_searches_per_hop` reaches it. Hitting either ceiling
stops the walk and adds `truncated: true` and `searches_issued: N` to the
response instead of raising, and those two fields are absent when neither
bound, so a walk that stayed under every cap has an unchanged response.
Read their absence narrowly: it means no ceiling tripped, NOT that nothing
was dropped. `max_searches_per_hop` is the cap that binds in ordinary use
and it deliberately sets no flag, because it changes only which re-queries
run, never the entities and edges the walk returns. `truncated` claims only
what it knows: some re-queries, and possibly deeper hops, were skipped, so
supporting texts and deeper entities may be missing — a ceiling that trips
inside the last permitted hop's re-queries leaves that hop's entities and
edges complete and cuts only `texts`. Graph expansion is deliberately
untouched (the hub gate and
`max_entities` already bound it): on the paired 20-question run
(`evals/recall_fanout_bench.py`,
`evals/results/recall-fanout-cap-20260904.json`) the caps took the mean
call to 12.40 searches and 4.166 s with the entity, edge and iteration
counts identical on every question and no expected target lost. A fourth
knob, `skip_part_of_expansion`, is eval-only and default-off: it drops the
re-query for entities reached only through `part-of` edges.

**`low_confidence: true`** means no seed entity matched the query — the
graph had no starting point. In that case fall back to `memory_search`.

**Driver config.** By default `memory_recall` uses the **mechanical** seed
driver (token-intersection heuristic — no LLM call, deterministic, fast).
Set `PSEUDOLIFE_RECALL_DRIVER=llm` to use the dream endpoint for seed
resolution (better recall on ambiguous entity names; requires the dream
extractor to be configured).

---

<!-- source: docs/guide/dreaming.md -->

# Dreaming — consolidating memories into facts

The dream pass, its extractor tiers (regex floor / agent-driven / headless
auto-sweep), the bundled CPU sidecar, upgrading to a bigger model, the
Sonnet-primary fallback setup, cadence, deep dream, and the deliberate
consolidation workflow. Part of the [user guide](../../README.md#documentation).

A **dream** distils the recent associative stream (MIRAS) into canonical
cortex facts: pull unconsolidated memories → extract
`(entity, attribute, value)` claims (a claim may also carry
`op: "add"|"remove"` to target a [set-valued
slot](memory-model.md#set-valued-slots) — solicited by the shipped prompt
since 2026-08-01, paired with a counts-are-never-members rule; see the
[memory model](memory-model.md#dream-extraction) for the measurement
story) → `memory_fact_set` → acknowledge the exact input entries.
Acknowledgement survives restart and does not depend on timestamp order:
a new entry remains pending even when it shares an older entry's timestamp
or arrives with a backdated timestamp. Returning to an old session adds
new pending entries; there is no "session finished" event to detect.

Claim application remains **at least once**. If claim writes succeed but
acknowledgement fails, a retry can apply those claims again. The numeric
**cursor** is monotonic display metadata, not the boundary that selects
pending entries. Relations and lesson synthesis run after the input batch
is acknowledged and are separate from this acknowledgement contract.

For manual extraction, retain the opaque `commit_token` returned by
`memory_dream(action="pull")`. After writing the extracted facts, call
`memory_dream(action="commit", commit_token=<that token>)`. It acknowledges
only that pull's entries. Repeating a successful commit is idempotent;
a token from another bank is rejected. A numeric
`cursor` cannot safely identify a batch and is no longer accepted for a
commit. Pull again to obtain a token. An empty pull has no token to commit.

An entry deleted between the pull and the commit does not fail the batch:
the surviving entries are acknowledged and the commit reports `missing: N`
for the ones that are gone, since a deleted entry can never be pulled
again. A pull likewise never stalls on an entry that failed to persist —
it re-persists what it can, excludes what it cannot, and reports
`skipped_unpersisted: N`; those entries stay pending for the next pass.

PostgreSQL schema v38 classifies old entries once using the previous cursor
and the configured source eligibility. Entries excluded by that policy stay
pending so a later policy change can include them. File mode persists entry
identities and acknowledgement in the same format-v7 checkpoint. This
migration preserves the old boundary; it does not recover entries already
skipped before migration. Logical imports create a new bank token identity;
old source-bank tokens cannot commit against the imported bank.
If a file import fails validation before writing any imported content,
repairing those source files allows a retry, including after the daemon
has accepted new entries. Once any import writes begin, retries require
the original source files so two different imports cannot be mixed.

Extraction is pluggable; pick the tier that fits — the stack ships with
tier 2 preconfigured (the extractor sidecar), and **no self-hosted model is
required** if you'd rather not run one:

| Tier | How it runs | Needs | Quality |
|------|-------------|-------|---------|
| **0 — none** | no extractor configured — the dream still runs, prunes and acknowledges input batches, but writes no canonical facts | nothing | none (single-writer cortex: `memory_fact_set` is your only writer) |
| **1 — agent-driven** | the **agent itself** is the gateway: the `/dream` judgment session (its manual-extraction branch fires only when no endpoint is configured) | the agent you already run | highest |
| **2 — shipped default** | daemon auto-sweep calls an OpenAI-compatible endpoint — the bundled sidecar out of the box, or any endpoint you point it at | nothing (sidecar) / one base-URL + key + model | high; free if local |

**Tier 1 — `/dream` (agent-driven).** Copy `examples/commands/dream.md` to
`.claude/commands/dream.md` in any project, then run `/dream`. The command
is a **judgment session**: the agent reads `memory_dream(action="status")`
— including the `deep_dream: {recommended, ...}` nudge — runs the
mechanical graph pass if the tick hasn't, and works the review queues
(link candidates, merge proposals, junk, store curation). Its manual
extraction branch (`pull` → extract → `memory_fact_set` → `commit`) fires
ONLY when no extractor endpoint is configured or reachable — on such
deployments the agent is the sole cortex writer. To run it on a cadence
instead of by hand, point a scheduled agent/cron job at the same prompt.

**Tier 0 — no extractor.** With no endpoint configured the cortex has no
automatic writer: `memory_dream(action="run")` still drains the backlog,
prunes outcome signals and acknowledges its input batch, but extracts no facts, and
the daemon logs a startup warning. Populate the cortex with deliberate
`memory_fact_set` calls, or configure tier 1 or 2.

## Tier 2 — headless auto-sweep

Point the daemon at any OpenAI-compatible endpoint and it dreams on its
own — no agent, no manual trigger:

```powershell
$env:PSEUDOLIFE_DREAM_BASE_URL = "http://localhost:11434/v1"   # e.g. Ollama
$env:PSEUDOLIFE_DREAM_MODEL    = "qwen2.5:7b"
# $env:PSEUDOLIFE_DREAM_API_KEY = "sk-..."           # hosted endpoints (Haiku, OpenRouter, ...)
# $env:PSEUDOLIFE_DREAM_TIMEOUT_SECONDS = "240"      # raise for a slow CPU / big model (default 240)
# $env:PSEUDOLIFE_DREAM_MAX_TOKENS      = "2048"     # extractor output budget (default 2048)
```

The daemon runs a background sweep every
`memory.dream.sweep_interval_seconds`; each tick it checks the same
backlog+quiescence trigger and, if it fires, runs a dream with the
configured extractor. Under the single-writer cortex a *successful* pass
that finds no canonical facts writes no facts and acknowledges the input
batch. A **failed** call (timeout, network, malformed output) instead leaves
those entries **pending**, so the next sweep retries them — up to three
times. A batch that keeps failing is re-run entry by entry; individual
offenders are quarantined and acknowledged under the existing retry policy,
so one unparseable memory cannot stall consolidation indefinitely.
There is no regex fallback either way. The extractor timeout defaults to
**240s** in code; the Docker stack ships **480s**
(`PSEUDOLIFE_DREAM_TIMEOUT_SECONDS` in the compose file) because the
default E4B sidecar generates at ~12–15 tok/s on CPU, so a full
`PSEUDOLIFE_DREAM_MAX_TOKENS` generation runs ~150–170s — raise it further
for slower hardware. The same env vars also upgrade
`memory_dream(action="run")`. A local model keeps all text on-box; a hosted
endpoint does not.

Every extractor request the daemon builds carries `cache_prompt: false`
(`memory.dream.extractor_cache_prompt`, default `false`): llama-server's
prompt cache measurably changes extraction output once populated, and the
pin's cost — ~7s of shared-prefix prefill per call on the shipped sidecar
(`evals/results/sidecar-cache-latency-sidecar-cache-0809.json`) — is noise
for a background sweep. Set the knob to `null` to restore the server
default if your deployment prefers the latency; non-llama.cpp endpoints
ignore the field.

## What the extractor captures

The tier-2 prompt (`_SYSTEM_PROMPT` in `pseudolife_memory/memory/dream.py`,
shared by the bundled sidecar and any endpoint you point the daemon at)
asks for four things and deliberately skips the rest — narrative,
opinions, meta-chat about the conversation, and values a later note already
superseded:

- **Durable current-state facts**, one slot per real fact.
- **Updates, landed on the slot the fact already had.** When several notes
  state or update the same fact, only the *current* value is emitted, under
  the same entity and attribute — so the cortex supersedes rather than
  accumulating near-duplicate slots.
- **The source's epistemic stance, kept.** A hedged or negated claim
  ("probably X", "no longer Y") lands with a `stance` marker on the fact
  (schema v29; the live v12-based prompt carries the v10 update-anchored
  stance rule) instead of
  hardening into a flat assertion — see
  [memory-model — how current is this fact?](memory-model.md#how-current-is-this-fact).
- **What a document prescribes.** When a note quotes or summarizes a spec,
  policy, protocol, runbook, or guide, its prescription is itself a durable
  fact, stored under the *document's* subject — and kept separate from what
  was actually done. Paste your deploy runbook, then mention a deploy that
  skipped a step, and you get two facts (the documented rule, and the
  incident), not one blurred into the other.
- **What the ASSISTANT said, labelled as the assistant's** (since
  2026-09-05). What the assistant asserted, described or recommended is
  extractable on the same terms as what you said — keyed to the *thing
  described*, never to "the assistant". A claim carries a `speaker` field
  **where the note makes the speaker knowable**: the extractor reads it off
  an explicit role marker (a leading `user:` / `assistant:`) when the note
  carries one, infers `assistant` only where the content is unmistakably
  the assistant's, and omits the field when unsure. Nothing in the daemon
  writes a role prefix — the dream sends your notes as they were stored,
  and the `[date] role: content` rendering is an eval-harness convention —
  so on a bank whose notes carry no marker many claims are simply
  unlabelled, which writes exactly as it did before 2026-09-05. An
  assistant-stated fact is written at the floor `assistant` provenance
  tier: it fills an empty slot, but parks as a contender against a value
  of any other origin rather than overwriting it
  (`memory.dream.assistant_claims`, default `contender`). Before this, a
  session whose answer lived entirely in an assistant turn consolidated
  with *zero* claims — see
  [Benchmarks](benchmarks.md#longmemeval-v2--agent-trajectories-and-procedures)
  and the "Assistant-stated facts" section of `evals/README.md`.

That document class is deliberate, and it is the reason the prompt names its
content classes rather than merely forbidding noise: an extraction prompt
that enumerates what to extract makes an obedient model **silently discard
whatever it doesn't name** — no error, no partial result, just a class of
knowledge that never reaches the cortex. It cost a whole benchmark category
to find (see [Benchmarks](benchmarks.md#longmemeval-v2--agent-trajectories-and-procedures)),
and it is worth remembering before narrowing this prompt further.

The Sonnet override prompt (`evals/prompts/sonnet_extractor_v5.md`, used
when you run the shim below) carries all four. A shim launched with
`--system-prompt-file` **replaces** the shipped prompt with that file —
keeping only the appended vocab/known-facts hints — so a prompt change made
in `dream.py` alone never reaches an install whose primary extractor is the
shim. v4 closed that gap on 2026-09-05: it is the v2 body plus the same
assistant-facts blocks the shipped prompt carries, composed by
`evals/gen_shim_prompt.py` from `dream.py`'s own constants so the two paths
cannot drift in what they ask for. Gated on the ladder `opus-5` rung, v2 vs
v4, two replicates per arm, and **re-gated** after the speaker rule was
rewritten the same day — v4 is generated from that constant, so the file
changed and the first verdict
(`evals/results/ladder-shimprompt-paired-verdict-threshold.json`) is
superseded by
`evals/results/ladder-shimprompt-rule2-paired-verdict-threshold.json`
(`gate: PASS`, `no_regression_gate: PASS`, gold 1.0 and stale 0.0 on both
replicates). v5 (2026-09-07) re-cuts the v2 body's two worked examples on
invented names — the same re-cut the daemon's shipped prompt took with the
v12 base — so the shim path no longer names a benchmark answer; gated the
same way, v4 vs v5
(`evals/results/ladder-shimv5-paired-verdict-threshold.json`: `gate: PASS`,
`no_regression_gate: PASS`, gold 1.0 and stale 0.0 on all four runs). v2
and v4 stay in the tree as the gates' pre arms; `sonnet_extractor_v3.md` is
an unrelated, never-adopted 2026-08-02 lineage.

Existing installs pick v5 up when the shim autostart is re-installed
(`ops/install-shim-autostart.ps1`) or the shim is restarted with the new
file. Rebuilding the daemon image alone does **not** reach the shim path.
The Codex shim passes no prompt file at all, so it already runs the shipped
prompt.

**Literal-faithfulness gate.** After extraction, every claim's digit-bearing
tokens (dates exempt — format variance makes digit matching unsafe there)
are checked against the pull's source notes: a fabricated number or
identifier is dropped and counted under the default
`memory.dream.literal_gate = "enforce"` (since 2026-08-02), or merely
counted under `"log"`.
The corpus is the whole batch's note union by default — derived sums and
cross-note values are measured false-drop classes under per-note gating.
The matcher normalizes the re-formattings extractors legitimately produce:
spelled numbers back digits ("three week" backs "3-week"), hyphenated
ranges and unit compounds gate per digit part ("1-3" ↔ "1 to 3",
"66-acre" ↔ "66 acres"), `N+` minimums match their base number, and
`~`-marked approximations are exempt like dates — classes triaged from the
at-scale firing probe (`evals/results/gate-firing-verdict.json`, where 15
of 17 batch-scope flags were normalization gaps, not fabrications).
The post-matcher re-probe left the survivors dominated by genuinely
unbacked literals — derived aggregates and imported world knowledge — at
1.3–1.7% of gateable claims, which is what made enforcement the default
(`evals/results/gate-firing-normfix-verdict.json`;
`literal-fidelity-verdict.json` has the original opt-in decision).
A companion prompt rule mandating verbatim literals was built, measured,
and **held** — it significantly degraded the KU cascade (same verdict
artifact).

## The CPU extractor sidecar (batteries-included default)

The stack ships a llama.cpp sidecar with a model baked in (the bespoke
Gemma 4 E4B extractor fine-tune, ~5.3 GB — multi-task since the v3 bake:
one adapter serves both the claims pass and the chronicle events pass —
see "Upgrading the extractor"
below for the lighter E2B bake), and `ops/docker-compose.yml` starts it by
default and routes dream consolidation to it. It's internal-only (never
published to the host). Single-writer cortex relies on it: with no
extractor configured, the cortex is populated only by `memory_fact_set` and
the daemon logs a startup warning. Reasoning models work too — the
extractor disables their `<think>` trace so they return structured output
instead of an empty budget. The `evals/` extractor-ladder benchmark is how
the default was chosen (even the smallest bake, Gemma 4 E2B, beats
naive-RAG at ~40× fewer tokens/query); see
[`evals/README.md`](../../evals/README.md).

The sidecar **unloads its model when idle**: after 5 minutes without a
request (llama-server `--sleep-idle-seconds`, tunable via
`PSEUDOLIFE_EXTRACTOR_SLEEP_IDLE_SECONDS` in `ops/.env`, `-1` = always
resident) the server frees the ~7 GB of weights and drops to a few hundred
MB. This matters most on shim installs where the sidecar is only the
*fallback* dreamer and would otherwise hold that memory around the clock
against a rare failure path. Waking is transparent and needs no operator:
`/health` keeps answering while asleep, and the next dream call simply
blocks while the model reloads (seconds on an SSD) — comfortably inside
`PSEUDOLIFE_DREAM_TIMEOUT_SECONDS`, so an unattended sweep that falls back
mid-run waits instead of failing. The first fallback dream after a long
idle is a little slower; nothing else changes.

## Upgrading the extractor — bigger local models

If you have a GPU (or a beefier box on your LAN), any OpenAI-compatible
server can replace the sidecar — the ladder measured a Qwen3.6-27B on a
single RTX 4090 at the ladder ceiling (gold 1.0 / stale-leak 0.0) while
extracting ~5× faster than the CPU sidecar — a bar the shipped bakes now
also clear, so the ladder no longer separates them; the separation is in
the LongMemEval numbers below. The win is speed, not recall: in the
replicated LongMemEval-KU comparison
([`evals/README.md`](../../evals/README.md), 2026-07-18) the bundled
fine-tune outscores the generic 27B class end-to-end (hybrid 0.762 ± 0.027
vs the 27B ceiling's 0.710 ± 0.019 — a same-stack comparison on the
since-retired TurboQuant server; point estimates from separate runs, not a
paired test, and not comparable to the ceiling's re-based 0.731), so point
at a bigger *generic* model for faster
dreams, not better answers. Two ways to switch:

*From the Console (no restart):* the **Extractor** panel in the Cortex
Console's config view edits the endpoint, model, timeout, and token budget
live — flip its "Settings source" switch to `config` first (while it is
`env`, the default, the `PSEUDOLIFE_DREAM_*` variables below own the
settings and the panel's values are ignored). The API keys (primary and
fallback) stay env-only either way. The *model alone* needs no source
flip: the **Dreamer** card at the top of the same view writes a model-only
override (`memory.dream.extractor_model_override`) that wins over both
owners while the endpoint wiring keeps its owner.

*Via env:* for the Docker stack, set the override in `ops/.env` (the
compose file interpolates it into the daemon) and restart the daemon
(`docker compose -f ops/docker-compose.yml up -d --no-deps pseudolife-daemon`):

```dotenv
# ops/.env — point dream consolidation at a local model server.
# From inside the container the host machine is host.docker.internal, NOT
# localhost (works on Linux too via the extra_hosts entry shipped in
# ops/docker-compose.yml).
PSEUDOLIFE_DREAM_BASE_URL=http://host.docker.internal:1234/v1
PSEUDOLIFE_DREAM_MODEL=qwen3.6-27b
```

Per-runtime defaults (all serve the same `/v1/chat/completions` shape):

| Runtime | Typical base URL (from the container) | `PSEUDOLIFE_DREAM_MODEL` |
|---------|----------------------------------------|--------------------------|
| **LM Studio** | `http://host.docker.internal:1234/v1` | the model's API identifier shown in LM Studio's server tab |
| **Ollama** | `http://host.docker.internal:11434/v1` | the tag, e.g. `qwen2.5:14b` |
| **llama.cpp** (`llama-server`) | `http://host.docker.internal:8080/v1` | anything (single-model server ignores it) |
| **vLLM** | `http://host.docker.internal:8000/v1` | the `--served-model-name` |
| LAN box | `http://192.168.x.x:PORT/v1` | per the runtime above |

The unused sidecar can be stopped (`docker compose -f ops/docker-compose.yml
stop pseudolife-extractor`) or left running as a fallback to switch back to.
The default bake is the bespoke
[Pseudolife extractor fine-tune](https://huggingface.co/Pseudogiant-xr/pseudolife-extractor-gemma-4-e4b)
(Gemma 4 E4B QLoRA — the v3 bake is multi-task, claims + dated events;
the v2 claims-only GGUF stays published on the same repo for rollback);
constrained machines can bake the lighter **Gemma 4
E2B QAT** instead (also ladder-verified) — see the `MODEL_URL` build-arg in
`ops/Dockerfile.extractor`, or mount any GGUF over `/models/extractor.gguf`
via a machine-local `ops/docker-compose.override.yml` (gitignored; example
in the compose file). If you run the daemon *outside* Docker (embedded
stdio mode), the `$env:` variables above apply directly and `localhost`
URLs work as-is. A local or LAN model keeps all memory text on your
network; the same env triple pointed at a hosted endpoint does not.

## Claude primary with local fallback

With a Claude Max plan, the dream pass can use a Claude model as its primary
extractor and keep the bundled local sidecar as an automatic fallback. The
installer does all of this in one go —
`ops/install.sh --extractor sonnet-fallback` (or `sonnet-only` to skip the
sidecar entirely; `ops\install.ps1 -Extractor ...` on Windows). The manual
steps:

1. Register the CLI shim (`evals/claude_shim.py`) to start automatically —
   requires a logged-in `claude` CLI:
   - Windows: `ops\install-shim-autostart.ps1` (Task Scheduler, at logon,
     `127.0.0.1:8082`; needs an elevated PowerShell — open it fresh from
     the Start menu, never from a terminal inside Claude Desktop or another
     Store-packaged app, or that app's next update fails to launch until a
     reboot — see
     [anthropics/claude-code#61635](https://github.com/anthropics/claude-code/issues/61635);
     `-Model` picks the served default —
     `claude-opus-5` since the 2026-08-02 dreamer comparison; the one-shot
     installer prompts for this choice on Claude-shim installs). Re-running
     the installer replaces a shim already serving the port: it stops that
     process tree first, then waits (`-StartupTimeoutSec`, default 90 s)
     for the new task instance to bind and echoes its startup log lines —
     and fails, rather than reporting success, if no listener appears.
   The shim also honors a concrete `claude-*` model named per request, so
   the Console's **Dreamer** card switches the dreamer live — one click
   between `claude-opus-5` / `claude-sonnet-5` / `claude-haiku-4-5` /
   `claude-fable-5` (or any `claude-*` name typed in), no shim restart and
   no settings-source flip; alias names like the compose default
   `extractor` keep the launch model.
   - Linux: `ops/install-shim-autostart.sh` (systemd `--user` unit, same
     `--model` choice; binds the docker bridge IP so the daemon container
     can reach it — `host-gateway` routes container→host traffic to the
     bridge, where a loopback bind is invisible).
2. Set in `ops/.env` (both vars must flip together — pointing only one at
   the shim leaves dreams silently on the sidecar):
   `PSEUDOLIFE_DREAM_BASE_URL=http://host.docker.internal:8082/v1`,
   `PSEUDOLIFE_DREAM_MODEL=extractor`,
   `PSEUDOLIFE_DREAM_FALLBACK_BASE_URL=http://pseudolife-extractor:8081/v1`,
   `PSEUDOLIFE_DREAM_FALLBACK_MODEL=extractor`,
   `PSEUDOLIFE_DREAM_EXTRACTOR_MODE=auto` (or `primary`/`fallback` to force
   a side — also switchable live in the Console's Extractor panel).
3. Redeploy (`ops/update.ps1` / `ops/update.sh`), then **verify**:
   `memory_dream(action="status")` should show `fallback_url` populated
   and, with the shim up, `primary_healthy: true`; after the next dream,
   `last_dream_extractor.which` should read `primary` against the `:8082`
   URL. The daemon also logs a startup warning for the common
   half-configurations (unresolvable `host.docker.internal`, `auto` without
   a fallback, primary == fallback).

When the shim is unreachable or the CLI is logged out, dreams automatically
use the fallback; the Console's Observatory shows which extractor is
active. Leave `PSEUDOLIFE_DREAM_FALLBACK_BASE_URL` unset to keep the
existing single-extractor behavior.

**API keys are per endpoint.** `PSEUDOLIFE_DREAM_API_KEY` authenticates the
primary only and is never sent to the fallback. The fallback sends its own
key, `PSEUDOLIFE_DREAM_FALLBACK_API_KEY`, or none at all — right for the
bundled sidecar and both CLI shims, none of which checks one, so the pairs on
this page set neither. A fallback that needs the primary's credential, such
as a second model on the same hosted provider, needs the key set again under
the fallback name.

## OpenAI primary — the Codex CLI shim

The same pattern works on an OpenAI subscription: `evals/codex_shim.py` is
the ChatGPT-plan twin of the Claude shim. It wraps headless `codex exec`
(the signed-in Codex CLI's included usage — no API key) as an
OpenAI-compatible endpoint on `127.0.0.1:8086`, serving `gpt-5.6-terra` by
default. The one-shot installer wires the whole mode:

```bash
ops/install.sh --extractor codex-fallback     # or codex-only; Windows: ops\install.ps1 -Extractor codex-fallback
```

which prompts for the GPT-5.6 dreamer (Sol / Terra / Luna), registers the
shim to start automatically (`ops/install-codex-shim-autostart.ps1` — Task
Scheduler, elevated pwsh opened from the Start menu, same caveat as the
Claude shim above; `.sh` — systemd `--user`, docker-bridge bind),
and writes the env triple for you. The autostart raises the shim's
health-probe interval to 1800 s (`--health-ttl`) because every `/health`
refresh is a real CLI call — metered spend on a free ChatGPT tier; a
stale-ok window only costs one failed primary attempt before the dream
falls back. To run it by hand instead:

```bash
python evals/codex_shim.py    # --model gpt-5.6-sol / gpt-5.6-luna to change the default
```

then point the env triple at it exactly as in step 2 above, with
`PSEUDOLIFE_DREAM_BASE_URL=http://host.docker.internal:8086/v1` (and, on
Linux, the same docker-bridge bind note as the Claude shim — pass `--host`
accordingly). Either way the shim honours a concrete `gpt-*` or `codex-*`
name per request, so the Console's **Dreamer** card switches between
`gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna` live, exactly like the
Claude presets. On Windows the shim finds the official installer's
`codex.exe` on its own (the `%LOCALAPPDATA%\OpenAI\Codex\bin\<hash>\`
layout is off PATH and rotates on auto-update — the shim re-resolves the
newest at every start).

Extraction quality: the `terra` and `luna` ladder rungs
(`evals/ladder_sweep.py --rung terra` / `--rung luna`, first measured
2026-09-01) score GPT-5.6 Terra and Luna at parity with the Claude
ceiling rungs on the extraction bench — see the ceiling-probe table in
`evals/README.md` for the numbers and the single-run caveats. (The shim
is also live-verified — smoke-tested 2026-08-31 against codex-cli
0.151.0-alpha on a free ChatGPT tier: health warm-up, a
production-prompt extraction, and a per-request model switch all pass.)
And no shim is required for any endpoint that already speaks
`/v1/chat/completions`: a hosted OpenAI API key or any local runtime
works directly via the env triple in the previous sections.

## Reasoning effort — the dreamer's thinking budget

By default neither CLI shim sets a reasoning effort: the Claude shim runs
at the `claude` CLI's per-model default and the Codex shim inherits the
host's `~/.codex/config.toml`, so what the dreamer actually spends is
decided outside this repo. To pin it, set
`memory.dream.extractor_reasoning_effort` (Console → Extractor panel, or
the **Effort** row on the Dreamer card). A set value rides every primary
extractor request as `reasoning_effort`:

- the Claude CLI shim maps it to `claude --effort`
  (`low`/`medium`/`high`/`xhigh`/`max`),
- the Codex CLI shim maps it to `-c model_reasoning_effort=`
  (`minimal`/`low`/`medium`/`high`/`xhigh`),
- OpenAI-compatible servers read the field natively; most local runtimes
  ignore the unknown field, though a hosted API may reject an unsupported
  value with a clear 400 — the failure is loud, never silent.

Empty (the default) means the field is never sent — exactly the pre-knob
behavior. The fallback sidecar never receives it, same rule as the
model-only override. Both shims also take a `--reasoning-effort` launch
flag for a pinned default without touching daemon config; a request's
value wins over the launch flag either way.

## Cadence — quiescence-gated, daemon-only

What gets consolidated and when is configurable under `memory.dream`
(`eligible_sources` / `exclude_sources`, and the `min_batch` /
`idle_seconds` backlog+quiescence thresholds that
`memory_dream(action="status")` reports).

Dream runs are single-flight: a `memory_dream(action="run")` that lands
while another run holds the guard returns `{"skipped":
"dream_in_progress"}` instead of racing it — scripted callers should treat
that as a normal outcome (the next sweep tick retries), not an error.

The auto-sweep (Tier 2) fires when:

```
backlog ≥ min_batch (8)
  OR  (backlog ≥ 1 AND idle ≥ idle_seconds (600s))
  OR  an episode is awaiting outcome inference
  OR  (an episode is awaiting a session digest AND backlog = 0)
```

The digest condition is gated on an empty backlog because the digest
stage runs only on the empty-pull (idle) branch of the dream cycle: with
entries still pending, firing on digest backlog alone would consolidate a
partial batch every sweep tick without making digest progress. The normal
cadence drains the entries first; the digest backlog then fires the quiet
ticks.

`idle` is time since the newest band entry, not since the last request — a
session that only *reads* stays quiescent. Polled every
`sweep_interval_seconds` (600s). It runs **only in the
daemon** — the embedded stdio mode never sweeps. There is **no turn-based
trigger** (the cortex does not "dream every N turns"), by design:
consolidating mid-session would distil half-formed, still-changing state
into canonical facts and burn the CPU extractor during your foreground
work. So during an active session, prose-stored facts stay in the
searchable bands and reach the cortex once you go quiet (~10 min idle) or a
backlog of 8 accumulates.

**Want a fact canonical *now*, mid-session?** Two on-demand paths bypass
the wait: `memory_fact_set` writes a canonical fact instantly, and
`memory_dream(action="run")` forces a full consolidation sweep on the spot
(the `/dream` command wraps it). `memory_search` finds the original prose
the entire time regardless.

**Privacy & cost.** Tier 0 is on-box and free. Tier 1 spends the agent
tokens you already pay for (a scheduled daily dream is small but non-zero).
Tier 2 with a *cloud* endpoint sends memory text off-box — a local model
(e.g. Ollama) keeps it on-machine.

## Session digests (opt-in) — one prose memory per closed session

With `memory.dream.digest_enabled` on, the idle dream cycle writes one
narrative prose digest per closed session episode — a mid-density layer
between raw turns and atomic facts, aimed at arc-shaped questions ("how
did the deadline change and why") that no single entry answers. Each
digest is a normal `source="digest"` band entry stamped to the episode it
summarizes: it competes in ordinary dense retrieval, is filterable like
any source, and is never re-mined for facts (`digest` is in
`exclude_sources`). The session briefing's recap renders the digest body
for the most recently closed session.

Mechanics mirror outcome inference: a cursor advances monotonically per
closed episode, transport failures hold the cursor, malformed or
unwritable digests get two attempts before the cursor advances past the
episode. Long sessions are split on line boundaries at
`digest_context_chars` (default 24,000) and map-reduce merged; the prose
length target is `digest_target_chars` (default 1,200 — re-targeted from
800 to the length the extractor naturally writes, measured in the
2026-08-27 sidecar probe). When first enabled, the
zero-start cursor backfills all history, `digest_max_per_cycle` (default
4) episodes per dream pass. Default-off: enablement gates on a human
review of what the configured extractor actually writes —
`evals/digest_sidecar_probe.py` generates that evidence.

## Dream runs — audit and rollback (schema v27)

Every dream pass that produces claims records a **run row** and a per-claim
**pre-image journal** — what each touched slot held before the write. The
journal lives outside the facts supersession chain on purpose: superseded-row
compaction purges that chain in steady state, so it was never durable enough
to revert from. Passes that write nothing (outages, zero-claim batches)
leave no row.

- `memory_dream(action="runs")` lists recent passes: id, cursor movement,
  tallies (including the literal-gate counters), and lifecycle status
  (`running | committed | failed | rolled_back`). A `failed` run means a
  claim write or acknowledgement failed — partial claim writes are
  journaled. A lost acknowledgement response may require a retry to discover
  whether the database committed it.
- `memory_dream(action="rollback")` reverts the **latest committed** pass by
  replaying its journal in reverse through the normal write paths — a
  superseded value is superseded back (history preserved, nothing deleted),
  a dream-inserted slot is retired, member adds/removes are mirrored.
  Rollback covers fact writes only (not relations/lessons/graph), keeps the
  source traces, and does not reset input acknowledgement or the display
  cursor. It refuses when a newer
  run is `failed`/`running` (unjournaled uncertainty) and on double
  rollback. Both actions are full-tier tools — expand with
  `memory_toolset(action="expand")` from a core-tier session.
- `memory_history(entity, attribute, as_of=...)` answers "what did this slot
  say on date X?" from the version chain (ISO or epoch). Compaction keeps
  only the newest few non-live versions past ~30 days, so a very old
  `as_of` may return an incomplete chain.

Retention: the newest `memory.dream.runs_keep` (default 50) runs survive;
older rows and their journals are pruned on the sweep tick beside
superseded-row compaction. Design doc:
`docs/superpowers/specs/2026-08-01-dream-run-journal-design.md`.

## Consolidation quarantine — the two-man rule (opt-in)

`memory.dream.quarantine_low_trust` (ships **off**) closes the dream's
poisoning-amplifier path with a defense keyed on *who wrote*, never on
what the text says (the MAFIA result in `SECURITY.md` closes the argument
that content inspection can defend this path). When on, a **scalar** claim
whose backing entry is agent-tier — its `source` maps to origin `agent` —
and outside `memory.dream.trusted_sources` never takes `current`
directly:

- it **parks** via the ordinary contender machinery (visible as
  `contested` in `memory_fact_get`, `quarantine:low_trust` in its
  provenance), including at a brand-new slot (a currentless contender);
- it **promotes** on exactly two routes: an explicit
  `memory_fact_resolve(accept=true)`, or an **independent second
  witness** — a later matching claim backed by a different witness token
  (the entry's episode, else its source) or by a non-agent origin —
  **and only when the witness's tier is not below the standing current's
  origin**: the two-man rule is never weaker than the provenance guard
  it reinforces, so two agent witnesses cannot supersede a user-stated
  fact. The same witness restating merely re-confirms the parked value;
  an automated promotion is stamped agent-supported (a literal, never
  the claim's own origin field), and never as a user act.

Run results carry `quarantine_parked` / `quarantine_held` /
`quarantine_promoted`; parks and promotions are journaled (a promotion
under its own action) and `memory_dream(rollback)` reverses both. Nothing
is dropped or hidden — quarantined claims stay stored, searchable, and
auditable through their engram links. Honest scope: episodic search still
surfaces a poisoned *entry*; the quarantine only denies it silent
*canonical* authority. Member ops are outside v1 (members are never
contested by design; the aggregate guard already parks the dangerous
member-over-scalar case). Preregistration:
`docs/superpowers/specs/2026-08-09-consolidation-quarantine-design.md`.

## Constraint entries survive verbatim — TypeCompact + guard (schema v35)

The dream is a compression step, and the compaction cliff (arXiv
2608.22752) is what compression does to a rule: a safety rule and an
episodic log are summarised at the same rate, but only the rule needs
its exact wording to stay enforceable. An entry whose
`distortion_tolerance` is `constraint` (set explicitly on `memory_store`,
or inferred by the `auto` heuristic for rule-sized deontic text — see
[memory-model](memory-model.md#who-said-it-and-how-exactly-must-it-survive-schema-v35))
is therefore treated as zero-distortion by the dream:

- **The carrier (TypeCompact).** Among the claims the extractor cites
  the entry for, at least one scalar claim must contain the entry's text
  verbatim (whitespace-collapsed, case-preserving). If none does, ONE
  claim's *value* is replaced with the entry text: the claim whose
  content tokens overlap the rule most (at least one must), and only if
  its target slot is empty or already holds a constraint — a standing
  non-constraint fact is never overwritten and a claim about something
  else is never hijacked, whatever position it has in extractor output.
  The extractor's entity and attribute are kept (slotting is what it is
  good at; wording is not), sibling claims are left alone, member (`op`)
  claims are never carriers, and with no eligible claim the carrier
  refuses and leaves the miss to the guard. Only the carrier earns
  `distortion_tolerance: constraint` (and the pin in recall); a
  paraphrased sibling is an observation and inherits its slot's label.
- **The guard verifier.** After the claims loop, every constraint entry
  in the processed window must have a derived item carrying its text
  verbatim (a parked contender counts; so does a slot the same entry
  formed on an earlier pass). Misses are reported on the run result as
  `constraint_misses` (entry id + text) beside `constraint_verbatim`, on
  the run row's tallies as `constraint_missed`, and logged at WARNING.
  This is a **flag, not a hard fail**: the paper fails a compaction whose
  input is still there to retry, but here the raw entry is never
  discarded (it stays in the associative store and is served by
  `memory_search`), and withholding acknowledgement would hold every other
  claim in the batch to one rule the extractor could not slot. The
  typical miss is an extractor that emitted no scalar claim for the
  entry at all — inventing a slot is not the dream's business.

**Authority rides along.** Every derived fact takes the *source entry's*
`authority` (`quoted` / `directive` / observation) and inherits the slot's
label when the source is unlabelled — never anything the extractor wrote,
which is model output and steerable by note text (the same trust class
as claim `origin`). Under the two-man rule above, a `quoted` source is
low-trust whoever relayed it: a third party's remark parks as a contender
instead of taking `current` on the relayer's tier. The label only ever
*demotes*; promotion stays keyed on entry metadata, so dressing a note up
as a quote gains nothing but a park. Rollback restores the previous
version's labels along with its value.

## Chronicle events (schema v28) — dated occurrences beside facts

Facts answer "what is current"; they systematically lose *occurrences* —
things that happened at a time ("adopted the kitten on May 13") rather
than states that hold. `memory.dream.chronicle` (**on by default**; needs
Postgres) makes the dream
pass extract those too, into `chronicle_events`, via a **separate
extractor call per batch** — a dedicated events pass with its own pinned
prompt artifact (`evals/prompts/events_pass_v1.txt`), run after the
claims call. The events pass failing is non-fatal by design: claims
commit regardless and the result carries `events_pass_failed: true`. The
bundled sidecar model is fine-tuned for both passes (see the sidecar
section above).

- **Event time vs record time.** `occurred_at` is when it happened;
  `recorded_at` is when the dream stored it. A date is accepted only as
  an exact `YYYY-MM-DD` *and* only when the batch actually contained
  date information — otherwise the event stores undated with the
  source's verbatim `occurred_phrase` ("a while back") and sorts behind
  dated rows. A date is never fabricated.
- **Additive-only.** Nothing updates a stored event; contradiction
  handling sets `invalidated_at` (invalidated rows stop serving but stay
  auditable). Exact restatements dedup against the live row.
- **Gated like claims.** The literal gate applies to event descriptions
  (batch scope, same `enforce`/`log`/`off` modes and counters).
- **Journaled like claims.** Event writes journal into the run's
  pre-image journal (kind `event`), so `memory_dream(action="rollback")`
  deletes exactly the rows that pass created — safe precisely because
  records are additive-only.
- **Serving.** A temporally-cued `memory_search` (when/first/before…, or
  an explicit year-first calendar date like `2026-08-08`) adds an
  `events` block: matching live events, oldest first, each with
  `date` (or `null` plus the verbatim `phrase`), capped at 6. An
  **aggregation cue** (how many/count/total…) widens the cap to 30 and
  adds `events_total` — a computed property of the served list, so the
  answerer can do arithmetic over a long enumeration without recounting
  lines (a count over a capped prefix would be wrong by construction).
  No serving knob — an empty table serves nothing.

Extraction is **on by default** (and surfaced as a Console knob) since
the 2026-08-12 soak review: the pipeline passed its preregistered gates
(separate-pass events, and the multi-task sidecar fine-tune that serves
it — see the CHANGELOG's measured entries), then ran a 2026-08-05..08-12
production soak (188 events, 0 incorrect dates, historical backdating
correct, dedup and literal gates load-bearing, ~160 kB/week volume).
Set `memory.dream.chronicle: false` to opt out. (Lineage: the Phase 1
retrieval-side knobs of
`docs/superpowers/specs/2026-08-03-aggregation-aware-recall-design.md`
measurably failed, which is what made extraction-time event capture the
live hypothesis.)

## Deep dream — full-corpus graph consolidation

The incremental dream (tiers above) is window-local: it distils only the
recent MIRAS tail into cortex facts. `memory_dream(action="deep")` is a
separate full-corpus GRAPH pass (Phase-2 'C'). Its MECHANICAL half also
runs itself: a need-based tick on the sweep timer applies Steps A/B —
rescore, guard-passing junk auto-delete, scope stamping, proposal
filing, snapshot-first — once the bank has grown by
`memory.deep_dream.auto_min_new_entities` (default 150) since the last
apply or `auto_interval_days` (default 7) have passed; every apply,
manual or tick, resets that clock (`auto_tick: false` disables). Step C
(judgment) is autonomous too, in measured stages: each sweep also sends a
bounded batch of pending merge proposals — with the same evidence pack the
review surfaces show, plus a caution line on pairs stamped
`low_differential` (whose snippets cannot tell the sides apart) — to the
configured model (`memory.deep_dream.judge_mode`,
default `shadow`; the dream extractor, or a dedicated `judge_url`), and
records the verdict + confidence + note on the proposal row (schema v30),
shown beside the evidence in every review surface. In `auto-reject` mode,
reject verdicts at/above `judge_reject_min_confidence` are applied
(`decided_by='dream-judge'`, pair dismissed). A row whose first verdict sat
below that gate gets a **second opinion** on a later sweep
(`judge_second_opinion`, optionally `judge_second_model` — both Console knobs) — a fresh batch,
so an independent sample: two rejects at mean >= `judge_reject_min_confidence_2`
apply, a disagreement stamps `split` on the note and leaves the row for a
human. `judge_mode: auto` goes one step further and folds a pair when two
independent accepts agree on a row that is not `low_differential` at mean
>= `judge_accept_min_confidence` — the only path that ever auto-applies an
accept. Since 2026-09-02 the other queues have judges too, each riding the
same sweep as a bounded batch, all but one defaulting to `shadow`: the
**link judge** (`link_judge_mode`; `auto` promotes accept verdicts to live
edges and applies rejects, each at its own gate — a *retype* is only
recorded, with its corrected relation on the row, for a reviewer to apply,
because the first ladder scored the judge's relation choice at 0/1; edges
are reversible, which is why this queue may run auto), the **junk judge**
(`junk_judge_mode`; `auto` deletes only under an evidence bar), the
**store-curation judge** (`curation_judge_mode`; `auto-distinct` applies
the reversible dismissal, `auto` also retires — never deletes — a losing
duplicate slot only when conservative content and metadata checks pass).
Lessons must have matching guidance categories and case-sensitive text, ignoring
outer whitespace. Substring
containment is not enough because a condition, negation or correction can change
the meaning. Model-invented rewrites stay in review. The survivor stays unchanged;
the loser's support and provenance remain in its retired row and audit, so an undo
restores the exact pair. Both records are checked again after inference;
the retirement and audit commit atomically before the resident state changes.
The **Step-C candidate judge** (`candidate_judge_mode`, defaulting to `off`)
works through a deep apply's candidates one
`judge_batch` slice per sweep tick — `propose` files an edge proposal and
`dismiss` marks the pair distinct, and every judged pair is memoised for
`candidate_rejudge_days`. Two mechanical additions stop the queues
refilling: ordinary sweeps file a bounded slice of the Console's analyzer
duplicate findings into the merge and link queues (`analyzer_file_duplicates`,
on by default); a deep apply still performs its full pass. Settling an analyzer
link also closes its duplicate finding, with bounded reconciliation for earlier
terminal decisions. `judges_enabled=false` also stops this ordinary-sweep
filing and reconciliation; explicit deep apply retains its separate switches.
The optional orphan sweep, once enabled, deletes week-old entities that carry no
evidence and no mention at all (`orphan_sweep`, off by default, at most
`orphan_max_per_apply` per pass: it is the one destructive switch that
would fire on the first apply after an upgrade). Which models
judge reliably is measured, not assumed: `evals/judge_ladder.py` scores the
merge judge against ratified triage verdicts
(`evals/results/judge-ladder-20260816.json`) and `evals/queue_judge_ladder.py`
scores every queue's judge against the 2026-09-02 blind-panel set
(`evals/results/queue-judge-panel-20260902.json`), simulating each auto gate.

Pending judgments are bound to the evidence and policy that produced them.
Changing the model, prompt, mode or supplied evidence invalidates an old opinion;
an in-flight reply cannot authorize an action on changed evidence. This does not
reopen a completed human decision. The Console's **Re-evaluate pending opinions**
button queues up to 32 opinions for the next sweep. Operators can use
`POST /api/graph/rejudge` with `{"queue":"all","limit":32}`; supported queues
are `merge`, `link`, `junk`, `curation` and `candidate`, with a total limit of
1–100. It queues work without changing automation modes or immediately calling
a model.

New automatic rejections and pair dismissals also retain the evidence and policy
behind the decision. A bounded sweep can reopen them when those inputs change;
candidate dismissals follow their endpoint evidence, so unrelated memory traffic
does not refill the queue. A human confirmation keeps the decision closed.
Legacy decisions without this provenance remain closed, and completed merges or
deletions are never undone automatically. The Console shows the latest 20
graph automatic decisions and reconsiderations; older records remain in the durable
audit. Judge results include reconsideration counts even when no new model call
is needed. An unverified model identity defers a candidate or curation action
without repeatedly calling the model; explicit re-evaluation can retry it.

A duplicate retirement can be undone through the existing lesson/world restore
action. If an entity has both curated and other retired slots, restore a specific
attribute so each curated undo can validate and commit its complete pre-image.

Each graph finding reports whether it is unfiled, pending, already decided,
gated or requires manual review. These counts are mutually exclusive. A weak
connection, a test-like name or low edge confidence is not
by itself authorization to remove information. Those cases retain their reason
for review unless an existing, separately guarded maintenance path applies.

The same need signal rides `memory_dream(action="status")` as the
`deep_dream: {recommended, reason, ...}` block — a harness-agnostic
nudge any MCP client can surface to its user when a triage session is
worth scheduling. A
dry-run (default) returns a preview of what it would change: re-scored
edges, hard type-violation edges queued for supersession, exact-duplicate
entity pairs queued for merging, and semantic link *candidates* across
sessions (each with truncated context snippets; items the apply path would
dedupe are flagged `already_proposed`). Adding `apply=True` first dumps the
five graph tables to a JSON forensic record under `data_dir/graph_snapshots/`
(refusing with `snapshot_failed` if it can't), then commits the safe
self-clean (re-score + supersede violations + merge exact dups) and returns
`candidates` for review. The agent then drives Step C in the same session
(see the `/dream` flow in `examples/commands/dream.md`): judge each
candidate from its snippets, post the real relations with
`memory_graph_review(action="propose")` — they land in the Atlas Review
queue (`proposed_link` findings) for per-item accept/reject before anything
reaches live edges — and record clearly-distinct pairs with
`memory_graph_review(action="dismiss_pair")` so they stop resurfacing. See
[the deep-dream runbook](../runbooks/deep-dream.md) for the operator
procedure.

A duplicate finding whose two names are a source file and its own bare stem
(`band.py` ↔ `band`) now arrives with `action: "relate"` and a
`suggested_relation` (`implements`) instead of forcing merge-or-dismiss:
the concept usually has identity the file does not, and several files can
realize one role, so merging asserts something false and dismissing throws
a real relationship away. Settle it with one call —
`memory_graph_review(action="relate", src=<file>, relation="implements",
dst=<concept>)` writes the edge *and* dismisses the duplicate pair — or
one Relate button in the Atlas review drawer, which does the same.

**Draining the quarantine.** Quarantined edges are almost all untyped
`related-to` co-mentions, and about half of them name a real relationship
that merely got the wrong label. Each dream therefore re-asks the extractor
to *type* up to `memory.dream.retype_quarantined_max` quarantined pairs
(default `3`), showing it only the notes where both entities co-occur. A
pair that comes back with a real relation is filed as a fresh review
proposal — a retype is a second guess on suspect material, so it never
writes a live edge — and the untyped original is rejected either way, so
the queue drains instead of accumulating. The pass runs even on a dream
with no backlog (the quarantine grows fastest when dreams are rare),
no-ops on an empty quarantine, and reports
`retyped: {considered, retyped, settled}` from `memory_dream(action="run")`.
Set `0` to disable.

**What no longer reaches the graph.** Five sources of review-queue noise
were closed at the write path rather than cleaned up afterwards: dotted
pseudo-entities minted when an extractor read a flattened
`entity.attribute` vocabulary hint as a name; the `<artifact> <aspect>`
nodes `memory_outcome` mints, which shared nearly every token with the
artifact they mentioned and so dominated the duplicate and orphan
findings; merge proposals pointing *at* a contentless entity, now that
fold direction ranks on facts as well as degree; edges to git branch
names, which typed as unknown — and therefore as neutral — and sailed past
the confidence floor; and merge proposals for name-shape false-positive
classes — a broader name paired with a date/run-tag-stamped event node,
and sibling ids differing only by numeric tokens (`CT200`/`CT400`) or the
pre/post pair — vetoed at both filing sites, with the rules gated by a
replay of the 2026-08-11 full-queue triage (they suppress 12 of that
pass's 101 rejected proposals and none of its 38 accepted ones).

Two more queue-quality knobs shape what gets proposed at all. Link
candidates skip pairs whose evidence-support overlap exceeds
`memory.deep_dream.max_support_overlap` — measured as **containment**
(`|shared| / min(|a|,|b|)`), a stricter test than the Jaccard ratio the
same number would suggest — and exclude pairs with a pending link proposal
or a junk-flagged side before top-k selection, so the queue refills with
new work instead of settled work. The trace-less-entity fallback scan is
capped at `memory.deep_dream.max_fallback_mentions` (default 30) per
entity; trace-backed mentions are never capped.

## Consolidation workflow (agent-driven dedup)

Long-running banks accumulate near-duplicate memories — the same fact
phrased five different ways across five sessions. The literature on
agent memory ([HiMem 2026](https://arxiv.org/abs/2601.06377);
[MIRIX 2024](https://arxiv.org/abs/2507.07957); the
[ICML 2025 position paper](https://arxiv.org/abs/2502.06975)) calls
consolidation — turning episodes into reusable semantic notes — *the*
most-important under-implemented capability of long-term LLM memory.

The dream pass (the extractor sidecar) handles fact extraction server-side,
but the server can't borrow *Claude's* judgment mid-call (Claude Code
doesn't yet expose MCP sampling — see
[feature request #1785](https://github.com/anthropics/claude-code/issues/1785)),
so near-duplicate cleanup is surfaced as clusters for Claude to consolidate
deliberately:

```
memory_consolidation_candidates(query="MCP transport choice", top_k=20)
# → {clusters: [{cohesion: 0.84, size: 3, members: [<entry>, ...]}, ...]}

memory_consolidate(
  entry_ids=[101, 102, 103],  # selected member IDs from the candidates above
  new_text="MCP transport is stdio — chosen over TCP to avoid port conflicts.",
  tags=["consolidated"],
)
# → {superseded_count: 3, new_memory_stored: true, ...}
```

Pass the selected member IDs rather than copying their text. All targets
must resolve before any changes; a missing, retired or ambiguous target
returns a no-op with diagnostics so the caller can reload the candidates.
Legacy `replaces=[...]` requires unique exact text and does not fall back to
similarity. File-mode entries have no row IDs and use that exact-text form.

The clustering is deterministic greedy: highest-relevance entry seeds
the cluster, any unclustered candidate whose cosine with the seed
clears `min_cohesion` (default 0.6) joins, cohesion is the mean
intra-cluster cosine, clusters are sorted by `cohesion × size`. Cost
is O(N²) within the candidate pool, bounded to `top_k` candidates.
Retired entries are excluded before candidate limits and clustering.

`memory_consolidate` reuses the supersession machinery so the
predecessors stay in the bank but rank below the canonical note —
the audit trail survives but retrieval defaults to the current
phrasing. Useful idiom: tag the consolidation with `["consolidated"]`
so you can later scan with `memory_search(..., tags=["consolidated"])`
to see what's been distilled.

---

<!-- source: docs/guide/episodes.md -->

# Episodes & session lifecycle

How session episodes open and close (daemon-owned, no hooks required), the
SessionStart briefing hook, nested sub-episodes, and tags. Part of the
[user guide](../../README.md#documentation).

## Session lifecycle — daemon-owned episodes

Two things wire to Claude Code's session lifecycle so the memory loop runs
reliably — without the agent having to remember:

1. **SessionStart briefing.** `pseudolife-mcp briefing` prints a compact
   block: **what your memory is unsure about** (surprising graph links +
   open questions), **lessons from past work** (avoid / prefer),
   **verified world facts** (fresh, cited, age-ranked), and **where we left
   off** (a one-line recap of your last closed session). Empty sections are
   omitted, so a cold bank prints nothing. As a hook (`--hook-json`, or the
   plugin) it injects a short memory core first and then this block without
   the unsure section (the Console's Insight view keeps it), fitted to the
   hook's size budget, so even a cold bank's session starts with the core.
   A resumed or compacted session is not served the block again: it gets
   the episode-handle line and a pointer to the full briefing (after a
   compaction, also a daemon-side `hook-instructions.md`).
2. **Episode lifecycle is owned by the daemon, keyed by a resolved session
   identity — hooks make that identity precise, but nothing about opening
   or closing an episode requires them.** Five tiers, strict precedence
   (full table + rationale:
   [Configuration — session identity](configuration.md#session-identity)):
   a stdio shim's `X-PL-Session` header outranks an explicit
   `episode` handle passed on a write (on the lifecycle tools —
   `memory_episode_start`/`_end`, `memory_session_title` — a resolved
   handle wins outright), which outranks the SessionStart-hook-registered
   active session. The legacy transport `mcp-session-id` tier is
   **retired** (per-**connection**, not per-session, and removed entirely
   by the MCP 2026-07-28 revision — SEP-2567, "Sessionless";
   `PSEUDOLIFE_LEGACY_TRANSPORT_SESSION=1` is a one-release rollback
   hatch), leaving writer id + idle-gap sessionization as the floor when
   nothing above resolved.
   - **Hook-registered identity.** The plugin's SessionStart hook forwards
     Claude Code's own `session_id` to the daemon, which opens (or
     resumes) that session's root episode immediately — no longer lazily
     on first store — and sets it as the machine-scoped active-session
     pointer. The returned briefing text carries a one-line **handle
     advertisement**: the episode id (truncated) plus the instruction to
     pass `episode="<id>"` on every memory write — the concurrency-correct
     channel, so attribution stays right even when other sessions are open. A
     SessionEnd hook closes that session's episode and clears the pointer
     when the session ends. If a client crashes without firing SessionEnd,
     the pointer expires after `PSEUDOLIFE_ACTIVE_SESSION_TTL_SECONDS`
     (default 6 h, the resume window; `0` disables) so a dead session stops
     attracting later tier-3 writes — SessionStart re-stamps it, so an active
     session (Claude Code re-fires the hook on resume/compact) stays live.
   - **Ownership guard.** `memory_episode_end` pops only the caller's own
     sub-episodes and never closes a session root, with or without a
     handle. The direct `POST /api/episode/end` with no `session_key` in
     the body can only close a root episode whose `session_key` matches the
     caller's own resolved identity — a session can no longer pop another,
     still-open session's root by accident. No match is a no-op:
     `{"closed": null, "reason": "no owned open session"}`. The idle
     reaper is separate: it closes any root idle past the threshold,
     using each root's own key — that's its job, not a guard bypass.
   - **The stdio shim** (the installer default) opens no episode of its
     own. Under Claude Code its `X-PL-Session` header is the session id
     Claude Code launched it with, which is the id the plugin's
     SessionStart hook registers. A write without an `episode` handle, or a
     `memory_session_title`, therefore lands on the hook's root, and that
     root's lifecycle stays with the hooks and the idle reaper: the shim's
     exit does not close it, because a reconnect restarts the shim
     mid-session. Without the plugin's hooks the daemon opens that root on
     the first write, and the idle reaper closes it. Other hosts get one
     session per shim process (Codex keys each call by its own thread
     instead). The daemon opens that session's episode on the first write
     that needs one, as for a direct-HTTP client, and the shim closes it at
     exit when the host lets it exit; otherwise the idle reaper does. A
     shim that is idle or only searches leaves no episode behind. Until
     2026-09-25 the shim opened a working-directory-titled episode at
     connect, which gave each Claude Code session a second root and left an
     empty root for every shim a host killed. One gap remains: `/clear` and
     an in-session `/resume` give the session a new id but keep the shim's.
     Afterwards a `memory_store` or `memory_episode_start` without a handle
     reopens the root under the old id (or opens one) and lands there, and
     a `memory_session_title` without one renames that root. A call that
     passes the handle SessionStart advertised lands on the new root and
     opens nothing under the old id. `--continue`, or `--resume` without an
     id, can likewise launch the shim with an id no hook registers.
   - **Direct-HTTP / sessionless clients** (no shim, no hook, no explicit
     handle) still get episodes: the daemon **lazily opens** one on the
     first store of a new session (so empty sessions never leave a husk)
     and the **idle reaper** closes it once inactive — firing the
     end-of-session dream for non-empty sessions
     (`PSEUDOLIFE_SESSION_IDLE_SECONDS`, default 30 min). An episode that
     is *empty* at reap time is closed but kept until it is also past the
     resume window (the session may only be on a break), then deleted with
     a **tombstone** left behind. One open episode
     is tracked *per resolved identity*, so concurrent sessions (e.g.
     different projects) don't clobber each other, subject to tier 3's
     last-start-wins limitation (see Configuration).

   A store arriving after the reaper closed the episode **resumes** it —
   same identity, same episode — rather than opening a new husk
   (`PSEUDOLIFE_SESSION_RESUME_SECONDS`, default 6 h; `0` disables). The
   briefing's `episode="<id>"` handle resumes under its **own, far longer
   window** (`PSEUDOLIFE_HANDLE_RESUME_SECONDS`, default 30 days; `0`
   disables): a handle is a daemon-minted id only that session's briefing
   carried — an explicit identity claim, not an inference — so a session
   parked for days (a deferred benchmark, a long weekend) still attributes
   correctly on return. A write carrying a handle whose root the reaper
   closed reopens that episode (without moving the current-episode
   pointer — the writer may be a different session); one whose empty root
   the sweep already deleted **recreates it from the tombstone under the
   original id** (keeping an agent-set title), so the always-pass handle
   stays valid across long pauses either way. Only roots the *reaper*
   closed empty are ever swept — an old episode whose entries were later
   evicted or forgotten is history, not a husk, and is never touched. The
   one deliberate gap in the promise is the manual prune
   (`POST /api/episodes/prune`): an explicit operator action that deletes
   empty closed episodes without a tombstone. Past the handle window, or
   on an ambiguous prefix, the write proceeds under normal identity with
   an `episode_warning`.
   Session titles start generic
   (`session - YYYY-MM-DD HH:MM`, since the daemon has no project `cwd`) —
   name the session with `memory_session_title` (store responses carry an
   `episode_hint` until you do, naming the handle when the store passed
   one); a session closing still-generic gets an
   auto-derived `"{dominant source} - {stamp}: {first-entry snippet}"`
   title. Fragmented history is repairable over REST:
   `POST /api/episodes/rename` and `POST /api/episodes/merge`. Set `TZ` in
   `ops/.env` for local time.

### Session record

An episode is not a durable record that a session happened: a root that
ends holding no stored entry is deleted. So every registration (the
SessionStart hook, or `POST /api/episode/start` from the stdio shim and the
CLI episode hooks) also writes one `client_sessions` row per session key
(schema v43), which no prune, sweep or tombstone expiry deletes. The row
holds how the session first registered (`hook` or `api`), the bearer's
principal, its first start and every registration time since (a resumed
client registers again), its most recent close and why (`end` for
SessionEnd or shim exit, `idle` for the reaper; cleared when the session
registers again or a store or handle reopens its root), the startup memory-policy variant the hook assigned
(for `full_separate_hook`, a plugin without the separate memory-policy hook
never delivers it), and every root episode id the session was given. A
session that only searched or logged outcomes loses its root at the end but
keeps this row, so its searches (by session key) and outcomes (by episode
id) still have a session to count against; `evals/capture_metrics.py`
reads it. A root the daemon opened lazily for a key that never registered
gets no row, and an operator's manual prune of an open root
(`include_open`) leaves that session open on record. Postgres only;
operational data, left out of `pseudolife-mcp export` like the retrieval
log.

## Inferred outcomes at session close

Most sessions never call `memory_outcome` — the agent stores facts and
moves on without logging how the work went. When a session episode closes
with stored entries but zero outcome signals, the end-of-session dream
runs an extra stage that infers up to 3 signals from the episode's own
record (`origin="inferred"`) before the usual lesson synthesis — the
context deliberately includes status-source entries too, since a
session's own status chatter is still evidence of how it went, just
weaker evidence than an explicit `memory_outcome` call. Lessons synthesised
from a batch that is *entirely* inferred signals are written at a
discounted confidence (0.4 vs the usual 0.6); a lesson that already
exists at a higher confidence isn't dragged down — the write path keeps
the higher value, as it always has. Kill switch:
`memory.lessons.infer_outcomes: false` (see
[Configuration](configuration.md)); the signal cap per episode
(`infer_outcomes_max_signals`, default 3) is tunable alongside it.

## Installing the briefing hook

One command installs the briefing, per-turn memory guidance, and a separate
startup instruction for coordination check-in:

```powershell
.\ops\install-hook.ps1     # Windows (PowerShell 7)
```
```bash
./ops/install-hook.sh      # Linux / macOS
```

It backs up your `settings.json`, then adds the hooks **alongside** any
existing ones (idempotent — safe to re-run; it installs only what's
missing). Requires `pseudolife-mcp` on PATH — `pip install -e .` in the
repo puts it there.

Prefer to wire it by hand? The briefing's `--hook-json` flag emits the
`hookSpecificOutput.additionalContext` payload Claude Code injects — the
same memory core and bounded briefing the plugin hook serves:

```json
{
  "hooks": {
    "SessionStart": [
      { "hooks": [
        { "type": "command", "command": "pseudolife-mcp briefing --hook-json" }
      ] }
    ]
  }
}
```

The briefing connects to the *already-running* daemon (never starts one)
and does nothing if the daemon is down — it can't slow or break session
start. Tune the printed briefing with `--max-unsure N` / `--max-lessons N` /
`--max-world N` (default 3 each); with `--hook-json` these are ignored,
because the daemon fits the hook context to the hook's size budget. The
briefing content is also available on demand via the CLI or the Console's
`/api/briefing` route.

The plugin's daemon-served memory hook uses a short operating guide rather
than repeating the full standing memory policy. Its bounded briefing retains
complete items, prioritizes lessons and recap, and reports omitted content. Full standing guidance is in
[`examples/CLAUDE.memory.md`](../../examples/CLAUDE.memory.md). A custom
`hook-instructions.md` in the daemon's data directory is also bounded: an
omission notice means the complete custom instructions must be obtained before
relying on the partial copy. That path belongs to the daemon host and may not
be readable from a remote client; `/api/briefing` returns the briefing, not
the custom instruction file.

The plugin additionally supplies independent startup and per-turn coordination
handlers for check-in and local inbox previews. The startup handler asks the agent to set its project, task
and status, discover peers, and receive pending mail. Full messages are read
with `memory_message`, then acknowledged after reading. The existing adapter
owns the mailbox; this handler does not create another identity or grant
permissions. The memory and coordination hooks have independent output budgets
and do not depend on execution order.

The lightweight `install-hook` scripts install the briefing, the coordination
check-in (`pseudolife-mcp briefing --coordination`, which prints it only where
the daemon serves it: a board that is on and usable by that bearer), and the
per-turn memory-change note (`pseudolife-mcp prompt-hook`). Re-running them
replaces the unconditional check-in echo and the static discipline echo
older versions wrote. They do not register an
agent identity or install the plugin's local inbox-preview handler. `pseudolife-mcp briefing --hook-json` reads
`/api/hook/session-start` (the plugin hook's memory core and briefing) but
forwards no session id, and no SessionEnd hook is written, so an install
wired this way has no hook-registered identity (tier 3) and no hook-driven
episode close: the idle reaper closes the episode instead, and the
briefing's `episode="<id>"` handle is the concurrency-correct attribution
channel. For the full lifecycle, use the plugin.

## Episodes + tags

An *episode* is a bracketed working session. While an episode is open,
every memory stored carries the episode's id + title automatically, so
later queries can scope by session. **Session episodes open and close for
you**, daemon-owned and keyed by a resolved session identity (five tiers —
shim header, `episode` handle, hook registration, legacy transport id, or
idle-gap sessionization; see
[Configuration — session identity](configuration.md#session-identity)) so
concurrent sessions don't collide; absent a hook, the daemon lazily opens
one on first store and an idle reaper closes it. For a substantial
multi-step task you open a **nested sub-episode** under the session:

```
memory_episode_start("auth refactor")            # nests under the open session
memory_store("Decided to keep tags orthogonal to source instead of merging them")
memory_episode_end()                             # pops back to the session
memory_search("design choices", episodes=[session_id])  # expands to the subtree
memory_episode_summary(session_id)               # stats + tag distribution + recent entries
```

Episodes **nest** (schema v15): `memory_episode_start` opens a child under
the current open episode — the parent stays open — `memory_episode_end`
pops back to it, and closing the session cascade-closes any still-open
children. A session-scoped `memory_search(episodes=[root_id])` expands to
the whole subtree, so a sub-episode's entries surface under their parent
session too. (Calling `memory_episode_start` with nothing open simply opens
a root.) In Postgres mode episodes live in the `episodes` table
(`session_key` + `parent_id` columns); in file mode they ride
`cms_state.pt` under the `episodes` key.

Tags are a parallel multi-valued axis to `source`: pass
`tags=["decision", "blocker"]` on store, filter with
`memory_search(..., tags=[...])`. Normalised at store time (lowercased,
stripped, deduped). Set intersection non-empty for the filter to pass
(OR within the filter list, AND with the other filters).

---

<!-- source: docs/guide/configuration.md -->

# Configuration

Every knob the daemon reads — environment variables, the tuned built-in
defaults, toolset tiers, the stdio shim, LAN sharing, data layout, and
backups. Part of the [user guide](../../README.md#documentation).

## Connection / deployment env vars

| Variable | Default | Effect |
|----------|---------|--------|
| `PSEUDOLIFE_MCP_DATABASE_URL` | _(unset → lite/file mode)_ | Postgres DSN; when set, PG is the source of truth (schema v49). Unset: with the `[lite]` extra installed the daemon auto-starts an embedded PostgreSQL and fills this in itself; otherwise v0.1 file-only mode (announced loudly at startup). |
| `PSEUDOLIFE_MCP_STORAGE` | `auto` | `files` opts the daemon out of the `[lite]` embedded Postgres (file mode even when pg0-embedded is installed). Only consulted when no DSN is set. |
| `PSEUDOLIFE_MCP_DAEMON_URL` | `http://127.0.0.1:8765` | Daemon the shim connects to (and auto-starts). Use an HTTP(S) origin: scheme, host and optional port, without a path, user information, query or fragment. |
| `PSEUDOLIFE_MCP_NO_SPAWN` | _(unset)_ | Set `1` on the **shim** to disable its spawn-a-daemon fallback: when nothing answers at `PSEUDOLIFE_MCP_DAEMON_URL` it waits (up to ~3 min) for an external daemon instead. The Docker-tier installers set this on every shim registration — after a reboot the shim can probe before Docker Desktop has bound the port, and a spawned host fallback then wins the bind race and shadows the real bank with whatever stale local state it finds. Leave unset on pip/lite installs, where the spawn fallback is the intended zero-config path. |
| `PSEUDOLIFE_MCP_HOST` / `_PORT` | `127.0.0.1` / `8765` | Daemon bind address. |
| `PSEUDOLIFE_MCP_TOKEN` | _(unset)_ | Bearer token; **required** to bind a non-loopback host (a `PSEUDOLIFE_MCP_TOKENS` map also satisfies this). Maps to the reserved principal `default`, which keeps the `X-PL-Writer`/`PSEUDOLIFE_WRITER_ID` writer path. |
| `PSEUDOLIFE_MCP_TOKEN_FILE` | _(unset)_ | Client-side private file containing the bearer token. The shim reloads it for each operation, so replacing its contents does not require a client restart. An explicitly configured file takes precedence over a literal token; an unavailable, unsafe or malformed file fails closed. The daemon continues to use its own token configuration. |
| `PSEUDOLIFE_MCP_PROXY_TIMEOUT_SECONDS` | `180` | Total deadline for one upstream shim operation, including connection and initialization. Accepts finite positive seconds; invalid values use the default. Set the client's tool timeout above this value to leave time for the shim's sanitized failure response. An uncertain write is never automatically replayed. |
| `PSEUDOLIFE_MCP_TOKENS` | _(unset)_ | Per-principal bearer tokens: `token:principal,token:principal`. A matched token's principal **is** the writer id and keys the toolset tier (the identity axis that survives the MCP 2026-07-28 stateless core). Malformed entries are logged and skipped — a skipped token does not authenticate, and a map that parses to zero entries with no singular token refuses startup rather than running open. May be set alongside `PSEUDOLIFE_MCP_TOKEN`; the map wins for its tokens. Note the singular-token holder is fully trusted and may still assert any writer via `X-PL-Writer` — mint per-principal tokens when that distinction matters. |
| `PSEUDOLIFE_MCP_TRUST_BIND` | _(unset)_ | Set `1` to allow a non-loopback bind without a token when the boundary is external (containerized, loopback-published). The compose daemon sets this; never set it for a host daemon. |
| `PSEUDOLIFE_MCP_DATA_DIR` | `./data` (cwd-relative) | Weights cache + legacy-migration source + ChromaDB. When the `[lite]` embedded Postgres engages, the default moves to a stable per-user dir instead (`%LOCALAPPDATA%\pseudolife-mcp`, `~/.local/share/pseudolife-mcp`, or `~/Library/Application Support/pseudolife-mcp`) — a per-launch-directory Postgres bank would be a data-scattering footgun. Windows lite note: must be ASCII-only (the daemon refuses otherwise, with the remedy in the message). |
| `PSEUDOLIFE_MCP_CONFIG` | `<data_dir>/config.yaml` if present, else built-ins | Override MIRAS / embedding / memory config. |
| `PSEUDOLIFE_WRITER_ID` | `unknown` | Identifies this writer on every canonical write (schema v11). The shim forwards it as the `X-PL-Writer` header; the compose daemon defaults to `mcp-client`, and the installer pins `claude-code` / `claude-desktop` / `codex` / `gemini` / `mcp-client` in `ops/.env` per the selected `--client`. Existing installs that predate the client selector should set `PSEUDOLIFE_WRITER_ID=claude-code` in `ops/.env` to keep their writer identity (and any `PSEUDOLIFE_MCP_TIER_MAP` keyed on it) stable. |
| `PSEUDOLIFE_MCP_AUTOSAVE_SECONDS` | `30` | Interval of the file-mode autosave loop (weights/state cadence; Postgres-mode entries are transactional regardless). |
| `PSEUDOLIFE_MALLOC_TRIM_SECONDS` | `60` | Daemon on Linux/glibc only (the Docker tier): how often a background thread calls `malloc_trim(0)` to hand back heap memory glibc keeps after embedder encode bursts. Measured 2026-09-23 with four persistent worker threads, 1,007-1,433 MiB of it was still resident at idle with the fp32 embedder (897-1,476 MiB bf16), and a trim took a median 7 ms with no measurable slowdown of the next encode (`evals/results/allocator-trim-pool-20260923.json`, `allocator-trim-probe-20260923.json`, `allocator-trim-latency-20260923.json`). It lowers what the daemon holds after a burst, not the peak of the burst itself. `0` disables. |
| `PSEUDOLIFE_SESSION_REAP_SECONDS` | `300` | How often the idle-session reaper sweeps. The idle *threshold* it enforces is `PSEUDOLIFE_SESSION_IDLE_SECONDS` — see [Episodes](episodes.md). |
| `PSEUDOLIFE_LEGACY_TRANSPORT_SESSION` | _(unset)_ | Set `1` to restore the retired `mcp-session-id` transport-session fallback for one release (rollback hatch; logs a warning on first use). The header names the HTTP *connection*, not the session — concurrent sessions share it — and the MCP 2026-07-28 revision removes it from the protocol. Session identity rides the hook-registered episode handle and `X-PL-Session` instead — see [Episodes](episodes.md). |
| `PSEUDOLIFE_DAEMON_MEM_LIMIT` | `6g` | Docker tier only (read by compose, not the daemon): hard memory cap on the daemon container, with the memory+swap total pinned to the same value — no swap, so exceeding the cap is a clean container restart rather than a host-wide memory event. Measured 2026-09-23 with the fp32 embedder, the daemon held ~3.1–3.3 GiB anon at rest and up to 4.5 GB hours later, and the old `4g` default OOM-killed it under an ordinary request burst; bf16 takes ~1.4 GB off. `/health`'s `memory` block reports use against the cap. Raise for very large banks. |
| `PSEUDOLIFE_EMBEDDING_CPU_DTYPE` | _(unset)_ | Overrides `embedding.cpu_dtype` (`auto` / `fp32` / `bf16`) — the torch embedder's precision on a CPU. Set `fp32` to roll a daemon back from bf16 without a rebuild; `/health`'s `embedder` block shows the resident dtype. |

For the Docker stack, set these 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). The
dream-extractor variables (`PSEUDOLIFE_DREAM_*`) are covered in
[Dreaming](dreaming.md).

When deploying with `ops/update.ps1` or `ops/update.sh`, an explicit assignment
to either authentication variable in `ops/.env` makes that file authoritative
for both. Inherited client token variables cannot add an unintended fallback;
the launching shell's environment is preserved after the deployment command.

## Experimental agent coordination

Coordination adds peer awareness and addressed mail within one bank. It is on
by default, behind bearer authentication, and does not reserve files or prevent
conflicting edits. Configure it in the daemon's `config.yaml`, then restart the
daemon; `enabled: false` turns it off:

```yaml
coordination:
  enabled: true
  awareness_limit: 5
  allowed_principals: [editor, reviewer]
  audit_retention_days: 90
  wake:
    per_recipient_per_hour: 20
    urgent_per_sender_per_hour: 6
    nightly_total: 200
    fan_out_stagger_seconds: 30
    active_seconds: 60
    nudge_interval_seconds: 3600
```

`audit_retention_days` is how long the [audit log](#audit-log) keeps each event:
a whole number of days, default 90, and `0` keeps the log forever.

`wake` caps the rings the daemon decides at send (schema v49; see
[park records and the wake decision](#park-records-and-the-wake-decision)).
Every ring is an unattended model turn in the recipient, so each is bounded:
`per_recipient_per_hour` counts every ring to one address (20, the figure the
Claude Code Stop hook already used); `urgent_per_sender_per_hour` (6) bounds
the `urgent` flag; `nightly_total` (200) is a rolling day of rings across the
bank; `fan_out_stagger_seconds` (30) spaces the rings from one sender's burst;
`active_seconds` (60) is the window in which a recipient's own last board
action makes new mail `hinted` rather than rung; `nudge_interval_seconds`
(3600) bounds the ring that asks an idle, unparked session to park. The
values are whole numbers; a cap of 0 rings nobody (or never honours
`urgent`), and the two windows are at least 1. Over a cap the send answers
`capped` with the cap's name.

Wake is on by default and policy-gated (maintainer decision, 2026-09-28), so
the caps are the guarantee, not the usual rate. `/health` reports the caps in
force, and `pseudolife-mcp doctor` prints them beside each registered
client's wake path (`stop_hook` for Claude Code, `doorbell` for Codex: `on`,
or `off` with the setting that turned it off, `off (no codex CLI)`; for
Codex also `off (PSEUDOLIFE_WRITER_ID is not codex)` and `off (no bearer
token)`, since the shim arms the doorbell only as the codex writer with a
bearer; for Claude Code `off (plugin not installed)` / `off (plugin
disabled)`, since only the plugin carries the Stop hook). The hooks and the
shim read these switches trimmed and case-insensitively, and a blank value
is unset. The client-side switches are
`PSEUDOLIFE_AGENT_COORDINATION=0` (the master off switch for that client),
`PSEUDOLIFE_AGENT_WAKE_HOOK=0` (the
[Stop hook](#waking-an-idle-claude-code-session-the-stop-hook)) and
`PSEUDOLIFE_CODEX_DOORBELL=0` (the [Codex doorbell](#codex-doorbell)).

`awareness_limit` must be an integer from 1 to 20 and caps peer summaries. Existing
episodes have no trustworthy project/task or principal fields, so unregistered
peers are shown with unknown scope and host capability. Titles do not establish
identity. Last reported activity comes from attributed writes; an open episode
does not prove a process is running. Refresh awareness before shared-resource
work and on resume.

The allowed names are principals from the bearer-token configuration above.
Without the key only `default`, the singular `PSEUDOLIFE_MCP_TOKEN` principal,
is admitted: principals of a `PSEUDOLIFE_MCP_TOKENS` map are separately
trusted identities and join the board only when listed (an explicit list
replaces the default; include `default` to keep it). An upgrade that already
authenticates clients through a map therefore finds them off the board until
they are listed. On the default setting, a shim whose bearer is unlisted
leaves coordination off at startup without an error, and memory keeps
working; with `PSEUDOLIFE_AGENT_COORDINATION=1` it shows a
coordination-unavailable hint instead. For Codex,
`ops/setup-codex-coordination.py --check` names this cause
([Codex CLI and desktop](#codex-cli-and-desktop)). Mailbox operations
require PostgreSQL, configured
bearer authentication and a registered adapter's private instance credential.
Two sessions sharing a principal still need distinct adapter identities. A
public agent ID, episode handle or task label never grants mailbox access.
Clients lacking a per-session credential-injecting adapter can use awareness,
but cannot send, receive or acknowledge another instance's mail. Awareness is
gated on the same allowed-principal list: a bearer whose principal is not listed
sees no peers and no awareness section in its briefing, and with no bearer token
configured there is no principal to list, so the board stays dormant on an open
loopback install: no awareness, no mail and no startup check-in. The
installers mint a token by default; see [Turning the board on](#turning-the-board-on).

The installed shim starts its adapter (for Codex, its per-thread registry) by
default when it holds a bearer token (`PSEUDOLIFE_MCP_TOKEN` or
`PSEUDOLIFE_MCP_TOKEN_FILE`) and the daemon serves that bearer the board; it
asks once at startup and otherwise stays quiet. `PSEUDOLIFE_AGENT_COORDINATION=0`
(any value but `1`, `true`, `yes` or `on`) turns it off for that client, and
`=1` skips the question and reports any refusal on stderr.

The startup check-in follows the board. The daemon serves the hook text
(`GET /api/hook/coordination-start`) only where the board is on for that
bearer: enabled, authenticated, a listed principal, PostgreSQL. The plugin
hook and the installers' `pseudolife-mcp briefing --coordination` hook print
what it serves, and the shim appends a compact check-in to the MCP
instructions only when its adapter is up. The daemon cannot see whether a
client has an adapter, so a check-in can still reach one that cannot complete
it: a client connected over HTTP without the shim whose hooks hold a token; a
client that opted out only in its MCP env block (set the opt-out where the
hooks see it too, since they cannot read that block); and a Docker install
wired by `ops/install-hook.*`, whose `docker exec` check-in asks with the
daemon container's own token. The check-in tells the agent to say so and
continue when the tools are unavailable.

Since 2026-09-28 the check-in also says when a message is due, not only
how to send one (a review of six sessions had found 15 status updates, 9
peer lists and 7 receives against no sends until a human asked for one). It
carries two field-neutral rules, the two of five candidates that changed
decisions in `evals/coordination_checkin_bench.py` (see `evals/README.md`):
before using something shared, look for whoever holds it or has it
booked, and if someone does, message them that you are next, even when
their status says when they expect to finish, because a status line is not
a queue (if the board shows it free, use it and say so in your status); and
keep your status true (what you hold, what you wait on, when you expect to
finish). The Codex form, inside its
512-character MCP-instructions budget, carries the first, bounded the same
way. An install's own
words for its shared things (a suite lock, a GPU, a style guide, an API
quota) belong in the daemon's `<data_dir>/hook-instructions.md`, which the
memory hook serves after its core (3.5 KB cap, see
[Startup memory policy](#startup-memory-policy-memory_policy) below);
[`examples/hook-instructions.md`](../../examples/hook-instructions.md) is
one host's copy (suite and GPU status words, the lease holder, a
pre-flight before a full run). For the Docker install the file goes into
the daemon's data volume (`/data` in the container). The hook reads it at
every session start, so no restart is needed:

```bash
docker cp examples/hook-instructions.md pseudolife-mcp-daemon:/data/hook-instructions.md
```

`evals/coordination_checkin_bench.py` measures whether the text moves the
send/no-send decision (see `evals/README.md`). Optional
`PSEUDOLIFE_AGENT_LABEL`, `PSEUDOLIFE_AGENT_PROJECT` and `PSEUDOLIFE_AGENT_TASK`
provide explicit display and relevance fields. For clients other than Codex,
set `PSEUDOLIFE_AGENT_STATE` to a
private file outside the repository for deliberate mailbox resume. Each concurrent
adapter needs its own state file; sharing one does not create a second identity.
Claude Code sessions use `PSEUDOLIFE_AGENT_STATE_DIR` instead, a private
directory. When the installers register Claude Code with a token file, they
set it beside the token to `~/.pseudolife-mcp/claude-code-agents`, keeping a
value the registration already has (see
[Turning the board on](#turning-the-board-on)); a registration made by hand
sets it itself. The shim keys one state file under it by the
`CLAUDE_CODE_SESSION_ID` Claude Code launches it with, so concurrent sessions
never share one and `claude --resume <id>` returns to the session's address.
That id is fixed for the shim's lifetime: `/clear`, compaction or an
in-session `/resume` keeps the running shim and its address. `claude
--continue`, or `--resume` without an id, may launch the shim with the
process's startup id instead of the resumed one, and the session then gets a
new address. A state-backed address registers as resumable and is kept for
seven days after its last activity or lease (longer while a retained message
names it), so the board holds about a week of sessions; a session resumed
after its address was removed registers a new one and keeps the old state
file with a `.stale` suffix. Without a state file or directory,
each launch gets a new address, registered as not resumable and retired an
hour after it goes quiet. Never infer recovery from a
title, checkout directory or implicit host resume. Credentials stay in that
private file and adapter headers, not model arguments or memory entries.

The adapter also keeps a per-turn digest: the daemon's `attach` and
`heartbeat` answers preview the five oldest pending messages (sender label,
one-line excerpt) beside the pending count, and the adapter renders them once
behind a watermark that moves only when the text changes. With a host session
id — `CLAUDE_CODE_SESSION_ID` for Claude Code, the thread id for Codex — the
digest is written to `~/.pseudolife-mcp/digests/<sha256(id)>.txt`
(`PSEUDOLIFE_DIGEST_DIR` overrides the directory; set it identically for the
hook's environment, which cannot see the MCP env block; `PSEUDOLIFE_PLUGIN_DIR`
is the daemon-side counterpart, naming the plugin tree whose hook scripts
`/health` digests — the image sets it to its own copy). The plugin's
coordination UserPromptSubmit hook prints the digest only when the watermark passed the
shared `.seen` marker; the tool-result hint uses the same marker, so a change
is delivered once and a quiet turn adds nothing. While mail stays pending and
unchanged, a one-line reminder rides every tenth tool result. The file is
removed when the shim exits; a session id without an adapter (or a host that
exports none, such as the app-level MCP servers Claude Desktop launches from
`claude_desktop_config.json`) gets hints only. Desktop's Code tab runs Claude
Code, whose per-session stdio shim does receive the id. That shim serves the
session's calls only while Desktop's app-level entry has a different name, so
the installer names that entry `pseudolife-desktop` (see
[Claude Desktop](providers.md#claude-desktop)).

Claude Code hooks see the current session id, which `/clear` and an
in-session `/resume` change, while the shim keeps the id it was launched with.
The plugin's session hooks therefore keep the shim's digest key once per
Claude Code process, in `claude-<CLAUDE_PID>.host` beside the digests, and
the prompt hook reads through that record while it is confirmed for the
current session. `CLAUDE_PID` is the Claude Code process id, which Claude
Code v2.1.214 and later export to hooks; older versions keep the per-session
key. The record passes to the next session only through a handoff that the
SessionEnd hook binds to the process's creation time. A record left by a
process that exited, even one whose PID was reused, is never followed, and a
host that cannot report a creation time falls back to the per-session key.
After `/clear`, compaction or a resume, the current digest prints once more. A `--continue` launch whose shim got the
startup id cannot be mapped, since no hook ever sees that id; such a session
gets hints only.

### Turning the board on

A default `ops/install.sh` / `ops\install.ps1` run turns the board on:

1. When neither `PSEUDOLIFE_MCP_TOKEN` nor `PSEUDOLIFE_MCP_TOKENS` is set in
   `ops/.env` or the installer's environment, it writes a random
   `PSEUDOLIFE_MCP_TOKEN` to `ops/.env`, makes that file owner-only, and never
   prints the value. The daemon's `default` principal is on the default
   `allowed_principals` list.
2. It writes an owner-only token file per shim client it wires,
   `~/.pseudolife-mcp/claude-code.token` and `~/.pseudolife-mcp/gemini.token`.
   A `PSEUDOLIFE_MCP_TOKENS` map entry for that client's principal
   (`claude-code`, `gemini`) wins over the singular token. List a map's
   principals in `allowed_principals`.
3. It registers Claude Code with `PSEUDOLIFE_MCP_TOKEN_FILE` (re-read on every
   call, so a rotation needs no restart), `PSEUDOLIFE_MCP_DAEMON_URL` and
   `PSEUDOLIFE_AGENT_STATE_DIR` (`~/.pseudolife-mcp/claude-code-agents`, which
   keeps a resumed session's board address), and Gemini CLI with the first two.
   Codex and Claude Desktop get their own credential files, as before.
4. With the Claude Code plugin, it sets `PSEUDOLIFE_MCP_TOKEN_FILE` and
   `PSEUDOLIFE_MCP_DAEMON_URL` in the `env` block of `~/.claude/settings.json`.
   The plugin's hooks read the Claude Code process environment, not the MCP
   registration, so without it they are refused; beside a Codex connection
   file they also refuse a token file without the matching URL. It leaves that
   block alone when it, or the installer's own environment, already sets
   `PSEUDOLIFE_MCP_TOKEN` or `PSEUDOLIFE_MCP_TOKEN_FILE`, and never replaces a
   URL already there.

An existing install gets the same by re-running the installer. After it
upgrades the shim behind an existing Claude Code registration, it adds the
three settings to that registration in place (a backup of `~/.claude.json`
is taken first) and keeps any credential the registration already has; restart
Claude Code sessions to load them. A custom or HTTP registration is left alone
with a warning: a token-gated daemon refuses an HTTP registration, which cannot
carry a token file, so register the stdio shim instead. An existing Gemini CLI
registration is always left alone with a warning naming the fix, since
`gemini mcp list` shows no environment and the installer cannot tell whether it
already carries a token.

The installer's final ladder and `pseudolife-mcp doctor` (its `board` field,
run from the registered command's environment) print one line: `on - token
present, principal allowed`, or `off - ` and the daemon's reason. The reason
comes from the `X-PL-Board` header on `GET /api/hook/coordination-start`
(`disabled`, `authentication_required`, `unauthorized`,
`principal_not_allowed` or `coordination_requires_postgres`).

To keep an open-loopback install with the board dormant, pass `--no-token`
(`-NoToken`). `--transport http` mints no token either, nor does a host that
cannot install the shim (no pipx, and no Python >= 3.10 whose pip may install
packages), since its registrations fall back to HTTP. None of these removes a
token that is already configured.

### Waking an idle session: `pseudolife-mcp wait-mail`

Mail reaches a recipient on its next Pseudolife tool call or prompt; nothing in
MCP can start a turn in a session that has gone idle, so the host has to.
`pseudolife-mcp wait-mail` gives the host something to wake on: it blocks until
the digest above shows mail nothing has shown yet, prints it and exits.

```sh
pseudolife-mcp wait-mail [--session-id ID | --digest PATH] [--timeout SECONDS] [--interval SECONDS]
```

It keys the coordination digest the way the shim does (`--session-id`, a Codex
thread id for instance, else `CLAUDE_CODE_SESSION_ID`; `PSEUDOLIFE_DIGEST_DIR`
applies); `--digest` names the file outright and accepts only a digest's own
`<64 hex digits>.txt` name. After `/clear` changes the session id, it follows a
`claude-<CLAUDE_PID>.host` record of the shim's spawn-time key for this Claude
process if one exists and its second line confirms it for the current session
(the SHA-256 of its id); without one, a waiter armed after `/clear` finds no
digest. It needs no daemon connection, token or
network. Each check is a file `stat` (every 2 s by default); the file is read
only after the adapter rewrites it. It fires when the watermark is past the
shared `.seen` marker and the digest lists pending mail, so mail that arrived
while the agent was busy fires at once and mail a prompt hook or tool-result
hint already showed does not. On firing it prints the digest body verbatim on
stdout, agent-origin framing included, then advances `.seen` so the hook and
hint do not repeat it, and appends a `wait` line to `ledger.log`. Exit codes:
`0` new mail; `3` timeout (default 4 h, at most 24 h), re-arm; `2` nothing to
wait on — no session id, no digest file (the adapter writes it when it
attaches: at shim start in Claude Code, on a thread's first `memory_*` call in
Codex), a file that disappeared because the shim exited, a file that cannot be
inspected when armed (a later read error is retried), a
stdout that cannot take the mail (left unmarked), or a bad argument.
Diagnostics go to stderr. The adapter refreshes the digest on its 20 s
heartbeat, so a waiter fires up to about 22 s after the send. It also rewrites
an unchanged digest every hour, without moving the watermark, so the day-old
sweep another adapter runs at start never takes a long-idle session's file.

In Claude Code, the agent arms it with the Bash or PowerShell tool and
`run_in_background: true`. Claude Code reports the exit as a task notification,
which starts a turn even in an idle session (observed on Claude Code 2.1.280,
2026-09-23):

1. After registering with `memory_agents`, arm one waiter; keep exactly one
   armed.
2. On exit `0`: `memory_message` receive, act, acknowledge each `message_id`,
   then re-arm. On `3`: re-arm. On `2`: read the stderr line, fix what it
   names (in Codex, make one `memory_*` call first) and re-arm once; if it
   persists, continue pull-only.
3. Before ending a turn that waits on a peer, make sure a waiter is armed.

Arm it from the main conversation: a command started by a foreground subagent
ends with that subagent's final response, and `-p` runs end background commands
shortly after their final result. When `pseudolife-mcp` is not on the shell's
`PATH`, call the shim's own executable or `python -m pseudolife_memory.cli
wait-mail` under the interpreter the shim runs on. In Claude Code's auto mode a
classifier reviews each such command, and in one 2026-09-23 session it refused
a long-running waiter script from the home directory as persistence (it allowed
the same script in another). The recommended setup is a narrow allow rule,
`Bash(pseudolife-mcp wait-mail *)` (and `PowerShell(pseudolife-mcp wait-mail *)`
on Windows), which also matches the bare command: auto mode resolves narrow
shell rules before the classifier runs, while it drops broad ones such as
`Bash(python*)` and every rule naming the Monitor tool, so arm the waiter as a
background Bash or PowerShell command, not a Monitor. Setting
`autoMode.classifyAllShell` suspends even narrow rules. Codex never starts a turn
when a background command exits, so run it there only in the foreground: a
background run would advance `.seen` with nobody reading its output.
Acknowledging some messages while a waiter is armed, and leaving others pending,
rewrites the digest and fires once, the same way the tool-result hint
re-delivers a changed digest.

### Leases: `pseudolife-mcp lease`

Awareness and mail say who is working on what; they do not stop two agents
starting the same GPU job or full test suite at once. A lease does: a named,
expiring hold on a shared resource, taken around any command.

```sh
pseudolife-mcp lease run NAME [--expect DURATION] [--ttl SECONDS] [--purpose TEXT] [--no-board] [--timeout DURATION] -- COMMAND [ARGS...]
pseudolife-mcp lease hold NAME --while-pid PID [--expect DURATION] [--ttl SECONDS] [--purpose TEXT] [--worktree PATH] [--no-board] [--timeout DURATION]
pseudolife-mcp lease check NAME [--json]
pseudolife-mcp lease list [NAME] [--json]
```

What excludes is an OS file lock, `~/.pseudolife-mcp/locks/lease-<NAME>.lock`
(`PSEUDOLIFE_LEASE_LOCK_DIR` overrides the directory; characters outside
`A-Za-z0-9._-` become `_`, plus a short hash of the name). The OS releases it
the moment the holding process exits or dies, so a crash leaves nothing stale.
With a bearer token (`PSEUDOLIFE_MCP_TOKEN` or `PSEUDOLIFE_MCP_TOKEN_FILE`) and
a daemon whose board is on, the board mirrors the lock: the run registers a
short-lived address (retired an hour after its last activity), queues for
`NAME` in arrival order, reports its position and the holder on stderr about
once a minute, then takes the OS lock and runs the command, renewing the board
lease every third of `--ttl` (default 120 s, from 30 s to a day). When a lease
frees, the head of the queue has 300 s to take it before the board passes it
on. `--expect` sets the expected end the board shows, counted from the grant
and marked stale once past; every call repeats the same value, which leaves it
alone. `--purpose` says what the lease is for.

Without a token, with the daemon unreachable, the board off or refused for this
bearer, or with `--no-board`, the run says once why and waits on the OS lock
alone: polled every 2 s, not in arrival order. The board never stops a command
from running: a board that keeps failing for two minutes is dropped the same
way, and a renewal that finds the lease lost warns once while the command
continues under the OS lock. A lock held by something the board does not show
(a `--no-board` run) delays a board holder until it is freed.

The command inherits the terminal and the environment, plus
`PSEUDOLIFE_LEASES_HELD` (comma-separated names, appended to any inherited
value). Exit codes: the command's own; `75` when `--timeout` (`90`, `90s`,
`20m`, `2h`) expired before the lease was held, and the command did not run;
`128+N` when stopped by signal N (`130` Ctrl-C, `143` SIGTERM, `129` SIGHUP);
`64` for a run nested inside a run of the same lease (its name is in
`PSEUDOLIFE_LEASES_HELD` while that lease's lock is held), which would
otherwise wait for itself forever; `2` a usage error; `71` an unusable lock
file; `126` or `127` a command that cannot start or is not found.

A stop never releases the lease under a running command. Ctrl-C reaches the
command too, so it first gets 10 s to clean up on its own; SIGTERM or SIGHUP
sent to the `lease` process is forwarded to it. After that it is interrupted
(POSIX only), terminated and killed, 10 s apart. The `lease` process holds
the lock, not the command: kill it outright (SIGKILL, Task Manager) and the
lock goes while the command may run on. On a case-insensitive filesystem,
names that differ only in case share one lock file, which can only make one
wait for the other.

`lease hold NAME --while-pid PID` is the lease for a process the command did
not start and cannot wrap: a launcher starts a detached server, then starts a
hold that lasts as long as the server's pid does. The order is the reverse of
`run`, because the process already owns the resource: the OS lock first (a
lock another process holds is waited for, or given up on at once with
`--timeout 0`, exit `75`), the board second, and both are released when PID
exits, or when the hold is stopped (`128+N`), which leaves PID running.
`--worktree` names the checkout in the notices below, by its name, never its path (a path names the OS user); `--expect` is the
expected end the board shows. All board traffic (the lease, its renewals, the
notices below, the release) runs on a thread of its own after the OS lock has
moved, so a slow or failing daemon never delays the lock; the release side gets
20 seconds, after which the board record is left to lapse at its ttl.
`evals/qwen_server.ps1` uses it around the bench server: `Start-Qwen` refuses to
launch while `lease check gpu` says the lease is held (beside its VRAM
busy-check, which stays the guard against anything that takes no lease), and
right after it launches a server it holds `gpu` for that server's pid, so the
lease covers the model load. It checks the hold a moment later and says so if
the hold could not take the lock (another process got it since the check) or
could not run. It runs the CLI from the checkout (`$env:PSEUDOLIFE_LEASE_PYTHON`,
else the checkout's `.venv`, else `python` on PATH, each as
`-m pseudolife_memory.cli`), and only then a `pseudolife-mcp` on PATH.

`lease check NAME` is the launch gate for an orchestrator, in place of watching
process CPU: it prints the local lock's state and the board's holder with the
expected end, and exits `0` when the lease is free, `1` when it is held, and
`70` when the check itself failed, which a gate must not read as held
(`--json` for one report). It is held when the local lock is held, or when the
board shows a holder. The one exception: a `lease hold` or suite mirror whose
board label carries this lock directory's instance id (`lease-hold@<id>`; the
id is 12 random hex digits in `instance.id` beside the locks, so no host or
user name reaches the board) beside a free local lock outlived its process
(killed outright), is shown as stale, and lapses at its ttl. Any other board
holder, such as a session that claimed the lease with `memory_agents`, a
`lease run`, or a hold from WSL or another machine or account, counts as held
until it is released or lapses, since no local lock can speak for it.
For `full-suite` it probes the test suite's own lock (`full-suite.lock` and its
slots, with the holder record's pid, worktree and start time), since that file,
not `lease-full-suite.lock`, is the truth for a full run. A run with
`PSEUDOLIFE_SUITE_LOCK=off` takes no lock, so no check sees it.

The test suite's lock is mirrored the same way. A full `pytest` run
(`tests/conftest.py`, `tests/suite_lock.py`) holds the board lease `full-suite`
behind its OS lock: while it queues it is a board waiter, once it holds the lock
it holds the lease, with the run's pid and worktree as its purpose and an
expected end from the median of the last five timed runs
(`~/.pseudolife-mcp/locks/full-suite.durations.jsonl`; 25 minutes until five
are on record). Only a run that ran its tests, passed or failed, is timed: an
interrupted run or a collection error would drag the median down. The lock is
freed first and the board told after, and a run that leaves the queue without
the lock (refused, a changed tree, Ctrl-C) gives its board place back. When the
lock's holder is a run the board does not show (older code, no bearer), the
board grants the lease to the first waiter; that waiter hands it back and asks
no more until it holds the lock, so the board never names a queued run as the
holder. The OS lock stays the truth: a board that is unreachable, refuses, or shows another
holder costs one line and never delays or stops the run, and
`PSEUDOLIFE_SUITE_LOCK=off` (CI) takes neither. The run's bearer and daemon URL
are read when conftest is imported, before the suite's own client isolation
strips them, and the mirror is built only for a run that takes the lock.

Acquiring and releasing `hold` and the suite's mirror send one notice each
(`LEASE NAME acquired: pid, worktree, expected end` / `LEASE NAME released:
pid, worktree, held for`) by board mail to the peers the lease concerns, in
the same project (compared without case; every project when the sender has
none set): live agents (attached, or registered without an adapter) whose
status says `suite=running`, `suite=queued` or `gpu=`, and any agent parked
with `park_clear_by` naming the lease while the park stands (a reason set, and
`park_expires` not yet passed), attached or not, since mail waits for a parked
session. The release notice rings such a session, subject to the wake path
and caps: for 60 seconds after a hold ends, the daemon counts its last holder
as the clearer the lease name stands for (taking a lease clears nothing, so
the acquire notice waits in the queue). Both leases go to both status groups
on purpose: a GPU server beside a full suite is the contention. At most 20
peers are told per event; one refused send does not stop the rest. The
notices are automatic and need no reply; they replace hand-written
SUITE-START/SUITE-END notes.

`lease list` shows each board lease (holder, purpose, age, expected end,
queue) beside the local lock files, each probed held or free, and whether the
test suite's own lock (`full-suite.lock`, which leases never take) is held.
Without the board it shows the local state with a one-line note. The instance
credential stays inside the `lease` process: it is never printed or passed to
the command.

`pseudolife-mcp lease break NAME` is the operator's way to free a lease whose
holder will never release it, such as a dead session's day-long claim. It opens
the bank directly, as `board-audit` and `export` do
(`PSEUDOLIFE_MCP_DATABASE_URL`, else the lite tier's data dir), grants the
lease to the next waiter, and logs a `lease_break` with the operator as its
actor. It frees the board's record only: a process still holding the local lock
keeps it until it exits.

Sessions hold leases too, from the model's side, with no process and no OS lock
behind them. `memory_agents(action="claim", lease=NAME, status=PURPOSE,
expect=SECONDS)` takes or queues for a session-held lease, such as
`coordinator:<project>` or `claim:<path>` for a work area; claiming again renews
it, and `action="release"` frees it or leaves its queue. A `claim:` lease lasts
a day between renewals, any other an hour. A claim is advisory: it tells peers,
it blocks no edit. A queued session is not told when its turn comes: it sees
the grant the next time it lists or claims, and must renew within the same
300 s window. `memory_agents(action="list")` carries the held and queued leases
(resource leases before claims, and `leases_truncated` when the page cut some
off), and `memory_agents(action="update", status=..., expect=SECONDS)` gives a
status an expected duration: past it the peer list marks the row
`status_overdue`. Over REST these are the coordination actions `lease`
(acquire, renew, or queue once), `release`, and `leases`, a listing that needs
only the bearer.

### Codex CLI and desktop

Use the ordinary stdio shim with `PSEUDOLIFE_WRITER_ID=codex`. Codex supplies
`_meta.threadId` on MCP tool calls; the shim uses this validated task UUID for
attribution and lazily attaches the task's mailbox on its first call. CLI and
desktop runtime probes confirmed that this metadata survives resume and changes
on fork. Process environment variables, checkout names and titles do not select
the mailbox. Missing or malformed metadata leaves ordinary memory available
without attaching a mailbox.

For an existing Codex stdio registration, run the following from a checkout using
the Python environment where Pseudolife is installed:

```sh
python ops/setup-codex-coordination.py --credentials
python ops/setup-codex-coordination.py --check
```

The check is read-only. Coordination is on by default, so a registration
without `PSEUDOLIFE_AGENT_COORDINATION` reports `ready (default-on)` when the
daemon serves the board to its bearer, the same question the shim asks at
startup. Nothing more is needed then. When it reports `needs-configuration`
because the daemon refuses the bearer's principal, its `reason` says so
(below). The report also names the wake path the shim would take with this
registration, read the way the shim reads the switches and `pseudolife-mcp
doctor` reports them: `wake` is `live` (the [app-server
bridge](#optional-codex-live-delivery)), `doorbell` (the [Codex
doorbell](#codex-doorbell), on by default since 2026-09-28, so a ready
registration with a `codex` CLI reports it) or `pull-only`, and
`wake_reason` says why: the switch that turned it off
(`PSEUDOLIFE_AGENT_COORDINATION=0`, `PSEUDOLIFE_CODEX_DOORBELL=0`), `no codex
CLI`, `no bearer token`, `PSEUDOLIFE_WRITER_ID is not codex`, a fixed
`PSEUDOLIFE_AGENT_STATE`, a server disabled in Codex, or the board question
the daemon answered no to.

`python ops/setup-codex-coordination.py --enable` is only for pinning explicit
mode (`PSEUDOLIFE_AGENT_COORDINATION=1`), after which the check reports
`ready (explicit)`. In explicit mode the shim skips the startup question and
keeps the adapter's own diagnostics. Enable also sets `PSEUDOLIFE_WRITER_ID=codex`
and `PSEUDOLIFE_MCP_NO_SPAWN=1`. It leaves `PSEUDOLIFE_AGENT_WAKE` as it is:
unset means no live delivery (the doorbell still rings by default), and a
live-delivery opt-in survives a re-run. Enable
requires a configured bearer and an enabled daemon that allows its principal;
it does not change the daemon's authentication or allowlist. The token must be
in the MCP registration's `env`, or explicitly forwarded through `env_vars`.
Setup preserves the command and unrelated settings, backs up the configuration
privately, and uses Codex's versioned configuration writer. Reconnect the MCP
server after changing its environment.

A Codex bearer from a `PSEUDOLIFE_MCP_TOKENS` map (principal `codex`, say) is
off the board until an operator lists it: without `allowed_principals` only
`default` is admitted. On the default setting the shim's startup question
then leaves coordination off with no error, and memory keeps working. In
explicit mode each task instead gets an "identity attachment unavailable"
hint. In either mode the check reports
`principal not allowed on the board (add 'codex' to coordination.allowed_principals in config.yaml)`.
Add the principal the map gives that bearer, keeping `default` if the
singular token should stay on the board, and restart the daemon:

```yaml
coordination:
  allowed_principals: [default, codex]
```

For authenticated connections, the normal installer prepares a private
credential file and connects both the stdio shim and lifecycle hooks to it.
Tokenless installations save their intended endpoint and explicit no-auth state,
so unrelated credentials in the app environment cannot select another bank.
For an existing installation,
`--credentials` performs that setup from the configured bearer. A non-secret
`pseudolife/connection.json` beneath the selected Codex home records the daemon
URL and token-file path for hooks, which do not inherit the MCP server's
environment. The setup refuses conflicting endpoints and follows no redirects.
Upgrading an already running shim requires one reconnect to load the new code
and file setting. Subsequent token-file replacements are read automatically;
the replacement token must resolve to the same bank and principal.

Setup pins `PSEUDOLIFE_AGENT_STATE_DIR` under the selected Codex home's
`pseudolife/agents` directory unless an explicit directory is already configured.
Files are scoped by bank URL and task ID, with credentials stored privately.
Existing state must be a private regular file owned by the current user;
the adapter preserves and rejects unsafe state rather than changing its
permissions and trusting potentially modified contents.
Each file pins the authenticated bank identity and principal, so bearer rotation
preserves the mailbox while a different bank or principal is refused. The first
upgrade can adopt the exact legacy file for the currently configured bearer
after the daemon proves possession of that mailbox's credential hash. The old
file is retained. Files belonging to previously retired bearers are not searched
or merged automatically. Do not set `PSEUDOLIFE_AGENT_STATE`
to one shared file in Codex: automatic attachment refuses that configuration.
`--disable` stops registration on subsequent connections and preserves saved mail.

Transport failures report a sanitized category, operation phase and whether the
operation outcome is known. The shim never automatically replays a tool call:
a write may have committed even when its response was lost or returned a service
error. Retry reads normally; verify uncertain writes before sending another one,
and reuse the original request ID when retrying an addressed message.

An active task should use `memory_agents` before shared-resource work and
`memory_message(action="receive")` on resume and when the coordination digest
(in the prompt hook or a tool result) shows pending mail. Receive does not
acknowledge; use `action="ack"` after reading, with one `message_id` or
several comma-separated (at most 50; a JSON array of strings, the form a
host that stringifies list parameters sends, is read as that list): a batch
returns the receipts in the order given and lists the ids that were not this
mailbox's, instead of failing whole. An ambiguous prefix in a batch refuses
the whole call, since acknowledging the wrong message cannot be undone.

A send names its recipient by agent id, or by a unique prefix of it of at
least 8 hex characters, the length every surface shows: a prefix that matches
several ids is refused with `ambiguous_recipient` and the candidates cut to
the shortest prefixes that tell them apart, and one that matches none fails
as the full id would (`recipient_not_found`). `reply_to` and `ack` take
prefixes the same way, resolved among the caller's own mail
(`ambiguous_reply`, `ambiguous_message_id`), so another mailbox's ids
neither resolve nor make a prefix ambiguous. A direct send's receipt names
the `recipient_agent_id` it resolved to. `to: "project:<name>"` sends to
every attached, non-idle agent in that project except the sender, and
`to: "all"` to every attached, non-idle agent on the board except the
sender: the peers the list shows with `adapter_available`. One request id
covers the burst, so a retry with it returns the same result: `recipients`
and one receipt per recipient with its `message_id`, `recipient_agent_id`
and a `wake` decision (`live` for an attached peer that opted into wake,
which the daemon rings; `pull` for one that reads at its next receive or
digest). The burst is atomic and refused whole, writing nothing, above 50
recipients (`fanout_too_large`), when nobody is reachable
(`no_recipients`) or when one mailbox is full (`queue_full`, naming that
mailbox's prefix); it counts once against the sender's rate, and a reply
cannot ride it. Each recipient gets its own message and its own audit event.
A refusal that carries such a detail surfaces it after the code in the MCP
tool's error (`ambiguous_recipient: 518a3e67aa, 518a3e67ab`) and as a
separate `detail` field beside `error` on REST.
These calls work in the CLI and desktop without live wake support.
Setup leaves Codex tool approvals unchanged and prints the approval choice at the
end of successful hook setup. A recipient running with approval policy `never`
cannot execute a tool that still requires approval. To authorize
unattended mailbox operations specifically, configure the installed server's
`tools.memory_message.approval_mode = "approve"` in Codex. This permits that
tool's send, receive and acknowledgment actions; it does not approve file writes,
commands or other tools. Without that choice, use the host's normal approval flow.

### Optional Codex live delivery

Codex's documented app-server API can accept tool output into an idle or busy
task. This integration is experimental: OpenAI also labels its WebSocket transport
experimental and unsupported. Install the optional dependency in the shim's exact
runtime with `python -m pip install 'pseudolife-mcp[codex]'`, or install the `codex`
extra from the checkout when testing unreleased changes.

The owner must expose an authenticated loopback WebSocket app-server and keep its
client connected. Configure that server's `--ws-auth capability-token` and
`--ws-token-file` options, then connect its CLI with `codex --remote` using the
same endpoint and credential. Follow the installed Codex CLI's help for client
authentication options. In that server's Pseudolife MCP environment, set:

```toml
PSEUDOLIFE_AGENT_WAKE = "1"
PSEUDOLIFE_CODEX_SERVER_URL = "ws://127.0.0.1:4500"
PSEUDOLIFE_CODEX_SERVER_TOKEN = "<local-server-bearer>"
```

The local-server bearer is separate from `PSEUDOLIFE_MCP_TOKEN`, which authenticates
to the bank. Keep both out of repositories and model prompts. The bridge accepts
only literal loopback endpoints with an explicit port and bearer authentication.
It verifies that the metadata-selected recipient is already loaded on that exact
server, then submits `turn/start` with empty user input and `toolOutput`. Peer
content remains tool output; no approval policy, model, sandbox or user-authority
override is supplied. Only the recipient's explicit acknowledgment marks receipt.

An installed desktop app using a private stdio app-server has no corresponding
external WebSocket endpoint. The bridge cannot attach to that connection and does
not start another server or resume the task elsewhere. Use pull messaging there.
Native app messaging tools and hooks do not establish a generic external wake API.
The desktop app-server binary was exercised separately; this does not establish
live delivery into the installed desktop UI.

See the [Codex validation record](../specs/2026-09-12-codex-coordination.md) and
[OpenAI's app-server contract](https://learn.chatgpt.com/docs/app-server).

### Codex doorbell

Codex starts no turn for MCP notifications, hooks or finished background
commands, so without the bridge a Codex task sees new mail only at its next
Pseudolife call. The doorbell wakes an idle task, desktop app included,
through Codex's own `codex queue` command. That command persists a message which
every app-server sharing the Codex home dispatches to the task once it is loaded
and idle; app-servers poll for it about every 10 seconds.

It is on by default since 2026-09-28 (before that, opt-in with
`PSEUDOLIFE_CODEX_DOORBELL=1`) whenever the shim finds a `codex` CLI and the
coordination adapter is up (on by default with a bearer token, off with
`PSEUDOLIFE_AGENT_COORDINATION=0`, which stays the master off switch). It
rings only when the daemon decides a message should wake the task: the task
is parked with a declared need and the message plausibly clears it (see the
`wake` caps under [Experimental agent coordination](#experimental-agent-coordination)).
Set these in the Pseudolife MCP server's environment, next to
`PSEUDOLIFE_AGENT_COORDINATION`, to turn it off or to name the CLI:

```toml
# Opt out (any value but 1/true/yes/on):
PSEUDOLIFE_CODEX_DOORBELL = "0"
# Optional: an absolute path; otherwise `codex` is looked up on PATH, then
# in the desktop app's own bin directory.
PSEUDOLIFE_CODEX_BIN = 'C:\path\to\codex.exe'
```

Reconnect the MCP server afterwards; the setup helper does not set either
value. The lookup uses absolute PATH directories only, never the working
directory (the task's checkout), so a repository cannot supply its own
`codex`; on Windows it then looks in the desktop app's
`%LOCALAPPDATA%\OpenAI\Codex\bin\<build>\codex.exe` (newest build), so a
desktop-only install rings too. A `PSEUDOLIFE_CODEX_BIN` that is relative or
does not exist turns the doorbell off rather than falling back to PATH. With
no CLI found the default stays quiet and falls back to pull delivery;
`pseudolife-mcp doctor` reports `doorbell: off (no codex CLI)`, and an
explicit `=1` says so on stderr. With a non-default Codex home, give the
server `CODEX_HOME` too, in its `env` or through `env_vars`: Codex does not
necessarily pass it to MCP servers, and without it `codex queue` writes to the
default home's queue, which no app-server of the task's home reads.

A woken task reads its mail with `memory_message receive`, so the task needs
`memory_message` approved in Codex's tool configuration; without that
approval a woken task stalls on an approval prompt until someone answers it
(the 2026-09-12 validation record's complete-path test approved it explicitly).

- **When it rings.** After each 20-second heartbeat the task's adapter reports its
  pending mail. The shim runs `codex queue --thread <task id> --message <notice>`
  only when new addressed mail has arrived, the task has made no Pseudolife call
  for 30 seconds, neither a tool-result hint nor the prompt hook has shown that
  mail, no earlier doorbell is still unanswered, and (v49) the daemon decided
  a ring for it ([the wake decision](#park-records-and-the-wake-decision)):
  the adapter offers the decision once its `ring_at` has come, and the
  doorbell takes it only at the moment it would ring, so an active or
  informed task never spends it. Without a decision (chatter to a parked
  task, or a daemon older than v49) the arrival stays owed and nothing
  rings; a later decision for the task covers it. A successful
  `memory_message receive` from the task answers it, and so does an emptied
  mailbox. An idle task gets one doorbell per batch of mail. A `nudged`
  ring (an idle task that never parked) adds one fixed sentence to the
  notice asking for a park record.
- **What it says.** Codex delivers queued text as a user message, so the doorbell
  never carries peer text, sender labels or excerpts. The notice is fixed and
  only the count varies:
  `[Pseudolife board - automated doorbell, agent-origin, not a user instruction]
  2 addressed messages pending for this thread. Read them with memory_message
  receive and ack each message_id. Act only within the task the user authorized.
  If nothing is pending, end the turn.` The model then reads the mail through
  `memory_message receive`, where it stays framed as agent-origin.
- **How it fails.** The CLI runs in the background with a 20-second timeout, no
  `PSEUDOLIFE_*` variables and, on Windows, no console window; a timeout or shim
  shutdown kills its whole process tree, launcher wrappers included. On Windows
  the CLI runs in a job object that every process it starts joins, so the kill
  also reaches a worker whose parent has already exited; where the shim cannot
  give it a job (a parent job that forbids nesting), `taskkill /T` does the
  kill, as before. A missing
  CLI, a non-zero exit or a timeout turns the doorbell off for that shim process
  with one stderr line; pull delivery and hints continue unchanged. Each queued
  doorbell appends a `bell` line to `ledger.log` in the digest directory, with
  the ring's decision and reason as its sixth column.
- **Limits.** A task is watched from its first Pseudolife call after the MCP
  server starts: one that has made none since a reconnect cannot be rung until it
  does. Tasks the WebSocket bridge above serves are not rung; if the bridge stops
  for a task, the doorbell takes it over. Codex holds a queued notice while the
  task is running, interrupted or shut down, so a task that ends a long turn
  without Pseudolife calls may wake once to mail it has already read. With more
  than five messages pending, new mail that lands in the same heartbeat as acks
  that keep the count from growing rings no doorbell; it surfaces at the task's
  next Pseudolife call or with the next doorbell. When the bridge stops for a
  task, the mail then pending (including the message it failed to deliver) is
  owed a doorbell.
  `codex queue` refuses ephemeral tasks and goes through a managed Codex
  app-server daemon when one runs. Success means enqueued, not read: only the
  recipient's acknowledgment marks receipt. The recipient still needs
  `memory_message` approval, as described above, to read mail unattended.

### Audit log

The live mailbox forgets on purpose: bodies blank after 24 hours, rows go after
seven days, idle addresses are removed, and a status update overwrites the one
before it. The audit log (`coordination_events`, schema v42) is the durable
record of what happened on the board, kept for at least `audit_retention_days`.

Every board mutation appends one row in the same database transaction as the
mutation itself, so a refused or rolled-back call leaves no event and no event
exists without its change. The events are `register`, `update` (the new values
and the ones they replaced, which is the status history), `attach`, `detach`,
`send` (with the full body; a burst to a project or the whole board writes one
per recipient, each with its own body and salt and `fanout: {to, recipients}`
in its payload), `read`, `ack`, `attempt`, the prune pass's
`expire` (bodies blanked) and `prune` (messages and addresses removed),
`bank_identity`, the lease events, the operator's restore `recover` and
`rebind`, and the operator's `redact` ([below](#redacting-a-body)). A `read`
records the first time a receive returned the message: an explicit receive
(`path: pull`), or the recipient's live-delivery adapter fetching it for a wake
attempt (`path: delivery`). The same time is stamped on the message as
`first_read_at`. The per-turn digest's 100-character preview is not a read.
Lease heartbeats are not logged: at the shim's 20-second cadence one session
would add about 4,300 rows a day, and `attach`/`detach` already bracket each
lease.

Each row carries a dense sequence number `seq`, the event, its actor (`agent`,
`daemon` or `operator`), the bearer principal the daemon verified for agent
actions (never a credential), the agent and recipient IDs, project and task,
the message ID, a JSON payload, `created_at`, the message's HLC stamp on `send`
(other events are ordered by `seq`: stamping every mutation would need the full
service initialization that mailbox calls deliberately avoid), and two hashes.
`hash` is sha256 of the previous row's hash followed by the row's canonical
content, so editing, inserting or reordering rows breaks the chain, and so does
removing any but the oldest (see below). Appends take a transaction-scoped
advisory lock after every board-row lock the mutation holds, which orders
writers on separate connections.

A `send` row written from schema v46 on keeps the message text in a separate
`body` column and a random 16-byte salt in `body_salt`, both outside the hash.
Its hashed payload holds sha256(salt || body) (`text_commitment`), and
neither the text nor its length, so the chain vouches for
the body without containing it, and an operator can remove one body without
breaking the chain. Redaction removes the salt with the body, so what stays in
the chain cannot be used to confirm a guess of what was removed. A `send` row written before v46 has the
text (`text`) inside its hashed payload and no `body`; that body cannot be
removed, and stays until audit retention removes the row.

Retention is separate from the mailbox. The prune pass that expires bodies also
removes the log's oldest rows once they are older than `audit_retention_days`.
It cuts on UTC day boundaries and removes only a fully expired prefix, so an
event stays at least the window. Normally it stays at most a day longer;
out-of-order timestamps can retain older rows behind a newer row until that
row also expires. The cut is always a prefix, recorded
as an `audit_prune` event naming the last removed row, and the surviving chain
starts from that anchor. `0` never prunes. The pass runs at most once a minute
and only while the board is in use (registration, sending or heartbeats on an
enabled board): a board that goes quiet, or has coordination disabled, keeps its
log, bodies included, until activity resumes.

A synthetic replay at the scale of the 2026-09-23/24 fifteen-session trial (40
agents and 623 messages, plus 15 status updates and 2 attachments per agent,
which the trial's export does not record) left 2,671 events in 1.6 MB including
indexes: 144.5 MB if every one of 90 nights were that busy
([artifact](../../evals/results/coordination-audit-volume-20260924.json)). In the
same run the append added 1.3 to 2.2 ms to the median send, receive and
acknowledgment on a local server, against a control arm with it disabled whose
own two runs differed by up to 0.6 ms. Status-update latency was too noisy there
to read (its two control runs were 1.8 ms apart), and with one writer at a time
the run did not measure waiting on the append lock.

The log is read by an operator, never by an agent: there is no MCP tool and no
REST route for it. `pseudolife-mcp board-audit` reaches the bank directly,
through `PSEUDOLIFE_MCP_DATABASE_URL` or the lite tier's embedded instance;
`export` and `verify` read one read-only snapshot, so they are safe beside a
running daemon:

```sh
pseudolife-mcp board-audit export --task fix-week --since 2026-09-23 --out board.jsonl
pseudolife-mcp board-audit verify
```

`export` writes one JSON object per line, oldest first, to stdout or to a new
`--out` file, which it never overwrites. Each line carries the row's columns,
the payload parsed, and `body` and `body_salt` (`null` except on a v46
`send` that has not been redacted). Prefer `--out` for anything you keep: a
PowerShell 5 `>` redirect writes UTF-16. The filters are `--project`, `--task`,
`--agent` (the acting agent or a message's recipient: a full id, or a unique
prefix of 8 or more characters, resolved against registered addresses and
the log's own ids, so an address the prune pass removed still resolves; an
ambiguous prefix is refused naming the candidates), and `--since` / `--until`
(epoch seconds or ISO 8601; a time without an offset is local). The daemon's
`expire`, `prune` and `audit_prune` rows and the operator's `recover` carry no
project or task and name agents only in their payload, so a filtered export
leaves them out.

`verify` walks the chain and prints one JSON report: `ok`, the number of
`events`, `first_seq`, the head (`head_seq`, `head_hash`, `head_created_at`),
and `start_cut`, the cut the log starts from once retention has removed its
oldest rows. It exits 0 when the chain is intact. It exits 1 with the first
failing `seq` and a `reason`: `sequence_gap`, `broken_link`, `hash_mismatch` or
`unanchored_start` for the chain; `body_mismatch` for a body that, with its
salt, does not open the commitment its `send` row's payload holds, a body on
any other row, a salt left without its body, or a body or salt written back
after a `redact` row named it; `body_missing` for
a v46 `send` whose body is gone without a later operator `redact` row that
names it and says it removed the body (reported after the whole walk, since
that row comes later); `body_not_exported` for a v46 `send` in an export that
has no `body` fields at all; or `head_missing`, `head_mismatch` or
`head_pruned` for an expected head. It exits 2 when it could not check.
`verify --input <file>` checks an export file instead of the bank; the export
must be unfiltered, since a filtered one has gaps, and a line that repeats a
key is refused. Export and verify with a v46 or later CLI: an export written
by an older one has no `body` fields, so its v46 sends fail as
`body_not_exported`, and an older `verify` checks no bodies at all. An export
of a pre-v46 log still verifies. In the Docker tier run it
inside the daemon container, which already has the database URL:
`docker exec pseudolife-mcp-daemon pseudolife-mcp board-audit verify`.

What `verify` shows: no row was edited, inserted or reordered, and none was
removed except the oldest, behind a cut record whose own fields add up (written
by the daemon, a window of at least a day, the cutoff that window gives at its
time, and a first surviving row no older than that cutoff; retention removes
only an expired prefix, so a later row stamped before the cutoff can remain).
No v46 body was edited, and none was removed except behind a `redact` row.
What it cannot show on its own, because no secret is involved: that the
newest rows were not dropped; that the table was not rewritten with every
hash recomputed; that the oldest rows were not removed by someone who
also appended a consistent cut record; and that a body was not removed by
someone who also appended a consistent `redact` row (which then stays in the
log, reason and all, like the operator's own).
Record `head_seq:head_hash` and `head_created_at` from each `verify` somewhere
outside the bank, and later run `verify --expect-head SEQ:HASH`. That catches
the first two. The third needs a series of recorded heads: retention never
removes a row created at or after its cutoff, so a recorded head that comes
back `head_pruned` although its `head_created_at` is at or after
`start_cut.cutoff` means rows went that retention would have kept (unless the
daemon's clock stepped backwards, or the window was raised since). A forged
cut stamped with the current time and your configured window passes
everything else. For history you must be able to prove, keep periodic `--out`
exports (privately) and check them with `verify --input`. The log records mutations made through
the coordination store; a direct SQL edit of the mailbox tables leaves no event.
It proves what was sent and by which verified principal, not that a message was
true.

The log is private data. It holds message bodies verbatim for the whole
retention window unless an operator redacts one, and bodies carry machine
paths and usernames. It lives only in the bank database and its full backups,
portable `export`/`import` archives omit it, and the CLI writes only to stdout
or a local file you name. Keep exports out of repositories and anywhere public.

#### Redacting a body

A body that must not stay in the log (a credential pasted into a message by
mistake) can be removed by the operator, never by an agent: there is no MCP
tool or REST route for it.

```sh
pseudolife-mcp board-audit redact --message-id <id> --reason "pasted a credential"
```

`--message-id` takes the full id or a unique prefix of 8 or more characters
(an ambiguous one is refused naming the candidates). A message sent to a
project or to `all` is one copy per recipient: redacting one leaves the
others, so the result lists them as `other_copies` (and says so on stderr);
redact each. In one transaction it blanks the `send` row's `body` and `body_salt`, blanks
the live copy in the mailbox if prune has not already and ends its delivery,
and appends a
chained `redact` row (actor `operator`, the message's agents, project and task,
and a payload naming the message, the `send` row's `seq`, the reason and
`audit_copy: removed`). After the commit it runs `VACUUM (ANALYZE)
coordination_events, coordination_messages` and `VACUUM pg_statistic`: the old
row versions that still hold the body are freed for reuse, and the planner
statistics are rebuilt, since `ANALYZE` copies sampled column values under
1 kB (bodies, salts, live texts, request fingerprints) word for word into
`pg_statistic`, where they would otherwise stay until the next automatic
analyze. It prints one JSON result, `{"ok": true, "message_id", "seq",
"redact_seq", "redact_hash", "expect_head", "live_body_cleared", "audit_copy",
"vacuumed"}`, and exits 0. Record `expect_head` outside the bank, as for
`verify`: a later `verify --expect-head` with it shows the redaction's own
record is still there. A failed vacuum does not undo the redaction; the result
says `"vacuumed": false`, and you can run both `VACUUM`s later. It says the
same, and prints Postgres's warning, when Postgres skipped a step instead of
failing it: a role that may not vacuum or analyze a table gets a warning and a
skip, and a skipped `ANALYZE` leaves the body in the statistics, so run the
two `VACUUM`s as the tables' owner or a superuser.

A message sent before v46 has its body inside the hashed payload, which cannot
change: that audit copy stays until retention removes the `send` row. While
its live copy is still in the mailbox (up to 24 hours), `redact` blanks it and
takes it out of delivery all the same, logging `audit_copy: kept`, and says so
on stderr. With audit retention under seven days, a message's `send` row can
go before its mailbox row's request fingerprint does; `redact` still blanks
that fingerprint (and any live text), logs `audit_copy: gone` with `"seq":
null` in the payload and the result, and says so on stderr.

It refuses, printing `{"ok": false, "message_id", "reason"}` and exiting 1,
when neither the log nor the mailbox has the message (`message_not_found`: an
unknown id, or one whose `send` row retention removed and whose mailbox row is
gone too), when the message was sent before
v46 and its live copy is gone (`body_in_hashed_payload`), when the body is
already redacted (`already_redacted`), or when `--reason` is blank, longer
than 240 characters, holds a control, format or line or paragraph separator
character (`invalid_reason`), or looks like a credential (`secret_like_body`).
It exits 2 when it could not run: the board busy (a row or the audit chain
locked for more than 5 seconds; nothing changed, retry), or a bank whose log
predates v46. It takes the same locks as the daemon's own board writes, so it
is safe beside a running daemon; in the Docker tier run it inside the daemon
container as for `verify`.

What redaction does not reach: audit copies of bodies sent before v46; full
backups, WAL archives and `--out` exports taken earlier, which still hold the
body (restoring such a backup brings it back, so redact again after a
restore); the database's write-ahead log until the server recycles it; row
versions a still-open snapshot (a long `export`) or a replication slot keeps
the vacuum from freeing; the bytes of freed row versions, which a vacuum
marks for reuse but does not overwrite (`VACUUM FULL` rewrites a table); the
superseded statistics row, when the role running `redact` may not vacuum
`pg_statistic` (reported as above; autovacuum frees it later); and whatever
the recipient already read. What stays in the bank
cannot confirm a guess of the body: the `send` row keeps only its salted
commitment, and the salt goes with the body; the mailbox row's request
fingerprint (a sha256 over the recipient, body, reply and expiry, kept seven
days for retries) is blanked too, so a retry of the redacted request is
refused as `request_conflict`. The reason is hashed into the chain for good;
describe the mistake, never repeat the secret.

#### Secret-shaped text

The board refuses text shaped like a credential wherever it would keep it: a
message body and its request id (`send`); a status, label, project, task,
episode or capability name (`register` and `update`, including
`memory_agents update`; project and task are copied into every later audit
row by that agent); a lease name
or purpose (`lease`, `release` and `leases`, including `memory_agents claim`,
whose status is the purpose); and a redaction reason. The call fails with
`secret_like_body` (HTTP 400 on the REST API) before the text is stored
anywhere, and the error never repeats the text. (The daemon's own
once-a-minute prune pass may run first on `register` and `send`; it involves
no caller text.)

The shapes are GitHub tokens (`ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_` with 36 or
more characters, `github_pat_`), GitLab `glpat-`, Hugging Face `hf_`,
Anthropic `sk-ant-`, OpenAI-style `sk-` and Stripe `sk_live_`/`rk_live_` keys,
Google `AIza` API keys, AWS access key ids (`AKIA`/`ASIA`) and secret access
keys, Slack `xox` tokens, JWTs, a `Bearer` token, the password in a DSN
(`postgresql://user:<password>@host`), PEM private-key headers, and a key
whose name contains `secret`, `token`, `password`, `passwd`, `credential`,
`key`, `auth` or `bearer` (such as `PSEUDOLIFE_MCP_TOKENS`,
`X-PL-Agent-Key` or `private_key`) given a generated-looking value after `:`,
`=` or, for a `--flag`, a space. A value is split at `,`, `:` and `=`, so each
token in a principal map (`name:token,name:token`) counts on its own, and a
piece counts when it is 20 or more characters of letters and digits with
lower case, upper case and digits all present, or 32 or more in one unbroken
run (no `_` or `-`, which word-joined identifiers have).
Where a prefix also starts ordinary identifiers (`ghs_`, `github_pat_`,
`sk-`), the rest must look generated too. Not refused: ordinary prose about
tokens and secrets; git SHAs, digests (whole or truncated), UUIDs, message and
agent ids; anything with a `/` after a key (paths, branches, `owner/repo`);
names, words, word-joined identifiers and counts; placeholders (`<token>`,
`$VAR`, `${VAR}`). Single-case passwords shorter than 32 characters get
through; this is a net for common
shapes, not a guarantee, and a v46 body it misses can still be redacted. Over
the 2026-09-23/24 fifteen-session trial's board export it refused none of the
816 message bodies and request ids, the 25 statuses, or the labels, projects,
tasks and episodes of its 26 agents.

### Coordination report

`evals/coordination_report.py` turns a board record into an aggregate-only
report, the measure a coordination change is judged by: a change should beat
the committed baseline of the 2026-09-23/24 trial
([artifact](../../evals/results/coordination-baseline-20260924.json)) by more
than night-to-night noise. One night is a reference point, not an interval:
that noise stays unmeasured until a second comparable night is reported. The
report reads an audit export, or the older whole-board export the trial was
recorded in, and writes a new JSON file plus a Markdown rendering beside it. It
never replaces either without `--force`, and never its own input:

```sh
pseudolife-mcp board-audit export --out board.jsonl
python -m evals.coordination_report board.jsonl --out night.json \
  --since 2026-09-26T16:00+10:00 --until 2026-09-27T08:00+10:00 \
  --window "evening=2026-09-26T16:00+10:00/2026-09-26T21:30+10:00"
```

Export the whole log and scope the report with `--since`/`--until` (messages
by send time; staleness is measured at `--until`). The report still reads the
registrations and statuses set before the scope, which an export filtered at
the source drops: it flags such an export (a gap in its sequence, or a start no
retention cut anchors). In a filtered export, a recipient that registered
before the cut and did not act after it appears under the principal `unknown`,
and staleness counts the agents with no status event.

It reports acknowledgement latency (median, p90, acknowledged and never
acknowledged) per recipient principal, overall and in each `--window`
(`LABEL=START/END` by send time, epoch seconds or ISO 8601 with an offset,
either side may be left open); the share of acknowledgements that covered three
or more messages at once; each directed pair's busiest 60 minutes; near-identical
fan-out bursts; the kind mix; SUITE-START/SUITE-END traffic and baton passes;
status staleness from an audit export (the older export has no status history),
leaving out detached and revoked sessions, whose statuses no peer is shown; and
resources agents coordinated by hand repeatedly, listed as candidate lease
declarations with counts only. Every metric carries its definition in the
output. Wakes per session-hour, requests past their reply-by time and the time
to answer a NEEDS-HUMAN message are `null` until the schema records what they
need.

The kind mix uses a message's declared `kind` when the event carries one and
otherwise a tag-first heuristic over the body, hand-calibrated on the trial and
marked `heuristic` in the output. Some of its rules depend on which agent
coordinates: `--coordinator auto` (the default) picks the agent with the most
distinct counterparties, `none` turns those rules off, and an agent id names
one.

The report is aggregate-only by construction. Bodies, labels, statuses, tasks,
projects and paths are matched against fixed keyword lists in memory and only
counts are written; agents appear as `<principal>-<n>` in first-seen order, and
no raw id or input path reaches either file. A principal is written by name
only when it is one of the installer's role names (`default`, `claude-code`,
`claude-desktop`, `codex`, `gemini`, `mcp-client`); any other is written as
`principal-<n>`, because an operator-chosen principal can be a username or a
host. `--keep-principal NAME` keeps one you know to be a role. Window labels are
limited to 40 letters, digits, spaces and `:._+-`. The input itself stays
private.

### Delivery and recovery

Use ordinary `pseudolife-mcp` for authenticated pull messaging. The optional
`pseudolife-mcp channel` mode also requires `PSEUDOLIFE_AGENT_WAKE=1` to emit live
events, plus the host's preview launch opt-in. The cached coordination digest
can appear in tool responses (once per change, then a one-line reminder every
tenth call); attaching it adds no network request to the tool path and never
acknowledges mail. Optional adapter startup requests cancellation after three seconds, then waits
for bounded in-flight request cleanup before falling back to ordinary memory
service. This is not a three-second ceiling on total shim startup time.

Messages have one recipient. Sending confirms durable enqueue; receiving does
not acknowledge. The recipient explicitly acknowledges a message ID, and an
acknowledgment does not mean the requested work is complete. Retries reuse the
same sender request key and content. Coordination traffic is not added to bands,
cortex, graph, retrieval or dream input by the messaging APIs. Store a useful
decision explicitly as ordinary memory if it should become durable knowledge.

Initial limits are 8192 UTF-8 bytes per message, 256 pending messages per recipient,
60 new sends per sender per minute (a send to a project or to `all` counts as
one, so a sender can reach at most 60 × 50 mailboxes a minute) and 50 messages
per receive page. Bodies stop
being served after 24 hours; request-key metadata is retained for seven days.
The [audit log](#audit-log) keeps its own copy of every body for
`audit_retention_days`, unless the operator [redacts](#redacting-a-body) it.
Text shaped like a credential (a body, request id, status, scope field, or
lease name or purpose) is refused with `secret_like_body`
([secret-shaped text](#secret-shaped-text)).
Opportunistic pruning runs at most once per minute during registration, sending
or heartbeats. Expired bodies remain unservable even when no adapter is running
to trigger physical cleanup. Full queues and rate limits return explicit errors.
Live delivery attempts a message at most three times in total across
attachments; past that it is left for explicit receive, so one unacknowledged
message cannot wake the host on every restart. The same prune pass removes an
address that is referenced by no retained message and has had neither its own
activity nor a lease for seven days, or for one hour when its adapter
registered without a state file (`capabilities.resumable: false`), since
nothing can attach to that address again. A held lease keeps a live shim's
address even while it is idle, so a daemon restart or a host sleep shorter than
that window cannot retire it; if a state-less address is ever retired, its
adapter registers a fresh one instead of stopping.
Addresses that predate the flag keep the seven-day rule. Idle
means no register, update, new attachment, send, acknowledgment or forwarded
tool call: the adapter's lease heartbeat counts as activity only when the shim
forwarded a tool call since the previous one, and an adapter re-attaching under
its own attachment ID (after a daemon outage or a host sleep) is recovering its
lease, not acting, so a parked shim is neither ranked nor retained as a working
one. A client that only reads must acknowledge what it
reads, or hold a lease, to stay registered. `memory_agents(action="list")`
shows peers active within the last hour, or within the last three hours while
they hold a lease, leased first; it reports the number of other matching peers
as `idle_omitted` and sets `truncated` when the page cut listed peers; a peer's
public agent ID stays addressable while its row exists. Each listed peer
carries `status_set_at`, `status_age` and `status_stale`. The time comes from
the [audit log](#audit-log): the newest registration or status update. A status
the log no longer covers is reported as older than the log's oldest event, for
example `more than 21 hours ago`. A non-empty status older than two hours is
marked stale. The two-hour and three-hour windows come from the first day of
the live audit log (2026-09-25). Working agents refreshed their status within
34 minutes at p95 and never went more than 51 minutes between board actions
inside a work block. Idle stretches ran 5.4 hours or longer.

Claude Desktop's app-level entry (writer ID `claude-desktop`) is one process
serving every conversation in the app, so it registers no coordination
address: whichever conversation called it would post, set status and read
mail as all of them. It refuses `memory_agents` `update`, `claim` and
`release`, and `memory_message`, with an error saying why, prepends the same advice to its MCP
instructions, and its `memory_agents(action="list")` shows open sessions only,
not the board. A Claude Code session makes those calls on its own per-session
server. In the Desktop app's Code tab that works only while the two entries have
different names: the installer registers both as `pseudolife-memory`, and
where the names match, Desktop serves the Code tab from its app-level entry.
The writer ID is operator configuration, not authentication: the guard keeps
honestly configured clients apart, while the daemon itself refuses any board
write that carries no instance credential. An
adapter with saved state registers a fresh address on its next start only when the authenticated
daemon explicitly confirms that the saved address no longer exists (pruned
after seven idle days with no retained mail, or absent from a restored
database, where `rebind` cannot restore it either). A bank-bound client first
verifies that the daemon is still its saved bank and principal. It keeps
the old state file beside it with a `.stale` suffix. A rejected bearer or instance
credential, or a different bank or principal, preserves the saved address and
requires corrected authentication or the deliberate restore/rebind procedure;
an HTTP status alone never proves that an address should be replaced.

A subagent that a Claude Code session spawns with its Agent tool runs in the
same shim process, so its board calls carry the parent's identity (probed
2026-09-27: the subagent's `memory_agents(action="list")` left out the parent's
own row, as the list does for the caller, and its receive returned the
parent's cursor). Nothing in the shim can tell the two apart: a subagent's
status update overwrites the parent's, its `ack` marks the parent's mail read
before the parent sees it, and its `send` goes out under the parent's name. So
a subagent only reads the board (`memory_agents(action="list")`,
`memory_message(action="receive")` without `ack`, `memory_search`), and the
orchestrating session owns the address. The served check-in says so. The
subagents get no addresses of their own: the parent names them on its own row
with `memory_agents(action="update", children=["review storage", "tests"])`, at
most 8 labels of at most 40 characters. Peers see them as `children`, a list of
`{label, since}` in which the daemon stamps `since` and keeps it for a label
the next update carries over. Omitting `children` leaves it unchanged and `[]`
clears it; a children-only update does not move `status_set_at`.

### Park records and the wake decision

A session that stops records why, so a peer's mail can wake it only when the
mail clears what it is waiting for (schema v49, maintainer decision
2026-09-28: on 2026-09-27 a session sat all night on a blocker that had
cleared, while any message could wake a session with nothing to wait for).
The **park record** lives on the agent row and is set through
`memory_agents(action="update", ...)`:

| Field | Meaning |
| --- | --- |
| `park_reason` | `done`, `blocked`, `needs_approval`, `needs_info`, `needs_resource` or `waiting_peer`; `""` (REST: `null`) clears the whole record |
| `park_needs` | What would clear it, one line (120 characters) |
| `park_clear_by` | Who can: an agent id, `maintainer`, a lease name, or `anyone` (120) |
| `park_resume` | What to do once cleared (240) |
| `park_expires` | An epoch after which the park no longer stands; a park set without one expires after 12 hours, and none may be more than 7 days ahead (`invalid_park`) |

An omitted field stays; a refinement or a new reason keeps the standing
expiry. A park past its `park_expires` no longer stands: a new reason over
it is a new park, with the 12-hour default counted from then and none of
the lapsed park's `park_needs`, `park_clear_by` or `park_resume` carried
over. A plain status
update while parked clears the record,
since a session that is working is not parked; a task or `children` update
leaves it. A park field on its own refines a standing park and is refused
(`invalid_park`) on an unparked row or a lapsed park, as are an unknown
reason and a bad expiry; credential-shaped text is `secret_like_body`. Every peer row in
`memory_agents(action="list")`, and the caller's own row in the update result,
carries the six `park_*` fields, `park_set_at` being the daemon's stamp.
`memory_agents`' description asks sessions to park when they stop, and the
[Stop hook park gate](#waking-an-idle-claude-code-session-the-stop-hook) asks
once when a turn ends without one. (The served check-in does not say it yet:
it is the text the check-in bench measured, and changes only with a new run.)

**The daemon decides, the shim rings.** `memory_message(action="send")` takes
two optional fields, `clears` (which parked need the message answers, 120
characters) and `urgent`, and returns `wake` beside the receipt:

| `wake.decision` | When | Extra fields |
| --- | --- | --- |
| `hinted` | the recipient is not parked and acted on the board within `active_seconds`; its next tool result carries the mail (a parked session has stopped, so it is decided on its park however recently it parked) | |
| `not_needed` | the recipient is parked `done` | |
| `no_path` | the recipient has no wake path: no live channel (`wake_enabled: false`) and no ring path declared at attach | the parked need, if any |
| `rung` | parked with a need the mail plausibly clears: the sender is `park_clear_by` (or, when that names a lease, released it or let it expire within the last 60 seconds, by the daemon's audit log; never for `maintainer`, an agent id or an id prefix), `park_clear_by` is `anyone`, `clears` names the need (the same words, or one's words as a run of whole words inside the other's, holding a word of four letters or more), or `urgent` within the sender's cap | `ring_at` |
| `withheld` | parked with a need the mail does not clear | `park_needs`, `park_clear_by` |
| `nudged` | idle with no park record (or an expired one), rung at most once per `nudge_interval_seconds` with a request to park | `ring_at` |
| `capped` | over a cap: `reason` names it (`recipient_hour`, `nightly`, `urgent_sender_hour`, `nudge_hour`) | the parked need, if any |

`reason` says which branch decided (`active`, `parked_done`, `wake_disabled`,
`clearer`, `anyone`, `clears`, `urgent`, `need_not_cleared`, `no_park`, or a
cap). Chatter never rings. A retry of the same `request_id` repeats the first
decision, and the audit log's `send` event names it. Rings from one sender's
burst are staggered by `fan_out_stagger_seconds` through `ring_at`. Each ring
is a `coordination_wakes` row; the recipient's attach and heartbeat answers
carry the newest for one heartbeat interval after it is first served
(`wake`, with the latest `ring_at`), so a retried heartbeat still gets it,
and the adapter takes each ring once. A wake path is a live channel or a
**ring path**: an adapter declares at register and at every attach whether
a ring reaches it without a channel (`ring`, kept in `capabilities`; the
Claude shim when it has a digest for the Stop hook, a Codex thread the
doorbell watches). A daemon older than v49 refuses the attach parameter
once, and the adapter stops sending it. The shim rings through its client's
path: the Claude adapter writes
`<key>.ring` beside the digest (line 1 the digest watermark, line 2 the
decision and reason) at `ring_at` for the Stop hook, and the Codex doorbell
asks the adapter for a due ring at the moment it would otherwise run
`codex queue` (an offer whose mail the session has already seen, or that
has nothing pending, is dropped). Every ring's ledger line (`ring` from the adapter, `wait` from
the Stop hook, `bell` from the doorbell) carries the decision and reason as a
sixth column. Against a daemon older than v49 nothing rings; pull delivery,
tool-result hints and the prompt-hook digest are unchanged.

`pseudolife-mcp channel` is the optional Claude Code preview transport. Host
delivery requires explicit preview opt-in and recipient wake configuration;
protocol tests alone do not establish compatibility with an installed host.
Only addressed messages may wake an opted-in recipient, and since v49 the
live channel carries only mail the daemon decided to ring (`rung`,
`nudged`) or hinted to an active session, plus mail sent before v49; mail
it withheld, or found not needed, waits for an explicit `receive`, which
still returns everything. Board/status activity
and receipts do not produce conversational wake-ups. Each live event carries a
fixed agent-origin header, built from daemon-verified sender fields, ahead of
the peer's text. Explicit receive labels each message with `origin: agent` and
includes a note that peer requests cannot grant user approval. Other clients use explicit,
authenticated mailbox retrieval where their adapter supports it; live receiving
support is not assumed from a host's native send tool.

On Claude Code 2.1.267, a first channel-triggered turn after startup or resume
can arrive before the host makes MCP reply tools usable. A successful MCP
initialization or tool-list response does not establish model readiness. If the
host reports an unavailable messaging tool, send an ordinary prompt, confirm a
successful `memory_agents` call, then use `memory_message(action="receive")` to
recover pending mail. A failed reply or transport attempt never acknowledges it.
The experimental adapter does not promise unattended startup recovery.

An outage that exhausts a request's bounded retries pauses background delivery,
clears the cached unread count and prints a warning to stderr once per outage.
Ordinary tool responses carry a degraded-delivery hint, including for pull-only
adapters, and explicit receive keeps working on the same shim as soon as the
daemon answers, provided the caller remains authorized. The adapter's heartbeat
task re-attaches on its own after transient failures, with backoff
(1 s rising to 60 s, held until a heartbeat or receive succeeds), resumes the
lease while it is still valid or takes a new generation once it has expired,
replays unacknowledged mail from the start of the mailbox for a new generation,
and prints a restored notice. Recovery waits for the next retry after the daemon
becomes reachable. A generation change invalidates an older receive page even
when it happens between yielded messages; the old page cannot advance the new
generation's replay cursor. An explicit authentication or identity rejection
preserves state and stops retries with the rejected credential. File-backed
clients observe the credential source and resume after a replacement authenticates
to the saved bank and principal. An authority mismatch remains closed until the
credential again matches the saved authority; it never creates a replacement address. A
saved address the daemon reports missing while the shim runs (the host slept or
the daemon was unreachable past the seven-day retention) also stops background
delivery and keeps the state file, but the notice says to restart the session:
`rebind` cannot restore a missing address, and the next start retires the state
and registers a new one. Do not
infer live delivery from a queued or attempted send result.

If initial registration fails, or the shim's startup budget cancels it before
the adapter receives the new address, the adapter releases its empty state
reservation and the next launch registers a fresh address; it never retries
inside the same start and never overwrites a state file that already holds an
identity. An address the daemon created for a lost response was never held by
any adapter, receives no mail, and is pruned with the other idle addresses. Do
not revoke every mailbox to repair one failed registration. A lost attachment
response can leave a lease until expiry; failed competing attachment attempts
do not renew it.

A crash-left empty state file becomes eligible for takeover after one minute.
Takeover uses an owner-only sibling `.lock` file and a nonblocking operating-system
lock, so concurrent launches cannot both register against that stale reservation.
The lock file remains on disk; lock ownership is released when the process exits,
including a crash. Do not delete it while an adapter might be using it.

Full database backups contain coordination mail and the audit log. Portable `export`/`import`
archives omit the coordination tables (agents, mail, leases, rings and the audit log) and their clock metadata so moving
knowledge cannot clone live mailboxes or instance credentials. Follow the
[offline mailbox recovery procedure](coordination-recovery.md) after a database
restore. See the [experimental design](../specs/2026-09-11-agent-coordination-design.md)
for delivery-state and host-verification contracts.

### Waking an idle Claude Code session: the Stop hook

Mail otherwise reaches a Claude Code session only at its next memory call or
prompt, so an idle session can sit on a message for hours. The plugin ships a
`Stop` hook that waits on the session's digest after every turn and wakes the
session when mail that should wake it arrives. It is on by default since
2026-09-28 (before that, opt-in with `PSEUDOLIFE_AGENT_WAKE_HOOK=1`); set
`PSEUDOLIFE_AGENT_WAKE_HOOK=0` in the hook's environment to turn it off (for
example in the `env` block of `~/.claude/settings.json`, which Claude Code
passes to the processes it starts), and `PSEUDOLIFE_AGENT_COORDINATION=0`
there turns off the whole board for the client, hook included. The hook's
command checks both flags before bash reads the script, and refuses a script
that does not parse, so a broken copy cannot wake every session at every turn
end. It needs the coordination adapter above, since it waits on the digest
file the adapter writes: without a digest directory it exits at once. It also
needs a Claude Code release that honours `asyncRewake` (verified on 2.1.280);
one that ignored `async` would run it in the foreground and hold each turn end.

A wake lets a peer allowed to mail this session start a model turn in it
while you are away, in whatever permission mode the session runs; peer text
still cannot grant approval. That is why wake is policy-gated: the daemon
rings a session only while it is parked with a declared need that the message
plausibly clears (the sender is the one it named, the message is tagged
`clears=<need>`, or the sender set `urgent`), and never for chatter. Every
wake spends tokens, and two sessions can keep waking each other, so wakes are
also capped (below, and by the daemon's `wake` caps under
[Experimental agent coordination](#experimental-agent-coordination)).
`pseudolife-mcp doctor` reports the hook's state under `wake.claude_code`.

- The hook runs with `"async": true` and `"asyncRewake": true`: in the
  background after each turn, and exit code 2 starts a new turn even when the
  session is idle. Verified in the Desktop Code tab on Claude Code 2.1.280, in
  auto permission mode (under a second from exit to the new turn). Claude Code
  labels the delivery "Stop hook blocking error"; that label is the wake, not
  a failure. The reminder is one line saying so, then the digest, which reads
  as agent-origin, not user authority.
- It fires on a ring the daemon decided (v49): when the shim's `<key>.ring`
  marker is past the `.seen` marker, the digest's watermark is past it too
  and the digest lists mail. The shim writes the marker for `rung` and
  `nudged` mail only ([the wake decision](#park-records-and-the-wake-decision)),
  so chatter to a parked session, mail the daemon withheld, and a digest
  that merely changed (an acknowledgement, an expiry) do not wake the
  session. A ring for mail that arrived during the turn fires at once; a
  digest the session already saw (through the prompt hook, the tool-result
  hint or an earlier wake) does not fire again at the next turn end. A
  nudge adds one sentence to the wake text asking for a park record. Firing
  advances `.seen` and appends a `wait` line to `ledger.log` whose sixth
  column is the ring's decision and reason; if the marker cannot be
  written, the hook does not wake at all. SessionStart clears `.seen` on
  resume and compact, so a pending ring can wake the session once more.
- At most 20 wakes per session in any hour, the same figure the daemon now
  applies per recipient before it decides a ring. A ring over the hook's
  cap waits for the window to free up; it is delayed, not dropped.
- **The park gate.** Before arming the wait, when the turn that ended is not
  itself a Stop-hook continuation (`stop_hook_active` is false) and the shim
  has named this session's board address in `<key>.agent`, the hook asks the
  daemon once, `GET /api/hook/park-gate?agent=<id>&since=<turn start>` (2 s,
  the start from the `<key>.turn` stamp the prompt hook leaves), whether
  the session parked. The daemon answers `block` when the row has no live
  park record and its status is not done-shaped (it does not start with
  done, complete, finished or merged), or when the session set no status or
  park during the turn; the hook then ends the turn at once with "Before
  ending: update your board status with why you stopped and what you need
  (memory_agents update park_reason=... park_needs=... park_clear_by=...
  park_resume=...)" as the wake text and a `gate` ledger line (its fifth
  column is the message's length in UTF-8 bytes plus one, on every client).
  Once: the continuation's Stop carries `stop_hook_active: true` and is not
  asked (Claude Code also caps stop-hook continuations at eight in a row).
  An async Stop hook cannot use the `decision: "block"` JSON, so the block
  rides the same exit-2 rewake as the mail wake. No answer (a daemon that
  is down, a bearer it refuses, a redirect, an answer cut off at the time
  limit, no address) is allow: the gate never holds a turn on an error.
  The bearer comes from `PSEUDOLIFE_MCP_TOKEN` or a private
  `PSEUDOLIFE_MCP_TOKEN_FILE` (owner-only, one link, the same check as the
  other hooks), the URL from `PSEUDOLIFE_MCP_DAEMON_URL`, as for the other
  hooks. On Windows, Git Bash uses the native ACL rules: current-user
  ownership, a protected DACL, and allow rules only for the owner or OWNER
  RIGHTS; reparse points in the file or its parents are rejected. A token
  file rejected by the Stop gate or coordination-start hook leaves a `token`
  line with value `rejected` in the digest directory's `ledger.log`, without
  a path or token. OneDrive-redirected profiles using reparse points are
  rejected: move the token file outside the redirected folder and update
  `PSEUDOLIFE_MCP_TOKEN_FILE`.
- One watcher per session: each turn end takes the lease in `<key>.wake`, and
  the previous watcher exits within one poll (5 s). A digest file absent when
  the watch starts is waited for; one that vanishes during it (the shim
  exited) ends the watch. After `/clear` it reads the
  digest named by the per-process `claude-<pid>.host` record, when
  SessionStart has written one.
- A watcher waits at most 3540 s after the turn that armed it; the hook's
  `timeout` is 3600 s, which Claude Code enforces on `asyncRewake` hooks.
  `PSEUDOLIFE_AGENT_WAKE_HOOK_WAIT` (seconds) shortens it. A session idle for
  longer is not woken; its mail still appears on its next prompt. The watcher
  also stops when Claude Code exits: at once on Linux and macOS, and within
  a minute on Windows, where it lists the process through `ps -W` at arm
  time and then once a minute (a Windows PID is invisible to `kill -0`). In
  `claude -p` runs, Claude Code ends a waiting hook at teardown.
- Codex loads the same `hooks.json` and gets only the park gate, on every
  platform: on Windows through the entry's native command
  (`lifecycle.ps1 -Event Stop`), on macOS and Linux through the same bash
  script, which recognises Codex context the way the other bash hooks do
  (`PSEUDOLIFE_CODEX_HOOK=1`, or `PLUGIN_ROOT` equal to
  `CLAUDE_PLUGIN_ROOT`), unless Claude Code started the hook for its own
  session (`CLAUDECODE=1` and `CLAUDE_CODE_SESSION_ID` equal to the
  payload's id), which always stays Claude's. This is the plugin install:
  a manual Codex install (`ops/setup-codex-hooks.py` without the plugin)
  has no `Stop` hook, so no gate. Either path makes the same one request,
  through the managed connection file under the Codex home or the explicit
  daemon
  settings (with the other hooks' checks: an explicit URL may not disagree
  with the managed one, the bearer file must be private), and returns a
  block the way Codex documents for `Stop`, `{"decision": "block",
  "reason": <the message>}` on stdout with exit 0, which Codex turns into a
  continuation prompt, plus the `gate` ledger line; allow, no address, a
  continuation's Stop, or no answer prints nothing. The wake itself stays
  Claude Code's: in Codex context the script exits after the gate and never
  arms the wait (the [doorbell](#codex-doorbell) is Codex's wake path). An
  explicit `PSEUDOLIFE_AGENT_WAKE_HOOK` or `PSEUDOLIFE_AGENT_COORDINATION`
  of `0`, `false`, `no` or `off` turns it off. Whether Codex honours the
  decision of a hook declared `async` has not been probed on a live install.
  `ops/setup-codex-hooks.py` approves it with the other three definitions
  (see [Codex specifics](providers.md#codex-specifics)).

## Startup memory policy (`memory_policy`)

Which standing memory policy the session-start hooks serve. The default is
the short core the memory hook has served since 2026-09-24; the other
variants exist so their effect on agent behaviour can be measured
(`evals/memory_policy_bench.py`) rather than argued.

```yaml
memory_policy:
  variant: compact          # none | compact | full_separate_hook
  ab_arms: []               # e.g. [compact, full_separate_hook] for an online A/B test
```

| Variant | What session start serves |
|---|---|
| `none` | No policy text. The episode line and the briefing still serve; the cold-bank onboarding block, which names memory tools too, does not. |
| `compact` (default) | The short core, ahead of the briefing, in the memory hook's output. Since 2026-09-25 it restates three of the full block's rules: search before stating a "current" version, number or benchmark; correct memory-vs-code drift on the spot; route verified external facts to `memory_world_set`. |
| `full_separate_hook` | The full memory-loop block ([`examples/CLAUDE.memory.md`](../../examples/CLAUDE.memory.md), 7.5 KB), served by a separate SessionStart output (`GET /api/hook/memory-policy`), because the block plus the briefing exceed the 9,500-byte budget of one hook output. |

The separate output is the plugin's third SessionStart handler
(`session-start.sh memory-policy`, or `lifecycle.ps1 -Event MemoryPolicy` in
Codex on Windows); `ops/setup-codex-hooks.py` installs and approves it for
manual Codex hooks too. For every other variant it answers an empty body and
adds nothing. The `install-hook` scripts' settings hooks do not carry it, so
`full_separate_hook` serves no policy to those installs.

Every variant's policy text is served once per conversation. On a resume or a
compaction (SessionStart `source=resume|compact`, forwarded by the plugin's
hooks) neither output re-sends it: the main output keeps the drift notices,
the episode-handle line and a pointer to the full briefing (after a
compaction, also a custom `hook-instructions.md`, which nothing else
carries), and the separate output adds nothing.

`ab_arms` assigns each session the SessionStart hook registers one arm, by a
SHA-256 of its client session id modulo the arm count; a variant may repeat
for an A/A arm. Sessions that reach the hook without a session id keep
`variant`. Each registration records the variant it served in the
session's `client_sessions` row (schema v43, see
[Episodes](episodes.md#session-record)), which outlives the session's root,
so an online comparison can be read from the bank for every hook-registered
session, including those that stored nothing (`evals/capture_metrics.py`
reports sessions per variant). A custom `hook-instructions.md` is served in
every variant.

## Built-in defaults (tuned for Claude's use case)

- **Embedding backbone `Qwen/Qwen3-Embedding-0.6B`** (`EmbeddingConfig.model_name`,
  default since schema v25) — torch on the CPU, no GPU sidecar, in the
  precision `EmbeddingConfig.cpu_dtype` picks: `auto` (the default) loads
  the model straight into bf16 when the CPU has native bf16 (x86
  AVX512_BF16 / AMX_BF16) and uses fp32 otherwise, since bf16 without
  native support is slow; `fp32` / `bf16` force one. Measured 2026-09-23 on
  the production image, bf16 held ~1.4 GB steady vs ~2.85 GB for fp32, and
  on 400 real bank entries bf16 queries against stored fp32 vectors kept
  top-8 overlap 0.994 and rank-0 60/60, with the regression gate scoring
  every arm identically to its fp32 baseline
  (`evals/results/embedder-cpu-bf16-probe-20260923.json`). The default
  applies everywhere the embedder runs, evals included: an eval on a
  native-bf16 CPU embeds in bf16. Vectors are stored as float32
  either way. `PSEUDOLIFE_EMBEDDING_CPU_DTYPE` overrides the config value;
  `/health` reports the resident `embedder.dtype`. It's
  instruction-asymmetric: query-side text (search/recall probes) is encoded
  with `EmbeddingConfig.query_prefix`'s instruction prefix via
  `encode_query()`; everything stored (entries, fact/world/lesson claim
  text, slot and entity-name embeddings) is encoded bare via `encode()` /
  `encode_single()`. `query_prefix` defaults to the Qwen3-Embedding card's
  exact instruction string — set it to `""` to restore symmetric behavior
  for a model (like the previous default, `all-MiniLM-L6-v2`) that doesn't
  distinguish query/document sides. `max_seq_length` caps the tokenizer at
  512 tokens (a min-with-model-default cap, never a raise) regardless of
  the model's native context window. See
  [asymmetric query/document encoding](retrieval.md#asymmetric-query-and-document-encoding)
  for what this changes about retrieval, and the
  [schema version history](#schema-version-history) below for the v25
  cutover itself.
- **ONNX acceleration is load-only** (`EmbeddingConfig.backend = "onnx"`).
  The MCP defaults select it only when the optional ONNX stack is installed
  *and* the loader would load it: the configured model's artifact already
  resolves locally, and, on native Windows, the model's Transformer module
  does not load from a nested subfolder (see the end of this item).
  Otherwise they choose torch up front and log one INFO line saying why. One
  deliberate exception: an `onnx_file_name` that fails validation (for
  example, one that leaves the model directory) keeps ONNX selected, so the
  loader's warning names the bad setting instead of hiding it. The
  default Qwen3-Embedding-0.6B ships no ONNX artifact, so the daemon runs it
  on torch; MiniLM, whose artifact the daemon image bakes, still gets ONNX.
  An explicit `embedding.backend` is never overridden: `backend: onnx`
  without a loadable artifact still warns and falls back to torch at load.
  `EmbeddingConfig.onnx_file_name` defaults to
  `onnx/model.onnx`; that exact artifact must already exist in a local model
  directory or a revision-specific cached Hub snapshot. A missing artifact falls
  back to torch before SentenceTransformers constructs its ONNX backend, in
  online and offline processes alike. The daemon never downloads ONNX artifacts
  at runtime. The daemon image provisions MiniLM's while building
  (`ops/provision_embedding_models.py` is the reference for how); a pip install
  stays on torch unless the operator puts `onnx/model.onnx`, or whatever
  `onnx_file_name` names, into the local model directory or the cached Hub
  snapshot. Each supported Transformer module must have the artifact in its own
  configured subdirectory; a root-level file does not cover a missing module
  artifact.
  Standard Transformer, Pooling, Normalize and Dense module layouts are
  recognized; unknown module classes use torch. Filenames must end in lowercase
  `.onnx` so validation matches the loader on case-sensitive filesystems.
  No validated ONNX artifact path or `modules.json` may traverse a link between
  the model directory and the file, because the loader's discovery glob does not
  descend into linked directories — a link that stays inside the model directory
  still hides the artifact and re-enables export. The one accepted link is a Hub
  snapshot's leaf link, and only after local-only Hub cache resolution and only
  when it targets that cached repository's own `blobs` directory. With the
  pinned Optimum stack, native Windows does not detect an artifact under a
  nested module subfolder such as `0_Transformer/onnx` and enables export, so a
  model whose Transformer module loads from a subfolder falls back to torch
  there before ONNX construction. A flat `onnx` subfolder resolves on both
  platforms, and the load-only ONNX path remains available in Linux and the
  daemon image.
- **Surprise threshold `0.0`** — the v0.5 store gate measures *novelty*
  (`1 − max cos` to existing entries). Claude stores deliberately, so the
  gate stays permissive (store everything; novelty still drives
  eviction scoring at capacity). Raise it above zero to dedup
  near-duplicate stores. Detected potential conflicts bypass this gate so
  low-novelty updates can land; this does not retire an earlier source note.
- **Meta-filter off** (`memory.meta_filter.enabled = false` in the MCP
  build) — the filter exists to drop auto-captured chat noise ("I don't
  have anything saved about that"); every MCP store is a deliberate tool
  call, and the filter's patterns collided with legitimate dev facts
  about memory systems themselves.
- **Recency base half-life 24h** (`memory.recency_base_half_life_s =
  86400`, vs the 1h chat default) — Claude Code sessions are hours-to-
  days apart; with a 1h half-life the recency boost was effectively
  always zero. This knob is **doubly dormant under the flat default**:
  the depth ramp it feeds has been off since 2026-07-25 AND the ramp is
  structurally inert with one band; it only bites on a multi-band preset
  with `recency_boost_enabled = true`.
- **MIRAS preset `flat`** (default since 2026-08-15) — one band named
  `flat` at capacity 5,250 (the previous continuum's summed total), with
  a `balanced` retention policy. Eviction is a retention-scored **true
  drop** that only fires at genuine capacity: it permanently deletes the
  entry's row (superseded entries go first), is counted
  (`memory_stats().true_drops` since start; `true_drops_total` and
  `last_true_drop` all-time, kept in the `meta` table on Postgres) and
  logged as a WARNING naming the entry — a bank under real pressure is
  visible, never silent. This is the arm the preregistered flat-band
  verdict measured as tying the 8-band continuum on every gate (ranking,
  forced-eviction retention quality, real recorded queries — see the
  [benchmarks page](benchmarks.md#band-structure)), so the simpler
  structure ships. The **`continuum` preset is retained** as the one-line
  rollback: the 8-tier `working … forever` layout with promotion
  thresholds, per-tier retention policies, and the 2026-07-25 demotion
  cascade (a full band demotes into the next; only overflow past
  `forever` drops).
  **Changing the preset in either direction is safe**: hydration reseats
  every row across the new band layout in one pass (rows whose old band
  name is gone land in the first band) and **reconciles the stored band
  stamps** to the new layout, idempotently. If the bank holds more rows
  than the new preset seats, the deepest band is left over capacity and
  the count logged rather than truncated at startup — normal eviction
  drains it from there.
  **Before the first delete**: from 80% of the last band's capacity (the
  only band whose evictions are true drops) `memory_stats()` carries a
  `capacity_warning` and `/health` a `capacity_warning: true` flag. **To
  raise the cap**, switch to a custom preset that keeps the band name
  `flat` (so hydration leaves every row's band stamp alone), merged under
  the existing top-level `memory:` key of `config.yaml` — never a second
  `memory:` key — then restart the daemon:

  ```yaml
  memory:
    miras:
      preset: custom
      bands:
        - name: flat
          max_entries: 10000   # size to the daemon's RAM and latency budget
          update_interval: 1000000000
          promotion_access_count: 1000000000
          promotion_surprise: 1.1
          retention_policy: balanced
  ```

  Every resident entry costs daemon RAM (a correction briefly holds a
  second copy of the bank), and search latency grows with the bank, since
  the BM25 pool is rebuilt over every entry per query.
- **No NLI scorer.** The `cross-encoder/nli-deberta-v3-xsmall`
  contradiction model (~278 MB) is an unwired seam, not a switch: the
  `[nli]` extra and `memory.nli.*` exist for library callers who inject a
  scorer themselves, and no daemon path constructs one. The four-path
  detector — slot identity, negation asymmetry, affirmative replacement,
  state transition — is what actually runs.
- **Cross-encoder reranker off** — wired into the pipeline but disabled by
  default; enable globally (`memory.reranker.enabled = true`) or per-call
  (`memory_search(..., rerank=True)`). Details: [Retrieval](retrieval.md#cross-encoder-reranking).
- **BM25 hybrid lexical pool ON** (since 2026-07-25) — a pure-stdlib
  sparse-retrieval channel that rescues exact-keyword queries. It shipped
  disabled, which meant every eval measured dense-only retrieval; turn it
  off with `memory.bm25.enabled = false` or per-call `bm25=False`. The
  cortex-fact analogue exists but ships **opt-in**
  (`memory.bm25.cortex_enabled = false` by default — a pre-registered A/B
  measured no end-to-end benefit on facts).
  Details: [Retrieval](retrieval.md#bm25-hybrid-retrieval).
- **Depth-ramped recency boost off** (`memory.recency_boost_enabled =
  false`, since 2026-07-25) — retrieval used to scale scores by a
  `0.4 → 0.0` ramp over band depth, treating depth as a proxy for age.
  Depth is set by promotion history, which without retrieval to accrue
  access counts tracks *surprise*, not age — so the ramp could rank a
  weaker shallow match above a stronger deep one (measured: up to 18
  points on the LongMemEval naive-RAG arm). Under the flat default the
  ramp is additionally structural dead weight (one band, no depths), so
  the knob has left the Console config surface; it still applies to
  multi-band presets via `config.yaml`.
- **Superseded entries stay visible** (`memory.hide_superseded = false`,
  since v0.7.3) — an explicitly superseded entry, or one carrying a mark
  from an earlier version, is still retrievable, downranked ×0.55 to favor
  current entries over their history. Ordinary stores do not apply this
  mark merely because the detector finds a potential conflict. Keeping
  history lets the agent say "you used to have X, then
  you said Y". Set it to `true` to restore the pre-v0.7.3 hard filter;
  that filter is why a category query once missed the only entry naming
  the category, and it costs knowledge-update recall, so treat it as a
  debug/audit switch. Before 2026-07-30 this knob was mis-registered as
  `memory.show_superseded` and did nothing.
- **Abstention off** (`memory.search_confidence_floor = 0.0`) — set it
  above zero and `memory_search` also returns `low_confidence: true` when
  the top match scores below the floor and no cortex fact clears
  `memory.cortex.guard_min_score`. No value is calibrated for the current
  embedder, and the pair this guide used to recommend would flag a fifth
  of real searches whose hits agents used:
  [Retrieval](retrieval.md#abstention--confidence-floors). The dense
  relevance floor under it, `memory.search.min_score` (`0.25`), is a
  separate knob and not an abstention signal either.
- **Dream slot resolver off** (`memory.cortex.dream_slot_match_threshold =
  0.0`) — a positive cosine floor lets the dream pass map a paraphrased
  `(entity, attribute)` onto an existing slot before writing, to catch
  small-model supersession forks. ⚠️ Calibration found **no measurable
  benefit** on the benchmark (stale-leak flat; a false-merge at `0.80`):
  the residual fragmentation comes from the deterministic regex
  auto-promote, not paraphrase. Left off; enable only with the
  false-merge risk in mind. See
  [the single-writer cortex design](../specs/2026-06-19-single-writer-cortex-design.md)
  for the structural fix.
- **Constraint pinning on** (`memory.cortex.pin_constraints = true`, schema
  v35) — a fact whose `distortion_tolerance` is `constraint` is served
  AHEAD of the cosine ranking, marked `pinned: true`, when it is in
  scope: in `memory_search`'s cortex block when the query names the
  fact's entity (separator-insensitive, word-bounded), in
  `memory_recall` when the entity is a seed of the walk. A pin must still
  clear the caller's `min_score` floor, pins take at most half of `top_k`
  (best cosine first) so the ranked answer keeps the rest, and the
  payload never grows. An unlabelled bank is served byte-identically
  either way; set `false` for plain ranking.
- **Slot read telemetry on** (`memory.cortex.read_tracking = true`, schema
  v33) — every cortex slot served as an answer (`memory_fact_get` and the
  cortex-first block of `memory_search`) bumps its `slot_reads` counter,
  one small upsert per fact-serving call. Feeds the `read_audit` section
  of `memory_stats` (never-read fractions, slot coverage). Deliberately
  uncounted: internal verification lookups, and the facts attached to
  `memory_recall`/`memory_graph` neighborhoods (context, not a direct
  answer) — treat a slot's never-read status as a lower bound. Set
  `false` to disable the write; the audit section stays available either
  way (it just stops moving). Since v34 the section also carries
  `graduation_candidates`: entries served in ≥60% of the last 30 days'
  distinct sessions (once ≥8 sessions are on record) — static-context
  ("promote to CLAUDE.md") candidates; vet against the cortex before
  promoting, since the log counts serves before the handler's fact-dedup.
- **Engram cross-index on** (`memory.traces.enabled = true`, schema v13) —
  the dream links each consolidated fact-slot to the dense episodes it came
  from. Forwards, that link is where a fact came from: `memory_get`'s
  `consolidated_into` / `source_entries`. Backwards, it powers two
  read-time cautions: `re_verify` on served facts and `derived_flagged` on
  `memory_supersede` (see [Memory model](memory-model.md#how-current-is-this-fact)).
  Set `false` to silence both — the read surfaces stop paying for the
  cross-index query but otherwise serve exactly as before.
  Since schema v39, correction events for existing traces survive source
  deletion and are preserved even while tracing is off; new trace formation
  remains disabled. Re-enabling tracing can therefore surface those warnings.
  `memory.traces.retention_boost` (default `0.0`) is the separate Phase-2
  MTT-retention weight this same cross-index feeds; `0.0` is today's
  eviction behavior unchanged.
- **No HyDE / no reflection** — both rely on an LLM callback. Claude *is*
  the LLM, so the natural way to reflect is for Claude to call
  `memory_store` with a self-composed summary.
- **Auto-outcome inference on** (`memory.lessons.infer_outcomes = true`) —
  a session episode that closes with entries but zero `memory_outcome`
  calls gets up to `memory.lessons.infer_outcomes_max_signals` (default
  `3`) signals inferred from its own record on the end-of-session dream;
  see [Episodes](episodes.md#inferred-outcomes-at-session-close). Set
  either to `false` / `0` to turn it off.
- **Dream edge quarantine on** (`memory.dream.relation_quarantine_below =
  0.5`) — dream-extracted graph edges scoring below the floor are filed as
  review proposals (`source="dream-low-confidence"`) instead of entering
  the live graph. At the default this catches exactly the untyped
  `related-to` co-mention edges (confidence 0.45); typed relations (0.70)
  write live as before. Set `0.0` to disable and restore write-live
  behavior.
- **Literal-faithfulness gate on, enforcing** (`memory.dream.literal_gate
  = "enforce"`, `memory.dream.literal_gate_scope = "batch"`) — digit-bearing
  tokens in a dream claim's value (date-like spans and `~`-marked
  approximations exempt) must appear in the pull's source notes, allowing
  the legitimate re-formattings extractors produce (spelled numbers,
  hyphenated ranges/compounds, `N+` minimums); unbacked literals are
  dropped and counted (`literal_dropped`/`literal_flagged` in dream
  results). Enforcement became the default on 2026-08-02, when the
  extended matcher left the at-scale probes firing almost exclusively on
  genuinely unbacked literals — derived aggregates and imported world
  knowledge — at 1.3–1.7% of gateable claims
  (`evals/results/gate-firing-normfix-verdict.json`). `"log"` counts
  without dropping; `"off"` disables. The batch-union corpus default
  exists because derived sums and cross-note values are measured
  false-drop classes under per-note (`"source"`) gating.
- **Provenance-span gate off** (`memory.dream.span_gate = "off"`) — the
  literal gate's sibling: where the literal gate checks digit-bearing
  values, the span gate checks that a scalar claim's *quoted source span*
  actually appears in the pull's notes — fidelity-to-source, not
  trustworthiness-of-source. `"log"` counts without acting; `"contend"`
  parks unbacked scalar claims as visible contenders with a
  `span:unbacked` marker, resolvable via `memory_fact_resolve`. Ships off
  because flipping it on requires the live extraction prompt to emit
  quotes (the live v12 prompt does not).
- **Lesson-synthesis dedup on**
  (`memory.lessons.synthesis_dedup_min_similarity = 0.88`) — a synthesized
  lesson that near-matches an existing *current* lesson at a different key
  with the same polarity is silently skipped and counted (`lessons_deduped`
  beside `lesson_signals`/`lessons_written` in the dream-run row).
  Opposite-polarity matches and explicit `lesson_write` callers are never
  gated. `0` disables.
- **Lesson-synthesis batch cap** (`memory.lessons.synthesis_max_signals =
  200`) — most outcome signals one dream sweep drains. The batch commits
  its lessons, graph edges and acknowledgements in one transaction under
  the service lock, so this bounds a single daemon pause rather than the
  total work; whatever it leaves behind is picked up by the next sweep.
  A chosen bound (roughly one extractor batch), not a measured one. `0`
  drains everything pending.
- **Outcome signals kept ten years** (`memory.lessons.signal_retention_days
  = 3650`, was `30` until 2026-09-23) — the dream sweep deletes
  `memory_outcome` signals, consumed or pending, once they are older than
  this. Signals are the only evidence behind a lesson: under the 30-day
  window, 760 of the live bank's 1,618 current lessons had already lost
  every signal they came from. The log grows about 800 rows (under 1 MB on
  disk) a month.
- **Pending signals offered for 30 days** (`memory.lessons.signal_retry_days
  = 30`) — a pending signal is offered to lesson synthesis, oldest first
  and up to `synthesis_max_signals` per sweep, only while it is younger
  than this. A signal whose extraction lands no lesson stays pending and
  is offered again on later sweeps. Past this age it is kept as evidence
  but no longer offered, so a full batch of permanently failing signals
  cannot hold newer ones back for the whole retention window. The age
  counts from when the signal was recorded, not from its first attempt:
  signals never offered (synthesis off, an extractor outage or backlog
  longer than this) age out too. They stay in the table, the Console's
  loop-health tile counts them apart from the pending ones, and raising
  the value offers them again. A chosen bound (the retry lifetime the old
  30-day retention implied), not a measured one. `0` offers pending
  signals for the whole retention window.
- **Slot-index shadow verification on** (`memory.slot_index_shadow_rate =
  0.01`) — ~1% of slot-pool queries recompute the index from scratch and
  compare; divergences land in `stats()` as
  `slot_index_shadow_divergences`. `0.0` disables, `1.0` checks every
  query (dev/debug).
- **Quarantine retype on** (`memory.dream.retype_quarantined_max = 3`) —
  per-dream cap on quarantined pairs re-offered to the extractor for
  typing, shown only the notes where both entities co-occur; a typed
  answer becomes a review proposal, never a live edge. Without it the
  quarantine only accumulates. Set `0` to disable.
- **Dream-run journal retention** (`memory.dream.runs_keep = 50`) — the
  newest N dream-run rows and their pre-image journals (schema v27)
  survive; older ones are pruned on the sweep tick beside superseded-row
  compaction. The journal is what `memory_dream(action="rollback")`
  replays, so this bounds how far back a pass stays revertible — see
  [Dream runs — audit and rollback](dreaming.md#dream-runs--audit-and-rollback-schema-v27).
- **Chronicle extraction on** (`memory.dream.chronicle = true`) — the
  dream pass runs a second, dedicated events-extraction call per
  batch and stores dated occurrences into `chronicle_events` (schema
  v28); temporally-cued searches serve them as an `events` block
  (aggregation cues widen the block and add `events_total`). Default-on
  since 2026-08-12: the pipeline passed its preregistered gates and a
  2026-08-05..08-12 production soak reviewed clean. Needs Postgres; an
  events-pass failure never stalls claims. Set `false` to opt out — see
  [Chronicle events](dreaming.md#chronicle-events-schema-v28--dated-occurrences-beside-facts).
- **Session digests off** (`memory.dream.digest_enabled = false`) — when
  on, the idle dream cycle writes one narrative prose digest per closed
  session episode as a retrievable `source="digest"` band entry (never
  re-mined for facts — `digest` is in `exclude_sources`), and the
  session briefing's recap renders the digest body. The zero-start
  cursor backfills history when first enabled,
  `memory.dream.digest_max_per_cycle` (default `4`) episodes per dream
  pass. `memory.dream.digest_target_chars` (default `1200`) is the prose
  length target passed to the extractor — re-targeted from `800` to the
  length the extractor naturally writes (probe, 2026-08-27) — and
  `memory.dream.digest_context_chars` (default `24000`) caps the
  per-call session context, with longer sessions split on line
  boundaries and map-reduce merged. Default-off pending human review of
  the sidecar quality probe
  (`evals/digest_sidecar_probe.py`).
- **Consolidation quarantine off** (`memory.dream.quarantine_low_trust =
  false`) — when on, a scalar dream claim whose backing entry is
  agent-tier (its `source` maps to origin `agent`) and outside
  `memory.dream.trusted_sources` never takes `current` directly: it
  parks via the existing contender machinery (visible in
  `memory_fact_get` as contested), promotable only by an explicit
  `memory_fact_resolve(accept=true)` or by an independent second
  witness — a later matching claim from a different witness token
  (episode, else source) or a non-agent origin. The same witness
  restating confirms but never promotes. Parks and promotions are
  journaled (schema v27) and covered by `memory_dream(rollback)`.
  Honest scope: this does not stop a poisoned entry from being stored
  or retrieved — episodic search still surfaces it; the claim is that
  poison does not silently gain *canonical* authority. Scalar claims
  only in v1; member ops keep their existing guards. See
  [dreaming](dreaming.md) and the threat model in `SECURITY.md`.
- **Aggregation-recall retrieval knobs off**
  (`memory.search.contiguity_neighbors = 0`,
  `memory.search.timeline_channel = false`) — Phase 1 retrieval-side
  experiments (neighbor expansion, a timeline channel) that measurably
  failed their gates and ship dormant; they remain settable for
  replication but there is no measured reason to enable them.
- **Candidate pool at the served width**
  (`memory.search.candidate_pool_multiplier = 1`,
  `memory.search.fusion = "weighted_sum"`) — the
  retrieve-then-rerank shape (a dense pool `top_k x multiplier` wide,
  optionally merged by reciprocal rank fusion instead of raw-sorting
  incommensurate channel scores) exists and is settable, and it **lost**
  its judged run: on the LongMemEval knowledge-update oracle slice
  (2026-09-04, n=78) multiplier 4 cost naive RAG 0.115 accuracy under
  `rrf` and 0.077 under `weighted_sum`, while serving 36-54% more
  context tokens on every arm that serves turns. Table, caveats and artifacts in
  `evals/README.md` ("Judged verdict (2026-09-04)"). CAUTION if you
  enable `rrf` anyway: it changes the SCALE of every served score to
  ~0.016-0.05, so `memory.search_confidence_floor` must stay 0, and
  `rrf` must not be combined with the cross-encoder reranker
  (`memory.reranker.fusion_weight` collapses to cross-encoder-only
  ordering, `memory.reranker.skip_margin` can never be reached) or with
  a populated reference bank (its raw cosines are not rescaled and
  outrank every memory once the reranker fires). Neither combination has
  been measured.
- **Assistant-stated claims parked, not adopted**
  (`memory.dream.assistant_claims = "contender"`) — what a dream claim
  labelled `speaker: "assistant"` becomes: `contender` writes it at the
  floor `assistant` provenance tier (it may fill an empty slot, but
  against a value or member set of any other origin it parks as a
  contender, and it ranks below user-origin facts at equal similarity),
  `supersede` treats it as an ordinary agent-tier dream claim, and `drop`
  discards it. An unrecognised value falls back to `contender` — a typo
  must not open the overwrite path. **Live on the default path since
  2026-09-05**, when the provenance extraction prompt shipped: an
  extraction can now carry a `speaker` label, so the knob decides what
  happens to assistant-stated claims on a stock install. (It was inert
  before that, because the old prompt never asked for the field. The
  label is asked for only where the note makes the speaker knowable, so
  on a bank whose notes carry no `user:` / `assistant:` marker most
  claims still arrive without one — as do claims from an older prompt or
  an extractor shim launched with `--system-prompt-file` — and those
  write exactly as they did before, whatever this is set to.) Kept off
  the Console deliberately: `supersede`
  is the setting that lets model-stated content overwrite a user-stated
  fact, which is a provenance decision rather than an operator dial. The
  measured comparison of the three values is in `evals/README.md`
  ("Assistant-stated facts").
- **Staleness served as annotation** (`memory.search.stale_policy =
  "annotate"`) — stale records (past 2×TTL for their freshness class)
  carry `effective_confidence`/`stale` flags and nothing more, today's
  behavior. `"demote"` additionally sorts stale records after non-stale
  ones on list surfaces and adds a top-level `warning`; `"quarantine"`
  replaces a stale record's `value` with a wrapper string and moves the
  original to `last_known_value` (data moved, never hidden). Applied at
  the shared record serialisers, so every scalar-fact read surface —
  including the compact `memory_search` / `memory_world_search`
  projections — behaves identically. Deliberate exemptions: version
  history (the audit surface and the recovery path), `chain` summaries
  and graph fact projections (machine-consumed), and set-valued slots
  (set members are structurally always evergreen — the set API carries
  no freshness class — so no set payload can be stale). Non-stale
  records are byte-identical under every policy; an unrecognised policy
  value degrades safely to `annotate`. Console note: the web console
  renders the record `value` field, so under `quarantine` a stale fact
  shows the wrapper there — a known P2 cost to weigh before ever
  flipping the default.

- **Compact MCP payloads on** (`memory.mcp.compact_payloads = true`,
  `memory.mcp.entry_text_chars = 600`) — the payload an MCP client reads
  *back* from a tool call, shaped for its context window: a
  `memory_search` hit's `text` is truncated to `entry_text_chars` and
  marked `truncated: true` (`memory_get` returns the full text); a
  superseded hit carries `replaced_by: {id, at, preview, verified,
  current}` — the successor's row id when one entry (or one current
  entry) has the replacement's text, the supersession date, the
  replacement's first 120 chars, whether an explicit correction
  (`memory_supersede` / `memory_consolidate`, successor source
  `correction` / `consolidation`; a custom consolidate `source` reads
  unverified) made the link, and whether that successor is itself still
  live (`current: false` marks a chain link or an unresolved successor)
  — instead of the replacement's full text, which `verbose=true` still serves
  (2026-09-23: about 4 in 10 links the automatic contradiction detector
  left before it stopped superseding point at an unrelated note, so the
  full text must not arrive framed as the answer);
  the cortex block serves `min(5, top_k)` facts,
  so a narrow search stops paying for five;
  and `memory_fact_get` serves the acting subset — value, kind/members,
  confidence, origin, `asserted_at`/`age`, freshness, the currency and
  label flags, `correct_with`, `source_entries`, `entity_ref`,
  `contenders` — moving provenance, support, writer/session id, tx/valid
  time and the supersession chain behind `verbose=True`. Measured on the
  2026-09-04 agent token ledger (`evals/agent_token_ledger.py`, r3): a
  default `top_k=8` search fell from 14,745 to 9,951 chars mean,
  `memory_fact_get` from 2,175 to 1,296. These are PROJECTIONS above the
  service layer — ranking, `min_score` and every benchmark number are
  unaffected. Set `compact_payloads: false` to restore the pre-2026-09-04
  payloads verbatim (superseded hits keep the `replaced_by` pointer, which
  `memory_get` also serves for a superseded entry, and
  `memory_episode_summary` still compacts its `recent_entries` like
  `memory_recent`, and every compact entry keeps its write `date`
  (2026-09-25) — none of the four follows the knob); raise
  `entry_text_chars` for long-form corpora where
  the tail of a note carries the answer.

## Toolset tiers

Three visibility tiers — `minimal` (9 tools: the recall/capture loop, the
set-slot pair, the gate), `core` (24: + graph/recall, world facts, lessons,
documents, episodes, stats, `memory_get`, `memory_fact_resolve`, coordination),
`full` (38) — filtered per principal at `tools/list` (the named principal
from a `PSEUDOLIFE_MCP_TOKENS` bearer, else the writer id; sessions sharing
a credential share a tier view). The filter is
visibility, not auth (the bearer token is the security boundary) — but
Claude clients gate calls against their own tool list, so in practice a
session expands its tier before calling a hidden tool. Defaults:
`PSEUDOLIFE_MCP_TOOLSET` (unset → `full`; the Docker compose file ships
`core`, so lite and host-process installs start at `full`) sets the baseline;
`PSEUDOLIFE_MCP_TIER_MAP="claude-desktop:minimal,claude-code:core"` sets
per-client defaults by principal (writer id). Any caller can step its tier
up or down at runtime with `memory_toolset(action="expand"|"collapse"|"status")`
— the daemon emits `tools/list_changed` so the client refreshes its list.
Eager-loading clients (Claude Desktop) start at ~1.5k tokens of manifest on
`minimal`; clients that defer schemas client-side (Claude Code) barely
notice tiers at all.

**Weak-model deployments:** set `PSEUDOLIFE_MCP_TOOLSET=core` — it exposes
the curated core set and hides the power/hygiene tools (`memory_forget`,
`memory_relation_define`, `memory_dream`, `memory_graph_review`, …) that a
small model can misuse.

## Host-process install (Windows, for GPU / dev)

Runs Postgres in Docker but the daemon on host Python. Use this if you
want to hack on the daemon or run the embedder on a local GPU. Requires
Python 3.10+, Docker Desktop, and roughly 2 GB of disk — the
Qwen3-Embedding-0.6B weights (~1.2 GB) download on first run, on top of
CPU torch and the Python environment.

```powershell
git clone https://github.com/Pseudogiant-xr/Pseudolife-MCP.git
cd Pseudolife-MCP
python -m venv .venv
.venv\Scripts\activate
pip install -e .

# 1. Start Postgres 18 + pgvector (one-time build, then persistent).
docker compose -f ops/docker-compose.yml up -d --build pseudolife-pg

# 2. Register the daemon to auto-start at logon (binds 127.0.0.1:8765).
ops\install-autostart.ps1
Start-ScheduledTask -TaskName "Pseudolife-MCP Daemon"
```

The `pseudolife-mcp` console-script is now on your PATH — run
`pseudolife-mcp --help` for all modes. The main ones: `pseudolife-mcp serve`
(the daemon), `pseudolife-mcp` (the stdio shim — auto-starts the daemon if
absent), `pseudolife-mcp embedded` (the v0.1 in-process stdio server; no
daemon, no Postgres — an escape hatch), and `pseudolife-mcp briefing`
(print the session-start briefing; used by the hook).

## stdio shim (per-session identity)

The installer wires this by default (`ops/install.sh` / `ops/install.ps1`;
pass `--transport http` / `-Transport http` to opt out) because it's the
mechanism that gives **concurrent** Claude Code sessions distinct identity —
an `X-PL-Session` header, the strongest of the five
[session-identity](#session-identity) tiers. Under Claude Code (writer id
unset or `claude-code`) the header is the session id Claude Code launched the
shim with, the same id its SessionStart hook registers, so the shim and the
hook share one session episode. Other hosts get one id per shim process. The
shim opens no episode itself; see [Episodes](episodes.md). The shim works against
**either** daemon deployment, host-process or the containerized stack — it's
just an HTTP client to `PSEUDOLIFE_MCP_DAEMON_URL` and only spawns a new host
daemon when nothing answers there already (a cross-process lock keeps
concurrent shims from each spawning one). On a Docker-tier install set
`PSEUDOLIFE_MCP_NO_SPAWN=1` in the shim's env — the installers do — so the
shim waits for the container instead of spawning a fallback that races its
port bind. Point Claude Code at it directly:

```json
{
  "mcpServers": {
    "pseudolife-memory": {
      "command": "C:\\path\\to\\Pseudolife-MCP\\.venv\\Scripts\\pseudolife-mcp.exe",
      "env": {
        "PSEUDOLIFE_MCP_DAEMON_URL": "http://127.0.0.1:8765",
        "PSEUDOLIFE_MCP_NO_SPAWN": "1",
        "PSEUDOLIFE_MCP_DATABASE_URL": "postgresql://pseudolife:pseudolife@127.0.0.1:5433/pseudolife_memory",
        "PSEUDOLIFE_MCP_DATA_DIR": "${USERPROFILE}\\.pseudolife-mcp"
      }
    }
  }
}
```

Replace `C:\path\to\Pseudolife-MCP` with wherever you cloned the repo. The
`PSEUDOLIFE_MCP_DATABASE_URL` matches the bundled `ops/docker-compose.yml`
defaults (user/password `pseudolife`, host port `5433`) — change it only if
you edit the compose file or override the password. The default password is
safe for the stock loopback-only stack (nothing off-box can reach Postgres);
to use your own anyway, set `POSTGRES_PASSWORD` in `ops/.env` **before the
first launch** (see the note in `ops/docker-compose.yml` for changing it
later).

The shim is torch-free, so sessions attach near-instantly; the daemon pays
the one-time embedder warmup once for everyone. On first run with a v≤0.1
`cms_state.pt` present in `PSEUDOLIFE_MCP_DATA_DIR`, the daemon
auto-migrates it into Postgres and renames the originals `*.pre-v8.bak`
(never deletes them). The import records its progress in a
`legacy_migration` meta row, so one that fails part-way resumes on the next
start instead of leaving a short bank behind. While it is unfinished the
daemon keeps serving and `/health` stays `status: "ok"` (so healthchecks and
`ops/update.ps1` are not tripped by it) but carries an extra
`migration_partial` field; the matching ERROR lines in the daemon log name
the resume path. A resume merges rather than overwrites — cortex facts
written during that window are kept, and only slots nobody has written land
from the legacy bank. Leave the original `.pt` files in place until it
completes: the resume reads them, and deleting one makes the bank
unfinishable.

The daemon owns its bank alone. It holds a Postgres advisory-lock *writer
lease* for as long as it runs. A second daemon, a stdio-embedded server, or
a maintenance script or eval that opens the same bank through the service
refuses to start, and names the process that holds it. Stop the daemon for
offline maintenance such as `ops/dedup_cortex.py`. If the daemon loses its
database session and another lease-holding writer used the bank
meanwhile, the daemon re-reads the bank before it serves or saves
anything. If loading the bank fails
at startup, the daemon serves nothing rather than a partly loaded bank:
- `/health` reports `status: "degraded"` with the reason in `not_ready`. A
  daemon refused the lease reads the same way.
- Tool calls are refused.
- Retries back off from 5 s, doubling to 60 s. The daemon retries a
  startup failure on its own for the first couple of minutes. After that,
  or for a failure first met by a later call, it retries on the next call
  or on the session reaper's 5-minute tick.

`init_refusal` is different. It marks a bank the daemon will never serve as
configured, such as an embedding-dimension mismatch, and the shim exits on
it.

## Session identity

Every request resolves "which session/episode does this write belong to"
through one chokepoint, evaluated in strict precedence order:

| tier | source | scope | notes |
|---|---|---|---|
| 1 | `X-PL-Session` header | per session | the stdio shim sends this on every call: Claude Code's own session id under Claude Code (the id tier 3 registers), one id per shim process elsewhere, the thread id on each Codex call; any integrator can |
| 2 | explicit `episode` argument | per call | pass an open episode id (or its unambiguous ≥8-char prefix) on `memory_store` / `memory_outcome` / `memory_fact_set`, and on the lifecycle tools `memory_episode_start` / `memory_episode_end` / `memory_session_title` — where a resolved handle wins outright (they never consult the header tiers); the daemon mints it and advertises it in the SessionStart briefing |
| 3 | hook-registered active session | machine-scoped pointer | the SessionStart hook forwards Claude Code's own `session_id`; a SessionEnd hook closes it. A singleton — concurrent sessions race it, which is why the lifecycle tools take the per-call handle |
| 4 | `mcp-session-id` header | per connection | **retired** — the header names the connection (concurrent sessions share it) and the MCP 2026-07-28 revision (SEP-2567, "Sessionless") removes it from the protocol. `PSEUDOLIFE_LEGACY_TRANSPORT_SESSION=1` restores it for one release as a rollback hatch |
| 5 | none | — | writer id + idle-gap sessionization (the reaper) — the documented floor when nothing above resolved |

**Why the header outranks the handle when both are present.** A shim
header is infrastructure-asserted, by the host or per OS process; an `episode` handle is
model-supplied and can be confused between two concurrent sessions'
briefings. But identity and target episode are separable — a write still
lands in the handle's named episode even when the header wins identity for
stamping, and it opens no episode for a different header session. An unknown,
closed, or ambiguous handle never fails the write —
it degrades to the next tier and the result carries
`"episode_warning": "unknown or closed episode handle"`.

**Tier 3's limitation.** The active-session pointer is one machine-scoped
value, last-start-wins: whichever SessionStart hook fired most recently
owns it until its own SessionEnd clears it (or a later SessionStart
overwrites it). Two concurrent sessions that are both *unheaded* (no shim)
and *handle-less* (no `episode` argument) still misattribute to the newer
one — tiers 1 and 2 are the actual concurrency answer, not tier 3. Accepted
as YAGNI until a real multi-writer/LAN deployment needs a per-writer
pointer.

This cuts across clients, not just across Claude Code sessions: because the
pointer is machine-scoped, a **second client that sets no identity of its
own** — e.g. Codex or a ChatGPT connector talking to the daemon over direct
HTTP with no shim, no hook, and no `episode` argument — resolves at tier 3
to whatever session the Claude Code hook last registered, so its writes are
attributed to Claude's session episode. The fix is the same as for
concurrent sessions: give the second client a tier-1 identity (run it
through the stdio shim) or pass explicit tier-2 `episode` handles on its
writes. The installer's shim mode wires **Codex** through the shim by
default (2026-07-19), and **Gemini CLI** the same way (2026-08-29); each
first-class provider's registration also carries its own
`PSEUDOLIFE_WRITER_ID` (`claude-code` / `codex` / `gemini`) so a shared
bank attributes writes per agent (see
[the providers guide](providers.md)). ChatGPT connectors and other
direct-HTTP clients still hit the tier-3 leak.

**Pointer TTL.** A client that crashes or is killed never fires SessionEnd,
so without a bound its pointer would attribute every later tier-3 write to a
dead session until the next SessionStart overwrote it. The pointer therefore
expires: one older than `PSEUDOLIFE_ACTIVE_SESSION_TTL_SECONDS` (default
`21600` = 6 h, the resume window — past it a return starts a fresh episode
anyway; `0` disables the TTL) is treated as stale and tier 3 falls through to
the transport/idle-gap floor. The timestamp refreshes on-set only, which
Claude Code re-fires on resume/compact, so a genuinely active session stays
live; resolution never refreshes it (a wrong client's traffic can't keep a
dead session's pointer alive).

The resolved identity becomes the episode's `session_key` wherever it's
used; `session_key` is a free-text field, so none of this required a schema
change.

## Sharing memory on the LAN

Run the daemon with `PSEUDOLIFE_MCP_HOST=0.0.0.0` and a
`PSEUDOLIFE_MCP_TOKEN`; remote clients set the same
`PSEUDOLIFE_MCP_DAEMON_URL` + `PSEUDOLIFE_MCP_TOKEN`. The daemon **refuses
to bind a non-loopback host without a token**, and Postgres itself stays
loopback-only — the LAN only ever sees the daemon.

The token is also what relaxes the MCP endpoint's DNS-rebinding guard. With
a token set, `/mcp` accepts any `Host` header — a LAN address, a
reverse-proxy hostname, a Tailscale name, a compose service name — because
`Authorization` already proves intent. Tokenless (loopback use, or a
container published to 127.0.0.1 via `PSEUDOLIFE_MCP_TRUST_BIND`), `/mcp`
serves loopback `Host` values only and answers anything else with
`421 Invalid Host header`; that is the guard against a rebinding browser
reaching an unauthenticated bank. So: fronting the daemon with a reverse
proxy under a real hostname means setting a token.

## Data layout

**Containerized / daemon mode (recommended).** The durable source of truth
is **Postgres**, which lives in an *external* Docker volume —
`pseudolife-mcp-bank` by default (entries + facts + graph). A second
external volume, `pseudolife-mcp-state`, holds the daemon's ChromaDB
reference bank, the counter file `weights.pt`, and the cortex snapshot.
Both are declared `external` in `ops/docker-compose.yml` precisely so a
container teardown can't take them with it. The host `data/` dir then holds
only backups (`data/backups/` from `ops/backup.ps1` — a `pg_dump` of the
bank *plus* a tar of the state volume) and one-time legacy-import staging —
*not* the live bank.

To wipe the bank in this mode you must drop those volumes deliberately —
**never `docker compose down -v` or `docker volume rm` without
`ops/backup.ps1` first**; `stop` / `start` and `up -d --build` keep both
volumes.

**File mode (no daemon / no Postgres — the `embedded` CLI, or unset
`PSEUDOLIFE_MCP_DATABASE_URL`).** Everything lives under
`PSEUDOLIFE_MCP_DATA_DIR`:

```
data/
├── memory_state/
│   └── cms_state.pt        # Associative entries + metadata (file mode)
├── cortex_state.pt         # Slot-keyed canonical facts (cortex, schema v8)
├── chromadb/               # Reference bank (RAG documents)
└── config.yaml             # Optional overrides
```

In **file mode only**, wipe memory by deleting `data/` and restarting; wipe
just documents via `data/chromadb/`; wipe just the associative store via
`data/memory_state/`. (In containerized mode these files are not the source
of truth — see the volume note above.)

## Windows / WSL2 memory (Docker tier)

Docker Desktop's WSL2 VM (`Vmmem`) claims up to **~50% of host RAM** by
default, which is far more than the stack needs. Adding up the parts
measured 2026-09-23 — daemon ~2.5 GB with the bf16 embedder or ~4 GB with
fp32, the extractor sidecar's ~5.3 GB mmapped model plus its context, and
Postgres — the whole stack wants ~9 GB under dream load with the default
sidecar (~10 GB with fp32), or ~3 GB in `sonnet-only` mode (~4.5 GB), where
the Qwen3 embedding backbone is the bulk of it. Encode bursts add up to
~1 GB on top.
Cap the VM by copying `ops/wslconfig.example` to
`%USERPROFILE%\.wslconfig`, tuning `memory=`, then `wsl --shutdown`.

The daemon container is separately hard-capped at 6 GB, with memory+swap
pinned to the same value so exceeding it is a clean container restart rather
than a host-wide memory event. `PSEUDOLIFE_DAEMON_MEM_LIMIT` in `ops/.env`
raises it for very large banks; `/health`'s `memory` block shows how close
the daemon runs to it (`near_limit` at 90%).

After `wsl --shutdown` the host port forward is gone; `docker restart
pseudolife-mcp-daemon` re-establishes it.

## Backups

`ops\backup.ps1` (Windows) / `ops/backup.sh` (Linux/macOS) runs `pg_dump`
inside the container into `data\backups\` with 7-day rotation, and also
tars the daemon **state volume** (ingested `document_ingest` files, cortex
snapshot, graph snapshots — those live only there, not in Postgres) into a
sibling `pseudolife_state-*.tgz`. An optional off-disk mirror via
`PSEUDOLIFE_BACKUP_MIRROR` carries both artifacts;
`PSEUDOLIFE_BACKUP_MIRROR_KEEP=N` (or `-MirrorKeep` / `--mirror-keep`) caps
the mirror at the newest N files per kind — handy for cloud-synced folders.
The matching `restore` script rehearses the newest backup into a scratch
database by default (never touching the live bank) and only replaces the
live bank with an explicit `-Apply` / `--apply`; add
`-StateArchive <pseudolife_state-*.tgz>` / `--state-archive` to also
restore the state volume (opt-in, so a DB-only restore never clobbers
current state).

Each dump also gets a `pseudolife_manifest-<stamp>.json` beside it: the
per-table row counts, read from the dump itself. The manifests drive a
**row-count gate**. If `entries`, `facts` or `lessons` fell by more than
25% (`-MaxRowDropPercent` / `--max-row-drop-percent`) against the newest
manifest that was not itself held, the script keeps the new dump but skips
local rotation and mirror pruning and says so loudly. It looks for that
baseline in both the backup folder and the mirror. A logical wipe therefore
cannot rotate the good copies away. It also holds when history exists but
none of it is usable (unreadable or count-less manifests, or a folder it
cannot list), so a gate that cannot see never waves a wipe through. On the
first run after upgrading there are dumps but no manifests yet; the
newest complete date-stamped dump is then read as the baseline, and only
a truly empty history rotates without one. The warning names the last
good dump and the `restore` command for it. With no file named, `restore`
skips held dumps (the newest one after a wipe is the one that shrank) and
refuses if every dump is held; naming a file overrides that. The hold repeats on
every run until one passes `-AcceptRowDrop` / `--accept-row-drop`, which
rotates and makes that dump the new baseline. The gate compares each dump
with the newest good one, so it is built for sudden loss: a slow decline
of less than the threshold per backup passes. The manifest is also
copied into the daemon, and `/health` reports it as `last_backup` (`at`,
`age_hours`, `rotation`). The key is absent until a backup script has
run; the pip tiers' `pseudolife-mcp backup` does not record one yet.

Deploys back up first, but nothing else backs up on a schedule. On
Windows, register a daily run once:

```powershell
ops\install-backup-task.ps1              # daily 03:00
ops\install-backup-task.ps1 -At 02:15
<dir>\ops\install-backup-task.ps1 -ScriptCheckout <dir>   # see below
ops\install-backup-task.ps1 -Uninstall   # remove it
```

The task runs the main checkout's `ops\backup.ps1`, even when installed
from a worktree; the installer warns if that copy predates the row-count
gate. It catches up at the next boot or logon if the machine was off,
waiting up to 10 minutes (`-DockerWaitSeconds`) for Docker to answer
first, and it runs as you, so `PSEUDOLIFE_BACKUP_MIRROR` applies. Each run
is appended to `data\backups\backup-task.log`, headed by the HEAD commit of
the checkout whose `backup.ps1` it ran.

If the main checkout cannot follow master (for example, it holds
uncommitted work), run the backup from a dedicated worktree of master
instead. Create it with `git worktree add --detach <dir> origin/master`
from the main checkout, lock it with `git worktree lock <dir>`, then install
with that worktree's own copy: `<dir>\ops\install-backup-task.ps1
-ScriptCheckout <dir>`. The installer refuses an unlocked worktree, because
worktree cleanup would otherwise delete the script the task runs. It also
refuses a script checkout that would receive the dumps itself, such as a
separate clone running its own installer. Dumps and the log still go to
the main checkout's `data\backups`, where a replica push looks for them;
`restore` from `<dir>` reads its own `data\backups`, so name the files
there with `-BackupFile` (and `-StateArchive`). Move the worktree forward
when you deploy (`git -C <dir> fetch origin master`, then
`git -C <dir> checkout --detach origin/master`); the log shows which commit
each night ran.

On Linux/macOS, a cron entry
that runs `ops/backup.sh` does the same job, but cron starts with a bare
environment: set `PATH` (so it finds `docker`) and any
`PSEUDOLIFE_BACKUP_MIRROR*` variables in the crontab itself.

The pip tiers (lite / host-process) use `pseudolife-mcp backup` instead:
same shape — a `pg_dump | gzip` of the bank (`--no-owner --no-acl`, so
the artifact restores under any role — rehearsed in the test suite
against a role-named PostgreSQL 18; since the Docker tier's 16→18 bump
(2026-08-14) both tiers run PostgreSQL 18, so a lite dump restores
straight into the Docker tier; the lite tier uses the embedded
runtime's own bundled `pg_dump`, attaching to the running instance or
starting it for the duration) plus a
`pseudolife_lite_state-*.tar.gz` of the data dir (ChromaDB, weights,
config; `embedded_pg/` is excluded — the dump covers it), with the same
7-day rotation (`--keep-days`). The artifact names
(`pseudolife_lite_memory-*` / `pseudolife_lite_state-*`) are deliberately
disjoint from `ops/backup.*`'s, so the two tools can share a directory
without either's rotation or restore-picker ever touching the other's
files. A backup never initializes a bank that doesn't exist yet, a run
that produced no dump never rotates dumps, and rotation only ever
deletes files the tool itself wrote.

### Logical export / import

Beside the physical backups, `pseudolife-mcp export` writes the bank as a
portable ZIP — one JSONL file per table plus a manifest (schema version,
embedding dimension, per-table counts) — from a single read-only snapshot,
so it is safe to run against a live daemon (the snapshot stays open for
the duration, which delays autovacuum on busy tables — prefer a quiet
moment for a very large bank). Unlike a `pg_dump`, the
artifact is deployment-tier- and Postgres-version-independent,
human-readable, and loads additively across schema versions: an export
from an older build imports into a newer one, with new columns taking
their DDL defaults. Embeddings travel verbatim (the manifest pins their
dimension), so neither command needs the embedding model.

`pseudolife-mcp import <archive.zip>` loads an export into a **fresh,
empty bank** in one transaction. It refuses a non-empty bank, refuses
while any other connection holds the database — stop the daemon first
(Docker tier: `docker compose -f ops/docker-compose.yml stop
pseudolife-daemon`); `--force` overrides for connections you know are
inert — and refuses an export whose format version or embedding dimension
it cannot honor. Operational telemetry (retrieval/read logs, the client-session
record, the dream-run journal), agent instance credentials, coordination mail and
the board's audit log deliberately stay behind, and the manifest lists exactly which
tables were excluded. Ingested `document_ingest` files live on the state
volume/data dir, not in Postgres — carry those with the physical backup's
state archive.

Both commands resolve the bank the way `backup` does: the explicit
`PSEUDOLIFE_MCP_DATABASE_URL` first (for the Docker tier that is
`postgresql://pseudolife:<POSTGRES_PASSWORD from
ops/.env>@127.0.0.1:5433/pseudolife_memory`), else the lite tier's
embedded instance, attached or started for the duration — never
initialized: importing is how a fresh bank gets *filled*, but creating
one is the daemon's job.

## Schema version history

The current Postgres meta version is **v49**; migrations are additive
`ADD COLUMN IF NOT EXISTS` on daemon start, and legacy file-mode `.pt`
banks auto-migrate into Postgres. The one exception is v25 itself: a
vector *dimension* change on an existing column is not additive, so
`ensure_schema` refuses to start against a bank still dimensioned at
v24 or earlier instead of attempting an in-place ALTER — run the
human-gated `ops/migrate_embeddings.py` first. Full step-by-step operator
procedure (backup, stop, dry-run, apply, deploy, verify, rollback):
[the v25 migration runbook](../runbooks/embedding-v25-migration.md).
Separately from the schema meta version, Docker-tier installs created
before 2026-08-14 also need the PostgreSQL 16 → 18 volume cutover —
[the PostgreSQL 18 migration runbook](../runbooks/postgres-18-migration.md).
The milestones:

| Version | What it added |
|---|---|
| v11 | Temporal/provenance stamp (tx/valid time, HLC ordering, writer/session) |
| v12 | Graph-insight communities |
| v13 | Provenance-trace engram + reinforcements |
| v14 | Episode `session_key` |
| v15 | Episode `parent_id` (nesting) |
| v16 | `entity_sources` (per-entity project attribution) |
| v17 | `edge_proposals` (deep-dream link candidates) |
| v18 | `entity_proposals` (deep-dream merge/junk candidates) |
| v19 | Partial unique indexes enforcing one current row per slot on facts/world_facts/lessons (+ startup heal of pre-existing duplicates; per-slot write-through persistence replaces the full-table snapshot rewrite) |
| v20 | `dismissed_pairs` (reviewed-distinct pairs stop resurfacing as duplicate findings) |
| v21 | `merge_decisions` audit + write-time near-duplicate merge proposals |
| v22 | `edges(dst_id)` index (dst-side graph lookups no longer sequential-scan) |
| v23 | `facts.freshness_class` — read-time currency on personal cortex facts (evergreen default, so existing facts are unchanged; mark transient ones `volatile` and they decay and flag `stale`) |
| v24 | `entity_kinds` (one `artifact`/`system`/`concept` kind per entity) — `freshness_class` now defaults to inferring from the entity's kind instead of a fixed default; only `system` entities can resolve `volatile`, and an empty table resolves everything to `evergreen`, so behaviour is unchanged until it is populated |
| v25 | `entries`/`facts`/`world_facts`/`lessons.embedding` move from `vector(384)` to `vector(1024)` — default embedding backbone swaps to Qwen/Qwen3-Embedding-0.6B (measured R@10 0.809 vs shipped MiniLM's 0.572). Qwen3-Embedding is instruction-asymmetric — see [asymmetric query/document encoding](retrieval.md#asymmetric-query-and-document-encoding) — so similarity-threshold semantics shift too. `ensure_schema` refuses to start against an existing v24-dimensioned bank rather than attempting an in-place ALTER; migrate first with `ops/migrate_embeddings.py` (dry-run by default; `--apply --backup-verified` to commit) |
| v26 | `facts.kind` (`scalar` \| `member`) and `facts.value_norm` — set-valued cortex slots (many concurrently-current members per `(entity, attribute)`, not one NOW value). The per-slot current-uniqueness constraint splits by kind (`facts_slot_current_scalar_uq` keeps one live scalar row per slot; `facts_member_current_uq` allows several current members on the same slot); the daemon-start duplicate-healing pass is scoped to `kind = 'scalar'` so it never demotes member rows. Additive/idempotent; every existing fact defaults to `kind='scalar'` and dedupes exactly as before. See [Set-valued slots](memory-model.md#set-valued-slots-schema-v26) |
| v27 | `dream_runs` + `dream_run_slots` — every dream pass that pulls entries records a run row (cursor movement, tallies, lifecycle status) and a per-claim pre-image journal (what each slot held before the write, `NULL` = slot absent). The journal is what `memory_dream(action="rollback")` replays, and it survives superseded-row compaction by construction (own tables, own newest-N retention via `memory.dream.runs_keep`). `dream_run_slots.src_entry_id` deliberately carries no FK — entries are evictable. Additive/idempotent |
| v28 | `chronicle_events` — dated occurrences as first-class records beside facts (`occurred_at` = event time, nullable and never fabricated; `occurred_phrase` = the source's verbatim wording; `recorded_at` = transaction time). Additive-only: contradiction handling sets `invalidated_at`, never deletes; event writes journal into `dream_run_slots` (new nullable `chronicle_event_id` column) so rollback can delete them by exact id. No FKs — `src_entry_id` references evictable entries. Extraction into the table (`memory.dream.chronicle`) shipped off by default and flipped on 2026-08-12 after its preregistered gates and a production soak both passed. Additive/idempotent |
| v29 | `facts.stance` — epistemic stance as a labelled field: the source's own hedge words ("probably", "per the runbook"), kept verbatim and separate from `value` so consolidation cannot silently turn a hedged claim into a confident canonical fact (the labelled-field-vs-inline retention result is arXiv:2608.06953). `NULL` = asserted plainly, exactly the pre-v29 behaviour, so the migration is a no-op on existing banks. Stance follows the latest asserting write (a plain restatement clears the hedge), surfaces in `memory_fact_get`/recall/history only when set, and is never an input to confidence, ranking, or supersession. Written by the dream path since the v10 update-anchored stance prompt shipped its gates (2026-08-14); not exposed on the `memory_fact_set` tool surface. Additive/idempotent |
| v30 | `entity_proposals.judge_verdict` / `judge_confidence` / `judge_note` / `judge_model` / `judged_at` — the autonomous Step-C judge's shadow verdict on a pending merge proposal, recorded by the sweep (`memory.deep_dream.judge_mode`: `off` \| `shadow` \| `auto-reject`) and surfaced beside the evidence in review payloads. The verdict is an opinion on the pending row; the durable decision record stays `merge_decisions`, written only when a decision path (human, agent, or the confidence-gated auto-reject) ratifies it. `NULL` = not yet judged, exactly the pre-v30 behaviour, so the migration is a no-op on existing banks. Judge-model floor measured by `evals/judge_ladder.py` (`evals/results/judge-ladder-20260816.json`). Additive/idempotent |
| v31 | `retrieval_events` + `retrieval_uses` — the retrieval event log (learned-reranker Phase 0). Every `memory_search` appends one event row (query text, the ranked served list as JSONB with entry ids/scores/ranks, writer session/episode); a later `memory_get`/`memory_reinforce` on a served entry in the same session writes an implicit relevance label (most-recent serving event wins, bounded by `memory.retrieval_log.use_window_seconds`; the asserted `memory_outcome(used_ids=)` label credits every serving event in that window — it names ids, not queries). Together they are the (query, served, used) training tuples for a future learned fusion/reranker stage — purely observational, no retrieval behaviour changes. Served ids carry no FK (entries are evictable; training joins tolerate dangling ids); labels CASCADE from their event; events are pruned on the dream-sweep tick after `memory.retrieval_log.retention_days` (default 365). Kill-switch: `memory.retrieval_log.enabled`. Additive/idempotent |
| v32 | `retrieval_events.params` — the ranking knobs in force for the query (effective `top_k` / keep-threshold, the recency ramp, BM25 weight and scorer params, the reranker's fusion weight + margin gate and whether it actually fired, timeline/contiguity settings, and the call's filters), logged beside a widened `served` list whose per-entry `components` blob carries the fusion INPUTS: bi-encoder score, cross-encoder score (`null` when the margin gate skipped the pass — a distinction a learned head needs), BM25 boost, surprise, recency and the source/supersession multipliers. Phase 0 logged only the fused score, which is the output a Phase-1 learned head is supposed to predict; the inputs are not recoverable afterwards, because config is mutable at runtime and band recency, supersession flags and access counts all mutate on every serve. Nothing new is computed at serve time — these values were already in hand and were being discarded. `NULL` params = a v31-era row. Additive/idempotent |
| v33 | `slot_reads` + `entries.explicit_reinforcements` — read telemetry. `slot_reads` counts how many times each cortex slot was *served as an answer* (`memory_fact_get` and `memory_search`'s cortex-first block), keyed on the stable `(entity_norm, attribute_norm)` slot like `memory_traces` so counters survive cortex snapshot saves; deliberately uncounted are internal verification lookups (e.g. the dream rollback's post-revert check) and the facts attached to `memory_recall`/`memory_graph` neighborhoods (context, not a direct answer), so never-read is a lower bound. `explicit_reinforcements` moves only on `memory_reinforce`, splitting the deliberate "this was useful" signal out of the shared `reinforcements` counter, which also counts dream-trace links (and still feeds the retention formula unchanged). Both feed the new `read_audit` section of `memory_stats` (never-read fractions by age and source, read/write balance, slot coverage) — motivated by the 2026-08-26 bank audit, where entry reads were measurable but the 4.6k fact slots had no read signal at all. Kill-switch: `memory.cortex.read_tracking`. Additive/idempotent |
| v34 | `retrieval_events.served_facts` — the fact half of the reranker training tuple. The v31 event log recorded only served *entries*; the cortex-first block's facts, served above those entries in every `memory_search` response, were invisible to a future learned reranker. The search handler now attaches them (`[{entity_norm, attribute_norm, rank, score, kind, contested}]`) to the exact event row that search wrote, keyed by the event id `search(return_event_id=True)` hands back — no session-window guessing. `NULL` = a pre-v34 row or a search that served no facts. Also (no DDL): `memory_stats` `read_audit` gains `graduation_candidates` — entries served in ≥60% of the last 30 days' distinct sessions (once ≥8 sessions are on record), i.e. static-context ("promote to CLAUDE.md") candidates that retrieval keeps re-paying for per query. Additive/idempotent |
| v35 | `entries.authority` / `entries.distortion_tolerance` and `facts.authority` / `facts.distortion_tolerance` — the write-time label pair (authority collapse, arXiv 2608.01679; the compaction cliff, arXiv 2608.22752). `authority` is the SPEECH ACT of the text (`directive` \| `observation` \| `quoted`), deliberately a separate axis from the `origin` tier (who wrote — which drives supersession arithmetic and which entries never persisted anyway); `distortion_tolerance` is the fidelity class (`constraint` \| `procedural` \| `belief` \| `preference` \| `episodic`). Set at write time — explicit `memory_store` / `memory_fact_set` parameters, or a deterministic heuristic under the `auto` default that asserts only `constraint` (rule-sized deontic/imperative text) and `quoted`/`directive` — and inherited through `memory_supersede` / `memory_consolidate` / fact supersession unless the new write restates one. Consumers: the dream carries a `constraint` source's text verbatim onto a derived fact and a post-dream guard reports any constraint entry left without a verbatim carrier (`constraint_verbatim` / `constraint_misses`); a `quoted` source is low-trust for the two-man rule; `constraint` facts are pinned ahead of cosine in `memory_search`'s cortex block and `memory_recall` (`memory.cortex.pin_constraints`). `NULL` = observation / unlabelled, exactly the pre-v35 reading, so the migration is a no-op on an existing bank — no backfill, by design. Additive/idempotent |
| v36 | Review-queue autonomy (2026-09-02). `edge_proposals.judge_verdict` / `judge_confidence` / `judge_note` / `judge_model` / `judged_at` / `judge_relation` / `decided_by` / `decided_at` — the link judge's opinion on a pending link proposal (the retype verdict's corrected relation in `judge_relation`) and who settled the row; `entity_proposals.judge2_verdict` / `judge2_confidence` / `judge2_model` / `judged2_at` — the merge judge's SECOND opinion beside the v30 first one (two-vote agreement is the apply gate for rows the single-vote 0.8 reject gate leaves pending); and `curation_judgments` (`store`, sorted slot keys, verdict, keep, fold, confidence, note, model, judged_at) — the store-curation judge's memo, because the lesson/world duplicate listings are recomputed per pass and would otherwise be re-sent every sweep. `NULL` judge columns = not yet judged, exactly the pre-v36 behaviour, so the migration is a no-op on existing banks. Gates measured by `evals/queue_judge_ladder.py` against `evals/results/queue-judge-panel-20260902.json`. Additive/idempotent |
| v37 | Retire-not-delete (2026-09-03). `store_decisions` (`id`, `store`, `entity_norm`, `attribute_norm`, `action`, `decided_by`, `reason`, `record` JSONB, `decided_at`) — the FK-free audit of lesson/world forgets and restores. A `memory_forget(scope="lesson"\|"world")` now retires the slot's rows (`status='retired'`, rows kept; `memory.compaction` treats them like any non-live record) instead of deleting them, and the audit row carries the verbatim record so `lesson_restore` / `world_restore` (`memory_graph_review(action="restore_slot")`, `POST /api/lessons/restore`, `POST /api/world/restore`) still work after compaction has purged the retired row. Also (no DDL): merge and junk rejects write text-keyed tombstones to `dismissed_pairs` (canonical pair / `junk:<canonical>` self-pair) so a verdict outlives the CASCADE-deleted proposal row. No column changes; the table starts empty on an existing bank, so the migration is a no-op there. Additive/idempotent |
| v38 | Durable dream acknowledgement. `entries.dream_state` records `pending`, `acknowledged`, or `legacy-covered`; pre-existing rows retain `NULL` for one-time classification against the legacy cursor and configured source eligibility. New writes default to `pending`, regardless of their timestamps. Exact-entry commit tokens use a bank-local secret in `meta`; logical export excludes that secret. The numeric cursor remains display metadata. This preserves the previous migration boundary; it does not repair historical skipped entries. Additive/idempotent |
| v39 | `memory_trace_invalidations` preserves source-supersession events by normalized slot and source entry ID, without entry or fact foreign keys. Explicit correction records entry retirement and existing trace invalidations together. Events survive source deletion, cortex snapshots and compaction; confirmation still clears the served warning. Table creation and older logical imports reconstruct only surviving superseded source/trace pairs. **Upgrade effect:** the first v39 start materialises one event per surviving superseded-source trace pair — 2077 pairs on the reference bank on 2026-09-11, measured with `ops/measure_reverify_population.py`. That reproduces the warnings the bank already served, but from then on they no longer drain when the source is evicted or deleted; each clears only when its slot is confirmed again (`memory_fact_set` at the slot with the same or a new value, or accepting a contender). To clear a population deliberately, re-assert those slots. `re_verify` stays a passive flag and is still excluded from `correct_with`. Additive/idempotent |
| v40 | Agent coordination (2026-09-11). Adds `coordination_agents` for bearer-owned instances, hashed credentials, explicit scope, activity and adapter attachment generations, and `coordination_messages` for one-recipient mail, per-recipient ordering, sender request-key deduplication, expiry and acknowledgment. Agent rows have no episode FK; episode cleanup cannot remove mail. No embeddings or changes to memory tables. Both tables are operational data excluded from portable knowledge exports. Additive/idempotent; existing banks start with empty coordination tables and the feature remains disabled until configured. |
| v41 | Audited continuum entry reinstatement (2026-09-22). Adds `entry_reinstatement_decisions`, an operation-keyed, FK-free append-only audit that survives later entry deletion. A single Postgres transaction binds the reviewed retirement preimage to the decision and clears only the entry's retirement fields; retries use the operation UUID. The first version refuses entries with trace invalidations and leaves all cortex state unchanged. Additive/idempotent; existing banks start with an empty decision table. |
| v42 | Board audit log (2026-09-24). Adds `coordination_events`, an append-only, FK-free, sha256-hash-chained record of every agent-board mutation (register, update with the replaced values, attach, detach, send with its body, first read, ack, attempt, expire, prune, bank identity, restore recover/rebind), written in the mutation's own transaction and pruned only by its own `coordination.audit_retention_days` window (default 90, `0` keeps it forever), which logs its cuts. Adds `coordination_messages.first_read_at`. Operational data, excluded from portable exports like the other coordination tables; read and verified with `pseudolife-mcp board-audit`. The log is cut at most once a day, on UTC day boundaries, and only while the board is in use. Additive/idempotent; existing banks start with an empty log, and history before the upgrade is not reconstructed: a message still unacknowledged at the upgrade has no `send` event, and its first read afterwards is logged as its first read. |
| v43 | Durable client-session record (2026-09-25). Adds `client_sessions`, one FK-free row per session key the daemon registered (the SessionStart hook, or `POST /api/episode/start` from the stdio shim and the CLI episode hooks): `registered_via` (`hook` \| `api`, the first registration's), the bearer's `principal`, `started_at` (first registration, never moves) and `start_times` (every registration, so a resumed client's new shim still pairs with it), `ended_at` + `end_reason` (the most recent close: `end` for SessionEnd or shim exit, `idle` for the reaper; cleared when the session registers again or a store or handle reopens it), the startup memory-policy `policy_variant` the hook assigned, and `episode_ids`, every root episode the session was given. A root that ends holding no entry is still pruned; the row is not, so the searches and outcomes of a session that stored nothing keep a session to count against, and an online `memory_policy.ab_arms` test keeps each session's arm. Written best-effort (a failed write never fails a session start); Postgres only; operational data, excluded from portable exports. Additive/idempotent; existing banks start with an empty table, and sessions before the upgrade are not reconstructed. [Episodes — session record](episodes.md#session-record) |
| v44 | Memory-loop observability (2026-09-25). Adds `lesson_search_events`: one row per `memory_lesson_search` call (query, caller session and episode, the lessons served by `(entity_norm, attribute_norm)` slot key with rank and score; an empty list for a search that found nothing). It is a separate table from `retrieval_events`, whose rows the retrieval replay and telemetry harnesses re-run as `memory_search` calls. FK-free; it shares the retrieval log's switch (`memory.retrieval_log.enabled`) and retention (`retention_days`). Adds `outcome_signals.used_ids` (JSONB): what an outcome's `used_ids` became, as `{"credited", "unmatched", "served_elsewhere"}` id lists, or `{"unchecked", "reason"}` when the label write failed; `NULL` when the outcome named no ids, the log is off, or this best-effort write failed (counted in `retrieval_log.write_errors`). The column is serving telemetry and stays out of portable exports, like the retrieval log. Additive/idempotent; existing rows read `NULL` and the new table starts empty. |
| v45 | Resource leases (2026-09-26). Adds `coordination_leases`, one FK-free row per lease name (holder agent and principal, purpose, the current grant's fence from the `coordination_lease_fence` sequence, so a name's fence never repeats, the acquired, expiry and expected-end times, the estimate the hold was given, and when the lease was last freed, after which a week free and unqueued forgets the row), `coordination_lease_waiters`, each lease's FIFO queue, and `coordination_agents.status_expires_at`, when a status says it stops being true. A process-held lease's truth is an OS file lock that `pseudolife-mcp lease run` takes on the host, and the row mirrors it; a session-held lease (`coordinator:<project>`, `claim:<path>`) lives only here. A freed lease goes to the head of its queue, which must renew within five minutes or lose it to the next. Grants, releases, expiries and operator breaks are audit events; renewals are not. Operational data, excluded from portable exports like the other coordination tables. Additive/idempotent. |
| v46 | Redactable board message bodies (2026-09-26). Adds `coordination_events.body` and `body_salt`. From v46 a `send` event keeps the message body in that column, outside the row hash, and its hashed payload carries sha256(salt || body) (`text_commitment`) instead of the text, and not its length, so `pseudolife-mcp board-audit redact` can remove one body behind a chained operator `redact` event and the chain still verifies. `verify` checks every present body against its salted commitment (`body_mismatch`) and accepts an absent one only behind such an event (`body_missing`). Send events written before v46 keep the body inside the hashed payload, which redaction cannot touch (it still takes their live mailbox copy); they leave the log only through audit retention. The columns are added only when missing, so an open `board-audit export` never blocks the schema pass. The board also refuses credential-shaped message bodies, request ids, statuses, scope fields, capability names, lease names and purposes, and redaction reasons with `secret_like_body` (no DDL). Additive/idempotent; existing rows read `NULL`. [Audit log — redacting a body](#redacting-a-body) |
| v47 | Subagents on the board (2026-09-27). Adds `coordination_agents.children`, a JSON list of `{label, since}` (default `[]`): the subagents a session runs under its own board address. `memory_agents(action="update", children=[...])` sets it (at most 8 labels of at most 40 characters, no duplicates; `[]` clears it, omitting it leaves it), the daemon stamps each label's `since` and keeps it for a label the next update carries over, and `memory_agents(action="list")` returns it on every peer row. The column is added only when missing, like v46's. Additive/idempotent; existing rows read `[]`. [Delivery and recovery](#delivery-and-recovery) |
| v48 | Fan-out mail and id prefixes (2026-09-28). One `memory_message` send may reach every attached, non-idle agent in a project (`to: "project:<name>"`) or on the board (`to: "all"`) under one request id, with one `coordination_messages` row and one `send` audit event per recipient, so the sender's request key becomes the unique index `coordination_messages_request_idx` over `(sender_agent_id, request_id, recipient_agent_id)`. The index is created before the pre-v48 `UNIQUE (sender_agent_id, request_id)` constraint is dropped, and the drop runs only where that constraint exists, so an open `board-audit export` never blocks the schema pass. Agent and message ids may be given by a unique prefix of 8 or more hex characters (no DDL). Additive/idempotent; existing rows are unchanged. [Experimental agent coordination](#experimental-agent-coordination) |
| v49 | Park records and the wake decision (2026-09-28). Adds `coordination_agents.park_reason`, `park_needs`, `park_clear_by`, `park_resume`, `park_expires` and `park_set_at`: a session's standing statement of why it stopped and what clears it, set through `memory_agents(action="update", park_reason=..., ...)`, cleared by a null reason or a plain status update; `coordination_messages.wake`: the wake decision a send returned, repeated on a retry (`NULL` on earlier messages); and `coordination_wakes`: every `rung` or `nudged` ring the daemon decided, with its reason, `ring_at` and `served_at`, read by the caps (`coordination.wake`), the fan-out stagger and the recipient's next attach or heartbeat, and cut after seven days by the prune pass. The columns are added only when missing, like v46's and v47's. Additive/idempotent; existing rows read no park. [Park records and the wake decision](#park-records-and-the-wake-decision) |

Later additions that write into these tables without new DDL are listed with the feature that added them rather than as schema milestones: `memory_outcome(used_ids=[...])` (2026-09-05; every in-window serving event credited since 2026-09-08) labels served entries under `used_via="outcome"` — see the memory-model guide.

After running the entity-kind backfill (`evals/apply_entity_kinds.py --apply`), the daemon must be restarted for inference to take effect — it caches the entity-kind map for the life of its process.

A kind you set by hand is locked against later classifier runs — `evals/apply_entity_kinds.py --apply` overlays the model's labels onto the existing table rather than replacing it, so a deliberate marking is never reverted by a re-apply. The R@10 figures behind the v25 swap, and the rest of the shootout, are in [Benchmarks — embedding backbone](benchmarks.md#embedding-backbone--chosen-on-our-own-corpus).

### Extension schemas

A fork or downstream customization that adds its own tables should not
consume the next integer `schema_version` — that number belongs to this
repository's migration ladder, and claiming it guarantees a collision with
the next upstream release. The sanctioned pattern instead:

- **A namespaced marker key**: store the extension's lineage under its own
  `meta` key ending in `_schema_version` (for example
  `myext_schema_version = "v34-myext"`), leaving the integer
  `schema_version` untouched. Keys with this suffix are build-owned:
  the logical export/import skips them exactly like `schema_version`
  itself, so a marker never travels into a bank whose build does not
  provide the extension.
- **Additive, idempotent DDL** (`CREATE TABLE IF NOT EXISTS`, `CREATE OR
  REPLACE FUNCTION`, `DROP TRIGGER IF EXISTS` + `CREATE TRIGGER`) applied
  after upstream's `ensure_schema` tail, so daemon startup converges on
  the same shape regardless of what version it last ran.
- **Explicit enumeration**: add the extension's tables to
  `BENCH_RESET_TABLES` (so bench tooling can reset them) and to the
  transfer CLI's `EXCLUDED_TABLES` (so ordinary bank transfer neither
  moves nor blocks on them); give them their own portable format if their
  data needs to travel.

Upstream migrations stay unaware of extensions by construction — an
extension that follows this pattern rebases cleanly across upstream
schema bumps, and an upstream bank that has never seen the extension
simply carries no marker.

---

<!-- source: docs/guide/coordination-recovery.md -->

# Recovering agent mailboxes after a database restore

A database backup contains agent addresses, credential hashes and pending mail.
Restoring it can also restore old attachment and wake permissions. The offline
recovery command revokes those permissions before agents reconnect, while
retaining mailbox contents for deliberate recovery.

Do not run this procedure for an ordinary daemon restart. A restart preserves
credentials and pending mail; an expired attachment can reconnect with a fresh
lease. A raw database restore cannot be detected automatically.

## Restore procedure

The authenticated bank identity is stored in the existing `meta` table and is
preserved by database backup and restore. A restored clone therefore represents
the same logical bank; it is not automatically a new independent mailbox
authority. The restore procedure below still revokes restored instance
credentials and requires deliberate rebinds.

1. Take a backup before replacing the database. Stop the daemon and all attached
   adapters. Keep them stopped through recovery; editing configuration cannot
   disable a daemon that already loaded its configuration.
2. Set `coordination.enabled: false` in the configuration the restored daemon
   will use; coordination is on by default, so a configuration without the key
   is refused. Retain the `allowed_principals` list needed for later mailbox
   ownership checks (without the key, only `default` is allowed).
3. Restore the database using the normal backup procedure. Set
   `PSEUDOLIFE_MCP_DATABASE_URL` in the operator's environment to the restored
   database. Recovery uses this environment variable only: it does not start
   PostgreSQL, launch a daemon, load a model or apply schema migrations.
4. Revoke every restored instance credential and clear attachment/wake state:

   ```console
   pseudolife-mcp coordination-recovery recover --config <config.yaml> --confirm-daemon-stopped --confirm-restore
   ```

   This preserves messages and addresses, advances attachment generations and
   disables wake. Old adapters can no longer authenticate. The command refuses
   an enabled configuration or a missing confirmation. The stopped-daemon flag
   is an operator assertion; it does not inspect or stop running processes.
5. Rebind only the addresses you intend to resume. Each address must retain its
   original principal, which must appear in `coordination.allowed_principals`:

   ```console
   pseudolife-mcp coordination-recovery rebind --config <config.yaml> --confirm-daemon-stopped --agent <agent-id, or a unique prefix of 8 or more characters> --principal <principal> --bank-url http://127.0.0.1:8765 --state <new-private-state.json>
   ```

   Use an existing private directory outside any Git repository and a **new**
   file path for each adapter. Existing files, symlinks and hardlinks are
   refused, and so is a state path under any directory that contains a
   `.git` entry (the command walks every parent), so a checkout or a worktree
   cannot end up holding a mailbox credential. `--bank-url` is the daemon's
   own address (the compose stack serves `8765`).
   The command writes the bank URL, address and fresh credential with owner-only
   file access. It prints no credentials and never overwrites old adapter state.
6. After the intended addresses are rebound, enable coordination in the daemon
   configuration and restart the daemon. Point each adapter at its new explicit
   state file. Wake remains off until separately requested at adapter launch;
   restoring a backup never grants live delivery by itself.

The Python module is also callable directly with the same arguments:
`python -m pseudolife_memory.coordination_recovery`.

## The audit log across a restore

The board's [audit log](configuration.md#audit-log) (`coordination_events`,
schema v42) is restored with the database, as of the backup, so everything the
board did after the backup is gone from it too. The restored chain still
verifies, because the chain alone cannot see that its newest rows are missing.
If you recorded a head earlier, `pseudolife-mcp board-audit verify --expect-head
SEQ:HASH` shows whether that head survived. `recover` and each `rebind` append
operator events (`actor: operator`) to the restored log in the same transaction
as the change. A body redacted after the backup was taken is back, and its
`redact` row is gone: run `pseudolife-mcp board-audit redact` for it again
([redacting a body](configuration.md#redacting-a-body)).

A backup taken before v42 restores without the log. Recovery never migrates a
schema, so both commands still revoke and rebind, print that the operation is
not recorded, and the next daemon start creates an empty log.

## Failure and retention

A failed private-state write rolls back credential issuance. A crash or uncertain
database commit can leave an empty reservation or a state file whose credential
was not committed. Keep coordination disabled, retain the file for diagnosis,
and do not infer success from its existence. The command does not automatically
register a new address or silently replace the file. If the commit outcome cannot
be established, run the restore recovery operation again while offline and
rebind the intended mailboxes into fresh paths; this revokes any previously
rebound credentials too, so update every affected adapter deliberately.

Body expiry still applies to restored mail: receiving never returns expired or
acknowledged messages. Message bodies expire after 24 hours, while request keys
and terminal metadata remain for seven days from creation. Maintenance purges
expired bodies and old metadata during coordination activity. The audit log
keeps its own copy of each body for `coordination.audit_retention_days`
(default 90 days), and restoring a backup restores that copy too. The operator
can remove a body sent from schema v46 on with `board-audit redact`; one sent
before v46 is part of the hashed chain and stays until retention removes it
(`redact` still blanks its live mailbox copy while one is left).
Pending capacity
errors never silently discard mail. The mailbox clock high-water mark survives
message pruning, so restart with a backward wall clock cannot regress its stamps.

### Malformed coordination clock row

Calls that initialize the bank fail with `invalid coordination clock high-water
mark`, reads included, while `/health` can still report the daemon up. The
`coordination_hlc_highwater` value in `meta` must be a two-element list of
non-negative integers: the physical and logical parts of the HLC.

Do not delete this row or reset it to zero. It can be the only surviving bound
for mailbox-only writes after message pruning. Neither the remaining messages
nor the cortex, world and lesson records necessarily contain the latest stamp;
an older backup alone does not cover writes made after that backup.

1. Stop the daemon and adapters, take a database backup, and preserve the damaged
   row for diagnosis before editing it.
2. Establish a verified HLC bound that is at least as high as every stamp issued
   before the corruption, including pruned messages. Use a trustworthy copy of
   the latest high-water mark or complete evidence of subsequent writes. Compare
   stamps as integer pairs, not strings. If no such bound can be established,
   keep the bank stopped; do not guess a replacement or discard the safeguard.
3. In a database session with errors configured to stop execution, replace the
   placeholders below with that verified pair and update only the damaged row:

   ```sql
   BEGIN;
   UPDATE meta SET value = '[<verified-physical>, <verified-logical>]'::jsonb
   WHERE key = 'coordination_hlc_highwater';
   SELECT value FROM meta WHERE key = 'coordination_hlc_highwater';
   COMMIT;
   ```

   Confirm one row was updated and the returned value matches the verified pair.
4. Restart the daemon with adapters still stopped. Re-seeding observes this bound
   alongside the slot stores, so subsequent stamps must exceed it even if the
   wall clock moved backward. Verify initialization succeeds before restarting
   the adapters. Retain the backup and repair evidence.

Portable knowledge exports exclude agent mailboxes, credentials, the audit log,
bank identity and operational metadata. Import also ignores any bank identity in an archive,
preserving the destination's identity. Full database backups retain it. See
[configuration](configuration.md#experimental-agent-coordination) for the
feature's defaults and [the experimental design](../specs/2026-09-11-agent-coordination-design.md)
for delivery and acknowledgment semantics.

---

<!-- source: docs/guide/providers.md -->

# Providers — one memory bank across every coding agent

The daemon speaks MCP, so any MCP-capable coding agent can use the same
bank. What differs per agent is how much of the **memory loop guidance**
its platform can carry: Claude Code and current Codex runtimes have
lifecycle hooks, while generic MCP clients only get
what the protocol itself delivers. This page is the honest map — what each
provider gets, what its platform cannot support, and what to do about the
gaps. The installer (`ops/install.sh` / `ops\install.ps1`) wires all of
this and prints the same matrix and a per-agent ladder at the end of every
run.

## Capability matrix

| Agent | MCP transport | Session briefing | Per-turn discipline | Standing file |
|---|---|---|---|---|
| Claude Code | stdio shim / HTTP | SessionStart hook or plugin | UserPromptSubmit hook | `~/.claude/CLAUDE.md` |
| Claude Desktop | stdio shim (entry written to `claude_desktop_config.json`) | — | — | — (server `instructions` only) |
| OpenAI Codex | stdio shim / HTTP | SessionStart hook (trust required\*) | UserPromptSubmit hook | `~/.codex/AGENTS.md` |
| Gemini CLI | stdio shim / HTTP | — | — | `~/.gemini/GEMINI.md` |
| Other MCP agent | stdio / HTTP (pasted config) | — | — | `AGENTS.md` (your path) |

\* Hook availability depends on the runtime and policy — see
[Codex specifics](#codex-specifics) below.

Every agent also gets, with no files touched: the **memory tools**, and the
MCP server **`instructions` field** — a compact statement of the memory
loop and startup messageboard check-in supplied at connect time; the client controls how it uses that field. It
is deliberately client-neutral and capped at 512 characters (guard-tested),
and the stdio shim forwards the running daemon's value unchanged.

## The hook-equivalent ladder

The installer combines the available delivery layers. These guide the model;
they do not enforce semantic compliance with every memory instruction:

1. **MCP registration** — the tools themselves. Universal.
2. **Server `instructions`** — the protocol-level memory loop. Universal,
   automatic.
3. **Standing instructions file** — the full memory-loop block
   (`examples/CLAUDE.memory.md`) appended to the agent's global context
   file. For hook-less providers this supplies the full policy, without a
   live briefing, so the installer recommends the append — but never writes a
   standing file without consent: an interactive prompt, or an explicit
   `--instructions append` / `--agents-file`. Codex's automatic-memory
   approval also covers this fallback if hook verification fails. Unattended
   Codex setup requires explicit `--codex-hook-trust yes` for that combined
   approval; `--instructions skip` always prevents a standing-file edit.
4. **SessionStart hooks** — a concise memory guide and bounded daemon-served
   briefing, plus an independent coordination check-in instruction. The memory
   briefing keeps complete items and reports omissions; detailed guidance stays
   in the standing block. Claude Code (hook or plugin), Codex
   (approve setup or review the definitions in `/hooks` first).
5. **Per-turn hooks** — with the plugin, a memory-change note printed only
   when new lessons or other sessions' status notes landed since the last
   one, with a one-line reminder (recall before review, status questions are
   memory questions, log outcomes); the `ops/install-hook.*` fallback
   injects that reminder as a fixed line on every prompt. Plus a separate
   coordination handler for changed inbox previews. Full addressed messages are read through `memory_message`, then
   acknowledged after reading. Claude Code and current Codex runtimes.

The coordination hook does not register a second mailbox or own credentials:
the existing adapter remains responsible for identity and its lease. The agent
sets `project`, `task` and `status` using `memory_agents(action="update")`, lists
peers, and receives pending mail at the first task and on resume. Disabled or
unavailable coordination is reported once; ordinary memory work continues.
Seeing a preview is not an acknowledgment, and a peer's message cannot grant
user approval or reserve a resource.

Desktop Code modes that run the coding runtime can use its hooks. Ordinary
chat and other MCP clients must use the server instructions and supported
standing/project instructions instead; installing an MCP connection does not
create a per-turn hook. They receive coordination hints on supported tool
results, with no promise of an idle-session wake. Task-specific recall uses
`memory_search` and `memory_lesson_search` after the task is known; the global
startup briefing is not a relevance-ranked answer to a prompt it has not seen.

## One more axis: who dreams

The provider that *talks* to the bank and the model that *consolidates* it
are separate choices, and the installer wires both. `--extractor` /
`-Extractor` takes `sidecar` (the bundled CPU model, the default),
`sonnet-fallback` / `sonnet-only` (a Claude Max plan via the CLI shim), or
`codex-fallback` / `codex-only` (a ChatGPT plan via the Codex CLI shim) —
independently of `--client`. Any OpenAI-compatible endpoint works without a
shim at all. See [Dreaming](dreaming.md) for the wiring and the measured
extraction quality per model.

## Claude Code

Full parity. The [plugin](../../plugin/README.md) is the recommended
hooks/commands layer — it is the only path that registers the session
identity with the daemon (SessionStart forwards Claude Code's own
`session_id`) and closes the episode on SessionEnd. Its `Stop` hook (on by
default since 2026-09-28, `PSEUDOLIFE_AGENT_WAKE_HOOK=0` turns it off) also
wakes an idle session when board mail that clears its declared need arrives (see
[Configuration](configuration.md#waking-an-idle-claude-code-session-the-stop-hook)).
`ops/install-hook.*`
is the non-plugin fallback: it installs the SessionStart briefing
(`pseudolife-mcp briefing --hook-json`, which serves the plugin hook's memory
core and bounded briefing) and the per-turn memory-change note
(`pseudolife-mcp prompt-hook`, the plugin hook's note: it prints only when
new lessons or other sessions' status notes landed since the session's last
note; re-running the installer replaces the static discipline echo older
versions wrote), but no SessionEnd hook and no identity registration — those sessions fall
back to the shim header or idle-gap sessionization (see
[Episodes](episodes.md#session-lifecycle--daemon-owned-episodes)). The MCP
transport comes from the installer either way (stdio shim by default),
registered with `PSEUDOLIFE_WRITER_ID=claude-code` so writes are
attributed per provider.

Upgrading from the fallback to the plugin leaves its hooks in
`~/.claude/settings.json`, where they duplicate the plugin's. The installer
offers to remove them once the plugin is installed and enabled for all
projects (`--claude-legacy-hooks remove` / `-ClaudeLegacyHooks remove` does
it unattended), and `ops/install-hook.* --remove-legacy` does the same by
hand. Only the exact entries the installers wrote are removed, after a
backup; an edited copy of one is listed for review and kept.

With the coordination adapter enabled, the plugin's coordination
UserPromptSubmit hook prints the session's coordination digest (the
fallback's `prompt-hook` does not) — pending addressed mail, rendered
by the shim into a per-session file — but only on the turn after it changed;
see [Configuration](configuration.md#experimental-agent-coordination) for the file layout
and `PSEUDOLIFE_DIGEST_DIR`.

Claude Code reads `CLAUDE.md`, not `AGENTS.md` — see
[the AGENTS.md standard](#the-agentsmd-standard) for the one-line bridge.

## Claude Desktop

`--client claude-desktop` writes the stdio-shim entry into
`claude_desktop_config.json` — Desktop has no `mcp add`. The merge lives in
`ops/register_claude_desktop.py` (standard library only), which both
installers call and which you can run by hand with
`--command <absolute shim path>` (`--dry-run` prints the resolved path and
entry). What Desktop does differently, and what the entry carries because
of it:

- **Its own name.** The entry is `pseudolife-desktop`. Desktop's Code tab
  runs Claude Code, which starts its own per-session `pseudolife-memory`
  server; where an app-level entry carries the same name, Desktop sends the
  session's `mcp__pseudolife-memory__*` calls to the app-level entry and the
  session's own server gets none (seen live on 2026-09-21), so the session
  has no board identity of its own. The registrar renames an entry it wrote
  under the old name, recognised by `PSEUDOLIFE_WRITER_ID=claude-desktop` in
  its `env`, and keeps its other settings: hand-added `env` keys, a
  configured token-file path, a literal token to migrate. When both names
  exist, `pseudolife-desktop` wins wherever both set a key, the old entry
  fills the gaps, and the output names the `env` keys whose old values were
  dropped (names, never values), apart from the settings the registrar
  rewrites on every run. A `pseudolife-memory` entry the registrar did not
  write is left untouched and reported on every run, and `pseudolife-desktop`
  is written beside it, so Desktop loads both. Every rewrite
  backs the config up first (`claude_desktop_config.json.bak-<timestamp>`).
  Afterwards Chat and Cowork list the tools as `mcp__pseudolife-desktop__*`.
- **Sanitized launch environment.** Desktop starts MCP servers with PATH
  plus a few system variables — none of your shell's exports. So `command`
  is the shim's absolute path (a bare `pseudolife-mcp` would not resolve),
  and a token-gated daemon gets `PSEUDOLIFE_MCP_TOKEN_FILE` — the path of a
  private file holding the bearer, reloaded per call — in the entry's
  `env`. A token exported in the OS environment never arrives. When the
  daemon is token-gated the installer *writes* that file (owner-only) from
  `PSEUDOLIFE_MCP_TOKEN` in its own environment or `ops/.env`, a unique
  `claude-desktop` principal in `PSEUDOLIFE_MCP_TOKENS`, or a literal token
  already in the entry — the shim reads the file
  first and unconditionally, so the registrar never points at a file it
  did not write or validate. With no token to write it registers without
  a credential and says so (exit 3): re-run with `PSEUDOLIFE_MCP_TOKEN`
  set. Without a usable credential every session fails as *"Couldn't start
  for Cowork and Code sessions … unhandled errors in a TaskGroup"*, a 401
  (or an unusable token file) the shim now names on stderr at startup.
- **The shim must be able to read that file.** Source installers now use
  the matching checkout, but PyPI releases through 0.15.0 read only the literal
  `PSEUDOLIFE_MCP_TOKEN`, which Desktop never delivers. Before writing
  anything the registrar runs `<command> --help` and looks for the
  `PSEUDOLIFE_MCP_TOKEN_FILE` line a capable shim prints; a shim that
  answers without it is refused (exit 4, nothing written) with the
  upgrade named — `pipx upgrade pseudolife-mcp`, or `pipx install --force .` from
  the checkout for a change not yet released — and so is a shim from
  before `--help` existed (it answers "unknown mode"). On Windows, run that
  upgrade with every session using the shim closed (Desktop fully quit
  from the tray), or it can leave the shim half-removed. A probe that yields
  no evidence (missing, not executable, timeout, any other non-zero exit,
  exit 0 with no output) is not blocking: the run proceeds and says the
  check did not happen, so a clean exit 0 from the registrar is proof only
  when it printed `shim check: … reads PSEUDOLIFE_MCP_TOKEN_FILE`. The
  probe gets no stdin and not the token variable. `--skip-shim-check`
  bypasses it for a wrapper the probe cannot see through.
- **Credential preservation on updates.** An ordinary rerun reuses and
  validates the entry's existing private token-file path, even if it differs
  from the installer's default. `PSEUDOLIFE_MCP_TOKEN_FILE` explicitly selects
  a replacement; an unusable replacement leaves the existing configuration
  intact. If a token map has no unique `claude-desktop` credential for a fresh
  setup, registration refuses to guess: provide an explicit private token
  file for that client. Credential values are never command-line arguments
  or printed configuration.
- **Config location.** macOS `~/Library/Application Support/Claude/`, Linux
  `~/.config/Claude/` (or `$XDG_CONFIG_HOME/Claude/`), Windows
  `%APPDATA%\Claude\` — except the Store/MSIX build, whose real file is
  `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json`
  (an unpackaged shell's `%APPDATA%\Claude` may not even exist). The
  registrar prefers the package cache when it exists and prints the path
  it wrote.
- **No hook layer, no standing file.** Desktop reads no `CLAUDE.md`; the
  MCP server `instructions` field is its whole briefing. Writes carry the
  `claude-desktop` writer id, so a shared bank can tell Desktop sessions
  from Claude Code ones and tier them separately.
- **Reload.** Fully quit Desktop (tray / menu-bar icon) and relaunch after
  any config change — closing the window does not reload the file.

## Codex specifics

MCP wiring is first-class (`codex mcp add`, shim or `--url` HTTP;
`PSEUDOLIFE_WRITER_ID=codex`). Current Codex runtimes support SessionStart,
UserPromptSubmit, and SessionEnd on Windows as well as Unix. Hooks are enabled by
default; the canonical feature key is `hooks` (`codex_hooks` is a deprecated
alias). A managed policy or `[features] hooks = false` can disable them.
This is runtime support, not a model capability or a promise about ordinary
ChatGPT conversations. See the [official hook protocol](https://learn.chatgpt.com/docs/hooks).

The Docker installer defaults to automatic hook-source detection. One setup
choice enables automatic memory briefings, reminders, and session cleanup
(plus, where the agent board is on, a board check-in at session start and a
new-mail hint when a peer's message is waiting), uses standing instructions
only, or skips this integration. The automatic
choice approves just PseudoLife's exact current hook definitions and permits
the standing memory block as a fallback if verification fails. It does not
approve unrelated hooks or turn off Codex's trust checks.

For an existing installation with the daemon running, use the same helper:

```bash
python ops/setup-codex-hooks.py
```

Auto detection reuses an enabled PseudoLife plugin when its complete hook
bundle matches this installation. Otherwise it installs a private copy of
the three lifecycle scripts and writes manual definitions to the Codex home
(`~/.codex/hooks.json` by default). Known old manual definitions are handled
to avoid duplicate PseudoLife events; unrelated hooks are preserved. An
incomplete or unrecognized plugin bundle requires review rather than
automatically granting trust. Disabled hooks and intentional feature or
policy restrictions remain in place.

The plugin's `hooks.json` also carries Claude Code's wake hook on
`Stop` (on by default since 2026-09-28), so Codex 0.148 and later lists a
fourth PseudoLife hook (earlier releases skip async hooks there). In Codex
it runs only the
[Stop-hook park gate](configuration.md#waking-an-idle-claude-code-session-the-stop-hook):
one request asking the daemon whether the thread parked, answered with
Codex's documented `{"decision": "block", "reason": ...}` when it did not,
and nothing otherwise (an explicit `PSEUDOLIFE_AGENT_WAKE_HOOK=0` turns it
off). On Windows the native command runs it; on macOS and Linux the bash
script does, in Codex context, through the managed connection file. The
wake itself is Claude Code's. Codex's own wake path is the
[doorbell](configuration.md#codex-doorbell), also on by default when a
`codex` CLI is found; a woken task needs `memory_message` approved, or it
stalls on a prompt. Setup approves it with the other three, and disabling it in
`/hooks` does not block setup. After a plugin update, Codex's startup hook
review lists it until setup reruns. Manual installs keep the three lifecycle
events.

For authenticated stdio connections, setup prepares a private bearer file and
records the same daemon URL and file path for the shim and lifecycle hooks.
Updating that file changes the credential used by subsequent operations; users
do not need to copy the bearer into each hook or restart a file-backed shim.
An already running older shim needs one reconnect after upgrading. See
[credential configuration and mailbox continuity](configuration.md#codex-cli-and-desktop)
for existing installations and rotation behavior.

After a successful fresh Codex registration, the installer supplies missing
startup and tool budgets of 240 seconds and marks memory as required. Explicit
settings and existing registrations are preserved. If saving these defaults
fails, setup reports the remaining step; retry with
`python ops/setup-codex-coordination.py --runtime-defaults`.

| Setting | Docker installer | Standalone helper |
|---|---|---|
| Hook source; default `auto` | `--codex-hooks auto\|manual\|plugin\|skip` | `--source auto\|manual\|plugin\|skip` |
| Scoped approval; default `ask` | `--codex-hook-trust ask\|yes\|no` | `--trust ask\|yes\|no` |
| Standing block; default `auto` | `--instructions auto\|append\|skip` | `--instructions auto\|append\|skip` |

PowerShell uses `-CodexHooks`, `-CodexHookTrust`, and `-Instructions` with
the same values. For unattended setup, explicit `yes` authorizes scoped
trust and the fallback; `ask` without an interactive terminal does not grant
approval. The helper also accepts `--non-interactive` to disable prompting.

```bash
# Full unattended setup with automatic memory approved:
ops/install.sh --extractor sidecar --client codex --codex-hook-trust yes
# Existing installation, same scoped approval:
python ops/setup-codex-hooks.py --trust yes --non-interactive
# Standing instructions only:
python ops/setup-codex-hooks.py --source skip --instructions append --non-interactive
```

```powershell
ops\install.ps1 -Extractor sidecar -Client codex -CodexHookTrust yes
# Standing instructions only:
ops\install.ps1 -Extractor sidecar -Client codex -CodexHooks skip -Instructions append
```

`--instructions append` can keep a standing copy even with working hooks.
Explicit `--instructions skip` prevents that edit, including fallback;
`--source skip` leaves existing hooks alone. The older
`ops/install-hook.ps1 -Client codex` and `ops/install-hook.sh --client codex`
still write briefing and reminder definitions, but do not perform the new
trust and readiness workflow.

The Windows installer and plugin supply
`commandWindows` overrides, which Codex runs; Claude Code ignores the field
and runs its Bash plugin commands through Git Bash, which it must find on
the machine (see the plugin README's
[Windows](../../plugin/README.md#windows) section). Plugin SessionEnd on Windows uses a bounded
request inside Codex's three-second maximum, with idle reaping as fallback.
SessionStart retries one transient failure within its 15-second budget. The
native command escapes non-ASCII context so redirected JSON stays valid under
Windows OEM code pages as well as UTF-8.

**Readiness requires execution.** The helper obtains hook identities and
hashes from the installed Codex runtime, backs up configuration, and persists
approved trust through Codex's configuration interface. It then checks the
startup briefing, per-prompt reminder, and episode open/close effects through
an actual local Codex lifecycle, without sending requests to an external
model provider. It reports
memory ready only when those checks pass. The check uses the configured Codex
home in a temporary workspace; project-specific overrides or a different app
runtime can affect another task. Start a fresh task in your Codex application
to receive its startup briefing.

If the runtime's hook or trust interface is unavailable or unsupported, or a
hook fails verification, setup reports what remains unresolved and provides
`/hooks` repair guidance. It installs the standing block only when approved;
installed files or saved hashes alone never count as working hooks. New or
changed definitions require approval again. Manual script bundles use
content-specific paths so updating their code also changes the definitions.

### Hooks versus AGENTS.md

The default SessionStart policy is a compact core of the memory
instructions, not the full block in `examples/CLAUDE.memory.md`; append that
block when you want the complete guidance. Neither replaces the rest of a
project's `AGENTS.md`: personality, coding rules, project conventions, and
other instructions still belong there. A custom daemon
`hook-instructions.md` is served after the core, capped at 3.5 KB.

| Mechanism | What it supplies |
|---|---|
| `AGENTS.md` memory block | Standing guidance to recall, capture, and reflect when the client loads instructions |
| `SessionStart` | A compact memory policy, a live briefing, and session episode identity |
| `UserPromptSubmit` | A short note on a prompt after memory changed (new lessons, other sessions' status notes); nothing otherwise |
| `SessionEnd` | Automatic session episode cleanup |

Hooks provide timed execution and lifecycle bookkeeping. Their briefings
and reminders still rely on the model to act on instructions: they do not
block work when recall is skipped or guarantee a memory write. Use verified
hooks as the primary integration and standing instructions when hooks cannot
run, or keep both when a standing copy is useful for subagents.

### Verify the registered runtime

The source installers install the host shim from their checkout, including
when an older installation has the same version number. This keeps the shim's
credential handling aligned with the daemon built from that checkout. The
Codex setup helpers can run before package installation; no `PYTHONPATH`
setting or preinstalled Pseudolife package is required.

Fresh registrations use the executable produced by the selected package
manager. A competing older executable on `PATH` must not be mistaken for the
new installation. For an existing bare command, a reported path mismatch
needs to be resolved before the installer can confirm the upgrade.

For an update, use the intended checkout and rerun its installer with the
same client selection when migrating an installation from before the agent
board. `ops/update.ps1` / `ops/update.sh` update the daemon only by default;
`-All` / `--all` also refresh host shims and client plugin caches, followed
by a client restart. Follow the [README update recipe](../../README.md#updating)
for the installer migration and Windows prerequisites. Existing custom MCP
registrations are preserved. If one points at a separate virtual environment,
upgrade that exact environment as described below. For a versioned plugin release,
update the Pseudolife plugin through the client's plugin manager. For changed
hooks within the same version, the manager reports "already latest"; use
`-All` / `--all` to refresh the cache instead. Then rerun hook setup and
approve the changed scripts. Editing a plugin cache directly does not
survive plugin updates.

Docker-tier stdio registrations must set `PSEUDOLIFE_MCP_NO_SPAWN=1` so a
client waits for the Docker daemon instead of starting a fallback over a
different bank. A missing, disabled, or unverified setting leaves setup
incomplete. Add the setting to the existing registration while preserving
its command, arguments, daemon URL, credential path, and other environment
entries. If a client's registration command cannot set environment variables,
upgrade the client or configure that entry manually before using the shim.

1. Inspect `codex mcp list` and `codex mcp get pseudolife-memory` (or the
   plugin's MCP configuration). Keep one registration. Identify the exact
   executable; a repo venv can differ from a global executable or plugin cache.
2. In that environment run `pseudolife-mcp doctor`. It reports interpreter,
   source path, installed package/SDK versions, health, instructions and tool
   annotations. It neither starts a daemon nor calls a bank tool. A healthy
   endpoint alone does not establish a working stdio handshake. Its `board`
   line says whether the agent board is on for that environment's token, or
   the daemon's reason it is off.
   An unreachable daemon report tells you to start it; a handshake timeout
   suggests checking MCP access and increasing `doctor --timeout` if needed.
   If the shim cannot fetch startup instructions within five seconds, it logs
   a sanitized stderr message and still initializes. Tool requests retain their own fresh upstream
   connections, but persistent authentication failures still need correction;
   reconnect after recovery to receive the startup guidance.
3. Run that interpreter with `-m pip check` and `-m pip show pseudolife-mcp mcp`.
   For a stale published installation, use that interpreter's
   `-m pip install --upgrade "pseudolife-mcp[lite]"`; for a source checkout,
   reinstall the intended checkout with `-m pip install -e .` to refresh
   dependencies and editable metadata. Docker shim-only hosts omit `[lite]`.
   On Windows, run either with every session using that shim closed
   (Claude Desktop fully quit from the tray), or it can leave the shim
   half-removed.
   Re-running the Docker installer preserves existing registrations; it does
   not repair a different interpreter already registered with Codex.
4. Reconnect and ask for a real memory search and lesson search. Confirm the
   tools are callable in the new task; `doctor` only proves protocol inventory.
   Store a truthful decision and verify it from another task when testing writes.

For a cold lite daemon, add `startup_timeout_sec = 240`,
`tool_timeout_sec = 240`, and `required = true` to the existing MCP server
table. This allows the shim's 180-second startup wait plus handshake margin;
the tool budget allows first-call model loading and leaves a margin beyond the
shim's 180-second operation deadline. Prewarm the daemon if the
initial model download takes longer. `required` waits for memory's initial
catalog and makes startup failure explicit. Codex otherwise has a 10-second
startup timeout and may assemble an optional catalog earlier. See
[official MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

### Discovery and approvals

Prefer the needed catalog at connection time. An unconfigured daemon defaults
to `full`; deployments can override that with a principal-specific tier map.
For clients that retain their initial catalog, the operator can explicitly
choose `codex:full` in `PSEUDOLIFE_MCP_TIER_MAP` for the intended identity and
then reconnect. Do not change the shared default or another principal simply
to discover one tool. A bearer principal takes precedence over writer identity;
check which identity the registration actually uses.

A September 2026 Codex check expanded core to full: the server listed 35 tools
and sent `list_changed`, but the running turn retained its initial 22 callable
tools. That verifies a current-turn limit only. After expansion, check a fresh
task/reconnection's actual callable catalog; do not infer success from the
server inventory or notification. Client `enabled_tools`/`disabled_tools`
filters can narrow it further.

All tools carry approval hints. Searches are read operations over claims;
access telemetry can still update. Explicit retention reinforcement and tools
mixing status with mutation (toolset, dream, graph review) are marked writes.
Destructive hints also cover replacing document chunks during reingestion and
replacing canonical facts through `memory_store` when auto-promotion is enabled.
Hints inform a client's `default_tools_approval_mode = "writes"`; they are not
authorization and do not override per-tool approval settings or managed policy.
An allow-once prompt does not guarantee durable approval. Inspect any existing
`tools.<tool>.approval_mode` override if prompts differ from the server default;
the installer and doctor do not change approval policy.

Codex can also filter tools **client-side, per project**: a project-scoped
`.codex/config.toml` (loaded for trusted projects only) may register the
server with an `enabled_tools` allow-list, exposing just a subset of the
memory tools to that one project (`disabled_tools` is the matching
deny-list, applied after it):

```toml
# <project>/.codex/config.toml — trusted projects only
[mcp_servers.pseudolife-memory]
url = "http://127.0.0.1:8765/mcp"
enabled_tools = ["memory_search", "memory_store", "memory_outcome"]
startup_timeout_sec = 20
tool_timeout_sec = 60
```

This complements the daemon's server-side
[toolset tiers](configuration.md#toolset-tiers): tiers key the roster to
the caller's identity for every session, while `enabled_tools` narrows it
further for a single project without touching the daemon. One operational
note: reconnect after registering a server and verify a real tool call in
the new task rather than relying on a config write.

## Gemini CLI

MCP wiring is first-class and scriptable (flags verified against Gemini CLI
0.57.0):

```bash
gemini mcp add -s user -e PSEUDOLIFE_WRITER_ID=gemini -e PSEUDOLIFE_MCP_NO_SPAWN=1 pseudolife-memory pseudolife-mcp
# or HTTP:
gemini mcp add -s user -t http pseudolife-memory http://127.0.0.1:8765/mcp
```

`-s user` matters — Gemini defaults to *project* scope.

> **Auth caveat:** since 2026-06-18 Google no longer serves individual-tier
> accounts (free, Google AI Pro, AI Ultra) through Gemini CLI — OAuth
> sign-in fails with `IneligibleTierError`, pointing at Antigravity as the
> migration path. The wiring above is auth-independent and stays correct,
> but to actually run sessions an individual account needs API-key auth
> (set `GEMINI_API_KEY`); enterprise Gemini Code Assist licenses keep
> working unchanged.

If you migrated to **Google Antigravity** (where that error points), it can
use the same bank. Its global MCP config is
`~/.gemini/config/mcp_config.json`:

```json
{
  "mcpServers": {
    "pseudolife-memory": {
      "command": "pseudolife-mcp",
      "args": [],
      "env": {
        "PSEUDOLIFE_WRITER_ID": "antigravity",
        "PSEUDOLIFE_MCP_NO_SPAWN": "1"
      }
    }
  }
}
```

A running Antigravity picks the file up from the refresh button in
Settings → Customizations → Installed MCP Servers, and asks per-tool
approval on first use. Verified live 2026-08-31: tools discovered, search
and fact writes round-tripped, writes attributed as writer `antigravity`.

`PSEUDOLIFE_MCP_NO_SPAWN=1` belongs on Docker-tier shim registrations
(every provider): it makes the shim wait for the compose container instead
of spawning a host fallback that can shadow the real bank after a reboot —
drop it only on the `[lite]` pip tier, where the spawn fallback is the
zero-config path. Gemini CLI has no
hook system that can inject session context, so the standing file supplies
the policy: the installer offers to append the block to `~/.gemini/GEMINI.md`
(Gemini's default context file on a stock install; it also reads
`AGENTS.md` where that has been configured as the context file name).

## Other MCP agents (Cursor, Windsurf, Zed, Copilot CLI, …)

`--client generic` prints two paste-ready `mcpServers` shapes — stdio shim
(per-session identity, needs `pip install pseudolife-mcp`) and plain HTTP —
plus the usual config homes per tool. These agents get the tools and the
server `instructions` field; there is no hook layer to wire, so pair the
config with a standing `AGENTS.md` block (the installer offers a
consent-gated append to a path you choose, or `--agents-file <path>`
non-interactively). Writes arrive as the neutral `mcp-client` writer unless
you set `PSEUDOLIFE_WRITER_ID` in the server's `env`.

## The AGENTS.md standard

`AGENTS.md` is the cross-vendor standard for standing agent instructions
(launched by OpenAI in 2025, since transferred to the Linux Foundation's
Agentic AI Foundation; read by 30+ agents including Codex, GitHub Copilot,
Cursor, Gemini CLI, Zed, and Windsurf). A per-project `AGENTS.md` carrying
the memory block reaches almost every agent at once. Claude Code is the
holdout — it reads `CLAUDE.md` — but a `CLAUDE.md` whose **first line is
`@AGENTS.md`** imports the shared file, so one copy serves every tool:

```
@AGENTS.md
```

## Writer ids

Each first-class provider's shim registration carries its own
`PSEUDOLIFE_WRITER_ID` (`claude-code` / `claude-desktop` / `codex` /
`gemini`), which the shim
forwards as the `X-PL-Writer` header — so a shared bank can tell which
agent wrote what, and toolset tiers can be keyed per client. HTTP
registrations cannot carry env; there the daemon-side default in `ops/.env`
applies (the installer sets it to the single selected provider's id, or the
neutral `mcp-client` for multi-provider and generic installs). Details:
[session identity](configuration.md#session-identity) and
[toolset tiers](configuration.md#toolset-tiers).

---

<!-- source: docs/guide/benchmarks.md -->

# Benchmarks

What the memory actually buys, measured. Part of the
[user guide](../../README.md#documentation); the full methodology and every
finding live in [`evals/README.md`](../../evals/README.md).

**The bench instrument changed on 2026-08-17.** Every accuracy on this page
was graded by a local **Qwen3.6-27B** answerer/judge; the bench stack has
since migrated to **Qwen3.8-27B**, and only the knowledge-update slice has
been re-run on it — the sole Qwen3.8 numbers here are that comparison's
right-hand column
([the knowledge-update slice](#the-knowledge-update-slice-78-of-the-500),
where both stacks are published side by side).
The instrument is a term in every number below: compare within a stack, and
treat a claim that has not been reproduced across judge families as
provisional. One number on this page has graduated out of that caveat:
the budget-matched hybrid arm of 2026-09-04, re-judged 2026-09-05 by a
second, independent judge family and still a win
([below](#the-budget-matched-hybrid-arm-2026-09-04)).

Nearly every number on this page was measured on the **pre-v25 stack**: the
384-d MiniLM backbone, with the BM25 hybrid pool off. Both defaults have
since changed — the backbone swapped at schema v25 and BM25 flipped on
2026-07-25 — and the arms that read raw turns (naive RAG, hybrid) *select*
those turns with the retriever that changed, whose measured R@10 moved
0.572 → 0.809. The exceptions are the two tables at the top — the
500-question sweep and the knowledge-update slice — which ran end to end
on the post-v25 stack, and the held-fixed rebuild below them, re-judged
2026-07-29 on the reproducible server with its fact ranking under the v25
backbone (though even there extraction and raw-turn selection are held at
the pre-v25 run — see the note under that table). Read the rest as
historical measurements of the design, not as what the shipped
configuration scores today.

## LongMemEval

[LongMemEval](https://arxiv.org/abs/2410.10813) has six question types and
500 questions. The headline table below is the **whole benchmark**; the
**knowledge-update** subset (78 questions — the "user's facts change over
time" ability the HLC supersession spine exists for) is published under it
as a named sub-slice, because it is the type this design is built to win
and publishing it alone overstates the system. Sections after that hold
older KU-only measurements and say so. Everything local: extraction,
answering, and LLM-as-judge grading all run on the author's own hardware
(judge = Qwen3.6-27B at temperature 0), so compare *within* the table, not
against GPT-4o-judged leaderboards.

> **Reading the numbers.** Except for the ceiling tables below
> (re-judged 2026-07-29 on the reproducible stock server), accuracies on
> this page are single-run point estimates unless marked mean ± std, and
> they were measured on a stack
> that **was not bit-reproducible**. Repeated runs of an *identical*
> config varied by several points (observed spread: ~7.7 pp on the cortex
> arm at n=78); that was long attributed to answerer/judge noise, and
> root-caused on 2026-07-27 to the TurboQuant fork's fused TBQ4_0
> flash-attention KV cache instead — `evals/results/judge-determinism-check.json`
> records 6.8–7.7% verdict flips on byte-identical input, with
> `verdict.reproducible: false`. On the stock server with
> `--cache-type-k/v q8_0` the same pipeline reproduces exactly:
> `evals/results/regression_gate.baseline.json` records **std 0.0000 on
> all three arms at n=7**. So the numbers on this page carry a run-to-run
> band that a re-measurement would not, and small single-run differences
> between configs are not meaningful **here**. Re-measure rather than
> reinterpret; decision-grade comparisons use replicates and a paired test
> — see [Variance and replication](../../evals/README.md#variance-and-replication).

## The full 500-question sweep — all six question types (2026-08-03)

The headline table is the **whole benchmark, not a slice**: all six
LongMemEval question types, 500 questions, oracle variant, run end to end
through the memory (qwen-27b extraction under the v25 embedding backbone,
BM25-on turn retrieval). Single pass — not replicated — graded by the local
Qwen3.6-27B judge. Artifact:
`evals/results/longmemeval-all-oracle-qwen-27b-alltypes-0803.summary.json`.

| arm | accuracy | context tokens/question |
|-----|----------|------------------------|
| naive RAG (top-6 turns) | 0.688 | ~1210 |
| cortex facts only | 0.416 | **~158** |
| hybrid (facts + top-3 turns) | 0.664 | ~842 |
| **commit-gated cascade** | **0.690** | ~883 |

Overall this is **a wash on accuracy at ~73% of naive RAG's context**:
0.690 vs 0.688 is one question in 500 on a single pass and carries no
weight as a win. The fact spine alone answers at ~13% of RAG's token
budget, at a large accuracy cost outside the types it is built for. The
**cascade** is a serving policy, not a fourth pipeline — serve the cortex
answer when that channel *commits*, fall back to RAG when it says "I don't
know". Routing reads only the response text, never correctness, so the
policy is deployable as-is; it is a *derived* metric
(`replicate.py cascade_correct`) over the judged rag/cortex arms.

Per type the picture is not uniform, and this is the honest shape of the
result:

| question type | n | naive RAG | cortex | hybrid | cascade |
|---|---:|---:|---:|---:|---:|
| knowledge-update | 78 | 0.859 | 0.756 | 0.910 | ~~0.936~~ (retired — [below](#the-knowledge-update-slice-78-of-the-500)) |
| single-session-user | 70 | 0.929 | 0.671 | 0.957 | 0.943 |
| single-session-assistant | 56 | 0.911 | 0.571 | 0.964 | 0.929 |
| single-session-preference | 30 | 0.800 | 0.733 | 0.600 | 0.700 |
| temporal-reasoning | 133 | 0.526 | 0.150 | 0.534 | 0.526 |
| multi-session | 133 | 0.504 | 0.211 | 0.383 | 0.474 |

The consolidated spine helps where a fact changes and where the answer sits
inside one session; it loses where the answer must be aggregated across
sessions or ordered in time, because per-fact consolidation is exactly what
discards that structure. BEAM-100K reproduces the same shape on a
completely different corpus — see
[BEAM](../../evals/README.md#beam-long-term-memory-benchmark-beam_adapterpy).

Two limits on this table, both load-bearing. **(1)** The hybrid arm here
served 3 raw turns against the rag control's 6; the bench default was
budget-matched to 6/6 on 2026-08-21, so every hybrid row on this page is a
half-budget arm and is not comparable to post-flip hybrid numbers. **(2)**
It was graded by the Qwen3.6 judge and has not been re-judged since the
2026-08-17 migration — and on the one slice that *was* re-run, the cascade
row moved by −0.090 (below). Read the cascade row here as an upper bound.

### The budget-matched hybrid arm (2026-09-04)

The wash above is a half-budget hybrid arm on a retired instrument. The
same 500 questions were re-run on 2026-09-04 with fresh `qwen-27b`
extraction, the Qwen3.8-27B answerer and judge, and the hybrid arm
**budget-matched** to the control at 6 raw turns
(`longmemeval-all-oracle-qwen-27b-raglite-all-fresh`). At a matched budget
the hybrid arm does not tie the raw-turn control — it beats it, and it is
**the one claim on this page reproduced across judge families**: the whole
run was re-judged on 2026-09-05 by `claude-opus-5` over the identical
recorded answers.

| arm | Qwen3.8-27B judge | claude-opus-5 judge | paired vs naive RAG | context tokens/question |
|---|---:|---:|---:|---:|
| naive RAG (top-6 turns, control) | 0.690 | 0.694 | — | ~1124 |
| **hybrid (facts + top-6 turns)** | **0.730** | **0.736** | **+0.040 / +0.042**, p 0.015 / 0.013 | ~1229 |

The paired column is a within-row permutation test over all 500 rows
(10,000 permutations, ±0.031 at 95% under both judges): 41 W / 21 L under
the local judge, 42 W / 21 L under Opus. Across the run no arm's accuracy
moved more than +0.010 between the two judges and per-arm item agreement
was 0.976–0.982, so the win is a property of the memory, not of the
instrument.

Three honest limits. **(1)** The hybrid arm buys accuracy with **more** context,
not less — ~1229 tokens against the control's ~1124 — so it is accuracy
bought, not budget saved. **(2)** The **cascade**, the arm that does save
context, stays a wash under both judges (+0.002 under Qwen, +0.010 under
Opus at p 0.4576) and is not promoted with it. **(3)** The win is not
spread evenly across question types: `temporal-reasoning` carries **+12 of
the +21** net rows under Opus and **+13 of the +20** under Qwen — most of
the effect out of 133 of the 500 questions — while
`single-session-preference` is flat-to-negative under both. Both judges
agree on that shape, and the per-type table is in
[`evals/README.md`](../../evals/README.md#second-judge-family-2026-09-05).
Artifacts:
`evals/results/longmemeval-all-oracle-qwen-27b-raglite-all-fresh.summary.json`,
`…arms-vs-rag.json`, `…rejudge-opus5.summary.json`,
`…rejudge-opus5.arms-vs-rag.json`; full per-arm tables, including the
token-matched `cortex`-vs-`rag1` pair, in
[`docs/runbooks/raglite-runs-20260904.md`](../runbooks/raglite-runs-20260904.md)
and [`evals/README.md`](../../evals/README.md).

## The knowledge-update slice (78 of the 500)

This is the slice the supersession spine is built for, measured on its own
with fresh qwen-27b extraction under the v25 backbone and reproducible q8_0
serving (`ceiling-e2e`, 2026-07-30: 3 byte-identical replicates —
std 0.0000). It was the README's front-door table until 2026-08-25; it is a
sub-slice of the 500-question sweep above and is published as one now.

| arm | accuracy | context tokens/question |
|-----|----------|------------------------|
| naive RAG (top-6 turns) | 0.859 | ~1237 |
| cortex facts only | 0.667 | **~259** |
| hybrid (facts + top-3 turns) | 0.833 | ~920 |
| **commit-gated cascade** | ~~**0.936**~~ (retired — see below) | ~702 |

> **RETIRED 2026-08-25 — the cascade's 0.936 does not survive the bench
> instrument (#188).** The 2026-08-17 migration to a Qwen3.8-27B
> answerer/judge re-ran the same 78 questions (`ceiling-v38`, also n=3 with
> std 0.0000). The naive-RAG control lands on 0.859 on both stacks; the
> cascade falls below it:
>
> | arm | Qwen3.6 stack (`ceiling-e2e`) | Qwen3.8 stack (`ceiling-v38`) |
> |---|---:|---:|
> | naive RAG (control) | 0.859 | 0.859 |
> | cortex facts only | 0.667 | 0.667 |
> | hybrid (facts + top-3 turns) | 0.833 | 0.846 |
> | **commit-gated cascade** | **0.936** | **0.846** |
>
> The mechanism is the routing gate, not the memory. The cascade serves the
> fact-spine answer unless that channel abstains, so its input is the
> *answerer's* willingness to say "I don't know": on the old stack the
> cortex arm abstained on **32 of 78** questions and its 46 commits were
> **46/46** correct; on the new stack it abstains **22 of 78** and its 56
> commits are **0.839** precise, so nine wrong answers are served where a
> RAG fallback would have rescued them. An adopter running Claude or GPT as
> the answerer has a different abstention rate and therefore a different
> number — which is what disqualifies 0.936 as a published claim about the
> memory system. (The migration moved extractor, answerer and judge
> together and the two runs' fact contexts are not byte-identical, so the
> artifacts do not isolate *which* term did it. That is the point: the
> claim was never instrument-independent, and nobody had measured whether
> it transferred.) Artifacts:
> `evals/results/longmemeval-ku-oracle-qwen-27b-ceiling-e2e.agg.json`,
> `evals/results/longmemeval-ku-oracle-qwen-27b-ceiling-v38.agg.json`
> (abstention and commit-precision counts recomputed from the per-question
> `…-ceiling-e2e.jsonl` / `…-ceiling-v38.jsonl` rows).

Within the 2026-07-30 stack, two findings still stand. First, the v25
retriever + BM25 lifted raw-turn selection so much (R@10 0.572 → 0.809)
that the **concatenation hybrid no longer beats naive RAG on this slice** —
mixing facts and turns in one prompt costs stale-fact overrides and extra
abstentions. Second, the channels are strongly complementary (their
per-question union is 0.949) — but how much of that a commit gate can
capture is exactly what the judge migration showed to be
instrument-dependent.

> **Currency note (2026-08-25): the full-haystack confirmation is a
> 2026-07-30 measurement and has never been re-judged.** On the `_s`
> haystacks (~50 sessions/question, tag `casc-q8`, reproducible server
> verified by process inspection), the cascade scored **0.462 vs 0.346**
> for naive RAG — delta **+0.115** at **p = 0.011** (paired permutation,
> 10,000 draws, seed 0) — with **commit precision 0.714** on a 14/78 commit
> rate. It was graded by the Qwen3.6 answerer/judge, and its extraction
> predates even the earliest committed op-prompt artifact (`v5`, committed
> 2026-08-01) — the shipped pin has since moved through
> `ku_op_prompt_v10_stance_update.txt` to
> `ku_op_prompt_v12_count_source_example.txt` (2026-09-07). The same cascade metric lost 0.090
> on the oracle slice when the stack migrated. Until it is re-run, it
> is an engineering-log result, not a front-door claim, and it was removed
> from the README on 2026-08-25. Honest scoping at the time: the margin
> over the concatenation hybrid there (+0.064) was directional only
> (p = 0.18), and the commit rate was low. Artifact:
> `evals/results/casc-q8-confirmation.json`.

This table is **not comparable per-arm** to the held-fixed table below:
it re-ran extraction and turn selection on the current stack, while the
table below deliberately holds both at the 2026-07-19 configuration.

## The held-fixed rebuild (`ceiling-v25`)

On the oracle variant (evidence sessions only), with the local-ceiling
extractor (`ceiling-v25`: 3 replicates on the reproducible stock server,
byte-identical — std 0.0000; contexts rebuilt from the 2026-07-19
context-persisted bank dumps):

| arm | accuracy | context tokens/question |
|-----|----------|------------------------|
| naive RAG (top-6 turns) | 0.628 | 1638 |
| cortex facts only | 0.590 | **~182** |
| **hybrid (facts + top-3 turns)** | **0.731** | ~1102 |

Within this held-fixed frame the consolidated-facts posture beats naive
RAG by ~10 points while reading **~67%** of the context — and the fact
spine alone trails RAG by only ~4 points on **~11% of its token budget**.
**Retired as a headline (2026-07-30):** on the current end-to-end stack
(section above) the concatenation hybrid's margin over naive RAG does not
survive the v25 retrieval upgrade. The commit-gated cascade replaced it as
the published posture and has since been retired too (2026-08-25) — on the
current bench instrument no arm beats naive RAG on this slice. This table
remains valid for what it
isolates — the serving-stack offset and cortex fact ranking under v25
with 2026-07-19 extraction and turn selection. Notably, the shipped E4B
fine-tune's replicated hybrid (0.762 ± 0.027, table below) beat this
ceiling's own-stack figure (0.710 ± 0.019, superseded table below) in the
one comparison that is valid — same stack, both on the TurboQuant fork —
so on knowledge updates the specialised small extractor at least keeps
pace with generic bigger models. No cross-stack comparison against the
0.731 above is made.

> **Why this table was re-based (2026-07-29).** Its previous published
> numbers (superseded table below) were judged on the TurboQuant fork.
> Re-judging the *same* contexts on the reproducible stock server moved
> the naive-RAG arm **+0.0615** — and that arm's context is copied
> **verbatim** by `rebuild_contexts.py`, so on byte-identical input the
> move is the answerer/judge stack alone. At 3.7× the old measurement's
> own rag std that is a systematic offset, not variance: the old stack was
> scoring this slice about six points low, and headline claims measured
> against a mis-scored control were never really established. Two things
> are still held fixed by the rebuild: **extraction** (the 2026-07-19
> banks) and **raw-turn selection** (the pre-v25 retriever picked the
> turns; BM25 is not exercised) — only the cortex fact ranking runs under
> the v25 backbone. Compare numbers only within a stack; across stacks,
> re-measure. Artifact:
> `evals/results/longmemeval-ku-oracle-qwen-27b-ceiling-v25.agg.json`.

**Superseded — the v2 / TurboQuant measurement** (5 replicates,
2026-07-19 context-persisted bank; judged on the nondeterministic fork,
~6 points low on the control arm — retained for the record, not
comparable to the table above):

| arm | accuracy (mean ± std) | context tokens/question |
|-----|----------------------|------------------------|
| naive RAG (top-6 turns) | 0.567 ± 0.017 | 1638 |
| cortex facts only | 0.559 ± 0.029 | **~124** |
| **hybrid (facts + top-3 turns)** | **0.710 ± 0.019** | ~1043 |

## Replicated results (2026-07-18)

The first 5-replicate runs (same banks, answer/judge phase re-run per
replicate; mean ± std) on the shipped-default fine-tuned extractor
(`e4b-ft`, Arm-1) vs its same-model pre-fine-tune baseline:

| arm | Arm-1 (shipped default) | baseline | paired p (78 questions) |
|-----|------------------------|----------|-------------------------|
| naive RAG (control) | 0.574 ± 0.006 | 0.585 ± 0.015 | 0.41 |
| cortex facts only | 0.682 ± 0.017 | 0.603 ± 0.013 | **0.17** |
| hybrid | 0.762 ± 0.027 | 0.749 ± 0.015 | 0.83 |

The control arm is what bounds the rest: it is built from raw turns and
never touches the extractor, so both runs feed it *identical* input and
whatever it moves is pure measurement floor. It drifted −0.010. Against
that, the cortex arm's +0.079 is roughly eight times the floor — a real
effect by direction and size — and still does not clear significance on
the paired test at n=78. Artifacts:
`evals/results/longmemeval-ku-oracle-e4b-ft-arm1-vs-baseline-cortex.compare.json`,
`...-hybrid.compare.json`, `...-rag.compare.json` (10,000 permutations,
seed 0).

Read honestly: the Arm-1 fine-tune's cortex-arm gain has a +8-point point
estimate but does **not** clear the pre-registered p < 0.05 on the paired
per-question test — the fine-tune fixes some questions and regresses
others, so the evidence for the shipped default is *suggestive, not
confirmed*, and the hybrid arm shows no measurable benefit at all. The
earlier single-run "+0.102" comparison overstated the effect. (The
ceiling table above was renumbered 2026-07-19 from a fresh
context-persisted 5-replicate run — its historical single-run
predecessor, hybrid 0.705, landed inside the replicated band — and
re-based 2026-07-29 onto the reproducible server, hybrid 0.731, with
the superseded TurboQuant figures retained above.)

## LongMemEval-V2 — agent trajectories and procedures

[LongMemEval-V2](https://arxiv.org/abs/2605.12493) (Wu et al.) is a
different content class from the KU benchmark above: WorkArena **agent
trajectories** — what an agent saw and clicked in an enterprise portal —
rather than chat sessions. The **complete 74-question `procedure`
category**, full 100-trajectory haystacks, scored by the benchmark's own
deterministic eval functions (single pass per prompt):

| arm | default answer prompt | composition-aware prompt |
|-----|----------------------|--------------------------|
| naive RAG (control) | 0.162 | 0.284 |
| cortex facts only | 0.068 | 0.216 |
| hybrid | **0.243** | 0.284 |

> **CORRECTED 2026-08-25 (scorer defect #173).** Every number in the table
> above is superseded. The multiple-choice scorer's no-box fallback
> accepted any standalone `[A-Ha-h]` token, so the English article "a" in a
> truncated reasoning trace scored as answer **A**. Re-scoring the same
> committed run under the anchored scorer
> (`evals/results/lme-v2-smoke-slice2-rescored-strictmc.summary.json` and
> `…-slice2-compose-rescored-strictmc.summary.json`, produced offline by
> `evals/rescore_strict_mc.py`):
>
> | arm | default answer prompt | composition-aware prompt |
> |-----|----------------------|--------------------------|
> | naive RAG (control) | 0.162 → **0.149** | 0.284 → **0.257** |
> | cortex facts only | 0.068 → **0.068** | 0.216 → **0.176** |
> | hybrid | **0.243** → **0.203** | 0.284 → **0.270** |
>
> All ten flips are the same defect in the same direction (gold answer
> **A**, previously-correct → wrong); no row moved the other way. The
> ordering is unchanged, but the exact compose-prompt tie below was an
> artifact of it: corrected, hybrid leads naive RAG there by 0.013 — one
> question, which is still no measurable difference.

Hybrid leads under the default prompt. Under the composition-aware prompt
it **ties naive RAG** — so the complementarity is real but
prompt-dependent, not universal. (The tie is a superseded number; see the
correction above — 0.270 vs 0.257 on the corrected scorer, which is the
same "no measurable difference" reading.)

> **Superseding the pilot.** An earlier 10-question slice (3 replicates)
> reported — and this table now supersedes —
> `| naive RAG (control) | 0.300 [0.30–0.30] | 0.500 [0.40–0.60] |`,
> `| cortex facts only | 0.167 [0.00–0.30] | 0.233 [0.10–0.30] |`,
> `| hybrid | **0.533 [0.50–0.60]** | **0.633 [0.60–0.70]** |`,
> concluding that *hybrid beat both single channels in every replicate
> under both prompts*. **That conclusion does not survive the full
> category.** The pilot's ten questions were simply the first ten in
> dataset file order, and they proved far easier than the category as a
> whole — every arm scores roughly half as well across all 74. This is
> what a selection-biased pilot looks like from the other side, and it is
> the reason for running the expansion at all.
>
> **CORRECTED 2026-08-25 (scorer defect #173).** The three quoted pilot
> rows are superseded by the same re-score
> (`evals/results/lme-v2-smoke-slice1-rescored-strictmc.agg.json`): naive
> RAG `0.300 [0.30–0.30] | 0.433 [0.40–0.50]`, cortex
> `0.167 [0.00–0.30] | 0.200 [0.10–0.30]`, hybrid
> `0.500 [0.40–0.60] | 0.533 [0.50–0.60]`. Seven flips, all gold **A**.
> The pilot's own conclusion weakens further: under the composition-aware
> prompt hybrid now *ties* naive RAG in one of the three replicates rather
> than beating both channels in all three.

Read honestly: these are single-pass point estimates, not replicated, so
small differences between arms carry no weight — the hybrid-vs-rag tie
under the compose prompt should be read as "no measurable difference",
not as parity established. The cortex arm remains the most run-to-run
volatile (extractor generation varies between runs even at temperature
0). None of this carries the 78-question paired testing the KU results
above do.

The more useful number is the starting one: **every arm scored 0.000**
before five adapter and extraction fixes. The decisive fix was ours to make
because the bug was ours to have caused — the trajectory-mode extraction
prompt said "extract exactly two kinds of claim and nothing else", so the
model *correctly* discarded the knowledge-base protocol articles that the
gold answers were drawn from. Naming a third class (what a document
prescribes) recovered the category, and the lesson was folded back into the
shipped extraction prompt — see [what the extractor
captures](dreaming.md#what-the-extractor-captures).

## Embedding backbone — chosen on our own corpus

The schema-v25 backbone swap was decided by a recall shootout on 150
LongMemEval questions over a 74,183-turn haystack
(`evals/results/embedder-recall-shootout-20260727.json`), scoring recall@k
of the gold turns rather than end-to-end accuracy, so the retriever is
measured without the answerer in the way.

| model | dim | R@10 |
|---|---|---|
| all-MiniLM-L6-v2 (previous default) | 384 | 0.572 |
| granite-embedding-english-r2 | 768 | 0.662 |
| snowflake-arctic-embed-l-v2.0 | 1024 | 0.732 |
| bge-base-en-v1.5 | 768 | 0.742 |
| **Qwen3-Embedding-0.6B (instructed)** | **1024** | **0.809** |

The winner's margin over the shipped model is decisive on a paired McNemar
test at k=10 (78 questions gained, 7 lost, p ≈ 3e-16). Every arm ran at the
harness's `max_seq_length: 512` (MiniLM caps itself at 256); the Qwen arm
used the instruction prefix that is now `EmbeddingConfig.query_prefix` —
see [asymmetric query/document encoding](retrieval.md#asymmetric-query-and-document-encoding).

## Band structure — the continuum earns nothing on either side

> **Outcome (2026-08-15): shipped.** The flat store is now the default
> preset. A preregistered rerun under the current retrieval backbone
> (v25 embedder + BM25-on) plus six steelman edge cases — forced
> eviction at matched capacity, depth-scaled recency at two half-life
> bases, 202 real recorded queries under a blind judge, lifecycle
> consumers, latency — came back a tie on every gate, in both
> directions: the significant July deltas below (each way) did not
> reproduce, and the write-side loss was fixed by the 2026-07-25
> demotion cascade before the rerun (survival now 0.0 loss both arms).
> The July results below are retained as the historical record that
> opened the question; the rerun's full gates table lives in
> `docs/superpowers/specs/2026-08-14-flat-band-verdict-preregistration.md`
> with committed `abl25-*` artifacts.

The 8-band cosine continuum was the memory's headline structure, so it was
worth asking what it buys. An offline ablation rebuilt every KU answer
context from the same banks with the bands collapsed into a **single flat
cosine pool**, under two timestamp regimes (`wall` — every entry stamped
now; `hist` — realistic aging), 5 replicates each, paired permutation test
over 78 questions:

| arm | Δ continuum − flat (`wall`) | p | Δ (`hist`) | p |
|-----|---------------------------|------|-----------|------|
| naive RAG | −0.067 | 0.10 | **−0.090** | **0.015** |
| cortex facts only | +0.008 | 0.76 | −0.010 | 0.53 |
| hybrid | −0.023 | 0.24 | +0.018 | 0.47 |

The continuum does not beat a flat pool anywhere, and under realistic aging
it is **significantly worse** at raw-turn selection. This is published
as-is because a negative result about one's own centrepiece is exactly the
kind that quietly goes unpublished: whatever the banding earns, it is not
retrieval ranking. That left one defence — the write side.

### The write side does not rescue it

The ablation above holds *ingest* fixed: both arms re-rank the same
surviving entries, so it cannot see what the banding does at write time.
A second ablation re-runs ingest itself through **one flat band at the
continuum's total capacity** (5,250 entries — the sum of all eight tiers),
so eviction and promotion never partition by tier and a different set of
entries survives. Run on the full-haystack `s` dataset (~488 turns per
question), where capacity pressure is real; 5 replicates, paired
permutation test over 78 questions.

**Write-side isolation** — identical flat ranking on both arms, so the
*only* difference is which entries survived ingest:

| arm | Δ continuum − flat (`wall`) | p | Δ (`hist`) | p |
|-----|---------------------------|------|-----------|------|
| naive RAG | −0.090 | 0.17 | −0.097 | 0.15 |
| hybrid | **−0.110** | **0.018** | **−0.108** | **0.027** |

**Whole system** — the continuum as designed (banded ingest *and* banded
ranking) against flat everything:

| arm | Δ continuum − flat (`wall`) | p | Δ (`hist`) | p |
|-----|---------------------------|------|-----------|------|
| naive RAG | **−0.274** | **0.0001** | **−0.251** | **0.0001** |
| hybrid | **−0.141** | **0.0038** | **−0.123** | **0.0153** |

(The cortex arm is omitted: its context is the fact block, which both arms
build identically, so the comparison is definitionally null. The two
`0.0001` p-values are the resolution floor of a 10,000-permutation test —
read them as "below 0.001", not as a precise estimate.)

The mechanism is capacity accounting, and it is visible without any
answering at all: at ~488 turns per question the continuum **evicts 31.1%
of everything stored** — the 200-entry `working` band overflows long
before promotion can drain it — while a flat pool of the *same total
capacity* evicts nothing. Discarding a third of the evidence costs
accuracy, and it does so on the arm that reads raw turns.

Read honestly, and this bounds the claim: because the flat arm never
evicts at all on this corpus, the comparison measures **eviction forced by
tier partitioning against no eviction** — not one eviction *policy*
against another. A corpus exceeding 5,250 turns per question would be
needed to test the policy itself. What is established is narrower and
still decisive for the design: partitioning a fixed capacity into
recency tiers throws away entries that an unpartitioned store of the same
size would have kept, and the memory is measurably worse for it.

Both of the continuum's July defences were measured here and neither
held. The 2026-08-15 preregistered rerun then closed the two bounds this
page flags: the demotion cascade (2026-07-25) eliminated the
partition-forced eviction entirely (loss 0.0 both ingest arms — the
whole-system tables above describe code that no longer ships), and a
capacity-scaled corpus where **both** arms genuinely evict found the
banded retention stack ties a single flat policy on gold-evidence
survival (0.459 vs 0.465, p = 1.0). With every gate a tie, the flat
store became the default on 2026-08-15; the `continuum` preset remains
one config line away.

## Extraction quality is the dominant factor

Running floor (Gemma 4 E2B, the smallest CPU-sidecar bake) vs ceiling
(Qwen3.6-27B) extractors with the RAG arm as a fixed control isolates
**extraction quality as the dominant factor** in fact-spine accuracy — the
measured case for upgrading the extractor when you have local compute to
spare (see [Dreaming — upgrading the extractor](dreaming.md#upgrading-the-extractor--bigger-local-models)).
Even the smallest bake beats naive-RAG at ~40× fewer tokens/query.

Read honestly: the floor/ceiling runs are single-run point estimates, not
replicates. The direction is safe anyway — the cortex arm collapses
0.564 → 0.192 when the extractor shrinks, while the RAG control moves
0.615 → 0.564 — a shift inside the run-to-run band, against a cortex
effect roughly five times it — but
finer-grained comparisons between adjacent extractor rungs are not
decision-grade under the same standard the tables above are held to.

The harder full-haystack (`_s`) results, the extractor-ladder screen used
to choose the default sidecar model, and the abstention-calibration sweep
are all in [`evals/README.md`](../../evals/README.md).

---

<!-- source: docs/guide/comparison.md -->

# Comparison — where this sits among agent-memory projects

Agent memory is a crowded category and most of the projects in it are good
at something real. This page says what *this* one is built around, names
the alternatives people actually evaluate against it, and — the part that
makes the rest worth reading — says plainly when you should pick one of
them instead. Part of the [user guide](../../README.md#documentation).

## How to read this page

**Claims about this project are checkable.** Every mechanism below names
the tool, config knob, or table that implements it, and the
[Benchmarks](benchmarks.md) page ships the run artifact behind every
number. If something here does not match the code, that is a bug — please
open an issue.

**Claims about other projects are dated and second-hand.** They come from a
competitive sweep run in **August 2026** against each project's own public
documentation. Open-source projects move fast; any of these may have
shipped the thing described as missing since. So the sections below are
written as *"here is our mechanism, concretely"* rather than *"they don't
have one"*, and anything specific is stamped with when it was read. If you
are choosing between tools, check the other project's current docs — do not
take a comparison table written by one of the vendors as current fact,
including this one.

## The honest baseline: a markdown file plus grep

Before any of this, the real competition: a curated `CLAUDE.md` (or
`AGENTS.md`, or a notes file) that you maintain by hand. It is free, it has
no daemon, it survives every session, and for a lot of projects it is
genuinely enough. Any memory system that cannot beat it is overhead.

What a hand-maintained file cannot do is answer four questions at once:

- **What is X *now*?** A file accumulates statements; nothing marks which
  one is current. Grep returns all of them.
- **What did X used to be, and when did it change?** Edits destroy the
  previous value. `git log -p` on the notes file is the closest thing, and
  it is a diff, not a timeline of a fact.
- **Who asserted this?** A line in a file has no writer, no origin tier,
  and no link back to the conversation that produced it.
- **Has it rotted?** Nothing in a file knows that a staging hostname is
  six months old and worth re-checking before you act on it.

Those four are what this project is built to answer, and they are the axes
below. If none of them is a problem you have, use the file.

## The axes

### One current value per slot

The **cortex** is slot-keyed: one *current* value per `(entity, attribute)`
pair. `memory_fact_get("staging", "host")` returns one answer, not a
ranked list of everything ever said about staging. Slots that genuinely
hold many concurrent values are **set-valued slots** — an explicit,
one-way conversion with add/remove semantics, not an accident of
accumulation ([memory model](memory-model.md#set-valued-slots-schema-v26)).

This is the axis the field is most split on. The 2026-08 sweep found the
common design to be *accumulate and rank at retrieval*: corrections are
stored alongside the value they correct, and the retriever is expected to
prefer the newer one. That works until it doesn't, and when it doesn't it
fails silently — the old value is still in the index, still similar to the
query, still winning some fraction of the time. Accumulation is a
legitimate design choice (nothing is ever lost), but "nothing is
overwritten" and "there is one current answer" are different products.

### Supersession with version history

A canonical-fact correction **supersedes**: the new value becomes current,
the old one is retained as a dated version with its writer and its **HLC** stamp, and
`memory_history(entity, attribute)` prints the timeline. Nothing is
silently overwritten and nothing is silently duplicated —
[memory model](memory-model.md#canonical-facts--the-cortex-schema-v8).

Source notes have a separate policy: storing a potential conflict retains
both notes for retrieval. Replacing a whole source note requires an
explicit `memory_supersede` or `memory_consolidate` operation.

The word is worth being precise about, because three different behaviours
get marketed with the same vocabulary:

| Behaviour | What you get afterwards |
|---|---|
| Append-only | Old and new both live; retrieval decides which you see |
| Destructive update | New value only; the old one is gone, unauditable |
| **Supersession** (this project) | New value is current; old one retained, dated, attributable, and queryable |

At the time of the sweep, the closest comparable behaviour in the field was
Zep/Graphiti's temporal edge invalidation, which does keep a history — the
difference we found was in *what decides* a supersession and *what happens
to a doubtful one*, which is the next axis.

### Provenance tiers, contenders, and a human gate

Not every claim deserves to become canonical. Three mechanisms decide:

- **Provenance tiers.** Writes carry an origin: `user` > `action` >
  `agent`. A lower-tier claim cannot silently overwrite a higher-tier
  value.
- **Contender parking.** A competing value is parked *against* the slot
  instead of taking `current`. `memory_fact_get` shows both, search flags
  the slot `contested`, and `memory_fact_resolve` settles it.
- **Consolidation quarantine** (the two-man rule, opt-in via
  `memory.dream.quarantine_low_trust`): an untrusted agent-tier **dream**
  claim parks as a contender, promotable only by an explicit human resolve
  or an independent second witness
  ([dreaming](dreaming.md#consolidation-quarantine--the-two-man-rule-opt-in)).
- **Authority, distinct from provenance.** `origin` (user/action/agent)
  says *who* wrote a claim; a separate write-time `authority` label
  (`directive`/`observation`/`quoted`) says *how* it was said — a quoted
  third-party remark is demoted to a contender by the two-man rule rather
  than landing as a standing fact, even from a `user`-origin write. Paired
  with a `distortion_tolerance` class
  (`constraint`/`procedural`/`belief`/`preference`/`episodic`), a
  `constraint`-labelled rule survives consolidation verbatim rather than
  being paraphrased at the same rate as an episodic log line
  ([memory model](memory-model.md#who-said-it-and-how-exactly-must-it-survive-schema-v35)).

The sweep did not find this combination elsewhere — the usual arrangement
is an LLM judging which of two conflicting values is newer or more
trustworthy, and then acting on that judgement unattended. We do that too
(the dream extractor is an LLM making judgements), but the judgement lands
in a contender, not in `current`, when trust is low.

### Human-reviewed merges, with the decision recorded

Entity dedup is where an automatic graph quietly eats itself: fold
`band.py` into `band` once and every fact attached to either becomes
ambiguous. Merges here are **proposals**, not actions. They queue in the
**review queue** (the Console's Atlas Review view, or
`memory_graph_review`), carry their evidence, and are subject to
**merge vetoes** — name-shape rules that block a bad **fold direction** at
filing time. Accepting or rejecting one writes an audit-stamped row in
`merge_decisions`, marked `decided_by=agent` over MCP or `human` via the
Console. A background judge may attach a *verdict* to a pending proposal;
the verdict is a lead, never a decision
([dreaming — deep dream](dreaming.md#deep-dream--full-corpus-graph-consolidation)).

### Staleness as a serving decision

Every cortex fact is dated and carries a `freshness_class` —
`evergreen` / `slow` / `volatile`, inferred from the entity's kind unless
you set it. Age decays `effective_confidence`; past twice the TTL the fact
flags `stale`, which means *re-verify at the source before acting*, never
"this value is wrong". The `stale_policy` knob can additionally withhold a
stale value at serving time (*serving-side quarantine*)
([how current is this fact?](memory-model.md#how-current-is-this-fact)).

The sweep found decay elsewhere mostly as a *retrieval* weight — older
memories rank lower. That is a different thing: a downranked fact still
gets served, and it gets served without the flag that tells the agent to
go check.

### Zero-egress extraction, and how to verify it

The precise claim: **your memory text never leaves the machine — on the
sidecar extractor mode.** The Docker tier's default ships a local CPU
extractor **sidecar**, so **dream** consolidation — the step that reads
your memory stream and turns it into facts — runs on your box with no
API key and no outbound request. The installer's `sonnet-only` /
`sonnet-fallback` modes trade this away deliberately — they route dream
extraction through the Claude CLI, which sends the extracted stream to
Anthropic — and the `codex-only` / `codex-fallback` modes trade it away
the same way toward OpenAI (the Codex CLI carries the stream).
Retrieval embeddings are local too, and the weights are baked into the
image. (Not the same as "never touches the network": the first pip install
downloads an embedding model, and image pulls are image pulls. Those carry
no memory content.)

This one is checkable rather than assertable, which is the point. Pull the
network, run a dream, and watch it produce facts. Or read
`ops/docker-compose.yml`: the extractor container is never published to
the host, and the only endpoint the daemon calls is the one you configure.
Point `PSEUDOLIFE_DREAM_BASE_URL` at a hosted model and you have traded the
property away deliberately — that is a supported configuration, and
[Dreaming](dreaming.md) says so where you make the choice.

Two honest caveats. First, the **lite** tier ships *no* extractor at all
(`pip install "pseudolife-mcp[lite]"`) — zero egress by default there,
because nothing extracts anything until you point it at an endpoint; see
the README's quickstart for exactly what that costs you. Second, the agent
calling these tools is usually a hosted model, so "no egress" describes
this server's behaviour, not your whole stack.

At the time of the sweep, free-tier extraction elsewhere generally required
an external LLM key. Self-hosting the extraction step was usually possible
with configuration; what differs is what happens when you install and
change nothing.

### Numbers that ship with their artifacts

Every published benchmark number in these docs has a committed run file
under `evals/results/`, and `tests/test_eval_evidence.py` fails the suite
if a claim loses its artifact. Retired numbers are marked retired at the
place a reader meets them, not only where they were replaced. Judging is
done by a local, byte-reproducible judge, so results are comparable within
a table and deliberately **not** comparable against GPT-judged
leaderboards ([Benchmarks](benchmarks.md)).

This project publishes **no LoCoMo score**, on purpose. Its ground truth
has been repeatedly reported as unreliable, and the same system has been
scored wildly differently by different parties — a spread far larger than
the differences anyone claims from it. A number produced under those
conditions tells you nothing about whether a system will remember your
staging host, and publishing one anyway would contradict everything above.
The refusal is the position, and this is where it is documented.

## The projects people ask about

Alphabetical. Each is described by what it appeared built for during the
**2026-08** sweep of its public documentation — not by a feature scorecard,
because a scorecard written by a competitor ages badly and flatters the
author. Read these as "why you might pick that instead", and check their
current docs.

**Cognee** — a memory pipeline built around ECL (extract, cognify, load)
that turns documents and conversation into a queryable graph. Strong fit if
your problem is *ingesting a corpus* and reasoning over its structure. The
sweep's note: corrections tended to enter as additional nodes rather than
replacing a prior value, which is the accumulate-and-rank design discussed
above.

**Letta** (formerly MemGPT) — an agent *runtime* with memory as one of its
subsystems: self-editing context, agent state, tool loops, a server and
SDK. If you want the framework to own the agent, Letta is doing something
this project deliberately isn't. Pseudolife-MCP has no agent, no chat UI,
and no opinion about your loop — it is tools your existing coding agent
calls.

**Mem0** — the most common thing people compare against, and the easiest
on-ramp in the category: hosted or self-hosted, a small API, broad
framework integrations. The sweep read its v3 memory design as
add-oriented, with retrieval expected to surface the right version. If your
workload is conversational personalization at volume and you want a managed
service, this is the mainstream choice and we are not it.

**Memori** — the sweep read it as a lightweight, SQL-first memory layer
that appeals for the same reason a notes file does: you can read the
database. Good fit if you want minimal machinery and full visibility,
and are content to own the policy questions (what supersedes what, what
goes stale) yourself.

**memU** — oriented toward companion and personal-assistant memory, with an
emphasis on rich profile-style recall. Different target user; if you are
building a companion app rather than instrumenting a coding agent, that
orientation will fit better than this one.

**Zep / Graphiti** — the closest thing to a peer on the temporal axis: a
bi-temporal knowledge graph with edge invalidation, so it genuinely keeps
history rather than overwriting. The differences the sweep surfaced are the
ones in the sections above — which claim gets to become current, whether a
doubtful one parks as a contender, and whether a human ever sees a merge
before it happens. Zep also offered a managed cloud service at the time of
the sweep, which this project does not and will not.

**LangMem / framework memory modules** — memory as a component of a larger
agent framework. Convenient when you already live in that framework; the
sweep's note was that update semantics there were commonly destructive
(the new value replaces the old with no retained version), which is the
distinction drawn in the supersession table above.

## Use something else if

This is the section that makes the rest credible. These are not
roadmap items being coy — they are deliberate non-goals, and a project
whose entire pitch is auditability should not fudge its own boundaries.

| If you need | Use | Why not this |
|---|---|---|
| **Multi-tenant SaaS memory** — one deployment serving many customers with tenant isolation | Mem0, Zep Cloud | One daemon owns one **bank**, single-writer by construction. Principals are bearer-token identities for *your* agents, not tenants; there is no tenant boundary in the schema |
| **SSO, RBAC, audit compliance** — SOC 2, SAML/OIDC, org-wide access policy | A commercial hosted platform (Mem0, Zep Cloud) | Auth is a bearer token, loopback by default. There are no roles, no directory integration, and no compliance attestations |
| **Managed hosting** — someone else runs it, patches it, backs it up | Mem0, Zep Cloud | There is no cloud tier and there will not be one: a hosted service would dilute the zero-egress claim and add a business to run |
| **An agent framework** — runtime, planner, tool loop, agent state | Letta, LangGraph | This is a memory server with no agent in it. Your coding agent is the intelligence |
| **Memory for a non-MCP application** — a web app, a chatbot backend | Mem0, Cognee, Memori | The interface is MCP plus a REST console. There is no general-purpose SDK, and the tool docstrings are written for a coding agent to read |
| **Cross-machine sync out of the box** | A hosted service | Memory lives on one machine's disk; syncing is left to rclone/syncthing |
| **A LoCoMo leaderboard number to put in a deck** | Anyone who publishes one | We publish a documented refusal instead — see above |

Also worth saying: this is **solo-maintained, best-effort** software. It is
carefully tested and deployed daily by its author, and that is not the same
as a support contract. If your organization needs someone to call, buy from
someone who sells support.

## Checking any of this yourself

```bash
# One current value per slot, with its provenance and age:
memory_fact_get("staging", "host")

# The version timeline behind that value:
memory_history("staging", "host")

# Is this bank extracting locally, or at all?
curl http://127.0.0.1:8765/health     # -> "extractor": none | configured | disabled

# Every published number's run artifact:
ls evals/results/
```

The version timeline is the one to try first. It is the artifact that most
directly shows the difference between "the system stored my correction" and
"the system knows what the value is now, what it was, and who changed it".

---

<!-- source: docs/guide/security-posture.md -->

# Security posture — memory poisoning (ASI06)

A memory system has an attack surface ordinary tools don't: content the
agent *reads* can try to get itself *stored*, and anything stored shapes
every later session. OWASP's agentic-threat catalogue lists persistent
memory poisoning as **ASI06** (published December 2025), and it is the
threat class that decides whether a self-hosted memory server is safe to
put in front of a working codebase.

This page states the threat model and maps every **shipped** mechanism to
the part of it that mechanism actually mitigates — and, at least as
importantly, names what is **not** defended. Vulnerability *reporting*,
the network/auth boundary, and scope live in
[SECURITY.md](../../SECURITY.md); this is the memory-integrity half.
Part of the [user guide](../../README.md#documentation).

Read the mitigations as *containment*, not prevention. None of them stops
a model from being talked into a bad `memory_store`. What they do is bound
how much authority that store can acquire, how visibly, and how cheaply it
can be undone.

## The threat model

**The write path is the agent.** Nothing writes to the **bank** except MCP
tool calls made by your model. A hostile web page, README, or ingested
document cannot write directly — it can only try to convince the model to
call `memory_store` or `memory_fact_set` on its behalf. That
instruction-following boundary belongs to the model and its host, not to
this server. Assume it fails occasionally.

**Dreams amplify.** The **dream** pass promotes episodic text into
canonical **cortex** facts, and cortex facts outrank raw entries at recall
time. A poisoned entry that survives to a dream becomes a poisoned *fact*
with elevated authority, cited to your own memory rather than to the web
page it came from. Consolidation is therefore the privilege-escalation
step, and most of the mechanisms below sit exactly there.

**Correction does not remediate.** The 2026 literature (MINJA,
arXiv 2601.05504) shows query-only injection against agent memories
succeeding at high rates, and shows that agents cannot be *talked* out of
a poisoned memory — conversational correction relapses. Deletion is the
remediation.

**Content inspection is in the evaded class.** MAFIA (arXiv 2608.03844)
defeats *audited* memory stores from the query interface alone: "factual
cloaks" preserve high semantic similarity and malicious effect while
dropping audit detection from ~83% to under 8% at ~90% attack success.
Anything that reasons about *what the text says* is in that class,
including this project's literal-faithfulness gate — which checks fidelity
to the source note, not trustworthiness of the source. The same work
optimizes *placement* so poisoned records win retrieval competition
against a large benign pool, which makes ranking machinery part of the
attack surface rather than a defense. Defenses that key on *who wrote*
are the class this attack does not straightforwardly evade, and that is
why the mechanisms below are provenance-shaped.

## Mechanism → threat map

Every row ships today. "Default" says what a fresh install does, because a
mitigation that is off by default is a mitigation you have not got yet.

| Mechanism | Poisoning step it mitigates | Default |
|---|---|---|
| **Provenance tiers** (`user` > `action` > `agent` > `assistant` origin on every write) | A planted `agent`-origin claim cannot silently supersede a user-stated value. `assistant` is the floor tier — a fact the assistant itself stated in a turn, reachable only from a dream whose extraction prompt asks for a `speaker` label — and it cannot supersede a value of **any** other origin: it parks as a contender, and that rule is not gated on `protect_provenance`. The rule covers **scalar and set-valued slots** alike — an assistant claim cannot convert a scalar slot to a set, cannot join a member set any other tier built (it parks), and cannot retract a member it did not put there (the retraction is dropped). Keys on *who asserted*, not on what the text says | On |
| **Contender parking** | A conflicting value is parked *against* the **slot** rather than taking `current`: `memory_fact_get` shows both, `memory_search` flags the slot `contested`, and `memory_fact_resolve` settles it. Poison must win an explicit decision, not a similarity contest | On |
| **Consolidation quarantine** (the two-man rule, `memory.dream.quarantine_low_trust`) | The dream's privilege-escalation step: an untrusted agent-tier claim parks as a **contender** instead of taking `current`, promotable only by an explicit human resolve or an independent second witness | **Off** — opt-in |
| **Human-reviewed merge queue** | Entity-level poisoning: folding a hostile entity into a trusted one would inherit its facts. Merges are **proposals** carrying their evidence; **merge vetoes** block bad **fold directions** at filing; accept/reject writes an audit-stamped `merge_decisions` row (`decided_by=agent` over MCP, `human` via the Console). By default (`judge_mode: shadow`) a background judge's verdict is a lead, never a decision; the opt-in `judge_mode: auto` folds a pair only when two accepts from DIFFERENT models agree on a non-low-differential row — measured 6/6 on one distinct-model pairing of the 2026-09-02 panel (n=6; not itself a recommendation to flip the default) | On (review required by default; `auto` is opt-in) |
| **Review-queue judges** (links, junk, lesson/world duplicates, deep-dream link candidates) | Same class of risk, scoped narrower: `link_judge_mode`'s `auto` accepts/rejects edge proposals (reversible via `memory_graph_unrelate`/supersede); `junk_judge_mode`'s `auto` deletes only under a structural evidence bar (degree <= 2, at most one fact slot); `curation_judge_mode`'s `auto-distinct` is a reversible dismissal, its `auto` retires (not deletes) the losing lesson/world slot; `candidate_judge_mode` turns deep-dream link candidates into filed proposals or dismissed pairs | `shadow` for links/junk/curation (verdict recorded, nothing applied); `candidate_judge_mode` off |
| **Unreachable-orphan sweep** (`orphan_sweep`) | Deletes entities carrying no evidence at all (no edge, fact, lesson, alias, scope or proposal) once older than `orphan_min_age_days`, capped per pass — the one review-queue mechanism that is a plain delete, not a judged accept/reject | Off — the one destructive default that would fire unattended on the first apply after an upgrade |
| **Dream rollback journal** (schema v27) | Blast radius of one bad consolidation pass. Every dream records a run row plus a per-claim pre-image of what each slot held before the write; `memory_dream(action="rollback")` replays it to revert the latest committed pass | On |
| **Engram cross-index** | Attribution and cleanup: every cortex fact links back to the source entries that produced it, so a bad fact is traceable to the entry that fed it and the rest of that entry's output can be found | On |
| **Supersession history** (**HLC**-ordered) | Audit. Nothing is silently overwritten, so "when did this value change, and which writer changed it" is answerable after the fact via `memory_history` | On |
| **Writer keying / per-principal tokens** | Narrows the blast radius of a leaked credential: a matched per-principal token *becomes* its caller's writer id, where the singular shared token's holder may assert any writer via `X-PL-Writer` | Single token / open loopback |
| **Source exclusion from consolidation** (`memory.dream.exclude_sources`, default `consolidation` / `reflection` / `status` / `log` / `digest`) | Keeps high-volume, low-value chatter out of the dream's input entirely — those entries stay searchable but are never mined for facts or graph edges, shrinking the surface that can reach canonical authority | On |
| **Serving-side quarantine** (`stale_policy`: `annotate` \| `demote` \| `quarantine`) | Not poisoning per se, but the same family: a fact past twice its TTL is flagged `stale`, can be demoted below fresh records, or — at `quarantine` — has its `value` replaced by a wrapper with the original moved to `last_known_value`, so a rotted value cannot be read as current. `stale: true` means *re-verify at the source*, never "the value is wrong" | `annotate` (flag only) |
| **`memory_forget` + engram links** | Remediation. `scope="memory"`/`"fact"` hard-delete; `scope="lesson"`/`"world"` retire (status flips, row kept with a `store_decisions` audit trail, undoable via `restore_slot` until compaction purges it) — a poisoned lesson/world fact is contained, not purged, until then. The links tell you what else to retire | On |

Two of these deserve their exact claim restated, because overselling them
would be the same failure this page is about:

- The **consolidation quarantine** does no