Mnemosyne

Mnemosyne

The next agent starts wiser.

Auditable memory for agents that act. Past beliefs replay exactly, corrections cascade through recorded dependencies, and consolidation is outcome-gated and reversible.

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, every memory that depended on it is retired, so the next agent starts from what is still true instead of repeating a stale lesson.

Mnemosyne connects memory to its consequences: a corrected requirement can retire a dependent procedure, a failed trial can withhold a skill, and a new agent can resume from an explicit handoff. Run the local engine in one SQLite file; connect your host through TypeScript, MCP, CLI, or authenticated HTTP with a Python client and live inspector.

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

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

New in 3.0.0-rc.2 (pre-release on npm next)

3.0.0-rc.2 is a 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 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 did not move: LoCoMo and LongMemEval-S recall are identical before and after (regression check). Recall latency was measured only on a loaded machine; 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 cases need lifecycle fields that the single-turn protocol does not send.
  • The default retrieval path is unchanged: LoCoMo and LongMemEval-S recall are identical before and after.

• Consolidation that has to earn its keep. A consolidation pass is a signed diff, replayed against the agent's own recorded outcomes. It is kept only when nothing regresses and no invariant breaks, and one command undoes it, back to the identical state hash. With consolidation on, the poisoning suite v1 run (227 synthetic cases, reproducible) has zero escapes: 0 of 167 attacks escaped and 0 of 60 benign controls were falsely quarantined, across 294 gate decisions. An ungated control lets 85 of the 167 attacks through. Consolidation gate · Signing and receipts

• Corrections that reach what nobody linked. Dependencies are inferred from successful co-use and proposed for review. Once accepted, they are declared through correct(), and runtime skills can be linked to their premises. The measurement is on a synthetic seeded corpus (dependency suite v1, seed 20261028, 120 corrections):

  • invalidation recall is 96.05 %;
  • precision of accepted edges is 98.06 %;
  • 0 stale procedures ran through the premise guard. That zero comes from the guard, a blanket hold on anything co-used with a changed premise: inference alone leaves 7 of 248 checks stale, and the guard's false-hold rate is 92.78 %.

  Inferred dependencies

• A demo that measures itself. mnemosy demo walks through five moments on synthetic corpora, offline, on the zero-model lexical path:

  1. a past belief replayed exactly;
  2. a correction reaching dependents nobody linked;
  3. bisect naming the record that caused a wrong answer;
  4. a poisoning attempt caught, with the suite run live;
  5. a consolidation kept, another rolled back, and the kept one undone.

  Each moment prints a PROOF line measured in that run. What each moment proves

npx -y -p mnemosy-ai@next mnemosy demo             # five moments, offline, each PROOF line measured live
npx -y -p mnemosy-ai@next mnemosy demo --classic   # the previous single-scenario demo

From a source checkout, run npm run build and then node dist/cli/index.js demo.

3.0 is a breaking release: the legacy vector engine moves to mnemosy-ai-legacy, which is not on npm yet; build it from a checkout or stay on mnemosy-ai@2 (3.0 migration). The release notes are in the changelog.

Install and connect an agent

npm install mnemosy-ai                   # stable: latest = 2.0.0; pin mnemosy-ai@2.0.0 to reproduce
npm install mnemosy-ai@next              # pre-release: next = 3.0.0-rc.2; pin mnemosy-ai@3.0.0-rc.2 to reproduce
npx --no-install mnemosy demo            # offline: no API key, no server, no Docker

Give the memory to an MCP client. Claude Code reads .mcp.json in the project root and Cursor reads .cursor/mcp.json; both take the same server entry. The entries below run the 3.0.0-rc.2 pre-release through mnemosy-ai@next; for the stable release write mnemosy-ai@2.0.0 in its place, and to pin the pre-release write mnemosy-ai@3.0.0-rc.2. Both versions expose the same MCP tools. The database file (mode 0600) and its parent directory (mode 0700) are created on first use. Relative paths resolve from the directory the client starts the server in; use absolute paths if your client launches servers elsewhere.

{
  "mcpServers": {
    "mnemosyne": {
      "command": "npx",
      "args": [
        "-y", "-p", "mnemosy-ai@next", "mnemosy", "mcp",
        "--db", "./.mnemosyne/memory.sqlite",
        "--workspace", "my-project", "--agent", "assistant"
      ]
    }
  }
}

Claude Code can register the same server from the shell:

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

Codex keeps MCP servers in ~/.codex/config.toml. Register the server with an absolute database path:

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

The command writes this table, which you can also add by hand:

[mcp_servers.mnemosyne]
command = "npx"
args = ["-y", "-p", "mnemosy-ai@next", "mnemosy", "mcp", "--db", "/absolute/path/project/.mnemosyne/memory.sqlite", "--workspace", "my-project", "--agent", "assistant"]

The first npx launch downloads the package; if a client gives up during that first start, install the package in the project first.

The server exposes 16 memory_* tools (memory_store, memory_recall, memory_context, memory_correct, memory_checkpoint, memory_resume, memory_observe, memory_skill, …); memory_forget is added only when the server is launched with --allow-destructive. Add --read-only to omit every mutation tool. A model cannot switch workspace, raise its own trust or report its own skill trials through MCP. Agent-readable summaries of this repository are in llms.txt and AGENTS.md; the full MCP contract is in Connect through MCP.

Measured: 409 of 500 on LongMemEval-S, with the misses printed

