Memory with continuity.
Evidence with control.

Install Mnemosyne 2.0

The 2.0.0-rc.9 release candidate is available as mnemosy-ai on npm. Run the commands below in your application directory with Node.js 22.16 or newer. The local demonstrations use temporary synthetic data and require no model API key.

npm install mnemosy-ai@2.0.0-rc.9
npx --no-install mnemosy demo
npx --no-install mnemosy learning-demo

mnemosy-ai@next selects the current v2 candidate; mnemosy-ai@latest remains on 1.0.1. These are release channels, not engine selections. Version 2 contains both engines. Pin the exact version when reproducing a result.

View the npm package · Read the release notes. Python registry publication is separate; the Python client is available from source.

Two engines. Your choice.

Both interfaces ship in mnemosy-ai@2.0.0-rc.9. Choose deliberately; their stores and lifecycle capabilities differ.

• Mnemosyne Vector Engine: use createMnemosyne from mnemosy-ai for the service-backed vector path. It requires its configured storage services and embedding endpoint. Review Vector Engine setup and compatibility.
• Mnemosyne Local Engine: use createLocalMemory from mnemosy-ai/local for a local database file, scoped memory and evidence-backed lifecycle controls. Default storage and lexical recall need no model provider. Explore the local API.

MemoryAgent from mnemosy-ai/agent connects the Local Engine’s experience runtime to your host-owned agent loop. Construction starts no worker. Choose the agent integration.

Installing version 2 does not move, delete or synchronize existing memory. Continue using either engine independently. To adopt the Local Engine alongside another store, explicitly configure the gradual bridge or review a full export import.

Start with the agent you already have

Mnemosyne connects the evidence, context and feedback around your existing agent. Choose a scoped interface; your application keeps control of model requests, credentials and actions.

• Mnemosyne Memory SDK: call the local engine directly from your application. Use the SDK.
• Mnemosyne Service API: connect through authenticated HTTP, including the bundled Python client. Connect a client.
• MCP: expose scoped memory operations through a local stdio server. Connect your host.
• Mnemosyne Memory Tools: connect virtual memory operations to your host’s tool-calling loop. Explore memory tools.

Already using the Mnemosyne Vector Engine? Review the existing-user path before choosing the separate Local Engine.

Build from source

Choose a source checkout when you want the repository examples, Python client or development scripts. Node.js 22.16 or newer and npm are required. The remaining node dist/..., npm run ... and examples/... recipes on this page assume this completed checkout.

git clone --branch v2.0.0-rc.9 --depth 1 https://github.com/28naem-del/mnemosyne.git
cd mnemosyne
npm ci --ignore-scripts
npm run build
node dist/cli/index.js demo
node dist/cli/index.js learning-demo

Using the npm installation? For CLI recipes below, replace node dist/cli/index.js with npx --no-install mnemosy. Import SDK modules through the package’s public exports, such as mnemosy-ai/local. Repository scripts and examples/... still require the source checkout.

Get source and release assets or inspect the recorded runtime evidence.

Already running the Mnemosyne Vector Engine?

The Mnemosyne Vector Engine includes our enhanced retrieval, indexing and scoped memory controls. createMnemosyne() remains its API; createLocalMemory() creates the separate Mnemosyne Local Engine. Their records and lifecycle capabilities differ; installing this checkout does not import, rename, delete or synchronize your existing collections.

Keep your existing application on its chosen backend while you evaluate the local path. The release candidate also changes vector retrieval scoring, startup indexing, explicit erasure and maintenance behavior. Review the v2 compatibility and migration notes and the existing Vector Engine deployment guide against an isolated copy.

Arrived from an older configuration, API or deployment bookmark? Those examples described the vector engine. Use the guides above for its current settings, or deliberately choose the local API. To move data between them, use an explicit export import or a host-supplied gradual migration adapter.

Store your first memory

Every CLI memory command needs a database path, workspace and agent. This example creates a private record owned by builder. Add --share only when other agents in that workspace should be able to read it.

node dist/cli/index.js store \
  --db ./project-memory.sqlite \
  --workspace my-project --agent builder \
  --text "Run the accessibility check before release." \
  --source "project://release-checklist"

node dist/cli/index.js recall \
  --db ./project-memory.sqlite \
  --workspace my-project --agent builder \
  --query "release accessibility"

