Mnemosyne

Mnemosyne

Mnemosyne is a local-first memory kernel written in Rust. Codex, Claude Code, Grok Build and Antigravity share readable Markdown memories through a native CLI, MCP tools and lifecycle events. Memory operations do not require Python, a background daemon, an LLM account or a separate database server.

中文文档 · Migration and compatibility

Version 2.0.2

Version 2 includes opt-in provenance, task checkpoints, semantic revision history, system-time queries, conservative Git applicability, reviewed proposals, daily maintenance, bounded offline sleep, derived source indexes and verified directory snapshots. See the interface contract and execution evidence.

This is a breaking Rust crate release: public struct additions can break downstream struct literals. CLI compatibility does not imply crate source compatibility. The eight MCP tool names and native aliases remain compatible.

Version 2.0.2 adds resumable sleep output pages and atomic receipts, preserves committed retries after source changes, includes completed receipts in snapshots, and fixes evaluation scoring. Unfinished sleep snapshots and forks containing sleep receipts are explicitly refused. V2 performance baselines cover 100/1,000 records; offline producer/consumer checks do not claim real model or host coverage. See validation and limits.

Downloads

• macOS ARM64
• Linux x86_64
• Source archive
• SHA256SUMS

Verify the downloaded archive against SHA256SUMS before installing it. Release binaries include the executable and release documents. ONNX Runtime, local model files and vocab.txt are external requirements and are not bundled.

Build and install

git clone https://github.com/Furinelle/Mnemosyne
cd Mnemosyne
cargo build --locked --release --features onnx
mkdir -p "$HOME/.local/bin"
cp target/release/mnemosyne "$HOME/.local/bin/mnemosyne"
export PATH="$HOME/.local/bin:$PATH"
mnemosyne --help

The onnx feature enables optional local model inference. Using those models also requires a compatible ONNX Runtime shared library and existing model files with vocab.txt. Put libonnxruntime.dylib (macOS) or libonnxruntime.so (Linux) next to the executable, or set ORT_DYLIB_PATH. Models are not downloaded automatically. Basic memory operations work without the library; omit --features onnx when local inference is unnecessary.

Existing Python installations and host settings are not changed by building the binary. Use its absolute path in host configuration to avoid resolving an old executable on PATH.

Upgrade an existing store

Version 2.0 uses schema 2 and writer protocol 3. Stop every old writer first, then back up and verify all canonical store data and separately capture host configuration. Preview the upgrade before committing it:

# Run each scope that exists on this host.
mnemosyne store-upgrade --scope global
mnemosyne store-upgrade --scope project

# Only after the old writers are stopped and the complete backups are verified.
mnemosyne store-upgrade --scope global --commit
mnemosyne store-upgrade --scope project --commit

snapshot DESTINATION and restore SOURCE TARGET verify canonical-store manifests and rebuild derived search caches; restore into a separate empty directory to test the backup. Snapshots exclude host configuration. To roll back, restore the complete pre-upgrade canonical store data, restore the captured host configuration, then use its compatible old writer. Do not delete store.json or run an old writer against an upgraded store as a substitute for rollback.

Quickstart

cd /path/to/your/project
mnemosyne init --agent codex
mnemosyne write --type codebase --importance 70 \
  --title "Auth service" --content "The auth token expires after 15 minutes."
mnemosyne search "auth token" --format json
mnemosyne prep "Investigate the auth callback"

Global memory lives in ~/.mnemosyne/ (MNEMOSYNE_HOME overrides it). Project memory lives in .mnemosyne/. core.md holds the small shared core; working/*.md and archive/ hold individual memories. Markdown is authoritative; SQLite search and vector caches can be rebuilt with mnemosyne reindex and mnemosyne embed-backfill.

Connect your host

init creates project files and preserves existing instruction files. install prints configuration suggestions; it does not edit host settings or claim that the host has loaded them. Templates are in assets/templates/.

Start the native MCP server with mnemosyne mcp serve. Its eight tools are mnemosyne_search, mnemosyne_write, mnemosyne_read_core, mnemosyne_show, mnemosyne_link, mnemosyne_graph, mnemosyne_maintain and mnemosyne_prep_context. Tools accept an absolute project_path when the host launches the server outside the project, including Antigravity. Project requests without a project context fail explicitly. Project configuration can restrict MCP exposure using mcp.expose_global and mcp.expose_project.

For CLI integrations, send JSON on stdin:

printf '%s\n' '{"prompt":"Investigate the auth callback"}' |
  mnemosyne inject --event turn_start --session my-session --format json

mnemosyne hook EVENT supplies the Claude-compatible JSON envelope. Hooks never emit a tool permission grant. inject --fail-safe reports errors on stderr and returns empty stdout without blocking the host. Context budgets cover the assembled output and are estimated, not exact tokenizer limits.

Capabilities and boundaries

• SQLite FTS5 and CJK-aware lexical retrieval, optional vectors, RRF fusion, typed relation expansion and optional cross-encoder reranking.
• Source, recorded date, expiry and evidence metadata. Expired and superseded memories are excluded from default retrieval; a recorded date is not a verification date.
• Conservative writes: lexical similarity does not authorize dropping or superseding a changed fact. Explicit relations and consolidation remain available; consolidation previews candidates before changes.
• UTC-day idempotent lifecycle maintenance, archiving and core candidates. Legacy maintenance calls normalize to the same daily accounting; candidates do not automatically rewrite core.md.
• Opt-in transcript distillation for Claude, Codex, Grok, role JSONL and text. Message roles are preserved; reasoning and tool payloads are not evidence by default. distill previews unless --commit is given.
• Atomic Markdown writes, file locks and recoverable relation mutations, including coordinated cross-store links. Pending operations must recover before moving a store or changing the global coordinator location.

Endpoint addresses, credential environment-variable selectors and local model paths are trusted only from global configuration. LLM extraction and model inference are optional. The format contract is in docs/interface.md, findings exchange in docs/handoff-format.md, and host mapping in docs/adapters.md.

The runtime is native-only. The previous Python package/import API and Hermes Python MemoryProvider are retired. CLI aliases codex-prep / codex-ingest and the mnemosyne_codex_prep MCP alias remain. See the migration guide before switching an existing deployment.

Development and validation

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets
cargo run --locked -- eval run --min-recall 0.95
cargo run --locked -- eval run --pipeline full --min-recall 0.95
cargo run --locked -- eval run --longmemeval --pipeline full --min-recall 0.95

Templates and embedded evaluation fixtures are under assets/templates/ and assets/eval/. tests/native_only.rs runs the executable with an isolated home and an empty PATH, checking event envelopes, transcript replay and MCP project isolation. It does not replace acceptance inside a real host.

Python files named tests/native_*_smoke.py are optional development test harnesses, using the standard library to drive the native executable. They are not an installed kernel or a runtime dependency. Model smoke tests require separately supplied local assets; fake-provider tests do not establish real model quality. The embedded LongMemEval sample is not the full public benchmark.

The v2.0.2 test suite contains 181 tests; Linux and macOS CI run the release checks. Local host-hook checks cover protocol behavior, not four real model conversations; optional ONNX model acceptance remains environment-specific. No general performance improvement is claimed.

Validation record · Local cutover record · Changelog. These records describe their stated revisions and scope, not a guarantee that every later build or host has been verified.

License: MIT.