mnemosyne-oss/mnemosyne instruction manual

1. What Mnemosyne is and how it relates to Claude Code

Mnemosyne is an MIT-licensed, Python 3.10+ memory system for AI agents. It stores working memory, long-term episodic memory, and temporal knowledge-graph facts in SQLite. Its documented retrieval combines vector similarity, FTS5 keyword matching, and importance weighting; its default weights are 0.5, 0.3, and 0.2. It can run locally without an external vector database or mandatory cloud service.

**Claude Code classification:** `tool_surface`, installed as a `claude_extension` through MCP, with medium setup effort. The evidence specifically documents a Claude Code MCP configuration in `claude.json`. Mnemosyne is not documented as a Claude Code plugin, hook, or skill; it runs as a separate local process that exposes memory tools over MCP. This makes it an MCP-based extension to Claude Code’s tool surface.

Install the core package, or the documented full-feature profile:

pip install mnemosyne-memory
pip install "mnemosyne-memory[all]"

For MCP alone, the integration guide gives the narrower extra:

pip install "mnemosyne-memory[mcp]"

The documented MCP client configuration is:

{
  "mcpServers": {
    "mnemosyne": {
      "command": "mnemosyne",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Add that object to Claude Code’s `claude.json`, then restart the client so it launches the stdio server. The integration overview documents three basic MCP tools: `mnemosyne_remember`, `mnemosyne_recall`, and `mnemosyne_forget`. Other supplied files describe larger, version-specific surfaces in other hosts, so inspect the active runtime rather than assuming Hermes or Zero tool counts apply to Claude Code.

2. Installation, verification, and storage profiles

The recommended installation source is PyPI. The core profile is the low-resource option and can use a remote embedding API; the `[embeddings]` profile adds FastEmbed for local vectors; `[all]` adds local embeddings and local-LLM consolidation dependencies. The README estimates roughly 50 MB, 800 MB, and 1.5 GB of RAM respectively, while recommending at least 2 GB free RAM for `[embeddings]` and 8 GB+ for `[all]`.

On Ubuntu 24.04 or Debian 12, use the documented virtual-environment procedure if pip reports an externally managed environment:

python3 -m venv .venv
source .venv/bin/activate
pip install mnemosyne-memory[all]

Verify the Python API with:

from mnemosyne import get_stats
print(get_stats())

Or verify the CLI and inspect memory counts with:

mnemosyne stats

If installed in an isolated virtual environment, activate it or invoke its `bin/mnemosyne` executable. The principal README lists `~/.hermes/mnemosyne/data` as the default database directory through `MNEMOSYNE_DATA_DIR`; a separate Hermes integration README lists `MNEMOSYNE_HOME=~/.mnemosyne` for that integration. Treat these as path-specific documentation rather than interchangeable defaults.

Contributor installation is separately documented:

git clone https://github.com/mnemosyne-oss/mnemosyne.git
cd mnemosyne
pip install -e ".[all,dev]"

This editable source installation is for contributors, not required for ordinary Claude Code MCP use. Upgrading the published package is documented as:

pip install --upgrade mnemosyne-memory

3. Core CLI and MCP server operation

Run the local MCP server over stdio for Claude Code and other desktop MCP clients:

mnemosyne mcp

The CLI also documents network transports:

mnemosyne mcp --transport sse --port 8080
mnemosyne mcp --transport streamable-http --port 8080

A non-loopback Streamable HTTP bind requires `MNEMOSYNE_MCP_ALLOWED_HOSTS`; browser clients also require `MNEMOSYNE_MCP_ALLOWED_ORIGINS`. Do not expose these transports without the host, origin, and network controls described by the repository.

Direct memory commands are:

mnemosyne store "User likes dark mode"
mnemosyne recall "preferences"
mnemosyne stats
mnemosyne sleep

`store` persists a memory. `recall` searches stored information. `stats` reports store statistics. `sleep` consolidates older working memories into episodic summaries.

Backup and migration use:

mnemosyne export backup.json
mnemosyne import backup.json

`export` writes memories to a backup file; `import` restores or migrates from a supported backup. Review backup files as sensitive data because they may contain user facts, source fields, or credentials.

The README also documents bidirectional instance synchronization:

mnemosyne sync --db-path /path/to/mnemosyne.db --remote https://my-vps:8765

Use a physically dedicated shared-surface database for sync rather than a private profile or session database. The deployment guide explicitly requires initialization of a new dedicated client database with `mnemosyne sync-init`. Mnemosyne’s ordinary local operation is described as having no telemetry, but remote embeddings, LLM services, MCP network transports, and sync are outbound surfaces and must be evaluated separately.

4. Python API, memory banks, and temporal knowledge graph

The convenience API stores and retrieves memories:

from mnemosyne import remember, recall

remember("User prefers dark mode interfaces",
         importance=0.9, source="preference")
results = recall("interface preferences", top_k=3)

`remember` stores content with optional importance and source metadata. `recall` returns matching memories, with `top_k` limiting results. Set `scope="global"` for cross-session visibility, or `valid_until` for expiry:

remember("User email is user@example.com",
         importance=0.95, scope="global")
remember("Temp token: abc123",
         importance=0.8, valid_until="2026-12-31")

Avoid storing secrets unless your threat model and retention policy permit it. Temporal recall adds a recency contribution:

results = recall("deployments",
                 temporal_weight=0.5, temporal_halflife=48.0)

`extract_entities=True` requests entity extraction, while `extract=True` requests LLM-driven fact extraction:

remember("Met with Abdias about the v2 release", extract_entities=True)
remember("User said they prefer Python for backend work", extract=True)

Temporal triples belong to a named bank:

from mnemosyne.core.triples import TripleStore
kg = TripleStore.for_bank("default")
kg.add("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
kg.query("Maya", as_of="2026-02-01")

`add` records a subject–predicate–object fact with temporal validity; `query` asks what was valid at a given time. Banks isolate domains:

from mnemosyne.core.banks import BankManager
BankManager().create_bank("work")
work_mem = Mnemosyne(bank="work")
work_mem.remember("Sprint review on Friday")

The supplied snippet uses `Mnemosyne` but does not show its import; consult the generated API reference before copying that fragment into a standalone program.

5. BEAM tiers, consolidation, retrieval, and experimental subsystems

BEAM means Bilevel Episodic-Associative Memory. Working memory holds hot context and uses TTL-based eviction. Episodic memory contains consolidated long-term summaries. `TripleStore` maintains temporal fact version chains. SQLite provides FTS5 and vector storage; the README describes MIB binary vectors as compressing 384-dimensional float32 embeddings into 48 bytes.

Advanced direct access is documented as:

from mnemosyne.core.beam import BeamMemory

beam = BeamMemory(session_id="my_session")
beam.remember("Important context", importance=0.9)
beam.consolidate_to_episodic(
    summary="User likes Neovim",
    source_wm_ids=["wm1"]
)
results = beam.recall("editor preferences", top_k=5)

`BeamMemory` binds operations to a session. `remember` writes working memory. `consolidate_to_episodic` creates a summary linked to source working-memory IDs. `recall` performs retrieval. Use this lower-level interface only when the convenience API does not provide the control you need.

The documentation index identifies additional shipped subsystems: memory hygiene supports noise scoring, auditing, cleaning, secret detection, and prevention of noisy writes; configuration profiles provide eight built-in profiles and warn that changing `vec_type` requires restart handling; the L3 persona tier stores durable behavioral facts and can inject an opt-in `persona.md`; and AAAK has a compression plugin interface with a legacy fallback. However, SHMR is explicitly described as library-only with nothing calling it yet. Likewise, RFC documents and the layered-memory roadmap are forward-looking proposals, not current functionality. Do not treat proposed tags, modality providers, media moments, archive boundaries, or roadmap layers as available merely because their designs are present.

6. Configuration, embeddings, language support, and privacy

The main storage and scoring controls are `MNEMOSYNE_DATA_DIR`, `MNEMOSYNE_JOURNAL_MODE`, `MNEMOSYNE_VEC_TYPE`, `MNEMOSYNE_VEC_WEIGHT`, `MNEMOSYNE_FTS_WEIGHT`, `MNEMOSYNE_IMPORTANCE_WEIGHT`, `MNEMOSYNE_WM_MAX_ITEMS`, and `MNEMOSYNE_RECENCY_HALFLIFE`. Vector types are `float32`, `int8`, or `bit`. `MNEMOSYNE_CONTEXT_INCLUDE_CONSOLIDATED` opt-in values are `1`, `true`, `yes`, or `on`; it affects `get_context()` injection, not `recall()`.

The journal default is WAL. Use `delete` on filesystems where WAL causes corrupt reads, such as the documented Linux-container/macOS-virtiofs case. `memory` and `off` remove disk-backed rollback protection and can corrupt data after a crash.

The default embedding model is English-optimized. Documented multilingual choices are:

export MNEMOSYNE_EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
export MNEMOSYNE_EMBEDDING_MODEL=intfloat/multilingual-e5-large
export MNEMOSYNE_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5

`MNEMOSYNE_EMBEDDING_DIM` overrides the built-in dimension table with a positive integer. `MNEMOSYNE_EMBEDDING_API_URL` selects an OpenAI-compatible embedding endpoint and defaults to OpenRouter when unset; credentialed endpoints must use HTTPS. `MNEMOSYNE_EMBEDDING_API_KEY` falls back to `OPENAI_API_KEY`, not `OPENROUTER_API_KEY`.

Local-first does not mean every configuration is local. A custom remote endpoint, an API-shaped model, or `MNEMOSYNE_EMBEDDINGS_VIA_API` can send memory text and recall queries to a provider. Sync similarly sends data off-device; without client-side encryption, content travels over TLS and is stored according to server controls. Mnemosyne documents no telemetry, but users remain responsible for stored content, access controls, backups, keys, and third-party policies.

7. Sync server, encryption, conflicts, and deployment

Sync is delta-based and supports bidirectional, push-only, and pull-only modes. The documented service supports API-key and JWT authentication, timeline-plus-importance conflict resolution, and an append-only event log. Start a server and client with:

mnemosyne sync-serve --port 8765 --api-key "your-secret-key"
mnemosyne sync --remote https://my-vps:8765
mnemosyne sync-status --remote https://my-vps:8765

Prefer key files over command-line secrets. Generate a client-side encryption key and enable encryption with:

export MNEMOSYNE_SYNC_KEY=$(mnemosyne sync-generate-key)
mnemosyne sync --remote https://my-vps:8765 --encrypt

Encryption uses documented Fernet authenticated encryption or PyNaCl SecretBox. With it enabled, the server sees metadata such as event IDs, timestamps, operation types, and device IDs, while memory content, importance, sources, and vectors are encrypted. Back up the encryption key separately; losing it loses access to encrypted memories.

For the supplied Docker Compose deployment, first create a private API-key file:

umask 077
mnemosyne sync-generate-key > mnemosyne-sync-api.key
printf 'MNEMOSYNE_SYNC_API_KEY_FILE=%s\n' "$PWD/mnemosyne-sync-api.key" > .env
docker compose up -d
docker compose ps
docker compose logs mnemosyne-sync

Replace the example domain in `Caddyfile` before startup. Initialize a dedicated client database once:

MNEMOSYNE_SYNC_DB="$HOME/.mnemosyne/shared-surface.db"
mkdir -p "$(dirname "$MNEMOSYNE_SYNC_DB")"
chmod 700 "$(dirname "$MNEMOSYNE_SYNC_DB")"
mnemosyne sync-init --db-path "$MNEMOSYNE_SYNC_DB"

Always use TLS in production, restrict server volumes, keep key files mode `0600`, and use `--encrypt-key-file` when the host is not fully trusted.

8. Other integrations, documented limitations, and safe operation

Beyond Claude Code, the repository documents MCP setup for Cursor, Codex, Windsurf, and generic clients; a native OpenWebUI tool; a Pi extension; an OpenClaw provider; Hermes provider/plugin paths; and a Zero plugin. The VS Code extension browses, searches, stores, refreshes, and displays memory statistics. The Obsidian desktop plugin exports memories as Markdown with YAML frontmatter, avoids overwriting edited notes, supports filtering, and can auto-sync every 5–120 minutes.

The Zero plugin provides `memory_remember`, `memory_recall`, `memory_stats`, `memory_sleep`, and `memory_forget`, plus an advisory `afterTool` hook that records file edits. It requires Zero 0.2+, the Mnemosyne CLI, and `jq`. Its skill is not yet automatically discoverable, session-start/session-end hooks are not dispatched, and `mnemosyne` must be on PATH.

Hermes has a much broader, version-specific integration: automatic post-turn capture, pre-turn recall, consolidation, temporal triples, graph traversal, shared memory, scratchpads, validation, export/import, and diagnostics. The current supported route is the standalone `mnemosyne-hermes` provider; the old source-checkout symlink installer is obsolete. A catalog plugin requires Hermes 0.21.4 or later. Do not infer Hermes’ 40-tool claims or lifecycle hooks for Claude Code.

Benchmark claims require caution. The published BEAM end-to-end score is a v3.0.0 point-in-time result; judges differ from competing runs, current features have not been rerun, pure-retrieval Recall@10 is documented as 20%, and the earlier 98.9% LongMemEval claim was withdrawn for lack of reproducible methodology. Finally, review stored material for secrets and legal restrictions, protect SQLite and exported files, use local embeddings for sensitive content, and remember that network MCP, remote embeddings, hosted LLMs, and sync change the repository’s default local-only privacy boundary.