OKF Agent Memory Puts Your Agent's Memory in Git. The Cost Is Buried in the Word BM25
A two-day-old Go project makes agent memory something you can review in a pull request. The benchmark table it leads with measures the wrong thing.
A repository called okf-agent-memory appeared on the GitHub trending board this week claiming that your agent's memory should live in your repo as markdown files you can read, diff, and review, with no database anywhere. It shipped v0.1.0 and v0.1.1 on the same day, September 6, 2026. It has 315 stars as I write this, which will be wrong by the time you read it.
The pitch is good enough that I want to be careful about it. Because the README leads with a performance table comparing itself against Mem0 and Letta on search latency, and latency is not the axis where this decision gets made. The interesting number in that table is 300 microseconds. The interesting word is the one right after it.
What it actually does
okf-agent-memory is a single Go binary with zero external dependencies that manages a directory called knowledge/ in your repo. Inside that directory are plain markdown files with YAML frontmatter, organized hierarchically, each one describing a single concept: an architectural decision, a domain fact, an operational rule.
It implements the Open Knowledge Format v0.2, which is a real published specification living at GoogleCloudPlatform/knowledge-catalog. The README calls it "Google OKF v0.2," and the project's own comparison doc says "Google Cloud published OKF v0.2 as an open specification," which is accurate as long as you read "open specification" the way the spec itself does. Section one of SPEC.md is unusually blunt about its own authority: "There is no schema registry, no central authority, and no required tooling. If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it." This is a format, not a standard anybody enforces.
The commands are the shape you would guess:
make build # produces bin/okf
./bin/okf bootstrap /path/to/project --name "My Service"
./bin/okf search "architecture layers" knowledge
./bin/okf validate knowledge --strict --drift
./bin/okf mcp knowledge # MCP server over stdio
bootstrap is the one that will make or break adoption, because it scaffolds the whole thing into an existing repo in one command: a conformant knowledge/ bundle, a .agents/skills/okf-memory/ skill definition, a project-tailored AGENTS.md, and a Makefile with validation and search targets. And okf mcp runs an MCP server over stdio, so Claude Code, Cursor, or Codex can query the bundle as a tool rather than having the whole thing dumped into context.
That last part is the design's actual spine, and the README names it: progressive disclosure. Instead of loading a 4,000-line CLAUDE.md every turn, the agent reads an index.md, sees what concepts exist with one-line descriptions, and opens only the two it needs.
The part of the spec that is genuinely good
I went and read OKF v0.2 rather than trusting the summary, and two things in it are better than they need to be.
The first is the separation of generated from verified. A concept records who wrote it (generated: { by: reference_agent/gemini-2.5-pro, at: ... }) and separately records who confirmed it, as a list, because a human sign-off and a nightly process check are different events. Consumers derive a trust tier from that: no verified key means unverified, verified by non-human actors means machine-confirmed, verified by a human:<id> actor means human-reviewed. The spec is explicit that these are "advisory signals, not access control," which is the honest framing.
The second is stale_after, and the reasoning behind it is worth stealing regardless of whether you use this tool. It is an absolute instant, not a relative TTL. The spec says why: an absolute instant "keeps the staleness decision a plain comparison with no reference to when the concept was read." Every cache-expiry bug I have ever debugged came from somebody storing a duration and having to reconstruct the clock. This is the right call and it is one line of frontmatter.
There is also a whole concept type in v0.2 called Attested Computation, which lets a knowledge bundle carry a sanctioned way to compute a number plus a deterministic non-LLM attester that checks a run receipt against it. It is the most ambitious idea in the spec, aimed squarely at agents that improvise SQL and then report the result as fact. As far as I can tell from the repo structure, okf-agent-memory does not exercise it. The example bundles are software architecture, coaching, and literature. That is a gap, not a flaw, but if attestation is what drew you here, check before you commit.
Now the tradeoff nobody wrote down
The README's headline benchmark table compares okf-agent-memory against "Python / Vector DB Runtimes (Mem0, Letta)" on Concept Search Latency: 150ms to 800ms for them, under 300 microseconds for okf. It compares cold-start overhead, memory footprint, and retrieval cost per thousand queries. Every row favors okf, and every row is measuring speed or cost.
None of them is measuring whether you find the right document.
The search is BM25. BM25 is lexical: it ranks documents by term frequency against your query terms, weighted by how rare those terms are. It is fast, deterministic, explainable, and it has been the workhorse of information retrieval since the nineties for good reason. It is also the reason vector databases exist.
Concretely: if your agent stored a decision under the title "Standardized on PKCE for client authentication" and later asks its memory "how do we handle login," BM25 has nothing to match on. Not one query term appears in that document. A vector store retrieves it because "login" and "client authentication" sit near each other in embedding space. BM25 returns nothing and your agent proceeds as though the decision was never made.
The comparison doc does gesture at this. It has a row called Context Navigation reading "Approximate vector similarity" for the managed frameworks against "Progressive Disclosure" for okf. But that framing treats vector similarity as the weakness, and it is not. Approximate is the feature. The whole point of an embedding is that it retrieves things you did not know how to name.
What okf substitutes is structure doing the work embeddings used to do: hierarchical indices, cross-links between concepts, and a stated convention that agents must search before they write so concepts do not duplicate. That can work. It is roughly how a well-maintained wiki works, and the project cites Karpathy's "LLM-maintained wiki" framing as its lineage. But it only works if the corpus is genuinely well-organized, which means it depends on the agent being disciplined about naming and linking over hundreds of writes, unsupervised, forever. That is a much bigger assumption than "BM25 is fast."
The second unpriced cost is the trust model. generated versus verified is only meaningful if somebody verifies. A knowledge/ directory containing four hundred concepts, every one of them generated by an agent and none of them carrying a verified entry, has precisely the epistemic status of an unreviewed scratchpad. It just looks rigorous now, with frontmatter and trust tiers and a validator that passes. Structure that implies review without producing review is worse than no structure, because it buys unearned confidence.
Putting this into practice
If you want to try it, the lowest-friction path is an afternoon, and I would do it in this order.
Start on one project, not your main one. Run okf bootstrap against a repo you already understand well. The scaffolding is additive and lives in knowledge/, so backing out is rm -rf plus a git checkout.
Seed it by hand with ten concepts, not two hundred by agent. Write the ten decisions you find yourself re-explaining to an agent every week. Architecture choices, deployment gotchas, the reason that one module is weird. Mark them verified: { by: human:yourname, at: ... }, because that is what the field is for and it establishes the baseline the agent's later writes get compared against.
Wire the MCP server before you let the agent write. Point Claude Code or Cursor at okf mcp /path/to/project/knowledge and spend a session in read-only mode. Watch what it retrieves and, more importantly, what it fails to retrieve. That is your BM25 recall test, run on your actual vocabulary, and it takes twenty minutes.
Adopt one naming convention and enforce it in review. Because retrieval is lexical, the title and description fields are your index. If your team writes "auth" in some concepts and "authentication" in others, you have two disconnected halves of your memory. Pick one, put it in AGENTS.md, and treat a violation as a review comment like any other.
Then let the agent write, and read the diffs. This is the whole benefit. git log knowledge/ is a record of what your agent came to believe and when. Read it weekly for a month. If you find yourself skipping it, you have learned something important about whether reviewable memory is actually a benefit for your team or just a nice property on a README.
Honest limitations
The project is two days old. v0.1.0 and v0.1.1 both released on September 6, 2026, MIT licensed, and the version number is telling you the truth about maturity. Anything at 315 stars and three commits has not met a hostile corpus yet.
Every performance number in the README is self-run. The comparison against Mem0 and Letta gives ranges (150ms to 800ms) without specifying which configurations, which embedding models, which hardware, or which corpus size produced them. The repo does ship a benchmarks/ directory and a make benchmark target for reproducing the token-reduction claims locally, which is more than most projects offer, and I have not run it. Treat the table as a vendor's claim about a competitor, because that is what it is.
The "-80% token reduction" figure and the sub-300µs search both come from the same self-benchmarking setup. The token reduction claim is the more plausible of the two, because progressive disclosure genuinely does avoid loading a monolithic file, and it is also the one whose baseline matters most: reduction compared to what, a 4,000-line CLAUDE.md or a well-pruned one?
And the honest framing of the whole category: nobody has solved agent memory. Mem0 and Letta have real weaknesses this project names correctly, and this project has a real weakness they do not have. The choice is between opaque recall that finds things you cannot name, and transparent recall that only finds things you can.
What to do with this
Pick based on what breaks you.
If your problem is that your agent forgets, and forgetting costs you re-explanation, a vector store is still the more forgiving tool. It will find the thing when you describe it wrong, and you will describe it wrong often.
If your problem is that your agent remembers things that are no longer true, and you have no way to find out which ones, then this design is aimed directly at you. Memory in git means memory in code review, and stale_after means a concept can announce its own expiry rather than sitting there being confidently wrong.
That second problem is the one I hear about more, and it is the one nobody has been able to fix by adding more retrieval. You cannot review a vector. You can review a markdown file, and this project's actual contribution is making that a default rather than a discipline.
Just go in knowing you are trading recall for legibility. That is a defensible trade. It is a worse one to make by accident because a benchmark table only showed you microseconds.
Sources: okf-memory/okf-agent-memory (MIT, v0.1.1 released 2026-09-06) · Open Knowledge Format v0.2 specification · Alternatives & Ecosystem Comparison. Star count read via cache-busted shields.io on September 6, 2026.
Medium metadata
- Title: OKF Agent Memory Puts Your Agent's Memory in Git. The Cost Is Buried in the Word BM25
- Subtitle: A two-day-old Go project makes agent memory something you can review in a pull request. The benchmark table it leads with measures the wrong thing.
- Tags: AI Agents, Developer Tools, Golang, MCP, Software Engineering
- Suggested publication: Tkay Nation's Writes
- Canonical: import from the fervorai.dev URL