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.
Build the wiki as work happens
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.
Raw sources
Hook observations
Wiki
Markdown in git
Schema
AGENTS.md block
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 |
One project
index.md
Decision
Gotcha
Procedure
Obsidian
grep
Another OKF tool
“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 ordinary Markdown tools can read the pages. Their search index can be rebuilt, but sessions, handoffs and accounts require a database backup too.
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 wiki
agentmemory
basic-memory
cognee
Hermes Agent
A-MEM
Hindsight
ai-memory
- 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 3.3.3 release run tested 470 answerable LongMemEval-S questions through real capture and search. Full text reached 0.951 hit@5; local embeddings reached 0.943. These are retrieval scores, not answer accuracy. Local hit@10 is back at 0.977, and the source report tracks the run-to-run movement in local mode.
- Full text only, before 2.00.617
- Stopword-filtered full text0.666
- Plus local embeddings0.815
- 3.3.3: full text, with the observation stream0.951
- 3.3.3: local embeddings, with the observation stream0.943
What each step was
- Dropping stopwords from full-text queries added 4.9 points of hit@5.
- The in-process embedding model added more, with no API key.
- The observation stream, on by default since 3.0, lets a session’s raw observations vote for its page. It took full text from 0.662 to 0.951.
- No API key and no LLM are involved in any row.
| Metric | Before 2.0 | Filtered full text | Local embeddings | 3.3.3, full text | 3.3.3, local embeddings |
|---|---|---|---|---|---|
| hit@5 | 0.617 | 0.666 | 0.815 | 0.951 | 0.943 |
| hit@1 | 0.449 | 0.532 | 0.536 | 0.857 | 0.760 |
Run it yourself
Add --candidate-embeddings local to the second command to run full text and local embeddings side by side. The published runs are dated November 3, 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 the observation stream recovered
A session page keeps only a short excerpt of each turn, so the detail a question asks about often lives only in the session’s observations. With the stream on, each matching session votes once, through its best observation, for its own page. Same 470 questions, same build, stream off and then on.
| Metric | Full text, no LLM | Local embeddings |
|---|---|---|
| hit@5 | 0.662 → 0.951 | 0.796 → 0.936 |
| hit@1 | 0.511 → 0.857 | 0.536 → 0.757 |
| hit@10 | 0.687 → 0.972 | 0.881 → 0.970 |
| recall@5 | 0.533 → 0.893 | 0.657 → 0.871 |
| Query time, 95th percentile | 90 ms → 112 ms | 264 ms → 234 ms |
| Context tokens, top five hits | 256.3 → 266.1 | 225.7 → 264.1 |
- This stream comparison is the October 12 decomposition experiment. The separate 3.3.3 release run measured 0.943 with local embeddings. It is not a rerun of this off/on experiment.
- With the stream on, full text alone scores a little above local embeddings. The page’s vector, like its full-text row, still sees only the title-only body.
- Within one run the harness is deterministic. Across separate runs the smaller question types move by up to 0.03 either way, so a dip in one of them from a single run means little.
- Numbers other tools publish on this dataset come from their own harnesses, often indexing whole raw sessions with no capture step. They are not like for like, and no ranking between tools is claimed.
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. In a contributor’s 102-question set, a documented adapter to a local judge model already matched the hosted reranker at a fraction of the latency.
Defaults backed by numbers
Confidence-based ranking, cold-page compaction, deduplication and the dream pass need explicit settings. Read-based retention already runs by default. Further default changes need measured evidence; typed links still have no extra ranking weight.
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
There is no local reranker yet, and memory aging has no measured result. 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.951 with full text and the observation stream, and 0.943 with local embeddings. 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.