OKF Agent Memory: Git-Native Persistent Memory for AI Coding Agents

The problem OKF Agent Memory addresses

An agent's context window closes and the architecture decisions it made an hour ago are gone. The usual workarounds are a hand-maintained CLAUDE.md or AGENTS.md file, which grows until nobody reads it, or a vector database that holds the same knowledge in a form you cannot review in a pull request. OKF Agent Memory takes a third position: memory lives in the repository as plain Markdown with YAML frontmatter, under a knowledge/ directory, and the tooling that reads it is a single Go binary.

The audience is narrow and specific. It is for teams running coding agents against a repository that already has a review culture, where a change to what the agent believes should be a commit like any other. The README describes the project as domain-neutral and ships examples under examples/books/, examples/coaching/ and examples/software/, but the mechanics (bundles, provenance, trust tiers) assume someone is willing to curate the corpus. A solo developer who wants memory to appear automatically from conversation is not the target reader.

How the OKF v0.2 bundle and the Go tooling fit together

The README lays the project out as five layers, from the normative OKF v0.2 specification down to the project knowledge corpus. The specification defines the file format: Markdown with YAML frontmatter, where each file is a concept and the frontmatter carries provenance (sources), a trust tier (generated versus verified) and lifecycle metadata (status, stale_after). Concepts link to each other, so the bundle is a graph, not a folder of notes.

Above the format sit three layers of convention: an agent memory convention describing behavioural rules the agent should follow, an agent skill holding prompts and workflows, and finally the tooling layer. The tooling is where the determinism lives. pkg/okf parses and validates bundles, and cmd/okf exposes that as a CLI and as an MCP server over stdio. Search is in-memory BM25, so retrieval is lexical rather than semantic: the index matches terms, it does not embed them. That is the design decision everything else follows from. It costs nothing per query and needs no network, and in exchange it will not find a concept that means the same thing in different words.

Progressive disclosure is the mechanism for keeping context small. The README describes hierarchical index.md files and a link graph, so an agent loads an index first and then only the concepts it needs. The repository also carries a log.md, which the create and update commands maintain alongside index.md bookkeeping. Validation checks bundle conformance, graph connectivity and something the README calls description drift, runnable together with one flag.

Installing okf and running a first search

The README's quickstart begins by cloning the repository and building the binary. The Makefile defines the build target, and the README states the result lands at bin/okf.

make build

With the binary in hand, the fastest way to see whether the format suits you is to scaffold a bundle in a scratch directory. The init command takes a path and creates a bare OKF bundle there.

./bin/okf init my-project/knowledge

If you would rather see the whole stack in place, bootstrap scaffolds the full architecture into an existing project: the knowledge/ bundle, a skill definition under .agents/skills/okf-memory/, a project-tailored AGENTS.md and a Makefile with validate and search targets.

./bin/okf bootstrap /path/to/my-project --name "My Service"

Writing a concept uses create, with the concept path, the bundle root and flags for type, title and description. The README's own example creates a Decision concept and states that log.md and index.md bookkeeping are handled automatically.

./bin/okf create decisions/auth-flow knowledge \
  --type Decision \
  --title "OAuth2 Authorization Flow" \
  --desc "Standardized on PKCE for client authentication."

Searching is a single command with a query string and the bundle path. Because the index is in-memory BM25, the query should use the words that actually appear in your concepts.

./bin/okf search "architecture layers" knowledge

To wire the same bundle into an agent platform, run the MCP server over stdio against the knowledge directory and register it in the client's config. The README gives this shape for claude_desktop_config.json or Cursor, with the binary path and the bundle path as arguments.

{
  "mcpServers": {
    "okf-memory": {
      "command": "/path/to/okf-agent-memory/bin/okf",
      "args": ["mcp", "/path/to/project/knowledge"]
    }
  }
}

Where lexical retrieval and Git-native storage stop working

BM25 matches terms. If a concept is titled "OAuth2 Authorization Flow" and an agent asks about "login token exchange", the index has nothing to match unless the same words appear somewhere in the text. Vector search handles that paraphrase case by construction; this project does not, and the README does not claim it does. The practical consequence is that your concept descriptions carry the retrieval burden. A corpus of terse titles will search badly, and no amount of tuning the binary fixes that.

