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
• Benchmark
• CLI Usage
• Python API
  • BEAM Direct Access
• Architecture
• Why Mnemosyne?
• Configuration
  • Environment Variables
• Hermes Plugin (23 tools)
• Contributing
• Support
• License

---

Works With Everything

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

LongMemEval (retrieval)

BEAM (end-to-end QA)

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%

BEAM retrieval (pure recall)

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

---

CLI Usage

# 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

---

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)
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")

Advanced: BEAM Direct Access

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
┌────────────────────────▼───────────────────────────────────┐
│                      Mnemosyne BEAM                         │
│  ┌────────────┐  ┌──────────────┐  ┌────────────────────┐   │
│  │ Working    │  │ Episodic     │  │ TripleStore         │   │
│  │ Memory     │──▶│ Memory       │  │ (Temporal KG)      │   │
│  │ (hot ctx)  │  │ (long-term)  │  └────────────────────┘   │
│  └────────────┘  └──────┬───────┘                           │
│                         │                                    │
│              ┌──────────▼──────────┐                        │
│              │     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?

---

Configuration

Environment Variables

| 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

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

---

Hermes Plugin (23 tools)

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.

Install profile comparison

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.

Tool categories

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

---

Contributing

See CONTRIBUTING.md for guidelines.

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

---

Support

---

License

MIT License — See LICENSE

Copyright (c) 2026 Abdias J

---

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