Mnemosyne

Zero-cloud AI memory that works everywhere. SQLite-backed. One pure-Python dependency.

---

Mnemosyne is a universal, Hermes-first memory layer that works with any agent framework (Claude Code, Cursor, Codex, OpenWebUI, OpenClaw, or your own custom agent). One pip install, one SQLite database. No external services required.

---

Table of Contents

• Works With Everything
• Quick Start
  • Add to your agent
• Benchmarks
• CLI Usage
• Python API
  • BEAM Direct Access
• Architecture
• Why Mnemosyne?
• Security & Privacy Model
• Configuration
  • Environment Variables
• Hermes Plugin
• Mnemosyne Sync
• Contributing
• Sponsors
• Support
• License

---

Works With Everything

Platform	Method	Setup
Cursor	MCP	Add to .cursor/mcp.json
Claude Code	MCP	Add to claude.json
OpenAI Codex CLI	MCP	Add to .codex/mcp.json
Windsurf	MCP	Add to .windsurf/mcp_config.json
OpenWebUI	Native @tool	Drop bridge file into data/tools/
Pi	Pi extension + skill	pi install npm:@mnemosyne-oss/pi-mnemosyne
OpenClaw	Native provider	pip install mnemosyne-memory[openclaw]
Hermes Agent	MCP + Plugin	Native -- ships enabled
Any MCP client	MCP (stdio/SSE)	One config line
Any Python agent	Direct SDK	import mnemosyne

See docs/integrations/ for complete setup guides per platform.

---

Quick Start

pip install mnemosyne-memory

# With all features (vector search + MCP server)
pip install "mnemosyne-memory[all]"

# Upgrade
pip install --upgrade mnemosyne-memory

Add to your agent

MCP-based (Cursor, Claude Code, Codex, Windsurf):

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

Python SDK (any agent):

from mnemosyne import remember, recall

remember("User prefers dark mode interfaces")
results = recall("user preferences")

OpenWebUI: Drop a 1-line bridge file into data/tools/.

OpenClaw: Add provider: mnemosyne.integrations.openclaw:create_provider to config.

---

Benchmarks

Mnemosyne is measured on BEAM (ICLR 2026), in one SQLite file with no cloud dependency. A LongMemEval (ICLR 2025) run is pending.

Read the version labels. These are point-in-time results, not a claim about the current build. The BEAM numbers were measured on v3.0.0 (May 2026) and predate polyphonic recall, enhanced recall, SHMR, and the persona tier. They have not been re-run since. Re-running BEAM and LongMemEval on the current tree is tracked as an open task.

LongMemEval