The CLI stores observed source assertions by default. The TypeScript store defaults to untrusted records unless the caller chooses a trust level. Repeated retrieval never upgrades a memory into verified evidence.

Connect an MCP client

The CLI starts a stdio MCP server. Configure your client to launch the command below, replacing the example paths for your machine.

{
  "mcpServers": {
    "mnemosyne": {
      "command": "node",
      "args": [
        "/absolute/path/to/mnemosyne/dist/cli/index.js",
        "mcp",
        "--db", "/absolute/path/to/project-memory.sqlite",
        "--workspace", "my-project",
        "--agent", "builder"
      ]
    }
  }
}

The configuration shape depends on your client. Use the absolute path to your Node executable as command if the client cannot resolve node.

Available tools include memory_store, memory_recall, memory_context, memory_inspect, memory_checkpoint, memory_resume and memory_correct. The controller fixes workspace and agent at launch; the model cannot select a different scope in a tool call.

• --read-only exposes only read operations.
• --allow-destructive explicitly exposes memory_forget. It is absent by default.
• Verified trust, outcome recording and reflection commits are controller operations, not model-facing MCP tools.

Memory is reference data. A recalled instruction or checkpoint does not grant permission to publish, delete, buy or run a command.

Use the local TypeScript API

The example below runs from the built source checkout. In an application using the npm package, replace ./dist/local/index.js with mnemosy-ai/local. Close the database when the owning process is done.

import { createLocalMemory } from './dist/local/index.js';

const memory = createLocalMemory({
  path: './project-memory.sqlite',
  workspaceId: 'my-project',
  agentId: 'builder',
});

try {
  const brief = memory.store({
    text: 'Catalogue images use a 1600 x 1200 canvas.',
    kind: 'decision',
    key: 'catalogue-output',
    trust: 'observed',
    visibility: 'workspace',
    source: { uri: 'project://catalogue/brief-v2' },
  });

  memory.store({
    text: 'Fit the original image inside 1600 x 1200; pad, never stretch.',
    kind: 'procedure',
    trust: 'observed',
    visibility: 'workspace',
    source: { uri: 'project://catalogue/resize-procedure' },
    dependencies: [brief.id],
  });

  const packet = memory.compile({
    query: 'catalogue image canvas',
    maxTokens: 4096,
  });
  console.log(packet.text);
} finally {
  memory.close();
}

Send packet.text as reference context to your chosen model. The budget covers that text; additional structured diagnostics are outside it. By default the counter uses a conservative UTF-8 byte upper bound. Supply a compatible tokenCounter when you need a model-specific count.

Connect Python through local HTTP

Run the authenticated HTTP service, then use MemoryClient from the bundled mnemosyne_memory module. The client supports Python 3.10 or newer and uses only the standard library at runtime; the memory engine still runs in Node.js.

Install from the checkout with python -m pip install ./python, or set PYTHONPATH=python to use the source directly. The Python distribution is mnemosyne-memory-client; this release is not published to PyPI.

The client sends the configured bearer token and offers recall, context, inspection, store, correction, forgetting and capture helpers. It uses timeouts and does not automatically retry mutations. Follow the HTTP and Python setup example for token handling and server limits.

Mnemosyne Memory Tools

Give your agent a consistent memory workspace through six virtual-file operations: view, create, replace, insert, rename and delete. The workspace is scoped to the selected identity and stored locally.

Your host selects a supported tool protocol, sends model requests and returns each tool result under its original call identity. Mnemosyne supplies the memory handlers; connecting a consumer chat account or discovering its history is not automatic.

Existing method names remain stable in the SDK. Use the integration contract shipped with the matching source release; product branding does not change configuration identifiers. Memory tool guide.

Mnemosyne Recall

Find evidence across the complete authorized indexed corpus, including older semantic matches behind newer records. Ranked lexical retrieval is the default; optional semantic candidates are combined independently before reranking.

Indexing is explicit. Scope checks and corrections are revalidated across asynchronous retrieval. A scan that reaches its deadline fails clearly instead of presenting incomplete coverage as a complete result. Retrieval behavior and controls.

Mnemosyne Timeline

Ask what was valid at a moment, and what your system knew at another. Context assembly accepts independent asOf and knownAt coordinates through the SDK, service API and MCP. The Python client exposes as_of and known_at.

