OKF Agent Memory

A memory layer for AI coding agents that keeps what they learn as plain Markdown in the repository, not in a database. Knowledge lives in an OKF v0.2 bundle — a knowledge/ directory of concept files with YAML frontmatter, index.md files and a log.md — read back by an in-process BM25 search rather than by embeddings. It is for people running coding agents over a repository (the README names Claude Code, Cursor and Codex) and for anyone who wants an agent’s decisions reviewable with git diff. Install by cloning and running make build, which produces the standalone binary at bin/okf; ./bin/okf validate knowledge --strict --drift then checks a bundle, ./bin/okf search "architecture layers" knowledge queries it, and ./bin/okf bootstrap /path/to/my-project --name "My Service" scaffolds the whole stack into another repository. The MCP server runs over stdio as ./bin/okf mcp knowledge (registered in claude_desktop_config.json or Cursor), make check runs the tests, and ./bin/okf hub init-vault, hub push and hub sync handle optional encrypted sync.

Who built itAn organisation account rather than a person: the repository is okf-memory/okf-agent-memory, and the metadata contains no owner profile. The work is one-sided — 144 of the 167 commits carry the sknr account (142 authored as sknr and 2 as Stephan Knauer), 12 come from google-labs-jules[bot], 5 from denis-samatov, 3 from dependabot[bot], 2 from yakimoto and 1 from dajiaohuang, and those accounts are exactly the six names on the contributor list. The sponsorship links point at github.com/sponsors/sknr in the funding file and in the README badge, which is the only maintainer identity the materials show.

1. 01

   A memory layer that says it implements Google OKF v0.2

   The repository describes itself in its own metadata as "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." The README opens on "A Domain-Neutral, Git-Native Persistent Project Memory for AI Agents based on the Open Knowledge Format (OKF) v0.2", and its first badge links those words to GoogleCloudPlatform/knowledge-catalog at okf/SPEC.md. The project’s own knowledge bundle repeats the same reference: knowledge/project/overview.md (2,485 characters) lists a source titled "Open Knowledge Format (OKF) v0.2 Specification" at that path. All of this is the project describing itself; the materials contain no statement from Google or from anyone else confirming the implementation. The one place the repository treats compliance as something to be argued rather than asserted is its own document docs/spec/OKF-COMPATIBILITY.md (6,241 bytes), which the README lists as the "OKF v0.2 Compatibility Matrix — Specification validation analysis". A closed issue shows that document doing real work: a reporter quotes it on a link form the specification allows but the validator rejected, and the maintainer closed the report as fixed in v0.4.4 via commit 9146138.

2. 02

   The performance numbers are the author’s, and one of them is his own doubt

   The speed figures here are self-reported. The README’s benchmark table sets "Concept Search Latency ... < 300 µs (Microseconds, In-Memory BM25)" against "150ms – 800ms" for "Python / Vector DB Runtimes (Mem0, Letta)", and gives "~4.0 ms" for a full corpus parse and graph validation, "< 4 ms" for cold start, "$0.00" per 1,000 queries and "< 15 MB" of resident memory. The metadata summary repeats the search number as "sub-300µs in-memory BM25 search" and states token savings as "80%", while the README’s own highlight says Agent Action Grammar saves "~78–85% tokens compared to natural language prompt instructions". No hardware, corpus size or procedure appears in the table; it points at make benchmark and a "Progressive Disclosure Benchmark Suite", and the repository does ship docs/guides/BENCHMARKING_METHODOLOGY.md (7,133 bytes), benchmarks/README.md (3,862 bytes), a 668-byte pkg/okf/search_benchmark_test.go and seven result files naming the models used. None was printed in the materials, so the method behind the sub-300µs figure could not be checked here. The maintainer’s own open issue 42 argues the same BM25 implementation has "three structural weaknesses in document frequency and term frequency calculation" — acronyms matching inside longer words and collapsing IDF, and prefixes matching short stems so that log matches login and auth matches author.

3. 03

   Fifteen releases in the first twenty-three days

   The metadata records the repository as created on 2026-09-05, and fifteen releases exist between that day and 2026-09-27: v0.1.0 on 2026-09-05, v0.1.1 on 2026-09-06, v0.1.2 on 2026-09-07, v0.1.3 and v0.1.4 on 2026-09-08, v0.1.5 on 2026-09-09, v0.2.0 on 2026-09-12, v0.3.0 on 2026-09-15, v0.3.1 on 2026-09-16, v0.4.0-rc.1 and v0.4.0 on 2026-09-17, v0.4.1 on 2026-09-18, v0.4.2 on 2026-09-19, v0.4.3 on 2026-09-23 and v0.4.4 on 2026-09-27. Twelve of them landed inside the first fourteen days and the last three spread across the following nine. All fifteen are marked neither prerelease nor draft, the release candidate included, and it was published at 08:26:58Z on 2026-09-17, about five hours before the version it precedes. Fifteen tags match the fifteen releases. The commit history has the same compressed shape: 167 commits, every one of them in 2026-09, from the oldest ("feat: initial commit of OKF Agent Memory v0.1.0", 2026-09-05T21:10:22Z) to the newest ("chore(release): prepare release notes and knowledge for v0.4.4", 2026-09-27T20:20:10Z); twelve of those commits come from google-labs-jules[bot] and three from dependabot[bot]. Around the repository sit 740 stars, 57 forks, 4 watchers and 4 open issues, and docs/releases/ keeps sixteen files, one per version plus an index.