A 98.9% Recall@All@5 figure from an April 2026 run was listed here until September 2026. No methodology or run log for it exists in any of the project repositories, so it has been withdrawn until LongMemEval is re-run on the current tree with a published, reproducible setup (#584).

BEAM (end-to-end QA), measured on v3.0.0

Scale	Mnemosyne v3.0.0	Honcho	Hindsight	LIGHT	RAG
100K	65.2%	63.0%	73.4%	35.8%	32.3%

Per-ability (100K): IE 91.5% · MR 87.5% · TR 75.0% · ABS 100.0% · CR 50.0% · KU 50.0% · EO 25.0% · IF 62.5% · PF 54.5% · SUM 55.6%

Judge caveat: Mnemosyne's run used Llama 3.3 70B with a DeepSeek V4 Flash judge, while Hindsight's published 73.4% used Llama-4-Maverick. Scores produced under different judges are not directly comparable, so the 65.2% and 73.4% figures in the same row should be read with that in mind. Hindsight leads on this benchmark as published. See beam-benchmark.md for the full methodology.

BEAM retrieval (pure recall)

This measures raw retrieval in isolation, with no answer synthesis, so it is a different quantity from the end-to-end QA scores above and is not comparable to them.

Scale	Recall@10	Latency	Storage	Messages
100K	20%	372ms	1.8 MB	200
500K	20%	412ms	3.2 MB	1,000
1M	20%	493ms	4.8 MB	2,000
10M	20%	35ms	7.2 MB	20,000

The notable property is that recall holds flat as the corpus grows by two orders of magnitude, and that storage grows sub-linearly: episodic compression delivers 9.4x savings. Abstention accuracy is 100%, meaning the system declines rather than inventing an answer when the corpus does not contain one. The absolute 20% Recall@10 is low, and the flatness rather than the level is the result worth citing.

Full reports: docs/beam-benchmark.md

---

CLI Usage

If Mnemosyne is installed in an isolated venv, activate that venv or invoke its bin/mnemosyne executable before running these commands.

# MCP server (works with any MCP client)
mnemosyne mcp                          # stdio (default)
mnemosyne mcp --transport sse --port 8080  # SSE (web clients)
mnemosyne mcp --transport streamable-http --port 8080  # Streamable HTTP (native MCP http)
# A non-loopback streamable-http bind also requires MNEMOSYNE_MCP_ALLOWED_HOSTS
# (and, for browser clients, MNEMOSYNE_MCP_ALLOWED_ORIGINS) -- see docs/cli-reference.md.

# Direct memory ops
mnemosyne store "User likes dark mode"
mnemosyne recall "preferences"
mnemosyne stats
mnemosyne sleep                         # Run consolidation

# Export / import
mnemosyne export backup.json
mnemosyne import backup.json

# Sync (bidirectional memory sync between instances)
mnemosyne sync --db-path /path/to/mnemosyne.db --remote https://my-vps:8765

---

Python API

from mnemosyne import remember, recall

# Store a fact
remember("User prefers dark mode interfaces",
         importance=0.9, source="preference")

# Store globally (visible across all sessions)
remember("User email is [email protected]",
         importance=0.95, scope="global")

# Store with expiry
remember("Temp token: abc123",
         importance=0.8, valid_until="2026-12-31")

# Search
results = recall("interface preferences", top_k=3)

# Temporal recall (recency boost)
results = recall("deployments",
                 temporal_weight=0.5, temporal_halflife=48.0)

# Entity extraction
remember("Met with Abdias about the v2 release",
         extract_entities=True)

# LLM-driven fact extraction
remember("User said they prefer Python for backend work",
         extract=True)

# Temporal triples (knowledge graph), scoped to a bank so it shares the
# bank's MCP tools instead of writing a standalone triples.db.
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")

# Memory banks (per-domain isolation)
from mnemosyne.core.banks import BankManager
BankManager().create_bank("work")
work_mem = Mnemosyne(bank="work")
work_mem.remember("Sprint review on Friday")

Advanced: BEAM Direct Access

When consolidation uses an OpenAI-compatible LLM endpoint (MNEMOSYNE_LLM_BASE_URL), Markdown bullet facts in its summaries are preserved. Prompt/token cleanup and reasoning safeguards still apply; local GGUF bullet-echo cleanup is unchanged.

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)

---

Architecture

+------------------------------------------------------------+
|                    Any AI Agent                            |
|  (Hermes - Claude Code - Cursor - Codex - OpenWebUI - MCP) |
+------------------------+-----------------------------------+
                         | MCP / SDK / Plugin
+------------------------v-----------------------------------+
|                      Mnemosyne BEAM                         |
|  +------------+  +--------------+  +--------------------+   |
|  | Working    |  | Episodic     |  | TripleStore         |   |
|  | Memory     |->| Memory       |  | (Temporal KG)      |   |
|  | (hot ctx)  |  | (long-term)  |  +--------------------+   |
|  +------------+  +------+-------+                           |
|                         |                                    |
|              +----------v----------+                        |
|              |     SQLite DB       |                        |
|              |  (single file)      |                        |
|              |  sqlite-vec + FTS5  |                        |
|              |  MIB binary vectors |                        |
|              +---------------------+                        |
+-------------------------------------------------------------+

BEAM (Bilevel Episodic-Associative Memory):

• Working memory -- Hot context, auto-injected before LLM calls, TTL-based eviction
• Episodic memory -- Long-term storage with sqlite-vec + FTS5 hybrid search
• TripleStore -- Temporal knowledge graph with version chains

Hybrid scoring: 50% vector similarity + 30% FTS5 rank + 20% importance, all inside SQLite.

Binary vectors: Information-theoretic binarization (MIB) compresses 384-dim float32 embeddings into 48 bytes -- 32x reduction. Hamming distance entirely within SQLite. No ANN indices, no external vector DB.

---

Why Mnemosyne?

