anamnesis

Portable project memory for AI coding agents. Keep Claude Code, Codex, and Cursor aligned without re-explaining the project every session.

Every new agent session starts with partial memory. Tool switches make it worse: Claude Code, Codex, and Cursor expose different context, hook, skill, and command surfaces.

anamnesis keeps one project-owned source of truth and renders it onto each tool. It manages context, ontology, active handoffs, Work state, hooks, and skills while preserving user-authored content.

Why use it

• Continue instead of re-briefing. Active Work, requirements, evidence, and handoffs survive compaction, new sessions, and agent switches.
• One configuration, multiple agents. The same Agentfile drives Claude Code, Codex, and Cursor integrations.
• Bounded context. Startup stays compact; detailed facts remain retrievable through source pointers.
• Safe updates. Dry-runs, managed regions, drift detection, backups, and an explicit executable-adapter gate protect local edits.
• Evidence-backed claims. Public benchmarks use sanitized fixtures, retain reproducible evidence, and state the limits of each comparison.

Retrieval batching: GPT-6 Astra / high

The unreleased base v29 candidate skips redundant discovery and batches already-required retrieval with independent startup checks. Compared with the released 1.24.3 policy, known-source edits used 27.8% fewer total tokens and missing/stale-evidence edits used 36.4% fewer in this controlled pilot. All 22/22 executions passed task correctness and original-source checks.

| Scenario | Paired runs | Mean total tokens | Mean elapsed time | | --- | ---: | ---: | ---: | | Known-source read | 3 pairs / 6 runs | -0.6% | +6.9% | | Known-source edit | 3 pairs / 6 runs | -27.8% | -25.6% | | Missing / stale evidence | 3 pairs / 6 runs | -36.4% | -5.2% | | Missing-path recovery holdout | 2 pairs / 4 runs | +0.4% | +4.0% |

Measured with gpt-6-astra, reasoning effort high; low was not tested. Changes compare arithmetic means, including cached input tokens, and are not billing savings. The retrieval engine is fixed at 1.24.3; only shared AGENTS policy varies. Small fixtures, uncontrolled caches, and overlapping executions limit generalization, especially timing. Native startup-hook efficiency and multi-turn behavior are not measured. Required searches and source reads remain.

Results and limitations · Raw measurements · Rebuild chart without model calls

Earlier Astra instruction-efficiency studies

Version 1.24 reduces Codex fallback context and repeated startup reads while preserving full procedures, source evidence and adapter permissions. Its read-only anamnesis context audit-instructions command reports instruction size, recorded ownership, drift and literal duplicates; it does not automatically rewrite instructions or control model settings. See usage and scope.

A frozen Astra/high study passed all 66 executions. On fresh reserved tasks, median paired total tokens fell 18.2%, while elapsed time rose 1.8% within the predeclared non-regression gate. Both arms used anamnesis with Work capture and Stop reminders disabled; this is not an on/off or whole-stack speed claim. A separate four-run Work completion follow-up measured 17.4% fewer total tokens and 11.2% less time versus its preceding repair, with correct state recovery. That small, tuned comparison is not independent holdout evidence, and uncached input increased 0.8%. Earlier Luna/Terra/Sol results above are separate studies.

| Study | Paired executions | Total tokens | Elapsed time | | --- | ---: | ---: | ---: | | V6 development | 9 pairs / 18 runs | -26.7% | -2.3% | | V6 fresh reserved | 24 pairs / 48 runs | -18.2% | +1.8% | | V8 vs V7 tuned follow-up | 2 pairs / 4 runs | -17.4% | -11.2% |

Changes are medians of per-pair ratios, not ratios of aggregate totals. Reserved tasks were outcome-unseen, not content-blind. The full report discloses the post-measurement evaluator correction and preserves failed revisions. Rebuild the chart from the checked-in JSON; this does not execute models.

Full Astra results, failed revisions and limitations

Measured Work continuity

The latest published real-Codex benchmark compares Work disabled and enabled across six continuity scenarios and nine paired repetitions per scenario. Correction turns are charged to the condition that needed them.

| Published strict 9-pair benchmark | Change with Work | | --- | ---: | | Average total tokens/run | -50.30% | | Average elapsed time/run | -44.19% | | Status recall | 72.59% → 100% | | Re-explained requirements/run | 17.11 → 0.33 |

Both conditions retained 100% completion and gate correctness; Work also reached 100% requirement and summary recall with no hallucinated or duplicate requirements. The strict contract passed all six scenarios (108 initial calls, 153 including bounded corrections). See the scenario evidence and methodology.

The same six-scenario diagnostic (n=3) reproduced the overall direction on two additional models:

| Cross-model diagnostic | Tokens/run | Elapsed/run | Enabled status recall | Token pair wins | | --- | ---: | ---: | ---: | ---: | | gpt-5.6-terra | -50.80% | -44.56% | 100% | 18/18 | | gpt-5.6-sol | -53.76% | -50.97% | 100% | 18/18 |