const packet = memory.compile({
  query: 'release procedure',
  asOf: '2026-09-03T00:00:00.000Z',
  knownAt: '2026-09-10T00:00:00.000Z',
  maxTokens: 4096,
});

Corrections preserve legitimate earlier guidance and scheduled changes take effect at their declared time. Erasure and current access controls still apply; ambiguous imported invalidations are kept inactive. Timeline semantics.

Mnemosyne On-Device Intelligence

Run optional semantic embeddings and reranking on your own CPU. After explicitly provisioning the pinned runtime and model files, inference can reopen offline without sending memory text to a remote service.

Local model providers are separate from the default installation. They use bounded text windows, isolated inference processes and cancellation deadlines. The tested setup includes a patched dependency and startup validation; use the exact installation recipe supplied with the matching release. Mnemosyne develops the integration, indexing and memory controls; optional components retain their own licenses. Local inference guide · Install and configure local models.

Mnemosyne Evidence Gate

Make a lesson earn reuse through distinct tasks and declared verifier identities. The recommended policy requires two of each before a candidate becomes ordinary advice. Requirements persist with the candidate, so restarting with weaker settings cannot lower them.

The compatibility default remains one controller trial. Verifier identities are supplied by your controller; they are not proof of independent people or cryptographic verification. Failures and changed prerequisites can retire previously useful skills. Promotion policy and limits.

Correct the source, inspect the effect

memory.correct(id, { text, source, reason }) creates a replacement and supersedes the original. Dependent lessons become inactive. You can inspect the historical records, while active recall excludes them.

Use memory.inspect({ includeInactive: true }) to review history, or memory.get(id) to inspect a visible record. Different active texts sharing an explicit fact key remain a conflict; the compiler does not silently choose a winner.

memory.checkpoint(...) records a task’s goal, completed and pending work, decisions, constraints, artifacts, rejected approaches and next action. Set dependencies: [sourceOrProcedureId] when its next action relies on a memory. memory.resume(taskId) retrieves eligible state; corrected, failed or conflicted evidence prevents obsolete handoffs from resuming. If multiple owners share conflicting checkpoints for the same task, resolve that ambiguity before resuming.

Logical export includes owned records with complete owned provenance. It can omit records that depend on another agent’s data; inspect the omitted count. Import is scoped to the same workspace and agent. Snapshots have record and byte limits.

Add a bounded reflection pass

Import reflect and commitVerifiedLesson from ./dist/reflection/index.js. You supply a proposer function using your chosen model or service. Mnemosyne chooses no provider and adds no paid fallback.

1. reflect(memory, options) compiles eligible evidence and makes at most one proposing call.
2. The response is checked for output limits, duplicate proposals and fabricated source IDs. Proposing writes no memory.
3. Your controller evaluates the proposal against a task or environment.
4. commitVerifiedLesson requires passed validation with evidence, a verifier and a task ID, then checks that source revisions remain valid.

A committed lesson remains an observed synthesis with validation metadata. Caller-supplied validation is not authenticated proof of truth. Timeouts signal cancellation; your provider must honor the signal to stop its own compute.

Source release access and status.

Use the experience runtime

The runtime adds selected-file and visible-transcript capture, original-source inspection, bounded durable observation jobs, source-backed topic models and skills that require controller trials before activation.

Use capture --file PATH --adapter text for a selected document or use generic for selected JSONL transcripts. Add --watch to keep that foreground process synchronized. These commands require the same database, workspace and agent flags shown above.

serve --token-file PATH starts the local HTTP service and live inspector. The token file must contain a private, unpredictable secret of at least 32 bytes. Python applications can use the bundled standard-library client. The inspector displays actual records from your running store after authentication.

Provider configuration is explicit. Hybrid retrieval uses an explicitly selected local model or embedding endpoint; observation jobs use a selected proposer. No cloud service or paid fallback is enabled automatically.

Follow the complete runtime guide with runnable examples for configuration, trials, branches, entity relationships and access controls.

Connect the agent loop

MemoryAgent wraps a host-supplied responder with context preparation, visible-turn capture and durable observation jobs. Use beforeTurn and afterTurn separately when your host already owns the loop. Capture is untrusted by default; asserting observed input is an explicit controller decision.

The supplied event adapters accept selected visible events. They do not install hooks, discover history or establish that a live provider SDK session has been tested. The host selects every provider and any action callback.