Feature	Mnemosyne	mem0	Letta	Honcho	SuperMemory	Hindsight	ChromaDB
Local-first	✅ SQLite	⚠️ Hybrid	❌ Docker+PG	⚠️ PG+worker	❌ SaaS	✅ SQLite	✅ Embedded
Zero deps	✅ pip only	❌ Qdrant/PG	❌ PG+vector	❌ PG+3 LLMs	❌ SaaS infra	✅ pip only	✅ pip only
MCP server	✅ Built-in	❌	❌	❌	✅	✅	❌
Python SDK	✅	✅	✅	✅	✅	✅	✅
Multi-platform	✅ 8+ targets	⚠️ 3 adapters	❌ Agent-only	⚠️ 4 adapters	✅ MCP	✅ MCP, 56+ direct integrations	❌ Library only
Open source	✅ MIT	✅ Apache 2.0	✅ OSS	⚠️ AGPL	❌ Proprietary	✅ MIT	✅ Apache 2.0
Benchmark	65.2% BEAM / 87.4% LongMem	49% LongMem	83.2% LoCoMo	90.4% LongMem	85.2% MemoryBench	73.4% BEAM / 94.6% LongMem	N/A (vector DB)
Self-hosted	✅ Yes	✅ Optional	✅ Optional	✅ Yes	❌ Enterprise	✅ Yes	✅ Yes
Integration template	✅ Published	❌	❌	❌	❌	❌	❌
Memory architecture	BEAM (3-tier)	Session + facts	OS-virtual context	Peer + reasoning	5-layer stack	Episodic + semantic + Graph + BM25	Vector store only
Purpose	Full memory system	Memory API

---

Security & Privacy Model

You are solely responsible for the content stored in Mnemosyne. Mnemosyne Sync supports optional client-side encryption. When disabled, memory content travels over TLS and is stored according to your infrastructure's security settings.

Feature	Mnemosyne	Detail
Local-first by default	✅	No data ever leaves your machine unless you enable sync or use remote embedding or LLM services; remote embeddings (a custom non-OpenRouter MNEMOSYNE_EMBEDDING_API_URL, an API-shaped model, or MNEMOSYNE_EMBEDDINGS_VIA_API) send the text of your memories and recall queries for vectorization, to the OpenRouter endpoint when no custom URL is set
No telemetry	✅	Zero tracking, zero analytics, zero cloud dependency
Optional sync	✅	Bidirectional delta sync between desktop and VPS
Client-side encryption (sync)	✅	Authenticated encryption via Fernet (AES-128-CBC) or PyNaCl SecretBox (XSalsa20-Poly1305). Key never leaves your machine.
BYOK / data-at-rest	✅	Via OS keychain, env vars, or passphrase-derived keys
Self-hostable	✅	Docker, bare metal, Fly.io -- you control the infrastructure
TLS enforcement	✅	HTTPS in production; point SSL_CERT_FILE at a private CA for self-signed dev certs.

When client-side encryption is enabled, the remote sync server sees only metadata (event IDs, timestamps, operation types, device IDs). Memory content, importance scores, source fields, and vector embeddings are all encrypted before transmission. The server cannot read your memories.

Full documentation: docs/security.md / docs/sync.md

Comparison: Mnemosyne is the only memory system with client-side encryption of sync payloads as a core feature. Zep offers BYOK for data-at-rest but manages the key server-side. Every other system (Mem0, Letta, Honcho, Supermemory) relies solely on self-hosting and TLS for privacy.

---

Configuration

Environment Variables

Variable	Default	Description
MNEMOSYNE_DATA_DIR	~/.hermes/mnemosyne/data	Database directory
MNEMOSYNE_JOURNAL_MODE	wal	SQLite journal mode for store connections (memory, beam, query cache, veracity consolidator; the sync client rides the beam connection). Valid: delete, truncate, persist, memory, wal, off; the value is trimmed and lower-cased, unset or blank falls back to wal, and non-blank invalid values warn and fall back to wal. Set delete on filesystems where WAL corrupts reads (Linux containers on macOS virtiofs). Only wal persists in the database file; every other mode is per-connection and reverts to SQLite's default (delete) on reopen, so each connection re-applies the mode itself. memory and off remove disk-backed rollback protection and can corrupt the database after a crash.
MNEMOSYNE_VEC_TYPE	int8	Vector compression: float32, int8, or bit
MNEMOSYNE_VEC_WEIGHT	0.5	Vector similarity weight
MNEMOSYNE_FTS_WEIGHT	0.3	FTS5 keyword weight
MNEMOSYNE_IMPORTANCE_WEIGHT	0.2	Importance weight
MNEMOSYNE_WM_MAX_ITEMS	10000	Working memory limit
MNEMOSYNE_RECENCY_HALFLIFE	168	Decay halflife in hours
MNEMOSYNE_CONTEXT_INCLUDE_CONSOLIDATED	(unset)	Include consolidated working-memory rows in get_context() prompt injection. Default: excluded. Truthy values: 1, true, yes, on. Does not affect recall().
MNEMOSYNE_EMBEDDING_API_URL	https://openrouter.ai/api/v1

