![\"tests\"](\"https://github.com/vornicx/Midas/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"PyPI\"](\"https://img.shields.io/pypi/v/midas-memory\")
\n ![\"npm\"](\"https://img.shields.io/npm/v/midas-memory-mcp?label=npm\")
\n ![\"Python](\"https://img.shields.io/badge/python-3.11%2B-blue\"){kind=icon}
\n ![\"License:](\"https://img.shields.io/badge/license-MIT-green\"){kind=icon}
\nThe local memory layer for long-horizon AI agents — remembers across sessions, keeps what's current, and won't act on stale memory.
No LLM at ingest · $0 per message · fully local · every recall traces to its source.
\n \n
\n Install in your agent\n ·\n See the benchmarks\n ·\n Complete overview\n ·\n Roadmap\n
\n\n---\n\n## Why Midas\n\nMost memory tools call an LLM to summarize every session — so you pay in tokens forever, add latency,\nship every turn to a provider, and get back *rewritten* facts you can't audit. Midas makes the opposite\nbet, and that bet is what makes it cheap, private, and trustworthy:\n\n- **$0 and private by construction.** No LLM at ingest or query → no API spend, nothing leaves your\n machine, fast local ops (~tens of ms, no per-turn network round-trip).\n- **You can trust what it recalls.** Recall returns the **verbatim source turn**, not an LLM rewrite —\n so there's no extraction step that can silently hallucinate a \"fact\" you never said.\n- **It stays current on its own.** Typed belief revision supersedes the old value instead of piling up\n duplicates; selective forgetting keeps it bounded — all with no LLM.\n- **It's safe to build on.** A provenance **guard** lets memory inform planning but **blocks\n memory-justified external or destructive actions** unless you explicitly confirmed them — and a\n *superseded* memory can't authorize an action at all.\n- **One file, many tools.** Point Claude Code, Cursor, and your chat app at one SQLite file and they\n share one live memory.\n- **Proven, not asserted.** Every claim has a reproducible benchmark — *including the experiments that\n failed.*\n\n## How Midas compares\n\nEvery Midas number below is measured and reproducible from this repo; the LLM-at-ingest column\nreflects the structural properties of that design class (Mem0, Zep, Hindsight) and the figures\ndocumented in [BENCHMARKS.md](BENCHMARKS.md).\n\n| | **Midas** | LLM-at-ingest systems (Mem0, Zep, Hindsight) |\n|---|---|---|\n| LLM calls at ingest | **0** | ≥1 per session |\n| Cost per message | **$0** | per-token API spend, forever |\n| Data egress at ingest | **None** | every turn leaves the box |\n| Ingest latency | **~16–116 ms**, local, embed-bound | ~668 ms + API round-trip |\n| Recall returns | **verbatim source turn**, traceable | LLM-rewritten facts (source `recall@k` not computable) |\n| Deterministic & reproducible | **yes — every number, one command** | no |\n| Works fully offline | **yes** (measured end-to-end with a local Ollama reader) | no |\n| LongMemEval-`s` judged answer (gpt-4o) | **0.84** | 0.84 — Observational Memory, with LLM ingest |\n| Whole-conversation aggregation / summarization | ❌ **by design** — top-k retrieval can't cover it ([documented](BENCHMARKS.md)) | ✅ their structural edge |\n\nThe last row is deliberate: Midas trades whole-conversation abilities for $0, privacy, and\nauditability, and publishes the measurements that show exactly where that trade bites.\n\n## More than recall: a memory you can govern\n\nFinding a buried fact is table stakes. A long-horizon coding agent needs memory it can **act on\nsafely** and **resume from cleanly** — which is where similarity search alone falls short:\n\n| You ask… | Midas answers with | Why top-k recall can't |\n|---|---|---|\n| *\"Can I run this destructive migration?\"* | **Guard**: allowed only if **you** confirmed it, and only if that confirmation is still current | provenance + currency aren't a similarity match |\n| *\"What's the current state of project Apollo?\"* | **`memory_state`**: the live, non-superseded decisions / constraints / facts | a broad \"current state\" query matches no single turn |\n| *\"What changed since our last session?\"* | **`memory_diff`**: beliefs added, and beliefs revised (old → new) | \"what's new\" isn't a content query at all |\n| *\"How do I speed up the transactions list?\"* | the **prior fix** resurfaces, so the agent doesn't re-diagnose it | — |\n\nThese properties are measured, not asserted — the **[agent-memory bench suite](docs/agent-memory-benches.md)**\nscores action-safety, decision-adherence, repeated-mistake avoidance, **resume fidelity**, **conflict\ndetection/precision** (live contradictions between agents found without over-flagging), and adversarial\n**memory-safety** across scripted multi-session projects. The safety eval blocks **10 / 10 adversarial attacks** (ASR\n**0.00**) — including a planted confirmation next to a prohibition, a confirmation for a *different* action,\na provenance-laundering supersession, and a cross-namespace approval — with **no over-blocking** (benign-pass\n**1.00**). Deterministic, $0, no LLM. **Reproduce every number with one command:**\n\n```bash\nuv run python -m eval.benches # the whole governance suite — or `midas bench` from a checkout\n```\n\n## How it does on the benchmarks\n\nDeterministic, reader-independent **retrieval** (`recall@k` — fraction of the gold supporting turns\npulled into context) on the **full public sets**, vs a recency-window baseline:\n\n| Benchmark (full set) | baseline | **Midas** |\n|---|---:|---:|\n| **LongMemEval-`s`** — 500 questions, 246,750 turns | 0.01 | **0.92** |\n| **LoCoMo** — 10 conversations, n=1,540 | 0.05 | **0.73** |\n| **BEAM** — frontier benchmark, 100K → **10M tokens** | 0.00 | **0.56 → 0.32** |\n\nAnd the cross-system metric, **judged answer-rate** (same gpt-4o judge the leaderboards use):\n\n| Judged answer | baseline | **Midas** |\n|---|---:|---:|\n| LongMemEval-`s` (gpt-4o reader, ties LLM-ingest SOTA at **$0 ingest**) | — | **0.84** |\n| BEAM-100K (gpt-4o judge, raw-turn floor, $0 ingest) | 0.05 | **0.40** |\n\nAll of it at **0 LLM calls, $0, and 0 data egress** at ingest. Full numbers, per-category breakdowns,\nreproduce commands, and the head-to-head vs Mem0/Zep/Mastra are in **[BENCHMARKS.md](BENCHMARKS.md)**.\n\n> **Eval-first means we publish the misses too.** Hybrid retrieval, reranking, thread-diversification,\n> dual-granularity indexing, and *naive distillation* were all measured to **not** help (or to hurt) and\n> are documented as such. That honesty is the point — see BENCHMARKS.md and\n> [`docs/frontier-2026.md`](docs/frontier-2026.md).\n\n---\n\n## Connect it to your coding agent\n\n**One command wires up everything:**\n\n```bash\nmidas init # creates the shared memory + configures every MCP client it finds\nmidas status # check what's wired · run `midas init --dry-run` to preview first\n```\n\nBoth take **`--json`** to emit a machine-readable *client wiring receipt* — which memory each client got\nwired to, under which scope/policy, and which clients were skipped (config paths only, never memory\ncontents). Paste it into a bug report, or let another agent verify the setup without scraping prose.\n\n`midas init` creates **one shared memory** (`~/.midas/memory.sqlite3`) and points the MCP clients it\ndetects — **Claude Code, Codex, Grok Build, Cursor, Claude Desktop, Windsurf, VS Code, Gemini CLI,\nCline, Zed** — at it. So all your agents read and write the **same** memory, autonomously, with no\nper-client paths to keep in sync.\n\nPrefer a single endpoint over per-client launches? Run one server and give your clients an **MCP URL**:\n\n```bash\nmidas serve --http # → http://127.0.0.1:7077/mcp (one server, one memory, every client shares it)\nmidas serve --http --token\n ![\"Two](\"docs/demo-multi-client.gif\")
\n
Real run, reconstructed chrome — the capture/recall lines are verbatim output of two separate processes sharing one file.
\n\n