What these numbers do not say. The 81.8% is not a paired gain over the earlier 71.2%: that baseline used a different 250-question sample, prompt and budget, so the improvement belongs to the whole bundle of changes. The reader is nondeterministic; rerunning one configuration moved its score by about a point. Retrieval numbers measure coverage, not answers. Two Tier 1 targets of 2.0.0 are not met and ship disclosed: recall latency at one million records is p95 139–223 ms against a 50 ms goal (opt-in indexMode: 'hnsw', see Tune the dense index), and contextual reranking ships at 71.98% all-evidence hit against a 72.80% gate, 0.82 points (13 of 1,531 questions) short; the best variant tried was still four short and was not merged. Commands and raw outputs are in reports/t1-targets/evidence/; the answer-accuracy and gate results are restated with their commits in the changelog, and the Mem0 and reranker retrieval tables are in COMPARISON.md.

Choose your engine

Both engines ship in 2.0.0; from 3.0.0-rc.2, mnemosy-ai ships the Local Engine and the Vector Engine moves to mnemosy-ai-legacy. Choose the storage and runtime that fit your application:

The MemoryAgent adapter uses the Local Engine's runtime. These engines have separate schemas and do not automatically migrate or synchronize data. To transition gradually, explicitly connect your existing store through the read-only migration bridge; it leaves that store unchanged.

Engine choice is separate from version: mnemosy-ai@latest is 2.0.0 and contains both engines; the 1.x line stays installable as mnemosy-ai@1. Upgrading from 1.x is a breaking change: read the migration notes before upgrading an existing Vector Engine application. From 3.0.0-rc.2 (npm next), the Vector Engine has moved out of mnemosy-ai into the mnemosy-ai-legacy package, which is not on npm yet; see the 3.0 migration notes.

Start with a working demonstration

Install the package in your project. Node 24 is recommended; the local memory engine needs no model API key, database server, or Docker.

npm install mnemosy-ai                   # stable 2.0.0; or mnemosy-ai@next for the 3.0.0-rc.2 pre-release
npx --no-install mnemosy demo
npx --no-install mnemosy learning-demo

Unqualified npm install mnemosy-ai follows the latest channel, which is 2.0.0 from 27 October 2026; pin mnemosy-ai@2.0.0 for reproducible deployments. npm install mnemosy-ai@next installs the 3.0.0-rc.2 pre-release; pin mnemosy-ai@3.0.0-rc.2 to reproduce it. If you are upgrading from the 1.x line, read the migration notes first: version 2 changes vector retrieval scoring, startup indexing and erasure, and does not migrate an existing database. Evaluate on your own workload before production. Python registry publication is separate; the bundled Python client can be installed from the checkout.

To build and run the same release from source (use --branch v3.0.0-rc.2 for the pre-release):

git clone --branch v2.0.0 --depth 1 https://github.com/28naem-del/mnemosyne.git
cd mnemosyne
npm ci --ignore-scripts
npm run build
npm run demo
npm run demo:learning

In 2.0.0, the first demo uses a temporary database to show a handoff, correction, private scope and forgetting. From 3.0.0-rc.2, mnemosy demo is the five-moment demo and the 2.0.0 demo is mnemosy demo --classic. The learning demo exercises capture, a scripted observation job, skill trials, explicit sharing and correction-driven retirement. Both run real local APIs with deterministic fixtures and no model calls. Choose your next example.

For full contributor validation, run npm run check, npm run check:docs and npm run check:public. 2.0.0 is the 2.0.0-rc.10 candidate promoted to stable with no source change (one dependency security patch, zod 4.6.2 → 4.6.7, is noted in the changelog); it carries the Tier 1 retrieval work (hybrid default, cross-encoder reranking, opt-in dense index and temporal routing) over the RC9 packaging. The recorded evaluation reports remain historical measurements of the versions and conditions they name.

To consume your built checkout from another project, run npm install /absolute/path/to/mnemosyne in that project. Keep the checkout and its dist directory available. The older RC8 GitHub release and checksummed downloads remain unchanged.

A correction should change what the next agent does

import { createLocalMemory } from 'mnemosy-ai/local';

const memory = createLocalMemory({
  path: './agent-memory.sqlite',
  workspaceId: 'catalogue',
  agentId: 'designer',
});

const brief = memory.store({
  text: 'Product images must be 1200 by 900 pixels.',
  kind: 'fact',
  key: 'catalogue.image-size',
  source: { uri: 'brief://catalogue/v1' },
  trust: 'observed',
  visibility: 'workspace',
});

const procedure = memory.store({
  text: 'Export catalogue product images at 1200 by 900 pixels.',
  kind: 'procedure',
  source: { uri: 'run://designer/export' },
  trust: 'observed',
  dependencies: [brief.id],
  visibility: 'workspace',
});

memory.correct(brief.id, {
  text: 'Product images must be 1600 by 1200 pixels.',
  source: { uri: 'brief://catalogue/v2' },
  reason: 'The delivery specification changed.',
});

console.log(memory.get(procedure.id)?.status); // invalidated
const context = memory.compile({
  query: 'catalogue product images',
  maxTokens: 2048,
});
console.log(context.text); // Send eligible context to your responder.
// Inspect context.citations and context.uncertainty alongside the text.
memory.close();

The old procedure remains inspectable but is no longer eligible as current guidance. Dependencies are declared by the controller. In 3.0, the dependencies module can also propose undeclared dependencies from suc