4. 04

   Four architecture candidates, three of them printed and quoted

   The report found four candidate architecture documents and printed three in full, naming CLAUDE.md as the one it did not print. The first is knowledge/project/overview.md (2,485 characters): "The OKF Agent Memory project provides an open, vendor-neutral, and domain-agnostic persistent memory layer for AI agents, built directly on Google’s Open Knowledge Format (OKF) v0.2." and, on where memory should live, "OKF Agent Memory solves this by treating an OKF knowledge bundle inside the repository (knowledge/) as the single source of persistent truth." The second is knowledge/convention/dual-memory-architecture.md (5,218 characters): "The Dual-Memory Agent Architecture (DMAA) v0.1 resolves the context-bloat and attention-drift dilemma across AI agents in all domains through a 2-layer cognitive model.", with the push layer "Strictly capped at 100–150 tokens" and the pull layer at "0 tokens in initial system prompt"; the two compose by an equation written into the document, "AGENTS.md = Domain Codex + OKF Memory Bridge". The third is the repository’s own AGENTS.md (2,191 bytes), written in the micro-syntax the project calls Agent Action Grammar: "- MUST execute okf_search(query=keywords, limit=3) before proposing architecture, dependencies, or changes." and "- NEVER scan knowledge/ via list_dir, grep_search, find, or raw readers."

5. 05

   A month of path-traversal fixes, and verification an agent cannot forge

   Nine of the thirty issues and pull requests are security hardening, and most trace back to one class of mistake. Pull request 26 reports that on POSIX systems filepath.Clean treats a backslash as an ordinary filename character, so a payload like ....ile.md could pass a containment check; 27 states the root cause plainly — "On POSIX platforms (Linux/macOS), Go’s filepath.ToSlash is a no-op because filepath.Separator is /" — and 32, 33 and 34 continue the work, with 36 adding that "The standard filepath.IsAbs() function relies on the runtime OS architecture to determine absolute paths", so a Windows absolute path goes unrecognised on POSIX. The same run of pull requests hardened YAML frontmatter: 36 describes "YAML Frontmatter Smuggling", and the still-open 43 explains that sanitizeConceptMetadata checked with strings.HasPrefix and could be bypassed with spaces, quotes or JSON-like syntax. That pull request names a second problem in the same file: "There was no logic preventing an agent from inserting a human: prefix in the Verified array within a tool payload, resulting in a false-sense of human provenance." The project had already written the rule into its own instructions: AGENTS.md says "NEVER forge human verification (verified: is human-only; declare generated: { by: "<actor>", at: "<iso-time>" })".

6. 06

   Beyond the command line: a Hub, a grammar linter and three example corpora

   The tree is larger than a parser plus a CLI. Two packages carry an encrypted Hub that the README calls Zero-Knowledge Sync: pkg/sync/ (12 files, 82 KB — engine.go 16,002 bytes, with client.go, hub.go, server.go, reconcile.go and log_merge.go) and pkg/vault/ (9 files, 33 KB — envelope.go, tree.go, kdf.go, commit.go), driven by ./bin/okf hub init-vault, hub push and hub sync, which take a password, a secret key and an optional token. pkg/okf/aag/ holds a 6,231-byte linter for the Agent Action Grammar the project invented, specified in docs/spec/AGENT_ACTION_GRAMMAR_RFC.md (16,980 bytes). The benchmark runner is one 62,626-byte file, cmd/okf-benchmark/main.go, and benchmarks/results/ holds seven result files (116 KB) naming models such as claude-opus-5, gpt-5.6-sol and qwen3-coder-30b, while the README describes that directory as logs "across 8+ local & cloud LLMs". Three example corpora — examples/software, examples/coaching and examples/books, thirteen files each — show the same bundle used for architecture decisions, coaching sessions and book reviews. Distribution is a Homebrew formula template (1,895 bytes) and a 9,113-byte release workflow. The project also keeps its own memory this way: knowledge/log.md is 15,964 bytes and one of its tests is called dogfood_test.go (3,304 bytes).