the short version
- OKF Agent Memory replaces an embedding API call with local lexical BM25, cutting retrieval cost from $0.10-$0.50 per 1,000 queries to $0.00 and search latency from 150ms-800ms to under 300µs.
- The repo publishes latency, memory footprint and an 80% token-reduction claim, but no recall or precision numbers, which is what two commenters on Hacker News asked for.
- okf create is documented as doing automated log.md and index.md bookkeeping; the sources say nothing about how those two shared files merge across concurrent branches.
- The unanswered adoption question is harness adherence: whether Claude Code or Codex will use a third-party MCP memory server over their built-in memory tooling.
OKF Agent Memory, published on GitHub on 5 September 2026, keeps agent context as version-controlled Markdown with YAML frontmatter in a knowledge/ directory, read and written by a single zero-dependency Go binary. On the operational axes the README publishes, it beats an embedding-plus-vector-DB stack outright: under 300µs for a concept search instead of 150ms-800ms, $0.00 per 1,000 retrievals instead of $0.10-$0.50, and under 15MB resident instead of 120MB-350MB. Against a CLAUDE.md monolith it claims an 80% cut in token bloat from progressive disclosure, with a Go benchmark runner you can rerun locally. Neither recall nor precision is reported anywhere in the sources, and neither is any merge or multi-author behaviour for the shared index.md and log.md files that every new concept updates.
The project positions itself between two things engineers already run. On one side, ad-hoc flat files: CLAUDE.md, AGENTS.md and .cursorrules, which the authors write on Hacker News balloon into 20k-token monoliths and cause lost-in-the-middle attention failure. On the other, vector databases and background daemons such as Mem0, Letta and Zep, which bring Python or Node runtimes, containers, proprietary storage and recurring embedding API costs. The repo is MIT-licensed, sits at 287 stars and 13 forks, and shows 3 commits; the Releases and Packages sections of the page are empty, and the version number v0.1.0 appears only in the authors' Hacker News post.
What git-native persistent memory stores
The implementation is five layers: the Open Knowledge Format v0.2 specification, an Agent Memory Convention that defines behavioural rules, an agent skill carrying the prompts and workflows, a Go library and CLI, and the project's own knowledge/ corpus. OKF v0.2 carries provenance via sources, trust tiers that distinguish generated from verified, and lifecycle metadata including status and stale_after. That trust-tier split answers a complaint raised on Hacker News, where one commenter described AI-generated documentation being given equal weight to what a human actually approved and committed. The convention also mandates a search-before-write step, querying existing memory before authoring a concept, to stop duplicate and divergent entries accumulating.
The corpus itself is plain files: index.md as the root progressive disclosure index, log.md as a dated change log in ISO 8601, and concept directories underneath. Creation is a CLI call with typed metadata, for example okf create decisions/auth-flow knowledge --type Decision --title "OAuth2 Authorization Flow". The repository ships three domain-neutral example bundles under examples/ for software architecture and ADRs, executive coaching, and literature and cognitive science, and uses its own knowledge/ directory as a self-documenting bundle validated by make check. Distribution is a Homebrew formula under packaging/homebrew and a compiled binary at bin/okf with a sub-5ms CLI startup time.
# scaffold knowledge/, .agents/skills/okf-memory/, AGENTS.md and a Makefile
./bin/okf bootstrap /path/to/my-project --name "My Service"
# validate bundle conformance, graph connectivity and description drift
./bin/okf validate knowledge --strict --drift
# in-memory BM25 scoring over the corpus
./bin/okf search "architecture layers" knowledge
# serve the same corpus to Claude Code, Cursor or Codex over stdio
./bin/okf mcp knowledgeWhere the 80% token reduction comes from
The mechanism is progressive disclosure: hierarchical index.md files and a link graph, so the agent loads only the concepts it needs instead of the whole corpus on every turn. That is the structural difference from a 20k-token CLAUDE.md, which enters the context window whole regardless of the task. The repo ships a benchmarks/ directory with monolith-document versus OKF-bundle fixtures and reproducible logs across 8 or more local and cloud LLMs, plus a Go benchmark runner invoked with make benchmark that measures Time-To-First-Token and the claimed 80% token reduction on local hardware through LM Studio or Ollama with Gemma, Qwen or Llama. The figure is therefore reproducible in principle, but it measures how many tokens you send, not whether the right ones arrived.
Does it beat a vector store on cost
The README's comparison table is against Python and vector-DB runtimes named as Mem0 and Letta, and against Deno or Node.js tooling. The entry that matters for anyone building on this is not the microseconds; it is the removal of a network roundtrip and an embedding API call from a high-frequency tool-calling loop, and a memory footprint small enough to leave resident next to the agent. A separate docs/ALTERNATIVES.md compares the project against Mem0, Letta and ad-hoc markdown, but its contents are not in the sources.
- Concept search latency: 150ms-800ms for embedding API plus vector DB, 40ms-120ms for Deno or Node tooling, under 300µs for in-memory BM25.
- Full corpus parse and graph validation: 200ms-1.5s for Python, 80ms-250ms for Node, roughly 4.0ms for 50+ concepts with a bidirectional graph.
- Process cold start: 250ms-600ms for a Python VM boot, 80ms-180ms for V8 or Deno, under 4ms for the compiled single binary.
- Retrieval cost per 1,000 queries: $0.10-$0.50 in embedding tokens, $0.00 for Deno or Node tooling, $0.00 for OKF, fully local.
- Resident memory: roughly 120MB-350MB for Python stacks, 60MB-140MB for Node, under 15MB for OKF.
What Hacker News is pushing back on
Two separate commenters made the same objection: the benchmarks measure latency, not capture and retrieval quality. One asked why the project benchmarks latency instead of recall and precision, arguing that optimizing for millisecond-level latency is meaningless in the context of LLM calls when accuracy is the tool's greatest value and there is no testing for it. The sources contain no answer. BM25 is lexical scoring, and nothing in the README reports how often a query returns the concept the agent needed.
this tool is not a ton different than just having the md files locally and having it use ripgrep to search over them
The same commenter, who otherwise praised the design, said adoption would be an uphill battle in their enterprise because the utility is so niche. Others raised harness adherence: whether a model inside Codex or Claude Code, whose vendors can tune the model against their own memory format and tool calling, will reliably reach for a third-party MCP server. One commenter reported mixed results getting LLMs to consistently use third-party tools. Another asked for cross-project memory, which the knowledge/ layout does not provide, and one asked for a benchmark against OpenAI's Symphony on token usage and task completion, which does not exist in the sources.
One commenter rejected the premise, arguing that AI memory wastes context in the same way skills do and that the most efficient workflow is a few well-written md files, not written by AI, across a clean codebase. That is the baseline OKF has to beat, and no benchmark in the sources measures it: the published fixtures compare a monolith document against an OKF bundle, not a small hand-curated file set against either.
What in-repo memory costs in merge conflicts
The headline benefit of keeping memory in-tree is reviewability. The README states that everything is version-controlled plain text and that you inspect, audit and review the agent's memory with standard git diff and git log. That is a real difference from a black-box vector store: a bad memory write shows up in a pull request rather than silently steering the next twenty sessions. It also follows from ordinary git semantics that memory is branch-scoped, so a concept written on a feature branch travels with that branch.
The cost side is not documented anywhere in the sources. Concepts are individual files, so two agents editing different concepts should not collide, but okf create is described as doing automated log.md and index.md bookkeeping, which puts two shared files in the path of every new concept; the README does not say whether okf update touches them. Nothing in the sources covers concurrent branches, conflict resolution or any multi-author workflow, and with 3 commits in the repository there is no track record to inspect. The validator is a partial backstop: okf validate knowledge --strict --drift checks bundle conformance, graph connectivity and description drift, and bootstrap installs a Makefile with make validate, so a merge that breaks the link graph should surface there. Teams should read docs/SECURITY.md before bootstrapping, since its data governance, secret prevention and PII rules matter more when memory ships in every clone.
Three things should decide adoption
The decision this changes is narrow. If you are paying embedding costs and a 150ms-800ms retrieval hop for project memory that only ever needs lexical lookup over your own decisions, a sub-15MB Go binary and a knowledge/ directory removes that dependency, under an MIT licence, at what the authors call v0.1.0. First, retrieval quality benchmarks, which the project does not publish and which two commenters asked for directly. Second, adherence data inside real harnesses, since the MCP server for Claude Code, Cursor and Codex is only useful if the model calls it. Third, whether the merge behaviour of index.md and log.md holds up with more than one agent writing at once, since nothing in the sources tests it; one commenter also asked whether Astra's move away from compaction removes the need for this class of tool entirely, and the sources do not answer that either.
Questions this raises
does OKF Agent Memory measure recall or precision?
No. Neither recall nor precision is reported anywhere in the sources, and two separate Hacker News commenters raised this as the central objection. The published benchmarks measure latency, token counts and Time-To-First-Token, not whether a BM25 query returns the concept the agent actually needed.
how is this different from markdown files plus ripgrep?
A Hacker News commenter made exactly that point, saying the tool is not much different from keeping local md files and searching them with ripgrep. The differences OKF adds are typed metadata, trust tiers separating generated from verified content, a bidirectional link graph and a mandated search-before-write step, but no benchmark in the sources compares it against a small hand-curated file set.
what happens when two agents write to the same memory files?
Nothing about merges or multi-author behaviour is documented. Every new concept updates the shared index.md and log.md files, which are the natural conflict points, and the sources say only that everything is version-controlled plain text you can review with git diff and git log.
These daily notes are drafted by a model I run and operate myself - the same kind of pipeline this site is about - from sources published in the previous 24 hours, and every one lists what it read. The longer essays, the talks and the preprint are mine, written by hand.