Full reference: docs/configuration.md

Language Support

Default embeddings are English-optimized (bge-small-en-v1.5). For non-English or multilingual recall, swap the model:

# Low-resource local multilingual embeddings
export MNEMOSYNE_EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

# Larger FastEmbed E5 multilingual embeddings
export MNEMOSYNE_EMBEDDING_MODEL=intfloat/multilingual-e5-large

# Or Chinese-specific embeddings
export MNEMOSYNE_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5

See docs/configuration.md#custom-embedding-models for tradeoffs (RAM, speed, dimension changes).

---

Hermes Plugin

When used with Hermes Agent, Mnemosyne exposes provider tools for the memory lifecycle, lifecycle hooks for automatic context injection, and MCP support.

mnemosyne_resolve_conflicts remains gated off by default. Its dry_run argument defaults to false (apply): use dry_run=true for deterministic preview, with no LLM calls or reflection reservation. Explicit dry_run=true,llm_eval=true previews LLM verdicts without superseding memories or emitting an apply audit, but can incur costs, write cost records and consume one reflection invocation. Evaluated previews now obey exhausted/cron guards instead of bypassing them. Both concrete Hermes provider copies expose these default-false arguments during migration; no core/MCP schema expansion is implied. See the provider resolver contract for gates, conservative reservation and cost-logging limits.

For the full Hermes setup guide, see docs/hermes-integration.md. That is the canonical, most up-to-date reference.

Install profile comparison

Profile	When to use	RAM	Key tradeoff
mnemosyne-memory (core)	Low-resource (Raspberry Pi, 1 GB VPS), or when using a remote embedding API	~50 MB	No local embeddings. Point MNEMOSYNE_EMBEDDING_API_URL to an external endpoint, and set MNEMOSYNE_EMBEDDING_DIM for models not in the built-in table (else direct startup fails loudly).
mnemosyne-memory[embeddings]	Mid-range systems with local embedding support	~800 MB	Adds fastembed for local vector generation. Best for single-user desktop agents.
mnemosyne-memory[all]	Full-featured -- local embeddings + local LLM consolidation	~1.5 GB	Adds sentence-transformers + local LLM deps (ctransformers). Maximum capability.
mnemosyne-hermes	Hermes Agent users -- always pair with one of the above	Same as base	Wraps core library with plugin manifest + entry points; degrades instead of exiting on core init errors. Run hermes config set memory.provider mnemosyne after install.

Hardware guidance: Core alone runs on a Raspberry Pi 4 (4 GB) with ~300 MB free for LLM. [embeddings] needs at least 2 GB free RAM. [all] recommends 8 GB+.

