local-first, open source, MIT licensed

Your agent's memory is
a folder of markdown files.

Open it in Obsidian. Edit a fact by hand. The agent sees your edit on its next thought, because there's nothing to sync.

why a vault, not a database

The databases are indexes. The vault is the truth.

Every other memory system stores an agent's knowledge as opaque rows you'd need a script to inspect. Mimir writes it as real markdown, with YAML frontmatter and wikilinks between facts and the entities they mention.

You can open it

The vault is a real Obsidian vault. Graph view, backlinks, full-text search, all free, all native.

You can fix it

Agent got something wrong? Edit the note. The fix takes effect on the next read. No re-ingestion, no cache invalidation.

It's yours

Copy the folder to a new machine and your agent remembers everything, everywhere. Git init it if you want history.

agent memory benchmark

Real numbers, not a cherry-picked sample.

51.3% personamem/32k, official AMB leaderboard harness
302/589 answered correctly, no judge involved

This is the number the AMB project's own omb harness produces end to end, not an internal eval script; it's what a real leaderboard submission would show. Full methodology, including an earlier retracted 59.6% and a second internal-only 62.1% figure that measures a different thing, is in the README's Benchmarks section.

setup

No server, no Docker, no API key.

Install and run

# that's the whole install pip install mimir-engine mimir serve --port 8080

GET /health works with zero config: no mimir.yaml, no Redis, no API key required. Grab mimir.yaml.example from the repo when you want to point at a local Ollama model, a cloud LLM, or a Redis instance; every setting has a sane default until then.

Use it from Claude Code (or any MCP client)

claude mcp add mimir --scope user -e MIMIR_USER_ID=you -- mimir mcp

No gateway to run: the embedded adapter imports the engine directly, so a process only exists while your agent session is open. Three tools show up: mimir_recall, mimir_remember, mimir_flush. Running more than one agent session at once? Start mimir serve and point every client at mimir mcp --gateway instead: same tools, same files, no lock contention. OpenCode, Pi, and a plain HTTP contract for anything else are documented in docs/CLIENTS.md.

Working on the engine itself

git clone https://github.com/hasil7677/mimir.git cd mimir/engine pip install -e ".[dev]" uvicorn app.main:app --port 8080

Same server, but picks up local edits. Talks to Claude Code or any MCP client out of the box. Add a local or cloud LLM later and every layer gets sharper automatically: nothing you built against ever has to change.

http api

Every MCP tool is also a plain HTTP endpoint.

No gateway process required for MCP, but if you're building outside Claude Code (a web app, another agent framework, a cron job), the same engine is reachable over HTTP once mimir serve is running.

POST /captureAppend a turn to the current session (best-effort Redis push, durable write to DuckDB).
POST /session/endFlush the session: extract atomic facts, dedupe against what's known, write the vault scene note.
POST /recallHybrid search (BM25 + vector) with the four-signal score, returns a ready-to-inject context string.
GET /vault/notesList every markdown note in the vault.
GET /vault/note/{target}Read one note by slug or wikilink target.
GET /export/{user_id}Full export: every fact, scene, and vault file for a user, GDPR-style.
DELETE /user/{user_id}Full erasure across every store: DuckDB, vault, Qdrant, Redis.
GET /healthLiveness check, works with zero config.

Full request/response shapes and the MCP tool contract: docs/CLIENTS.md. Module-by-module walkthrough of what happens behind each call: docs/ARCHITECTURE.md.