node dist/cli/index.js agent --action work --watch \
  --db ./agent-memory.sqlite --workspace my-project --agent assistant \
  --provider-config ./provider.json \
  --json '{"maxCycles":10,"maxDurationMs":60000,"maxCalls":4,"maxTotalInputBytes":262144}'

This foreground process performs bounded background work until a limit or cancellation. Construction starts no worker, and the command installs no daemon. A later explicit worker can recover durable queued jobs and expired leases. Read the agent overview, then follow the provider configuration example and bounded worker setup.

Build context that can return to its sources

AdaptiveContext.build selects eligible observations, hierarchical summaries and original excerpts within a declared budget. It makes no model call. An optional, caller-selected proposer creates compact detail batches and an overview through separate, bounded refresh and compact operations.

Use expand with a returned source handle to recover exact original UTF-8 text in bounded pages. Handles and local selection caches retain identities, ranges and state hashes, not extra raw-text copies. Corrections, erasure, trust changes, source checks and outcomes invalidate affected generated context across the full dependency chain. Older generated records without complete proof fall back to eligible originals.

Call validate(packet) immediately before dispatching retained context. The token budget covers packet.text; metadata sits outside it. Supply a named tokenizer for model-specific counting; the default is a conservative byte estimate. API, runnable example and limits.

Keep typed fields tied to evidence

MemoryProfiles accepts a caller-defined validation schema. Each field is known with supporting source IDs, unknown, or a conflict with separately cited candidates. Define the fields, explicitly refresh them with selected sources and a host-owned proposer, then read them without inference.

All supplied inputs become dependencies. Reads validate the schema and complete generation state; stale or unavailable profiles return unknown fields without old values. These private, advisory projections preserve attribution and uncertainty. A schema check or citation does not prove a claim true.

Profile API, typed examples and limits.

Migrate as your agent uses memory

Keep the existing memory system running. Connect its search through an explicit read-only adapter, then let Mnemosyne copy the records your agent actually retrieves.

1. Shadow: the old system leads while exact source copies accumulate.
2. Assist: successful paired recall checks increase Mnemosyne’s share. Missing matches still come from the old system.
3. Prefer Mnemosyne: use more current local results while continuing legacy reconciliation. Return to legacy routing at any time.

The bridge never writes to or deletes the old store. Progress measures observed queries, so it cannot claim every unused memory has migrated. Full export migration remains available below.

npm run build
node --experimental-strip-types examples/gradual-migration.ts

The gradual migration guide documents the adapter, agent integration, fallback, rollback and shared forgetting protections. The example uses synthetic data and no external model.

Mnemosyne Migration

Bring existing memories across through 11 explicit export profiles for supported memory records, conversation histories, graph facts, legacy Mnemosyne snapshots and Markdown. Imports preserve the supplied representation and report what the source export cannot represent.

Choose a profile that matches the actual export shape. Product branding does not change SDK profile identifiers; the matching release includes the exact format registry. A plain document needs no vendor-specific format:

node dist/cli/index.js migrate \
  --file ./MEMORY.md --profile markdown \
  --logical-path project/MEMORY.md --assume-missing-owner \
  --source-store previous-memory \
  --workspace my-project --agent assistant \
  --acknowledge-partial --out ./reviewed-plan.json

node dist/cli/index.js migrate --action apply \
  --file ./reviewed-plan.json --db ./agent-memory.sqlite \
  --batch first-import --confirm

Preview opens no destination database. It reports completeness, owner selection and byte accounting. Apply checks the source bytes again. Imports are private and untrusted by default; source data never grants execution permission.

Review full imports, guarded undo and replay protection. Prefer gradual adoption? Keep the old system alongside Mnemosyne.

Check evidence that quietly becomes stale

Use MemoryMaintenance from mnemosy-ai/maintenance to set explicit recheck intervals, record controller-supplied source evidence and filter stale dependencies from freshness-aware recall. Bounded probes distinguish confirmed, changed and unavailable sources. Merely retrieving a fact never refreshes its confirmation.

For an action derived from memory, create a short-lived read set bound to its exact operation, arguments and complete memory dependencies. Validate it again before the host considers that action. Changes, failures or expiry reject the old read set; this does not lock an external system or grant permission to act.

