OKF Agent Memory: Git-Native Persistent Memory for Coding Agents, Built in Go
Git-native persistent memory for AI coding agents. Implements Google OKF v0.2 with sub-300µs in-memory BM25 search, embedded MCP server, and progressive disclosure. Slashes token bloat by 80% with zero external databases or dependencies. Built in pure Go.
At a glance
- What is it?
- OKF Agent Memory stores an agent's project knowledge as Markdown files with YAML frontmatter under knowledge/, then exposes them through a Go CLI and an embedded MCP server. The wager is that lexical BM25 over a version-controlled corpus beats a vector database for most coding-agent recall, and the trade-off is that you give up semantic matching to get it.
- Who is it for?
- Adopt OKF Agent Memory if your team already reviews pull requests and you want an agent's accumulated project facts to arrive in those same diffs, and if your recall needs are name-and-term lookups rather than paraphrase matching. Do not adopt it if your questions are conceptual and phrased differently from how the notes were written, or if you need hosted multi-tenant memory shared across machines, because a git-committed directory is a poor fit for both.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is not storage, it is reviewability
An agent's context window closes and the architectural decisions it made with you are gone. The README frames this directly: conversations reset, and decisions, domain discoveries and operational facts are lost unless stored persistently. The usual answers are a CLAUDE.md or AGENTS.md file that grows until nobody reads it, or a vector database that holds embeddings you cannot diff.
OKF Agent Memory targets the second half of that problem. Memory lives in a knowledge/ directory as plain Markdown with YAML frontmatter, so a change to what the agent believes about your system shows up in git diff and git log like any other change. The intended user is a team running coding agents inside a repository that already has a review process. If your agent memory is not something a colleague would ever want to read, the project's main advantage does not apply to you.
A five-layer stack, and only the bottom two are code
The README describes the architecture as five layers. The top layer is the OKF v0.2 specification itself, a normative Markdown and YAML format maintained in Google's knowledge-catalog repository. Below that sits an agent memory convention, which the README characterises as behavioral rules covering search, review and trust. Then an agent skill, meaning LLM prompts and operational workflows. Only then does the Go tooling appear, and below it the actual knowledge corpus.
That ordering is the honest description of the project. The Go binary is a parser, validator, search index and MCP server. It does not decide what to remember. The convention and the skill prompts do, and those are shipped as text you can read and edit rather than as logic compiled into the binary.
The format layer carries the metadata that makes the corpus auditable. Concepts can record provenance through a sources field, a trust tier distinguishing generated from verified content, and lifecycle metadata including status and a stale_after field. That last one is the most interesting: a concept can declare when it should be considered out of date, which turns memory rot from a vague worry into a field a validator can check.
BM25 over an in-memory index, not embeddings
Search is lexical. The CLI parses the bundle, builds an in-memory BM25 index, and scores queries against it. The README claims sub-300 microsecond concept search and roughly 4 milliseconds to parse and validate a corpus of 50 or more concepts with a bidirectional graph. Those figures come from the project's own benchmark table, which compares them against ranges for Python and vector-database runtimes and for Deno and Node tooling. Treat the comparison as the project's framing, not as an independent measurement.
What matters for adoption is the mechanism, not the number. BM25 matches terms. If your note is titled OAuth2 Authorization Flow and you search for PKCE, you get a hit because the term appears in the description. If you search for how do we log users in, you may not, because the words do not overlap. Vector search handles that paraphrase case and BM25 does not. The project's answer is that agents are usually looking up a named thing they just encountered, and that progressive disclosure through hierarchical index.md files and link graphs narrows the search space before scoring even matters.
The zero API cost claim follows from the same choice. There are no embedding calls because there are no embeddings. That is a real operational difference, and it is also the boundary of what this tool can do.
Getting it running: build, bootstrap, connect over stdio
The README's quickstart is short. Clone the repository and run make build, which produces bin/okf. From there the commands are subcommand-shaped around a bundle path.
./bin/okf validate knowledge --strict --drift checks conformance, graph connectivity and description drift. ./bin/okf search "architecture layers" knowledge runs the BM25 query. ./bin/okf show architecture/layers knowledge --json inspects one concept and its relationships. ./bin/okf create decisions/auth-flow knowledge --type Decision --title "OAuth2 Authorization Flow" --desc "Standardized on PKCE for client authentication." writes a new concept and updates log.md and index.md alongside it. ./bin/okf update changes an existing one.
For a new project, ./bin/okf bootstrap /path/to/my-project --name "My Service" scaffolds the whole stack: the knowledge/ bundle with its index.md and log.md, an agent skill under .agents/skills/okf-memory/, an AGENTS.md with project-tailored operating instructions, and a Makefile with validate and search targets. ./bin/okf init my-project/knowledge creates just a bare bundle if you do not want the rest.
The MCP server is a single command, ./bin/okf mcp knowledge, speaking over stdio. The README gives a claude_desktop_config.json example pointing the command at the absolute path of the binary and passing mcp and the bundle path as args. That is the whole integration surface. There is no daemon, no port, no service to keep alive.
Where the lexical index breaks down
The failure mode is vocabulary mismatch, and it is not hypothetical. A corpus written by an agent on Monday and queried by a different agent on Friday will drift in phrasing. BM25 will not bridge that gap, and the drift check in validate is a lint on descriptions, not a semantic rescue.
The second limitation is scale. The benchmark language is explicit about 50 or more concepts. The README does not state where the in-memory approach stops being comfortable, and I cannot confirm a ceiling from the supplied material. A repository with several thousand concepts is untested territory as far as this review can tell, and the honest position is that the project does not publish a figure for it.
The third is the one that disqualifies it for some teams: git-committed memory is per-repository and per-branch. Two engineers on different branches have different memories until they merge. An agent running in CI has whatever the checkout contains. If you want a single shared memory that accumulates across every machine and every project, this design works against you, and no amount of BM25 speed fixes that.
The real alternative is a vector store, and the difference is the retrieval model
Mem0 and Letta appear in the README's own comparison table as the Python and vector-database side. The distinction is not language preference. Those systems embed text and retrieve by similarity, which means a query phrased completely differently from the stored note can still match, and it means retrieval cost scales with embedding calls unless you self-host the model. They also tend to own the storage layer, so the memory is a service you query rather than a directory you commit.
OKF Agent Memory inverts both properties. Retrieval is exact-term and free; storage is a file tree you already have tooling for. You gain diffs, review, and no recurring API line item. You lose paraphrase matching and any notion of a shared remote memory.
A second, quieter alternative is the status quo: a hand-maintained AGENTS.md. That is also plain text in git, and it costs nothing to adopt. The difference the project offers is structure. Frontmatter fields, a link graph, an index hierarchy, and a validator that can flag a concept whose description has drifted from its content. Whether that structure is worth a Go binary depends on whether your AGENTS.md has already outgrown reading in one sitting.
Maintenance cost and what the MIT licence leaves you
The dependency story is the strongest maintenance argument here. The README describes a single binary with zero external dependencies, which means no lockfile to audit and no transitive upgrade treadmill. The trade is that you own the corpus. Concept files accumulate, stale_after fields go unchecked unless validate runs, and index.md files need bookkeeping that the create and update commands handle but do not enforce on hand edits.
There is also a versioning question the material does not settle. The project implements OKF v0.2 and pins that in its badges and links. The README does not describe a migration path if the upstream specification moves, so a team adopting this is implicitly accepting that a future format revision may require rewriting frontmatter. That is a real cost and it is not quantified anywhere in the supplied material.
The licence is MIT, which permits commercial use, modification and redistribution with the copyright notice retained. That is the extent of what can be said here; questions about your organisation's policy on vendoring a memory layer into a proprietary repository belong with your legal team, not with this review. Releases are frequent and recent, with v0.1.3 through v0.1.5 landing within two days of each other in September 2026, which is consistent with an early-stage project still settling its surface area rather than a stable one.
Editorial conclusion
Adopt OKF Agent Memory if your team already reviews pull requests and you want an agent's accumulated project facts to arrive in those same diffs, and if your recall needs are name-and-term lookups rather than paraphrase matching. Do not adopt it if your questions are conceptual and phrased differently from how the notes were written, or if you need hosted multi-tenant memory shared across machines, because a git-committed directory is a poor fit for both. Before committing, run ./bin/okf validate knowledge --strict --drift on a corpus of twenty or so real concepts and read the drift report, then run ./bin/okf search against three or four questions you would actually ask, phrased the way you would actually ask them. If the right concept does not surface in the top few hits, the lexical index is the wrong retrieval model for your notes.
Community notes