mnemosyne

Mnemosyne

The next agent starts wiser.

Mnemosyne is local-first, long-term memory for AI agents: one SQLite file that keeps what an agent learned together with the evidence it came from, served to any host over TypeScript, MCP, CLI or HTTP. When a source is corrected, the memories recorded as depending on it are retired, so the next agent starts from what current recorded evidence still supports instead of repeating a stale lesson. The local engine needs no model API key, database server or Docker.

• Evidence on every memory. Each record keeps its source and trust tier, and the superseded version stays inspectable after a correction.
• Corrections that reach dependents. A corrected requirement retires the procedures and skills recorded as depending on it; 3.0 can also propose dependencies nobody declared, for review.
• Auditable over time. Past beliefs replay exactly. Given the records a failed retrieval should have returned, bisect finds the records that pushed them out. In the 3.0 pre-release, consolidation is outcome-gated and reversible.
• Any host. MCP for Claude Code, Cursor and Codex; a TypeScript SDK; a CLI; and authenticated HTTP with a Python client and live inspector.

Stable: 2.0.0 (npm install mnemosy-ai) · Newest pre-release: 3.0.0-rc.4, the breakthrough release (npm install mnemosy-ai@next) · MIT · Node.js ≥22.16

Website · Quickstart · Documentation · Examples · Migration · Measured results · Trust evidence · Claims and evidence · Releases · npm · Contributing · Issues

Note Which Mnemosyne is this? This repository is the TypeScript package published on npm as mnemosy-ai, with its site at mnemosy.ai. It is a separate project from mnemosyne-oss/mnemosyne, the Python memory library published on PyPI as mnemosyne-memory; the two share a name, not code or maintainers. Please file issues for that project in its own repository.

This repository predates mnemosyne-oss/mnemosyne: GitHub records its creation on February 24, 2026; the separate Python repository was created on April 5, 2026.

Try it

The first npx run downloads the package; after that, the 3.0.0-rc.4 demo runs offline on synthetic corpora, with no API key and no model, and measures each claim while it runs:

npx -y -p mnemosy-ai@next mnemosy demo

The recording above is one unedited run (assets/demo.tape regenerates it with vhs). The last line of each of its five moments, matching the recorded run of 28 October 2026 (site/demo-five.json; timings vary by machine; the pass bars printed after each line are omitted here):

PROOF  replay determinism: 1000/1000 identical, 24000/24000 as-of answers = ground truth   [PASS]
PROOF  downstream repair: undeclared invalidated 3/3, accepted edges true 3/3, stale after correction 0 (11 probes)   [PASS]
PROOF  blame precision / time-to-locate: precision 1.00, 0.40 s, 2000 records   [PASS]
PROOF  poisoning suite v1, live: 227 cases, 0 escapes, 0 false quarantines   [PASS]
PROOF  consolidation receipts: kept 1 (delta +2), rolled back 2 (regression, invariant violated), rollback identical hash true, chain verified 4 receipts   [PASS]

5/5 moments proved.

What each moment proves, and what it does not. Then give the memory to Claude Code (other clients: Install and connect an agent):

claude mcp add mnemosyne -- npx -y -p mnemosy-ai@next mnemosy mcp --db ./.mnemosyne/memory.sqlite --workspace my-project --agent assistant

For the stable release, write mnemosy-ai@2.0.0 in place of mnemosy-ai@next; on 2.0.0, mnemosy demo runs the earlier single-scenario demo.

Contents: 3.0: the breakthrough release · Install and connect an agent · Measured results · Choose your engine · A working demonstration · Corrections in code · Tune the dense index · What you can build · Entry points · Migrate · Limits · Operational boundaries · Build with us

New in 3.0: the breakthrough release (pre-release on npm next)

3.0 is the breakthrough release. Replay and bisect already existed in 2.0.0. 3.0 adds four things: dependencies nobody declared, inferred and proposed for review, so that corrections reach them once accepted; a poisoning gate checked against a reproducible attack suite; outcome-gated, reversible consolidation with signed receipts; and opt-in precision controls. bisect also gained the hybrid retrieval path: since 3.0.0-rc.4 the mnemosy bisect CLI re-executes the store's own path (--retrieval auto|lexical|hybrid, default auto, which picks hybrid when the store has stored vectors for the bundled model; an hnsw index is refused). bisect is not a public package export, so from npm the CLI is the entry point. Each of these is documented and tested below, and each public claim is listed with its evidence in Claims and evidence. 3.0.0-rc.4 is the current release candidate on the npm next channel: npm install mnemosy-ai@next installs it, while npm install mnemosy-ai still installs the stable 2.0.0. Every number below was measured on 3.0.0-rc.2, offline, with no API key, no paid model and no LLM judge. Each one reproduces with the commands in Benchmarks and trust evidence, which also lists what is not claimed.

The default retrieval path's recall did not move: LoCoMo and LongMemEval-S recall are identical before and after (regression check). Recall latency was measured only on a loaded machine, with a scratch harness that is not committed, so those figures cannot be reproduced from this repository; the known limits, including a slowdown of the non-default overlap scorer, are in the changelog.

• Precision you can switch on. The new opt-in controls are a names gate and guarded single-edit fuzzy matching. Empty answers are native abstentions, and the ledger records why. With the controls on, the kernel scores 70/77 single-turn cases and 11/12 session turns on PrecisionMemBench (session was 6/12 with the rc.1 filtered configuration). That run was protocol-exact, in retrieval mode, with no LLM judge, no wrapper-side filter and no wrapper kinds predicate, and the lexical and hybrid paths score the same. The 12th session turn needs an open-question kind policy that the kernel is not told about.
  • For comparison, the kernel scored 22/77 unfiltered and 48/77 with the fixture-tuned wrapper filters of rc.1.
  • The benchmark fixture is public, and the controls were designed against it, so this is not a held-out estimate.
  • The 7 remaining misses are those of our metadata-based configuration; the single-turn protocol does not send explicit lifecycle fields.