Mnem

[](LICENSE) [](https://github.com/Uranid/mnem/actions/workflows/ci.yml) [](https://crates.io/crates/mnem-cli) [](https://pypi.org/project/mnem-cli/) [](https://www.npmjs.com/package/mnem-cli) [](rust-toolchain.toml) [](#install)

[English](README.md)  ·  [中文](README.zh-CN.md)  ·  [Español](README.es.md)

mnem is Git for AI Agent Knowledge. A persistent, versioned knowledge layer for AI agents, with best-or-tied recall on every public benchmark we tested.

Drop in source code, PDFs, Markdown docs, conversation exports, or whole directories and mnem parses, chunks, and indexes them in one command. File types are auto-detected: heading-aware chunking for Markdown, function- and class-level parsing for source code across many languages, sliding-window extraction for PDFs. No LLM call at ingest, so the same input always produces the same graph; re-ingesting an unchanged file is a no-op.

Skills, decisions, and conventions live as nodes and typed edges in a queryable knowledge graph inside your project's .mnem/ directory. Commit it alongside your code and every teammate's agents start from the same baseline; branch, diff, merge, or roll back any write the same way you would source. Forgetting is first-class: revoke a fact and every retrieval path filters it out automatically, with the audit trail preserved.

Retrieval fuses vector, keyword, and graph traversal in a single pass and reports exactly how many tokens were spent and what was dropped at the budget; nothing gets silently truncated. Optional multi-hop graph expansion stitches answers together across linked documents.

One binary, no server, no external database, fully offline; the same engine runs as a CLI, an HTTP server, an MCP server, or a Python library, and in the browser via WebAssembly. Wire it into Claude Code, Cursor, Gemini CLI, or any MCP host with one command. Zero-config out of the box; swap the embedder provider in one line of config when you outgrow the default.

https://github.com/user-attachments/assets/bd744a7e-8e89-4531-bd96-fdee0030c390

1. [The Problem](#the-problem)
2. [Benchmarks](#benchmarks)
3. [vs others](#compared-to-others)
4. [Install](#install)
5. [Quickstart](#quickstart)
6. [Integrate / Unintegrate](#mnem-integrate---wire-into-any-agent-host)
7. [Commands](#commands)
8. [MCP Tools](#mcp-tools)
9. [Python API](#python-api-mnem-py)
10. [GraphRAG](#graphrag)
11. [What you get](#what-you-get)
12. [When NOT to use](#when-not-to-use-mnem)
13. [Docs](#documentation)
14. [Contributing](#contributing)

The Problem

> Who this affects: If you use AI coding assistants (Claude Code, Cursor, Gemini CLI, etc.) or build software where an AI agent needs to remember things between sessions, this is the problem mnem solves.

> Every session starts from zero.

• Sessions are isolated. Plan a migration in Claude Code (an AI coding assistant). Open Cursor (another AI coding assistant) tomorrow. That agent has never heard of it.
• Memory you can't inspect isn't memory. Something changed in your agent's context. You don't know what, when, or why. There's no log.
• Conventions rot in flat files. Six engineers, six AGENTS.md files (agent configuration files many AI tools read automatically) diverging in silence. No merge, no history, no way to tell which is current.

> Your codebase has git. Your agent's knowledge doesn't.

Benchmarks

Measured head-to-head against mem0 and MemPalace on six public datasets. mnem leads on five‡†; ties MemPalace on LongMemEval.

Methodology, footnotes, query speed, and reproduction steps

> Methodology: mem0 numbers are our own reproduction under the same harness - mem0 does not publish R@K (Recall at top K - the fraction of correct answers returned in the top K results) headline scores on these datasets. MemPalace headline numbers are cross-verified under our harness. This is disclosed, not hidden: reproducible artifacts ship alongside the binary.

Default harness embedder: MiniLM-L6-v2 (a small pre-trained text model in ONNX format - ONNX is an open file format for AI models; you don't need to install anything separately), same bytes across all systems in each test. FinanceBench uses bge-large on all systems for fair comparison (see † footnote). No LLM rerank. Sample counts per run: LongMemEval 500 Q, LoCoMo full dataset (~1986 Q), ConvoMem 50/category, MemBench 100/config. All benchmarks use dense-only retrieval (no sparse/BM25 lane). Reproduce: bash benchmarks/harness/run_bench.sh.

mem0 columns: our reproduction under the same harness (mem0 doesn't publish R@K headlines on these datasets). MemPalace columns: public headline numbers cross-verified under our harness. Raw artefacts: [benchmarks/results/v0.1.0/](benchmarks/results/v0.1.0/). † FinanceBench uses Ollama bge-large (1024-dim) on all systems; MemPalace shown at best configuration (bge-large direct ChromaDB); mem0 applies LLM memory extraction before storage. Pipeline note: mnem FinanceBench run used hybrid retrieval (--hybrid-boost --query-expand); MemPalace bge-large used pure vector retrieval - pipelines differ. Full methodology: [benchmarks/results/analysis/financebench.md](benchmarks/results/analysis/financebench.md). ‡ LoCoMo: mnem uses MAX-over-turn-hits session scoring (lenient); MemPalace uses per-turn aggregation (stricter) - scores reflect different evaluation methodology. See [benchmarks/results/analysis/locomo.md](benchmarks/results/analysis/locomo.md).

Query speed

Reproduce

mnem bench fetch longmemeval     # download datasets (one-time, 264 MB)
mnem bench                       # TUI; select benchmarks interactively
mnem bench run --benches longmemeval --limit 50 --non-interactive
mnem bench results ./bench-out   # re-render results from a prior run

# Legacy bash harness (canonical path for headline numbers)
bash benchmarks/harness/run_bench.sh

Methodology, raw artifacts, per-bench breakdowns: [benchmarks/](benchmarks/) and [docs/src/benchmarks/](docs/src/benchmarks/).

Compared to others

✅ full support  ·  ~ partial or limited  ·  ✗ not supported  ·  n/a not applicable  ·  + see footnote

| | mnem | mem0 | MemPalace | Hermes | Supermemory | Graphiti | Letta | Cognee | |--|:--------:|:--------:|:-------------:|:------------:|:---------------:|:------------:|:---------:|:----------:| | Local-first | ✅ | ~ | ✅ | ~ | ✗ | ✗ | ~ | ~ | | Versioned history | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ | ~ | ✗ | | Branch & merge | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | Content-addressed storage + | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | WASM / edge | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | API-free ingest | ✅ | ~ | ✅ | ~ | ✗ | ✗ | ✗ | ~ | | Token-budget transparency | ✅ | ✗ | ✗ | ~ | ✗ | ✗ | ~ | ✗ | | Single binary | ✅ | ✗ | ✗ | ✗ | n/a | ✗ | ✗ | ✗ | | No external DB | ✅ | ~ | ✗ | ✅ | n/a | ✗ | ✗ | ~ | | Knowledge graph | ✅ | ✗ | ~ | ✗ | ✗ | ✅ | ✗ | ✅ | | Hybrid retrieval | ✅ | ~ | ~ | ✗ | ~ | ✅ | ~ | ~ | | MCP native | ✅ | ~ | ✅ | ✗ | ✅ | ~ | ✅ | ✅ | | License | Apache-2.0 | Apache-2.0 | MIT | MIT | MIT | Apache-2.0 | Apache-2.0 | Apache-2.0 |

Footnotes and head-to-head comparisons

• Content-addressed storage: same bytes always get the same ID; identical facts auto-deduplicate  ·  Hybrid retrieval here means vector + sparse + graph in one pass  ·  Hermes is an agent runtime, not a memory store; mnem attaches as a MemoryProvider plugin and rows show Hermes' native memory only (bounded MEMORY.md + FTS5 session log)  ·  mem0 v2 (Apr 2026) dropped graph backends from the OSS SDK  ·  Graphiti needs an LLM key + a graph backend (Neo4j / FalkorDB / Kuzu / Neptune); ships an MCP server  ·  Letta "MCP" = MCP client (Letta agents call MCP servers)  ·  MemPalace defaults to ChromaDB (backend pluggable)  ·  Supermemory self-host needs Cloudflare + Postgres + OpenAI  ·  Cognee needs an LLM key for graph extraction; first-party MCP server since v0.3.5  ·  verified 2026-05-19

Deeper write-ups:

• [mnem vs mem0](docs/src/comparisons/mem0.md) - agent memory layer, OSS leader
• [mnem vs MemPalace](docs/src/comparisons/mempalace.md) - benchmark peer
• [mnem vs Hermes](docs/src/comparisons/hermes.md) - agent runtime; mnem plugs in as the memory layer
• [mnem vs Supermemory](docs/src/comparisons/supermemory.md) - cloud-hosted memory service
• [mnem vs Graphiti](docs/src/comparisons/graphify.md) - AI coding assistant knowledge graph tool
• [mnem vs Letta](docs/src/comparisons/letta.md) - agent-memory framework (formerly MemGPT)
• [mnem vs Cognee](docs/src/comparisons/cognee.md) - KG-for-agents alternative

Full matrix: [docs/src/comparisons/README.md](docs/src/comparisons/README.md).

Install

Pick one:

Cargo (Rust) · compiles from source, ~5-15 min first run

No Cargo yet?

Install via rustup (free; also installs rustc). Verify with cargo --version.

# Linux only: sudo apt-get install g++ (Debian/Ubuntu/WSL)  or  sudo dnf install gcc-c++ (Fedora/RHEL)
cargo install --locked mnem-cli --features bundled-embedder

Skip the source compile (cargo binstall)

cargo install compiles from source (the ~5-15 min above). To grab a prebuilt binary directly, install cargo-binstall once and then:

cargo binstall mnem-cli

Resolves to the GitHub-release archive in seconds. Same bytes, same features (bundled-embedder baked in). Reach for cargo install when you need a custom feature set (e.g. --features bundled-embedder-cuda).

~~pip (Python)~~ ~~· pre-built binary, bundled embedder, works immediately~~

> [!CAUTION] > macOS binaries not yet published. pip install mnem-cli installs v0.1.7, which uses a runtime downloader that fails on macOS. Per-platform wheels (Linux · Windows · macOS) ship in v0.1.8 — use cargo install above in the meantime.

No pip yet?

Install Python (free; pip is bundled with Python 3.4+). Verify with python --version.

pip install mnem-cli

> Using Python to call mnem from your own app? pip install mnem-cli gives you the mnem command-line tool. To import mnem from Python code (import pymnem), use pip install mnem-py instead - see [Python API](#python-api-mnem-py).

~~npm (Node.js)~~ ~~· pre-built binary, bundled embedder, works immediately~~

> [!CAUTION] > macOS support pending. npm install -g mnem-cli installs v0.1.7, which uses a runtime downloader that may fail on macOS. Per-platform sub-packages ship in v0.1.8 — use cargo install above in the meantime.

No npm yet?

Install Node.js (free; npm is bundled, Node 18+ required). Verify with node --version.

npm install -g mnem-cli

From source · the unreleased main branch, for local changes or pre-release commits

When to pick this over cargo install

Use this if you need a commit that hasn't been published to crates.io yet, or you're making local changes. Otherwise prefer the published-crate path above. Requires Rust 1.95+ (rustup install 1.95 && rustup default 1.95 if needed).

# Linux only: sudo apt-get install g++ (Debian/Ubuntu/WSL)  or  sudo dnf install gcc-c++ (Fedora/RHEL)
git clone https://github.com/Uranid/mnem
cd mnem
cargo install --path crates/mnem-cli --features bundled-embedder

Docker · runs the HTTP server; no local install needed

docker run --rm -p 9876:9876 -e MNEM_HTTP_ALLOW_NON_LOOPBACK=1 \
  ghcr.io/uranid/mnem:latest http --bind 0.0.0.0:9876

mnem --version    # confirm install
mnem doctor       # checks embedder + store + config, prints a green/yellow/red checklist

> If mnem: command not found: Try opening a new terminal first (PATH changes only take effect in new sessions). On Linux, pip installs to ~/.local/bin - if that's not in your PATH, run export PATH="$HOME/.local/bin:$PATH" then add that same line to ~/.bashrc (this is a one-time fix; the file change makes it permanent). On Windows: 1. Run pip show mnem-cli. 2. Copy the Location value (e.g. C:\Users\you\AppData\Roaming\Python\Python312\site-packages). 3. Replace site-packages with Scripts to get the Scripts folder path. 4. Open System Properties → Environment Variables → Path → Edit → New → paste the Scripts path → OK. 5. Open a new Command Prompt - PATH changes require a new window to take effect.

> [!NOTE] > --locked pins exact tested dependency versions. --features bundled-embedder packs the embedder (~40 MB) into the binary so mnem retrieve works immediately - no extra setup. This flag is Cargo-only; pip and npm ship with the embedder pre-baked. Without it (and without configuring another provider in config.toml), mnem retrieve fails with "embedder not configured".

Full install matrix: [docs/src/install.md](docs/src/install.md).

> Embedding mnem inside a Python app? The pip install mnem-cli above ships the CLI binary as a wheel. The native Python API (import pymnem) lives in a separate package. Jump to [Python API (mnem-py) ↓](#python-api-mnem-py) for pip install mnem-py and snippets.

Quickstart

Step 1: Try it now (standalone, no AI assistant needed)

mkdir my-graph
cd my-graph
mnem init          # required once per project - creates the .mnem/ folder that stores your graph
mnem ingest --text "mnem is a versioned knowledge graph for AI agents"
mnem retrieve "what does mnem do"

> mnem init is required once per project before mnem ingest or mnem retrieve - it creates the .mnem/ folder. If something looks wrong, run mnem doctor.

Expected output:

[1] score=0.94  mnem is a versioned knowledge graph for AI agents
    tokens_used=12  candidates_seen=1  dropped=0

Step 2 (optional): Wire your AI assistant

> Prerequisite: This example uses Claude Code. Don't have it? Download free at claude.ai/code. No agent? Skip to "Session 2" - mnem retrieve works standalone.

> Working directory: Open Claude Code from my-graph/ (or a subdirectory) after wiring - launching from a different folder means it won't find this graph.

# Session 1: add a fact and wire the agent
mnem init     # skip if you already ran this in Step 1
mnem ingest --text "The API retry policy uses exponential backoff with a 3-attempt limit"
mnem integrate claude-code    # Cursor: use `mnem integrate cursor`

# Session 2 (next day, new terminal): memory persists
cd my-graph
mnem retrieve "what is our API retry policy"

After mnem integrate, close and reopen the application (not just the terminal). To verify: open any session and send a message - you should see mnem: N item(s) before Claude replies. 0 item(s) means the graph is empty but the integration is working.

> Local vs global graph: .mnem/ in your project directory holds project-specific memory. ~/.mnemglobal/.mnem/ (the global graph, where ~ means your home directory - e.g. C:\Users\you on Windows, /home/you on Linux/macOS) holds facts that span all your projects - personal preferences, shared team conventions, cross-repo entities. Use mnem global retrieve and mnem global add to target it.

Next steps:

• Ingest a file: mnem ingest README.md (or mnem ingest your-docs/ --recursive for a whole directory)
• Wire your AI assistant: mnem integrate (Claude Code, Cursor, and more)
• Ask anything: mnem retrieve "your question"

Five minutes from zero. See [docs/src/quickstart.md](docs/src/quickstart.md) for the full walkthrough.

mnem integrate - wire into any agent host

> Not using Claude Code, Cursor, or another AI coding assistant? Skip this section - mnem integrate is only needed if you want one of those tools to pick up mnem automatically.

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Uranid
• Source: Uranid/mnem
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.