Skip to content
Back to search

mnemosyne

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mnemosyne-oss/mnemosyne with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mnemosyne-oss/mnemosyne'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mnemosyne-oss--mnemosyne/badge.svg)](/listings/mnemosyne-oss--mnemosyne)

HTML

<a href="/listings/mnemosyne-oss--mnemosyne"><img src="/api/listings/mnemosyne-oss--mnemosyne/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 546 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="/assets/mnemosyne.jpg" alt="Mnemosyne" width="40%">
  3. # Mnemosyne
  4. *Zero-cloud AI memory that works everywhere. SQLite-backed. One pure-Python dependency.*
  5. <a href="https://trendshift.io/repositories/27293?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-27293" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/27293/daily?language=Python" alt="mnemosyne-oss/mnemosyne | Trendshift" width="250" height="55"/></a>
  6. [![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
  7. [![PyPI](https://img.shields.io/pypi/v/mnemosyne-memory.svg)](https://pypi.org/project/mnemosyne-memory/)
  8. [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  9. [![CI](https://github.com/mnemosyne-oss/mnemosyne/actions/workflows/ci.yml/badge.svg)](https://github.com/mnemosyne-oss/mnemosyne/actions/workflows/ci.yml)
  10. [![BEAM](https://img.shields.io/badge/BEAM-ICLR%202026-purple.svg)](https://beam-benchmark.github.io/)
  11. [![Discord](https://badgen.net/discord/online-members/nousresearch)](https://discord.gg/nousresearch)
  12. [![ProductHunt](https://img.shields.io/badge/ProductHunt-Launch-orange)](https://www.producthunt.com/products/mnemosyne-2)
  13. [![MCP](https://img.shields.io/badge/MCP-Ready-6366f1)](https://modelcontextprotocol.io)
  14. </div>
  15. ---
  16. **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.
  17. ---
  18. ## Table of Contents
  19. - [Works With Everything](#works-with-everything)
  20. - [Quick Start](#quick-start)
  21. - [Add to your agent](#add-to-your-agent)
  22. - [Benchmarks](#benchmarks)
  23. - [CLI Usage](#cli-usage)
  24. - [Python API](#python-api)
  25. - [BEAM Direct Access](#advanced-beam-direct-access)
  26. - [Architecture](#architecture)
  27. - [Why Mnemosyne?](#why-mnemosyne)
  28. - [Security & Privacy Model](#security--privacy-model)
  29. - [Configuration](#configuration)
  30. - [Environment Variables](#environment-variables)
  31. - [Hermes Plugin](#hermes-plugin)
  32. - [Mnemosyne Sync](#mnemosyne-sync)
  33. - [Contributing](#contributing)
  34. - [Sponsors](#sponsors)
  35. - [Support](#support)
  36. - [License](#license)
  37. ---
  38. ## Works With Everything
  39. | Platform | Method | Setup |
  40. |----------|--------|-------|
  41. | **Cursor** | MCP | Add to `.cursor/mcp.json` |
  42. | **Claude Code** | MCP | Add to `claude.json` |
  43. | **OpenAI Codex CLI** | MCP | Add to `.codex/mcp.json` |
  44. | **Windsurf** | MCP | Add to `.windsurf/mcp_config.json` |
  45. | **OpenWebUI** | Native @tool | Drop bridge file into `data/tools/` |
  46. | **Pi** | Pi extension + skill | `pi install npm:@mnemosyne-oss/pi-mnemosyne` |
  47. | **OpenClaw** | Native provider | `pip install mnemosyne-memory[openclaw]` |
  48. | **Hermes Agent** | MCP + Plugin | Native -- ships enabled |
  49. | **Any MCP client** | MCP (stdio/SSE) | One config line |
  50. | **Any Python agent** | Direct SDK | `import mnemosyne` |
  51. See [docs/integrations/](docs/integrations/README.md) for complete setup guides per platform.
  52. ---
  53. ## Quick Start
  54. ```bash
  55. pip install mnemosyne-memory
  56. # With all features (vector search + MCP server)
  57. pip install "mnemosyne-memory[all]"
  58. # Upgrade
  59. pip install --upgrade mnemosyne-memory
  60. ```
  61. ### Add to your agent
  62. **MCP-based** (Cursor, Claude Code, Codex, Windsurf):
  63. ```json
  64. {
  65. "mcpServers": {
  66. "mnemosyne": {
  67. "command": "mnemosyne",
  68. "args": ["mcp"],
  69. "env": {}
  70. }
  71. }
  72. }
  73. ```
  74. **Python SDK** (any agent):
  75. ```python
  76. from mnemosyne import remember, recall
  77. remember("User prefers dark mode interfaces")
  78. results = recall("user preferences")
  79. ```
  80. **OpenWebUI:** Drop a 1-line bridge file into `data/tools/`.
  81. **OpenClaw:** Add `provider: mnemosyne.integrations.openclaw:create_provider` to config.
  82. ---
  83. ## Benchmarks
  84. Mnemosyne is measured on **BEAM** (ICLR 2026), in one SQLite file with no cloud dependency. A **LongMemEval** (ICLR 2025) run is pending.
  85. > **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.
  86. ### LongMemEval
  87. 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).
  88. ### BEAM (end-to-end QA), measured on v3.0.0
  89. | Scale | Mnemosyne v3.0.0 | Honcho | Hindsight | LIGHT | RAG |
  90. |-------|------------------|--------|-----------|-------|-----|
  91. | **100K** | **65.2%** | 63.0% | 73.4% | 35.8% | 32.3% |
  92. 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%
  93. **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](docs/beam-benchmark.md) for the full methodology.
  94. ### BEAM retrieval (pure recall)
  95. 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.
  96. | Scale | Recall@10 | Latency | Storage | Messages |
  97. |-------|-----------|---------|---------|----------|
  98. | 100K | 20% | 372ms | 1.8 MB | 200 |
  99. | 500K | 20% | 412ms | 3.2 MB | 1,000 |
  100. | 1M | 20% | 493ms | 4.8 MB | 2,000 |
  101. | **10M** | **20%** | **35ms** | **7.2 MB** | **20,000** |
  102. 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.
  103. Full reports: [docs/beam-benchmark.md](docs/beam-benchmark.md)
  104. ---
  105. ## CLI Usage
  106. If Mnemosyne is installed in an isolated venv, activate that venv or invoke its `bin/mnemosyne` executable before running these commands.
  107. ```bash
  108. # MCP server (works with any MCP client)
  109. mnemosyne mcp # stdio (default)
  110. mnemosyne mcp --transport sse --port 8080 # SSE (web clients)
  111. mnemosyne mcp --transport streamable-http --port 8080 # Streamable HTTP (native MCP http)
  112. # A non-loopback streamable-http bind also requires MNEMOSYNE_MCP_ALLOWED_HOSTS
  113. # (and, for browser clients, MNEMOSYNE_MCP_ALLOWED_ORIGINS) -- see docs/cli-reference.md.
  114. # Direct memory ops
  115. mnemosyne store "User likes dark mode"
  116. mnemosyne recall "preferences"
  117. mnemosyne recall "preferences" --preview # Explicit 150-character display preview
  118. mnemosyne stats
  119. mnemosyne sleep # Run consolidation
  120. mnemosyne diagnose --python /path/to/python # Check a specific runtime interpreter
  121. # Export / import
  122. mnemosyne export backup.json
  123. mnemosyne import backup.json
  124. # Sync (bidirectional memory sync between instances)
  125. mnemosyne sync --db-path /path/to/mnemosyne.db --remote https://my-vps:8765
  126. ```
  127. Human-readable `recall` output reads the current full content of selected
  128. working-memory, episodic-memory and MEMORIA hits. Ranking and scores stay the
  129. same; public `recall()` results, JSON output and cached payloads retain their
  130. configured content cap. `--preview` displays 150 characters and the full length
  131. when available. If a source is unavailable, its prefix has changed, or its hit
  132. type cannot be expanded, the CLI labels the remaining recall preview and reports
  133. the full length as unknown. These are current reads, not historical snapshots.
  134. ---
  135. ## Python API
  136. ```python
  137. from mnemosyne import remember, recall
  138. # Store a fact
  139. remember("User prefers dark mode interfaces",
  140. importance=0.9, source="preference")
  141. # Store globally (visible across all sessions)
  142. remember("User email is user@example.com",
  143. importance=0.95, scope="global")
  144. # Store with expiry
  145. remember("Temp token: abc123",
  146. importance=0.8, valid_until="2026-12-31")
  147. # Search
  148. results = recall("interface preferences", top_k=3)
  149. # Temporal recall (recency boost)
  150. results = recall("deployments",
  151. temporal_weight=0.5, temporal_halflife=48.0)
  152. # Entity extraction
  153. remember("Met with Abdias about the v2 release",
  154. extract_entities=True)
  155. # LLM-driven fact extraction
  156. remember("User said they prefer Python for backend work",
  157. extract=True)
  158. # Temporal triples (knowledge graph), scoped to a bank so it shares the
  159. # bank's MCP tools instead of writing a standalone triples.db.
  160. from mnemosyne.core.triples import TripleStore
  161. kg = TripleStore.for_bank("default")
  162. kg.add("Maya", "assigned_to", "auth-migration",
  163. valid_from="2026-01-15")
  164. kg.query("Maya", as_of="2026-02-01")
  165. # Memory banks (per-domain isolation)
  166. from mnemosyne.core.banks import BankManager
  167. BankManager().create_bank("work")
  168. work_mem = Mnemosyne(bank="work")
  169. work_mem.remember("Sprint review on Friday")
  170. ```
  171. ### Advanced: BEAM Direct Access
  172. Direct reads with `beam.get(memory_id)`, `Mnemosyne.get()`, and MCP
  173. `mnemosyne_get` include the stored `channel_id` and `trust_tier` for working
  174. and episodic memories. These fields may be `None` in rows without recorded values.
  175. JSON export/import preserves both fields, including explicit `None` values.
  176. Older exports without these keys retain the import defaults (`channel_id=None`,
  177. `trust_tier="STATED"`).
  178. When consolidation uses an OpenAI-compatible LLM endpoint (`MNEMOSYNE_LLM_BASE_URL`),
  179. Markdown bullet facts in its summaries are preserved. Prompt/token cleanup and
  180. reasoning safeguards still apply; local GGUF bullet-echo cleanup is unchanged.
  181. ```python
  182. from mnemosyne.core.beam import BeamMemory
  183. beam = BeamMemory(session_id="my_session")
  184. beam.remember("Important context", importance=0.9)
  185. beam.consolidate_to_episodic(
  186. summary="User likes Neovim",
  187. source_wm_ids=["wm1"]
  188. )
  189. results = beam.recall("editor preferences", top_k=5)
  190. ```
  191. ---
  192. ## Architecture
  193. ```
  194. +------------------------------------------------------------+
  195. | Any AI Agent |
  196. | (Hermes - Claude Code - Cursor - Codex - OpenWebUI - MCP) |
  197. +------------------------+-----------------------------------+
  198. | MCP / SDK / Plugin
  199. +------------------------v-----------------------------------+
  200. | Mnemosyne BEAM |
  201. | +------------+ +--------------+ +--------------------+ |
  202. | | Working | | Episodic | | TripleStore | |
  203. | | Memory |->| Memory | | (Temporal KG) | |
  204. | | (hot ctx) | | (long-term) | +--------------------+ |
  205. | +------------+ +------+-------+ |
  206. | | |
  207. | +----------v----------+ |
  208. | | SQLite DB | |
  209. | | (single file) | |
  210. | | sqlite-vec + FTS5 | |
  211. | | MIB binary vectors | |
  212. | +---------------------+ |
  213. +-------------------------------------------------------------+
  214. ```
  215. **BEAM** (Bilevel Episodic-Associative Memory):
  216. - **Working memory** -- Hot context, auto-injected before LLM calls, TTL-based eviction
  217. - **Episodic memory** -- Long-term storage with sqlite-vec + FTS5 hybrid search
  218. - **TripleStore** -- Temporal knowledge graph with version chains
  219. **Hybrid scoring:** 50% vector similarity + 30% FTS5 rank + 20% importance, all inside SQLite.
  220. **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.
  221. ---
  222. ## Why Mnemosyne?
  223. | Feature | Mnemosyne | mem0 | Letta | Honcho | SuperMemory | Hindsight | ChromaDB |
  224. |---------|-----------|------|-------|--------|-------------|-----------|----------|
  225. | **Local-first** | ✅ SQLite | ⚠️ Hybrid | ❌ Docker+PG | ⚠️ PG+worker | ❌ SaaS | ✅ SQLite | ✅ Embedded |
  226. | **Zero deps** | ✅ pip only | ❌ Qdrant/PG | ❌ PG+vector | ❌ PG+3 LLMs | ❌ SaaS infra | ✅ pip only | ✅ pip only |
  227. | **MCP server** | ✅ Built-in | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
  228. | **Python SDK** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  229. | **Multi-platform** | ✅ 8+ targets | ⚠️ 3 adapters | ❌ Agent-only | ⚠️ 4 adapters | ✅ MCP | ✅ MCP, 56+ direct integrations | ❌ Library only |
  230. | **Open source** | ✅ MIT | ✅ Apache 2.0 | ✅ OSS | ⚠️ AGPL | ❌ Proprietary | ✅ MIT | ✅ Apache 2.0 |
  231. | **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) |
  232. | **Self-hosted** | ✅ Yes | ✅ Optional | ✅ Optional | ✅ Yes | ❌ Enterprise | ✅ Yes | ✅ Yes |
  233. | **Integration template** | ✅ Published | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
  234. | **Memory architecture** | BEAM (3-tier) | Session + facts | OS-virtual context | Peer + reasoning | 5-layer stack | Episodic + semantic + Graph + BM25 | Vector store only |
  235. | **Purpose** | Full memory system | Memory API | Agent runtime | Managed memory | Consumer + agent | Full memory system | Vector database |
  236. ---
  237. ## Security & Privacy Model
  238. > **You are solely responsible for the content stored in Mnemosyne.**
  239. > Mnemosyne Sync supports optional client-side encryption. When disabled, memory content travels over TLS and is stored according to your infrastructure's security settings.
  240. | Feature | Mnemosyne | Detail |
  241. |---------|-----------|--------|
  242. | **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 |
  243. | **No telemetry** | ✅ | Zero tracking, zero analytics, zero cloud dependency |
  244. | **Optional sync** | ✅ | Bidirectional delta sync between desktop and VPS |
  245. | **Client-side encryption (sync)** | ✅ | Authenticated encryption via Fernet (AES-128-CBC) or PyNaCl SecretBox (XSalsa20-Poly1305). Key never leaves your machine. |
  246. | **BYOK / data-at-rest** | ✅ | Via OS keychain, env vars, or passphrase-derived keys |
  247. | **Self-hostable** | ✅ | Docker, bare metal, Fly.io -- you control the infrastructure |
  248. | **TLS enforcement** | ✅ | HTTPS in production; point `SSL_CERT_FILE` at a private CA for self-signed dev certs. |
  249. 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.
  250. **Full documentation:** [docs/security.md](docs/security.md) / [docs/sync.md](docs/sync.md)
  251. **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.
  252. ---
  253. ## Configuration
  254. ### Environment Variables
  255. | Variable | Default | Description |
  256. |----------|---------|-------------|
  257. | `MNEMOSYNE_DATA_DIR` | `~/.hermes/mnemosyne/data` | Database directory |
  258. | `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. |
  259. | `MNEMOSYNE_VEC_TYPE` | `int8` | Vector compression: `float32`, `int8`, or `bit` |
  260. | `MNEMOSYNE_VEC_WEIGHT` | `0.5` | Vector similarity weight |
  261. | `MNEMOSYNE_FTS_WEIGHT` | `0.3` | FTS5 keyword weight |
  262. | `MNEMOSYNE_IMPORTANCE_WEIGHT` | `0.2` | Importance weight |
  263. | `MNEMOSYNE_WM_MAX_ITEMS` | `10000` | Working memory limit |
  264. | `MNEMOSYNE_RECENCY_HALFLIFE` | `168` | Decay halflife in hours |
  265. | `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()`. |
  266. | `MNEMOSYNE_EMBEDDING_API_URL` | `https://openrouter.ai/api/v1` | Custom embedding API endpoint (OpenAI-compatible). When unset, the OpenRouter default is used directly; there is no `OPENROUTER_BASE_URL` fallback. Credentialed endpoints must use HTTPS: the client refuses to send `Authorization` over a non-HTTPS URL. |
  267. | `MNEMOSYNE_EMBEDDING_API_KEY` | `${OPENAI_API_KEY:-}` | Embedding API key. Falls back to `OPENAI_API_KEY`; there is no `OPENROUTER_API_KEY` fallback (set `MNEMOSYNE_EMBEDDING_API_KEY` explicitly if your chat key differs). |
  268. | `MNEMOSYNE_EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` | Embedding model. Low-resource multilingual: `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`; larger FastEmbed E5 option: `intfloat/multilingual-e5-large`; `BAAI/bge-m3` is another multilingual option. |
  269. | `MNEMOSYNE_EMBEDDING_DIM` | *(unset)* | Optional embedding dimension override (positive integer); takes precedence over the built-in model table. Blank/whitespace-only is treated as unset. |
  270. Full reference: [docs/configuration.md](docs/configuration.md)
  271. ### Language Support
  272. The Russian lexical fallback folds case and `ё`/`е` spelling when selecting
  273. candidates and scoring inflections (for example, `свеклы` can match `Свёкла`).
  274. Stored text is preserved. The fallback still averages scores over query words
  275. and uses the normal lexical admission gate; this does not guarantee admission
  276. for multi-word paraphrases or cross-language queries.
  277. Default embeddings are English-optimized (`bge-small-en-v1.5`). For **non-English or multilingual** recall, swap the model:
  278. ```bash
  279. # Low-resource local multilingual embeddings
  280. export MNEMOSYNE_EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
  281. # Larger FastEmbed E5 multilingual embeddings
  282. export MNEMOSYNE_EMBEDDING_MODEL=intfloat/multilingual-e5-large
  283. # Or Chinese-specific embeddings
  284. export MNEMOSYNE_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
  285. ```
  286. See [docs/configuration.md#custom-embedding-models](docs/configuration.md#custom-embedding-models) for tradeoffs (RAM, speed, dimension changes).
  287. ---
  288. ## Hermes Plugin
  289. When used with Hermes Agent, Mnemosyne exposes provider tools for the memory lifecycle, lifecycle hooks for automatic context injection, and MCP support.
  290. The packaged `hermes mnemosyne` CLI uses the provider's database under `HERMES_HOME/mnemosyne/data`, even when `MNEMOSYNE_DATA_DIR` points elsewhere. Profile-isolated commands select the active profile bank below that root; `doctor` reports its selected database. Standalone Core commands still honor `MNEMOSYNE_DATA_DIR`, and the packaged CLI uses the Core resolver when `HERMES_HOME` is unset. Existing stores are not moved or merged.
  291. `mnemosyne_resolve_conflicts` remains gated off by default. Its `dry_run`
  292. argument defaults to `false` (apply): use `dry_run=true` for deterministic
  293. preview, with no LLM calls or reflection reservation. Explicit
  294. `dry_run=true,llm_eval=true` previews LLM verdicts without superseding memories
  295. or emitting an apply audit, but can incur costs, write cost records and consume
  296. one reflection invocation. Evaluated previews now obey exhausted/cron guards
  297. instead of bypassing them. Both concrete Hermes provider copies expose these
  298. default-false arguments during migration; no core/MCP schema expansion is
  299. implied. See the [provider resolver contract](integrations/hermes/README.md#configuration)
  300. for gates, conservative reservation and cost-logging limits.
  301. > **For the full Hermes setup guide, see [docs/hermes-integration.md](docs/hermes-integration.md).** That is the canonical, most up-to-date reference.
  302. ### Install profile comparison
  303. | Profile | When to use | RAM | Key tradeoff |
  304. |---------|-------------|-----|-------------|
  305. | `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). |
  306. | `mnemosyne-memory[embeddings]` | Mid-range systems with local embedding support | ~800 MB | Adds `fastembed` for local vector generation. Best for single-user desktop agents. |
  307. | `mnemosyne-memory[all]` | Full-featured -- local embeddings + local LLM consolidation | ~1.5 GB | Adds `sentence-transformers` + local LLM deps (`ctransformers`). Maximum capability. |
  308. | `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. |
  309. API embeddings require NumPy in the interpreter running Mnemosyne. For an API-only installation, use `python -m pip install mnemosyne-memory numpy` (or add `numpy` alongside `mnemosyne-memory[mcp]`). FastEmbed and a local model are not required. Missing or broken NumPy is reported before any embedding request; after installing or repairing it, calls can retry without restarting.
  310. **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+.
  311. For optional per-input character and UTF-8 byte limits on both local and API embeddings, see [embedding input caps](docs/configuration.md#custom-embedding-endpoint). These caps default to off and do not guarantee a local inference memory ceiling.
  312. > **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.
  313. **Install (Hermes users):** Select the active Hermes home and runtime interpreter using the [Hermes integration guide](docs/hermes-integration.md). Follow the package-installation, installer and provider-status commands for your chosen route in that guide; persistent wrappers install the packages into a separate side environment. POSIX symlink mode links the package directory; native Windows, persistent wrappers and legacy recovery use their selected interpreter or route-specific executable. Do not link individual package files. Set `memory.provider` to `mnemosyne`, then check `hermes memory status` for the same home. Existing per-file plugin directories require the [ownership-checked recovery](docs/hermes-integration.md#recover-a-legacy-per-file-plugin-directory) before installation.
  314. After installing, verify the provider in the active Hermes profile and start a new session or restart the gateway:
  315. ```bash
  316. hermes memory status
  317. ```
  318. 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`.
  319. See [docs/hermes-integration.md](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](docs/hermes-integration.md#multiple-profiles-agent-teams-and-group-chats).
  320. ### Tool discovery
  321. The provider tool inventory is version-specific. Confirm the active provider with `hermes memory status`, then inspect the runtime tool surface:
  322. ```bash
  323. hermes tools list | grep mnemosyne_
  324. ```
  325. 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.
  326. **Updating:** For the persistent side-venv wrapper path, use the side venv rather than a bare `pip`:
  327. ```bash
  328. export HERMES_HOME=/opt/data # Replace with the active Hermes home
  329. VENV="$HERMES_HOME/.mnemosyne/venv"
  330. "$VENV/bin/python" -m pip install --upgrade 'mnemosyne-memory[embeddings]' mnemosyne-hermes
  331. "$VENV/bin/mnemosyne-hermes" install --mode wrapper --force --python "$VENV/bin/python"
  332. hermes gateway restart
  333. ```
  334. The forced install regenerates the wrapper plugin files and does not modify the Mnemosyne database.
  335. 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).
  336. ---
  337. ## Mnemosyne Sync
  338. Bidirectional, delta-based memory sync between Mnemosyne instances. Designed for desktop-to-VPS sync, team collaboration, and backup.
  339. **Key features:**
  340. - Delta/change-based protocol -- only transfers changes since last sync
  341. - Bidirectional, push-only, or pull-only modes
  342. - Optional client-side payload encryption (Fernet, or PyNaCl SecretBox XSalsa20-Poly1305)
  343. - API key and JWT authentication
  344. - Timeline + importance conflict resolution
  345. - Append-only event log for auditability
  346. ```bash
  347. # Start a sync server on your VPS
  348. mnemosyne sync-serve --port 8765 --api-key "your-secret-key"
  349. # On your local machine, sync bidirectionally
  350. mnemosyne sync --remote https://my-vps:8765
  351. # With client-side encryption
  352. export MNEMOSYNE_SYNC_KEY=$(mnemosyne sync-generate-key)
  353. mnemosyne sync --remote https://my-vps:8765 --encrypt
  354. # Check sync status
  355. mnemosyne sync-status --remote https://my-vps:8765
  356. ```
  357. **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.
  358. **Full documentation:** [docs/sync.md](docs/sync.md) / [docs/security.md](docs/security.md)
  359. ---
  360. ## Contributing
  361. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  362. Full docs: [`docs/`](docs/README.md) . Changelog: [`CHANGELOG.md`](CHANGELOG.md) . Releases: [GitHub Releases](https://github.com/mnemosyne-oss/mnemosyne/releases) . Integrations: [docs/integrations/](docs/integrations/README.md)
  363. ---
  364. ## Sponsors
  365. 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](https://mnemosyne.site/en/partners)**.
  366. ### Compute Partners
  367. 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.
  368. *Compute Partners are disclosed material connections under FTC Endorsement Guides (16 CFR Part 255). Sponsors have no editorial control over benchmark methodology or results.*
  369. ### Partner with us
  370. 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 `sponsors@mnemosyne.site` or open an issue tagged `sponsorship`.
  371. ---
  372. ## Support
  373. <div align="center">
  374. **Discord:** [Join the Mnemosyne community](https://discord.gg/nousresearch) . **Issues:** [GitHub Issues](https://github.com/mnemosyne-oss/mnemosyne/issues)
  375. <a href="https://github.com/sponsors/AxDSan"><img src="https://img.shields.io/badge/%F0%9F%92%96_GitHub_Sponsors-30363D?style=for-the-badge&logo=github&logoColor=white" alt="GitHub Sponsors"/></a>
  376. <a href="https://ko-fi.com/axdsan"><img src="https://img.shields.io/badge/%E2%98%95_Ko-fi-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white" alt="Ko-fi"/></a>
  377. **Star the repo if you find it useful!**
  378. </div>
  379. ---
  380. ## License
  381. MIT License -- See [LICENSE](LICENSE)
  382. Copyright (c) 2026 Abdias J
  383. ---
  384. <p align="center">
  385. <em>"The faintest ink is more powerful than the strongest memory." -- Hermes Trismegistus</em>
  386. </p>
  387. ## Docker self-hosting
  388. For shared MCP memory on a NAS or VPS, see the [Docker deployment guide](deploy/docker/README.md), including direct LAN HTTP, existing reverse proxies and optional Caddy HTTPS. See its verification record for tested platforms and clients.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.