node --experimental-strip-types examples/migration.ts
node --experimental-strip-types examples/maintenance.ts

Both examples use temporary databases and make zero model calls. The freshness example uses an injected clock and scripted source checks. Existing generic recall does not automatically apply this additional policy. Follow the freshness SDK guide and CLI examples.

Verify a backup, restore to a new path

Operator recovery covers the whole database, including all workspaces, private records, queued work and replay guards. It has broader authority than a scoped logical export. The following example starts with an existing database and new private directories:

mkdir -m 700 backups recovery
node dist/cli/index.js operations --action backup \
  --db ./agent-memory.sqlite --out ./backups/snapshot.mnemo-backup
node dist/cli/index.js operations --action verify \
  --file ./backups/snapshot.mnemo-backup
node dist/cli/index.js operations --action restore \
  --file ./backups/snapshot.mnemo-backup --out ./recovery/memory.sqlite

Outputs must be new paths. Verification checks bundle hashes and database integrity; it does not authenticate a signer or encrypt the data. Restore performs no service cutover. Protect and retain these plaintext copies separately: a live-store deletion cannot erase an older backup. Operator API and tested limits.

Measured progress. Inspectable evidence.

The published rc.8 study records a matched retrieval comparison on 500 questions from a public long-conversation corpus. The rc.9 packaging release retains this evidence; it does not represent a new benchmark run. Reference answers stay outside retrieved memory. The same dataset, question set, chunking and context budget are used for both retrieval conditions.

• Complete source-session coverage before packing: 386/470 (82.13%) with the previous lexical scorer; 425/470 (90.43%) with the upgraded scorer.
• After the same 8,192-byte context envelope: 367/470 (78.09%) improves to 382/470 (81.28%).
• All 500 questions retained: 470 have positive source annotations; 30 abstention questions remain in the run but are not included in those positive-coverage denominators.

Coverage means that every annotated source session has a representative retrieved chunk among the top 20. It does not prove that the answer-bearing sentence reached the agent, or that the agent answered correctly. This run used no embeddings, generated answers or model judge.

Check the whole memory lifecycle

An additional 16-scenario synthetic diagnostic improves from 9 passes, 1 failure and 6 errors to 15 passes, 1 failure and no errors. The remaining case conservatively retires valid guidance after an unrelated source-field edit. Alternative sufficient evidence is not yet supported.

The separate agent evaluation harness measures answer correctness, grounding, stale actions and transfer under matched readers and budgets. Its scripted fixtures are implemented; public generated-answer and real-agent task results remain open. Evaluation guide and limits.

Choose where compute happens

Mnemosyne is MIT licensed, with no Mnemosyne license fee. The local core store, default lexical recall and context assembly run without model calls. You supply the machine, storage and any hosting.

Optional embeddings, observation, reflection and generated context use providers you explicitly configure. Those services may charge for inference, and self-hosted models still consume your compute. The Mnemosyne Vector Engine also requires its configured embedding endpoint. Your agent’s normal model requests remain separate from memory operations.

Start with the offline demos, then enable only the providers your application needs. Set explicit call, input-byte and time budgets for observation work. Mnemosyne selects no paid provider or fallback automatically.

Know the boundaries

• Retrieval is configurable. The default ranked lexical search scores matching terms using their frequency, rarity and record length. The local store also supports explicitly configured CPU embeddings, hybrid recall and reranking, with offline inference after provisioning. Model-based semantic quality depends on the chosen provider and remains to be evaluated on your tasks.
• Scopes are application boundaries. Anyone with direct database access or control of the process can act outside them. Use your operating system and application authentication to protect the store.
• Outcome evidence comes from the controller. Success and failure records help evaluate reusable advice. They are not independent authentication or model training.
• Forget purges the live store. It cannot remove prior exports, backups or context already delivered to a model.
• Fine-grained retirement is still evolving. An unrelated edit to a supporting source can conservatively retire useful advice. Alternative sufficient evidence is not yet supported.
• Encryption and enterprise services are separate work. Database files and backups are plaintext; built-in enterprise identity and bidirectional synchronization are not included.
• Memory is one component of an agent. This release does not establish AGI or a published advantage on agent benchmarks.

The reference guides above describe this release candidate. The tagged engineering documentation includes detailed API contracts, operational boundaries and reproducible evaluation protocols.