Mnemosyne

Zero-dependency AI memory that works everywhere. SQLite-backed. Sub-millisecond.

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.

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

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

pip install mnemosyne-memory

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

# Upgrade
pip install --upgrade mnemosyne-memory

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.

Mnemosyne holds top-tier scores on the two major memory benchmarks, LongMemEval (ICLR 2025) and BEAM (ICLR 2026), both in one SQLite file, zero cloud dependencies.

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%

Recall holds flat across all scales. 100% abstention accuracy, never hallucinates on unknowns. Episodic compression delivers 9.4x storage savings.

Full reports: docs/beam-benchmark.md

# MCP server (works with any MCP client)
mnemosyne mcp                          # stdio (default)
mnemosyne mcp --transport sse --port 8080  # SSE (web clients)

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

# Export / import
mnemosyne export --output backup.json
mnemosyne import --input backup.json

# Sync (bidirectional memory sync between instances)
mnemosyne sync --remote https://my-vps:8765
mnemosyne sync --remote https://my-vps:8765 --encrypt
mnemosyne sync serve --port 8765 --api-key "sk-..."

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 user@example.com",
         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)
from mnemosyne.core.triples import TripleStore
kg = TripleStore()
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")

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)

+------------------------------------------------------------+
|                    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.

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.

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.

| MNEMOSYNE_EMBEDDING_API_URL | ${OPENROUTER_BASE_URL:-https://openrouter.ai/api/v1} | Preferred name for custom embedding API endpoint (OpenAI-compatible). Falls back to OPENROUTER_BASE_URL. | | MNEMOSYNE_EMBEDDING_API_KEY | ${OPENROUTER_API_KEY:-${OPENAI_API_KEY:-}} | Preferred name for embedding API key. Falls back to OPENROUTER_API_KEY, then OPENAI_API_KEY. | | MNEMOSYNE_EMBEDDING_MODEL | BAAI/bge-small-en-v1.5 | Embedding model. Low-resource multilingual: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2; larger options: intfloat/multilingual-e5-base, BAAI/bge-m3. |

Full reference: docs/configuration.md

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 multilingual embeddings
export MNEMOSYNE_EMBEDDING_MODEL=intfloat/multilingual-e5-base

# 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).

When used with Hermes Agent, Mnemosyne exposes 23 tools for full memory lifecycle management -- 3 lifecycle hooks (pre_llm_call, on_session_start, post_tool_call) for automatic context injection, plus MCP support.

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

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+.

Install (Hermes users):

pip install mnemosyne-hermes
hermes config set memory.provider mnemosyne
hermes memory setup

Then disable Hermes' built-in MEMORY.md/USER.md system so Mnemosyne is the sole memory provider. Do NOT use hermes tools disable memory -- that also kills all 23 Mnemosyne-registered tools.

Edit ~/.hermes/config.yaml:

memory:
  memory_enabled: false
user_profile_enabled: false

See docs/hermes-integration.md for the full setup guide.

All 23 tools surface through the mnemosyne-hermes package, which wraps the mnemosyne-memory core library. The plugin manifest at integrations/hermes/ is also discoverable by Hermes' plugin system.

Updating: pip install --upgrade mnemosyne-hermes && hermes gateway restart or git pull && pip install --upgrade integrations/hermes && hermes gateway restart (source).

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 (XChaCha20-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

See CONTRIBUTING.md for guidelines.

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

MIT License -- See LICENSE

Copyright (c) 2026 Abdias J

"The faintest ink is more powerful than the strongest memory." -- Hermes Trismegistus