Git-native agent memory: OKF puts context in your repo
OKF Agent Memory stores AI coding agent memory as plain Markdown in your git repo instead of a vendor database. Why that design matters if you're building on a small budget.
Git-native persistent memory for AI coding agents is a design choice, not a feature, and that is the interesting part of OKF Agent Memory, a Go project that landed on Hacker News this week. Instead of shipping another vector database, it writes your project's accumulated knowledge into a knowledge/ directory of plain Markdown files with YAML frontmatter, tracked in git like any other source file.
I want to argue that the storage decision matters more than the tool.
🧠 What the project actually does
The README describes it as "A Domain-Neutral, Git-Native Persistent Project Memory for AI Agents based on the Open Knowledge Format (OKF) v0.2." The premise is one every person using a coding agent has hit: conversations reset when the context window closes, and the architectural reasoning you spent an hour establishing goes with it.
The layout is deliberately boring:
| Piece | What it holds |
|---|---|
knowledge/index.md |
Root index for progressive disclosure |
knowledge/log.md |
Dated changelog in ISO 8601 |
| Concept subdirectories | One Markdown file per concept, YAML frontmatter |
| Frontmatter fields | sources, status, stale_after, and a generated vs verified trust tier |
Agents reach it two ways: a CLI (search, show, create, update, validate) and an MCP server over stdio, which the README says connects to Claude Code, Cursor and Codex. It is written in Go 1.26+ with zero external dependencies and ships as a single binary under the MIT licence.
Key takeaway: if your agent's memory is a folder of Markdown in your repo, it survives the agent. Switch tools, switch vendors, switch machines, and the knowledge is still there in
git log.
💰 Why "no embedding API" is a bigger deal here than in San Francisco
The project claims sub-300µs BM25 search, roughly 4ms to parse and validate 50+ concepts, under 15MB of memory, and zero API cost because nothing leaves your machine. Those are the author's own numbers and I have not benchmarked them, so treat them as claims rather than results.
But the architectural point holds regardless of whether the microseconds are exact. Lexical search costs nothing per query. Embedding search bills you per document, forever.
For a builder in Sri Lanka this is not a rounding error:
- Every re-embed of your knowledge base is a foreign-currency charge on a card that may already be near its limit.
- Free tiers on agent tools are metered in tokens, and re-explaining your project at the start of every session is the single most wasteful thing you can spend them on.
- A local Go binary runs fine on the kind of hardware most of us actually own. No GPU, no hosted index, no monthly floor.
If you want a sense of how much of your quota a context file is eating before you commit it, run the text through our AI token counter. The README claims an 80% reduction in token bloat from progressive disclosure. You can sanity-check the direction of that claim on your own files in about thirty seconds.
🔁 The real product is portability
Line up the options and the trade-off gets obvious:
| Approach | Portable? | Reviewable in a PR? | Ongoing cost |
|---|---|---|---|
| Chat history in the tool | No | No | Free, but lost on reset |
| Vendor memory feature | No | No | Bundled, locked in |
| Vector DB (Pinecone, pgvector, etc.) | Partly | Not really | Per-embed, per-query |
Markdown in knowledge/, git-tracked |
Yes | Yes | Zero |
That third column is the one people undersell. When agent memory is a text file in the repo, a wrong fact becomes a diff. Someone can open a pull request that says "this decision is stale, here's the correction," and you review it the same way you review code. Memory stored inside a vendor's account has no such thing.
The README's search-before-write principle, which requires an agent to query existing memory before authoring anything new, is the other half of it. Without that rule, any write-enabled memory system slowly fills with near-duplicate restatements of the same fact.
⚠️ What I would check before pointing an agent at it
I run an autonomous pipeline on this site and I keep a file-based memory for exactly the reasons above, so I am sympathetic to the design. I would still be careful about three things:
knowledge/is committed. Anything an agent writes there gets pushed. Connection strings, client names, an API key it saw in a stack trace: all of it becomes permanent git history. The repo ships adocs/SECURITY.md, and reading it before enabling writes is not optional.- Trust tiers only work if you enforce them.
generatedversusverifiedis a good idea, but nothing stops an agent from marking its own guess as verified unless you review the diffs. - Staleness is a discipline, not a field.
stale_afterrecords an intent. It does not go and check whether the tax rate you wrote down in March is still correct in September.
The failure mode of persistent memory is not forgetting. It is confidently remembering something that stopped being true.
🛠️ Steal the idea even if you never install it
You do not need the binary to get most of the benefit. Start here:
- Create a
knowledge/(ordocs/decisions/) folder in your project today. - Write one file per fact, not one giant context dump. Small files are what make selective loading possible.
- Put a one-line index at the root so the agent can decide what to load instead of reading everything.
- Record why, not what. The code already shows what. The reasoning is what disappears.
- Date every entry, and delete entries that turn out to be wrong rather than appending corrections.
That is a free afternoon's work, it survives you changing agents, and it works for a two-person team in Colombo as well as it works for a funded startup.
What this means for you
If you are a student or a small-team builder using coding agents on a free or cheap tier, the useful lesson from this project is not "install a Go binary." It is that your agent's memory should be an artefact you own, in a format you can read, in a repo you control.
OKF Agent Memory is one implementation of that idea, MIT-licensed and worth reading if you like Go. The idea itself costs nothing and outlives whichever tool you are using this month. Given how fast the agent tools are turning over, that is the property I would optimise for.