Product
Research and rationale
Every part of ai-memory has a reason you can check: an idea it came from, a bug in an earlier tool it avoids, or a number it was measured against. This page walks through them in six short chapters.
Compile, don’t retrieve
In April 2026 Andrej Karpathy published a short “idea file” about what he called an LLM wiki. ai-memory is that idea, adapted for coding agents that never stop producing material.
“The knowledge is compiled once and then kept current, not re-derived on every query.”
Three layers
Raw sources that never change, a wiki of markdown pages that the LLM maintains, and a schema file that tells the agent how the wiki works.
Three operations
Ingest a source and update the pages it touches. Query the wiki. Lint it for contradictions and orphans.
What ai-memory kept
- Markdown files in a git repository as the thing a person can open, diff and read.
- Compiling knowledge when it arrives, with one session fanning out into several pages.
- Wikilinks between pages as the graph.
- Lint for contradictions, stale pages, orphans and duplicate titles.
- A schema block installed into CLAUDE.md or AGENTS.md so the agent knows how to use the wiki.
What it changed
Karpathy’s pattern is curated by a person, one source at a time. A coding agent produces material continuously and nobody is watching.
| In the gist | In ai-memory |
|---|---|
| You hand the LLM one source at a time | Lifecycle hooks capture every session on their own |
| The agent reads index.md first | One fused index: full text, entities, links and vectors |
| An LLM does all the maintenance | Rule-based summaries by default. An LLM is opt-in |
| One person, one wiki | Handoffs between agents, several users, per-project scoping |
| Pages live forever | Tiers, decay, supersession and TTLs keep stale pages out |
Tiers, decay and supersession are not in Karpathy’s gist. They come from agentmemory and the “LLM Wiki v2” writing around it. The full reading notes are in the repository.
Your memory is already in an open format
Open Knowledge Format is a specification Google Cloud published in June 2026. It describes knowledge as a plain directory of markdown files with YAML frontmatter, one concept per file, and a single required field: type. There is no SDK and no runtime.
- Since 2.0 the wiki is natively an OKF v0.2 bundle. The files ai-memory works on are the OKF files, so no export step can drift from the truth.
- One project is one bundle, with a generated
index.mdat its root. - Every page has YAML frontmatter with a
type, derived from the folder it lives in. - Upgrading from 1.x rewrites frontmatter in place after a verified backup. If the backup fails, the migration stops.
ai-memory export-okf --project myproject -o myproject-bundle.tar.gz
There is no import command. Unpack a bundle into a project’s wiki directory and the file watcher indexes it. The OKF mapping is documented field by field, and the specification lives in Google Cloud’s knowledge-catalog repository.
| Folder | OKF type |
|---|---|
sessions/ | Session Summary |
decisions/ | Decision |
gotchas/ | Gotcha |
procedures/ | Procedure |
concepts/ | Concept |
_rules/ | Rule |
notes/ | Note |
runbooks/ | Runbook |
_slots/ | Invariant or State |
“The model and the harness are rented, the project’s memory is yours.”
Eight decisions, and the reason for each
Most of these trace back to a specific issue in an earlier memory tool.
We chose
Markdown in git as the truth
because backing up or moving is a git clone or an rsync. The database can be rebuilt from the files, so corruption is recoverable, and any tool that reads markdown can read your memory.
We chose
One SQLite file
because full text, packed vectors and link tables live in a single embedded file. Other projects’ issue trackers showed what syncing three stores costs in correctness bugs.
We chose
Zero LLM calls by default
because session summaries are rule-based, so a fresh install spends nothing. The lesson came from default-on LLM features elsewhere that surprised users with token bills.
We chose
One binary
because SQLite is bundled, libgit2 is vendored and the embedder is pure Rust. A separate sidecar engine was the largest cluster of user pain in the project this one succeeds.
We chose
No graph database
because the graph is SQL tables: a links table and recursive queries. That covers one-hop expansion and typed edges without an embedded graph engine to keep alive.
We chose
Vectors are optional
because local embeddings are on since 2.0 and still never required. Search is brute-force cosine inside SQLite; a vector extension waits until page counts or latency call for it.
We chose
Handoffs as a typed, claim-once protocol
because every research pass flagged cross-agent transfer as the weak spot of earlier tools. A handoff is a typed record matched by directory, and exactly one session can accept it.
We chose
Pages over fact rows
because a page about a decision can be read, edited and explained in prose. A table of extracted facts cannot be opened in Obsidian or reviewed in a diff.
Standing on shoulders
The project read the code and the issue trackers of the tools that came first, kept the ideas that held up and left out the parts that kept breaking.
- Karpathy LLM Wiki
- Compile, don’t retrieve. The wiki on disk is the artifact.
- agentmemory
- Automatic hook capture, memory tiers, supersession, decay as a formula and fused ranking. ai-memory is its Rust successor: the ideas stayed, the substrate changed.
- basic-memory
- Files as the source of truth with a derived index, and forward links to pages that do not exist yet.
- cognee
- The task-pipeline shape, provenance stamps on every page and feedback that adjusts ranking.
- Hermes Agent
- The design of the self-improvement loop that reviews finished sessions in the background.
- A-MEM
- Zettelkasten-style atomic notes that link to each other automatically.
- Hindsight
- Typed redaction labels, per-page evidence counts and a briefing that leads with settled rules.
- Honcho
- Answers with citations, reasoning levels, and the scheduling of the dream pass: idle trigger, cancel on activity, most novel first.
None of these projects endorse ai-memory. For where each of them is ahead, see the comparison.
What was measured
The retrieval stack is scored on LongMemEval-S: 470 questions about long chat histories, run through the real hook path and the real search. The harness is in the repository.
- Full text only, before 2.00.617
- Stopword-filtered full text0.666
- Plus local embeddings (the default)0.815
What each step was
- Dropping stopwords from full-text queries added 5.1 points of hit@5 and 8.5 of hit@1.
- The in-process embedding model added the rest. Getting masked-mean pooling right was worth about 6.6 points on its own.
- No API key and no LLM are involved in any row.
| Metric | Before 2.0 | Filtered full text | Local embeddings |
|---|---|---|---|
| hit@1 | 0.449 | 0.532 | 0.536 |
| hit@5 | 0.617 | 0.666 | 0.815 |
| recall@5 | 0.472 | 0.536 | 0.677 |
Run it yourself
Add --candidate-embeddings local to the second command to run full text and local embeddings side by side. The published run is dated September 21, 2026, on a Ryzen 9 7950X3D.
cargo build --release -p ai-memory-cli
cargo run --release -p ai-memory-eval -- retrieval --fetch
Full results, per question type
Write throughput was measured too. The numbers are on the architecture page.
What local embeddings buy, and what they cost
The same 470 questions, run twice: with full text only, then with the default local embedding model. Embeddings find the evidence far more often in the top ten, and add about 90 ms to a query.
| Metric | Full text, no LLM | Local embeddings | Change |
|---|---|---|---|
| hit@1 | 0.532 | 0.536 | +0.004 |
| hit@5 | 0.666 | 0.815 | +0.149 |
| hit@10 | 0.694 | 0.891 | +0.198 |
| recall@10 | 0.564 | 0.817 | +0.254 |
| Query time, median | 5 ms | 94 ms | +89 ms |
| Query time, 95th percentile | 40 ms | 162 ms | +122 ms |
| Context tokens per query, mean | 350.3 | 415.7 | +65.4 |
- Two full runs on the same commit scored 0.815 and 0.821, so read hit@5 as about 0.82, give or take 0.005. The earlier run, from September 1, 2026, scored 0.823, which is the same result. Memory aging is off by default, so default search did not change.
- Within one run the harness is deterministic: running one configuration twice gives identical accuracy and token counts. Across separate runs, the smaller question types move by up to 0.03 in either direction, so a dip in one of them from a single run means little.
What is next, and where it is behind
These are documented recommendations in the repository. None of them has a date.
Recommended next
Answer accuracy at full scale
The second harness has a full retrieval run, with accuracy, query time and context tokens. Its answer-accuracy mode has only a 20-question sample so far, and the items below wait on it.
A local reranker
A cross-encoder that runs in process with no LLM. It waits on the harness above to prove its worth.
Defaults backed by numbers
The confidence score and the aging features ship switched off. Each one becomes a default only after the harness shows it helps. Link types still carry no ranking weight.
A bounded sync command
Either a plainer description of the one-server model or an ai-memory sync built on the git wiki.
An easier start for Claude Code users
An importer for people coming from Claude’s built-in memory.
Not planned: a graph database, a self-editing memory OS, cloud connectors, or growing the tool count for its own sake.
Behind today
Raw retrieval scores sit below the tools that rerank, and memory aging has no measured result yet. The full list is on the comparison page.
“1.x proved the idea worked. 2.0 is the version I’d recommend without an asterisk for someone else to put on a team.”
Questions and answers
What is the Karpathy LLM Wiki idea behind ai-memory?
Andrej Karpathy’s April 2026 gist describes an LLM that builds and maintains a persistent wiki of markdown files between you and your raw sources, so knowledge is compiled once and kept current. ai-memory applies that to coding agents, with automatic capture from lifecycle hooks and a default path that makes no LLM calls.
Is ai-memory compatible with the Open Knowledge Format?
Since 2.0 every project in the wiki is natively an OKF v0.2 bundle. Each page has YAML frontmatter with a type, each project has a generated index.md, and ai-memory export-okf packages a project into a validated tarball.
What does the LongMemEval-S benchmark measure for ai-memory?
Retrieval only: whether a session holding the evidence appears in the top results, over 470 questions. hit@5 is 0.815 with the default local embeddings and 0.666 with full text only. It does not measure answer accuracy.
Read the reasoning. Then try it.
Free and open source. The default install makes no LLM calls and listens on your machine only.