Scenario variance remains material — Terra delegation/review was nearly flat at -0.19% while Sol reached -50.02% — so Luna n=9 remains the strict baseline and both n=3 runs are directional cross-model evidence.

Terra diagnostic evidence · Sol diagnostic evidence

Parallel-agent benchmark

The latest bounded Luna diagnostic measured three paired, externally orchestrated pipelines: leader planning, two concurrent children, authoritative review, and final integration. Both conditions were exact in all three pairs, while Work reduced paired total-token p50 by 1.19% (90% bootstrap upper bound -0.98%), combined-child tokens by 2.78%, and reviewer tokens by 0.27%. Critical-path p50 was +0.64% and passed its preregistered non-regression gate. The 24-call harness, quality, stage-cost, latency, and diagnostic-efficiency contracts all passed. This is a small, scenario-bounded efficiency signal—not a release-quality or general native subagent performance claim.

V10 diagnostic evidence · Parallel-agent methodology and historical evidence

Quickstart

Install the scoped package (anamnesis without the scope is an unrelated npm package):

npm install -g @mcprotein/anamnesis

Preview first-time setup in a project:

cd /path/to/your/project
anamnesis init --dry-run

Install the managed project context and native agent adapters:

anamnesis init --tools all --allow-exec-adapters
anamnesis status

Native hooks, commands, skills, and Cursor rules are written only when --allow-exec-adapters is explicit. Content-only setup remains the default.

Successful initialization registers the project in a private user-level index. Preview every registered project, or upgrade the CLI and apply only safe plans:

anamnesis projects plan
anamnesis upgrade --apply

Moved, replaced, conflicting, or user-modified projects are skipped and reported independently. Project-local Agentfiles and manifests remain authoritative; the global index is only a discovery and trust-preference layer.

New installs materialize an active Work profile: adaptive continuity briefings, advisory independent review, automatic delegation assessment, and bounded repository-side prompt-capture policy. Existing projects retain their current behavior; explicit opt-out and trust-boundary details are in the user guide.

Running anamnesis prints the short first-run guide. Use anamnesis --help for grouped help and anamnesis --help --all for the complete command reference. Daily human output is compact and verdict-first; add --verbose to supported lifecycle, health, hooks, and Work commands for full diagnostic provenance. Structured --json output remains unchanged for automation.

What it manages

your-project/
├── Agentfile                         # fragments, tools, and policy
├── AGENTS.md                         # canonical managed context + your prose
├── CLAUDE.md                         # Claude Code entrypoint
├── .anamnesis/
│   ├── manifest.json                 # drift and ownership evidence
│   ├── ontology/                     # static, bootstrap, and enriched context
│   ├── handoff/                      # active and archived handoffs
│   └── work-units/                   # typed Work ledgers and projections
├── .claude/                          # Claude Code adapters
├── .codex/                           # Codex hooks, config, and skills
└── .cursor/rules/                    # Cursor rules

Managed AGENTS.md sections use <!-- anamnesis:region ... --> anchors. Content outside those anchors remains yours. anamnesis is a context lifecycle manager, not an application scaffolder; it does not generate project source code.

Core workflow

anamnesis init --dry-run              # preview first installation
anamnesis apply --dry-run             # preview managed updates
anamnesis apply                       # apply reviewed updates
anamnesis status                      # inspect drift and continuity state
anamnesis doctor                      # run integrity diagnostics
anamnesis context query "<terms>"     # retrieve exact source pointers
anamnesis context audit-instructions # inspect instruction size, ownership and duplicates
anamnesis context resume              # render a compact resume bundle
anamnesis work status --work <id>     # refold authoritative Work state

The user guide covers setup choices, lifecycle commands, generation boundaries, fragments, capability mapping, and building from source.

Safety model

• Executable agent surfaces require --allow-exec-adapters.
• apply --dry-run previews managed writes.
• User-modified or untracked files are not silently overwritten.
• Backups are created before managed files are changed.
• Work mutations use typed append-only evidence, expected-head checks, and fail-closed review/delegation policy boundaries.

See DESIGN.md and WORK-UNIT-DESIGN.md for the detailed trust and execution model.

Documentation

• Documentation map — current guides, proposals and historical records

• User guide — setup, lifecycle, fragments, capabilities

• Work design — requirements, evidence, policy, briefings

• Agent switching guide — move between supported agents

• Benchmarks — evidence index and deterministic suites

• Work A/B evidence — scenario results and limitations

• Terra Work A/B diagnostic — three-pair cross-model evidence

• Sol Work A/B diagnostic — three-pair cross-model evidence

• Parallel-agent Luna benchmark — held-out accuracy, cost, and latency gates

• Roadmap — shipped and deferred work

• Contributing — fragments and project development

• Changelog — release history

License

MIT — see LICENSE.