Legacy bash harness (canonical path for headline numbers)

<div align="center">

<img src="assets/logo/mnem-banner.svg" alt="mnem: Git for Knowledge Graphs" />

[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/Uranid/mnem/ci.yml?style=for-the-badge&label=CI)](https://github.com/Uranid/mnem/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/mnem-cli?style=for-the-badge)](https://crates.io/crates/mnem-cli)
[![PyPI](https://img.shields.io/pypi/v/mnem-cli?style=for-the-badge)](https://pypi.org/project/mnem-cli/)
[![npm](https://img.shields.io/npm/v/mnem-cli?style=for-the-badge)](https://www.npmjs.com/package/mnem-cli)
[![MSRV 1.95](https://img.shields.io/badge/MSRV-1.95-orange?style=for-the-badge)](rust-toolchain.toml)
[![Runs on Linux macOS Windows WASM](https://img.shields.io/badge/runs%20on-linux%20%7C%20macos%20%7C%20windows%20%7C%20wasm-2ea44f?style=for-the-badge)](#install)

</div>

<hr>

<div align="center">

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

</div>

<hr>

1. [The problem](#the-problem)
2. [Benchmarks](#benchmarks)
3. [Install](#install)
4. [Quickstart](#quickstart)
5. [Integrate](#mnem-integrate---wire-into-any-agent-host)
6. [What it is](#what-it-is)
7. [Commands](#commands)
8. [Python API](#python-api-mnem-py)
9. [GraphRAG](#graphrag)
10. [vs others](#compared-to-others)
11. [Docs](#documentation)
12. [Contributing](#contributing)

<hr>

## The problem

> **A transcript is not a memory.**

You already have a mental model for this: git. Commits with history you can diff and revert, branches you can merge, a log of every decision and why. Your agent's memory gives you none of that. It's a transcript pasted back into the prompt, or a search index you can't inspect or edit. Conventions live in flat `.cursorrules` files - useful, but not queryable or versionable. And sessions are isolated: plan a migration with Claude Code today, open Cursor tomorrow, and that agent has never heard of it.

mnem brings the git model to agent knowledge. Every write is a **content-addressed commit** - same bytes, same CID, any machine. Skills, decisions, and notes live in a **versioned, branchable, mergeable graph**: `diff` what changed between sessions, `revert` a bad batch of facts, `merge` knowledge from two agents the same way you'd merge a branch.

Retrieval is **hybrid and transparent**: vector + keyword + graph traversal in one pass, with an explicit token budget - mnem reports exactly what it found, what it skipped, and how many tokens were used. **Swap the embedder, reranker, or LLM with one config line.** One `mnem integrate` wires it into Claude Code, Cursor, Codex, Gemini CLI, or any MCP host. Single ~40 MB binary. No daemon, no cloud, no API keys.

> Close the laptop. Open it tomorrow. Your agent remembers.

<hr>

## Benchmarks

**Measured head-to-head against mem0 and MemPalace on six public datasets. mnem leads on all of them.**

ONNX MiniLM-L6-v2 embedder, same bytes on every system. No LLM rerank. Reproduce: `bash benchmarks/harness/run_bench.sh`.

| Benchmark | mem0 | MemPalace | **mnem** |
|-----------|-----:|----------:|---------:|
| LongMemEval 500 Q: R@5 | 0.946 | 0.966 | **0.966** |
| LongMemEval 500 Q: R@10 | 0.962 | 0.982 | **0.982** |
| LoCoMo 1986 Q: R@5 | 0.466 | 0.508 | **0.726** |
| LoCoMo 1986 Q: R@10 | 0.676 | 0.603 | **0.855** |
| ConvoMem 250 conv.: avg recall | 0.558 | 0.929 | **0.976** |
| MemBench simple/roles 100: R@5 | 0.410 | 0.840 | **0.960** |
| MemBench highlevel/movie 100: R@5 | 0.970 | 0.950 | **1.000** |
| FinanceBench 150 Q: hit@5† | 0.033 | 0.767 | **0.973** |

<sup>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. Full methodology: [`benchmarks/results/analysis/financebench.md`](benchmarks/results/analysis/financebench.md).</sup>

### Query speed

| Benchmark | mean retrieve |
|-----------|-------------:|
| LongMemEval 500 Q | 711 ms |
| LoCoMo 1986 Q | 333 ms |
| ConvoMem 250 conv. | 398 ms |
| MemBench simple/roles 100 | 1874 ms (e2e) |
| MemBench highlevel/movie 100 | 491 ms (e2e) |
| FinanceBench 150 Q | 2087 ms (global) |

<sup>(e2e) = end-to-end mean when the adapter doesn't expose phase timing. (global) = corpus-wide scan with no per-session label scope.</sup>

<details>
<summary><b>Reproduce</b></summary>

```bash
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   # r

... (truncated)