The Git-native model has a second cost that the README does not discuss: memory is only as good as the commits. The search-before-write principle is stated as a mandate in the README, which means it is a convention the agent is asked to follow, not something the tooling enforces. Nothing in the documented command set prevents an agent from writing a duplicate concept, and validate checks graph connectivity and drift rather than semantic duplication. If two concepts describe the same decision, the bundle will pass validation and the agent will retrieve both.

There is also an operational boundary. The README states the toolchain has zero external dependencies and compiles to a single binary, and go.mod pins go 1.22.0. That is a low-maintenance story for a Go shop. For a team that does not build Go binaries, bootstrap and the Makefile targets assume a working Go toolchain, and the README does not document a prebuilt distribution channel beyond the packaging/ directory in the repository listing.

How this differs from Mem0 and Letta

The README's own benchmark table places OKF Agent Memory against Mem0 and Letta, which it groups as Python and vector database runtimes. The difference is not speed, it is where the memory lives and what it costs to read it. Mem0 and Letta keep memory in a service backed by embeddings, so retrieval is semantic and the store is opaque to git. OKF Agent Memory keeps memory as files you can open in an editor, and retrieval is a local lexical index.

That trade is legible in the failure modes. A vector-backed store remembers that "PKCE" and "proof key for code exchange" are related; a BM25 index does not unless you wrote both. In the other direction, a vector-backed store gives you no git diff of what the agent learned this week, and every retrieval is a network roundtrip with an embedding cost. The README states retrieval costs $0.00 per 1,000 queries because the index is local, and that the process cold-start is under 4 ms for a compiled single binary. Those are claims from the project's own benchmark table, not independent measurements, and the README points readers to a benchmark runner in benchmarks/ to reproduce them locally with LM Studio or Ollama.

If your knowledge is genuinely unstructured (long meeting transcripts, support tickets, research notes you never rewrote) a vector store will serve you better. If your knowledge is decisions, interfaces and operational facts that someone is willing to write down in a sentence, the Markdown bundle is the more reviewable artifact.

Maintenance, licensing and what the README leaves open

The repository is not archived, and the last push was on 2026-09-10. Releases v0.1.3, v0.1.4 and v0.1.5 all landed between 2026-09-08 and 2026-09-09, so the version line is moving, but v0.1.x means the format and the CLI flags are not yet frozen. A team adopting this should expect the bundle schema to change under them at least once. The Makefile shows the project dogfoods its own skill files: sync-assets copies .agents/skills/okf-memory/ into pkg/okf/assets/skill/ so the bootstrap assets stay in step with the active skill, and the test target includes what the Makefile calls a dogfood asset drift check.

The licence is MIT, stated in the README badge and in the LICENSE file at the repository root. MIT is permissive: it allows commercial use and modification, and it disclaims warranty. That is the whole of what the repository states; whether the OKF v0.2 specification itself (hosted in a separate GoogleCloudPlatform repository, per the README badge link) carries additional terms is not addressed there.

Upgrade cost is the open question. The README documents validate, search, show, create, update, bootstrap and init, and the MCP server, but it does not document a migration path between bundle schema versions, nor does it say what happens to existing concepts when the format changes. The changelog between v0.1.3 and v0.1.5 is not in the repository. Before adopting, the thing to check is whether validate --strict passes on a corpus you wrote, and whether the drift check flags the concepts you would expect it to.

Editorial conclusion

Adopt OKF Agent Memory if your agents work inside a Git repository and you want memory that shows up in code review, and skip it if you need embedding-based semantic retrieval over free-form notes. Before committing, run ./bin/okf validate knowledge --strict --drift on your own corpus and confirm the drift check reports what you expect, because the README documents the flag but not the exact rule it applies.

Frequently asked questions

Official sources

1. License: MIT
2. okf-memory/okf-agent-memory on GitHub
3. Project website
4. README
5. Releases