Privacy note on remote embedding endpoints. Embeddings go to a remote API whenever MNEMOSYNE_EMBEDDING_API_URL points at a custom (non-OpenRouter) endpoint, the model name is API-shaped (openai/*, text-embedding*), or MNEMOSYNE_EMBEDDINGS_VIA_API is truthy; on the OpenRouter default (or an OpenRouter URL) the last two are what route, and with no URL set the OpenRouter default is used. That service receives the text of your memories and of your recall queries (working-memory content, summaries, annotations, and search queries) for vectorization. For privacy-sensitive or local-first deployments prefer a local-embedding profile ([embeddings] or [all]); use a remote endpoint only when you accept that the embedding provider sees your content.

Install (Hermes users):

source ~/.hermes/hermes-agent/venv/bin/activate
python -m ensurepip --upgrade
python -m pip install --upgrade pip
python -m pip install mnemosyne-hermes
mkdir -p ~/.hermes/plugins/mnemosyne
ln -sfn "$(~/.hermes/hermes-agent/venv/bin/python -c 'import pathlib, mnemosyne_hermes; print(pathlib.Path(mnemosyne_hermes.__file__).resolve().parent)')"/* ~/.hermes/plugins/mnemosyne/
hermes config set memory.provider mnemosyne

After installing, verify the provider in the active Hermes profile and start a new session or restart the gateway:

hermes memory status

Do not use hermes tools disable memory: that disables the memory toolset, including provider tools. In current Hermes versions, built-in memory and an external provider are separate mechanisms; hermes memory off disables the external provider only. Keep existing built-in memory as a rollback/reference point during a transition and confirm the active provider with hermes memory status.

See docs/hermes-integration.md for the full setup guide. For multiple Hermes profiles, agent teams, or group chats (Telegram, SimpleX, etc.), see Multiple Profiles, Agent Teams, and Group Chats.

Tool discovery

The provider tool inventory is version-specific. Confirm the active provider with hermes memory status, then inspect the runtime tool surface:

hermes tools list | grep mnemosyne_

Mnemosyne exposes memory, knowledge-graph, multi-agent-surface, working-note, and operational tools. Treat the runtime list as authoritative. The installer or wrapper registers the plugin manifest under $HERMES_HOME/plugins/mnemosyne, where Hermes discovers it.

Updating: For the persistent side-venv wrapper path, use the side venv rather than a bare pip:

export HERMES_HOME=/opt/data  # Replace with the active Hermes home
VENV="$HERMES_HOME/.mnemosyne/venv"
"$VENV/bin/python" -m pip install --upgrade 'mnemosyne-memory[embeddings]' mnemosyne-hermes
"$VENV/bin/mnemosyne-hermes" install --mode wrapper --force --python "$VENV/bin/python"
hermes gateway restart

The forced install regenerates the wrapper plugin files and does not modify the Mnemosyne database.

For a direct or source install, use pip install --upgrade mnemosyne-hermes && hermes gateway restart or git pull && pip install --upgrade integrations/hermes && hermes gateway restart (source).

---

Mnemosyne Sync

Bidirectional, delta-based memory sync between Mnemosyne instances. Designed for desktop-to-VPS sync, team collaboration, and backup.

Key features:

• Delta/change-based protocol -- only transfers changes since last sync
• Bidirectional, push-only, or pull-only modes
• Optional client-side payload encryption (Fernet, or PyNaCl SecretBox XSalsa20-Poly1305)
• API key and JWT authentication
• Timeline + importance conflict resolution
• Append-only event log for auditability

# Start a sync server on your VPS
mnemosyne sync-serve --port 8765 --api-key "your-secret-key"

# On your local machine, sync bidirectionally
mnemosyne sync --remote https://my-vps:8765

# With client-side encryption
export MNEMOSYNE_SYNC_KEY=$(mnemosyne sync-generate-key)
mnemosyne sync --remote https://my-vps:8765 --encrypt

# Check sync status
mnemosyne sync-status --remote https://my-vps:8765

When encryption is enabled, the remote server sees only metadata (event IDs, timestamps, operation types). Memory content is encrypted before leaving your machine and can only be decrypted with your key.

Full documentation: docs/sync.md / docs/security.md

---

Contributing

See CONTRIBUTING.md for guidelines.

Full docs: docs/ . Changelog: CHANGELOG.md . Releases: GitHub Releases . Integrations: docs/integrations/

---

Sponsors

Mnemosyne development is supported by paid sponsorships and by companies providing compute credits (LLM, embedding, GPU), hosting, and developer tooling. See the full list, tiers and sponsorship policy at mnemosyne.site/partners.

Compute Partners

The Compute Partner position is currently open. It is held by one inference provider at a time, whose credits run the nightly recall benchmarks and multi-model parity tests, in exchange for the top placement in this README, the partners page and a dedicated documentation page.

Compute Partners are disclosed material connections under FTC Endorsement Guides (16 CFR Part 255). Sponsors have no editorial control over benchmark methodology or results.

Partner with us

Sponsorship is paid, in cash or in credits, and every placement is disclosed. To ask about the Compute Partner position or a Sponsor slot, email [email protected] or open an issue tagged sponsorship.

---

Support

Discord: Join the Mnemosyne community . Issues: GitHub Issues

Star the repo if you find it useful!

---

License

MIT License -- See LICENSE

Copyright (c) 2026 Abdias J

---