Agent memory is moving to Markdown files — from Karpathy's LLM wiki to Google's OKF 0.2: what the spec covers and what it doesn't

1. Executive summary

Some definitions first. Frontmatter is the YAML metadata block wrapped in --- at the top of a Markdown file. A bundle is a directory tree of OKF files, distributed as a git repository or an archive. Producer (the side that writes the files: people, agents, export pipelines) and consumer (the side that reads them: agents, UIs, search indexes) are the spec's terms. A concept is the unit one file describes; it can be a table, a metric, an API, a playbook, a runbook or anything else. The LLM wiki is a pattern Karpathy named, in which an agent reads source material and itself builds and revises a set of interlinked Markdown pages. Vector search turns text into numeric vectors to find items with similar meaning, and BM25 is a traditional full-text search score based on word matches.

Spec quotations in this report are from the original SPEC.md (v0.2) in the GoogleCloudPlatform/open-knowledge-format repository, and the tools' performance figures are claims from each repository's README. Star counts are GitHub API values from 2026-09-21.

2. Six months — from a gist to a spec to tools

The three threads point the same way. Karpathy proposed a way of working in which the agent writes the wiki itself, Google Cloud defined a convention for representing that wiki as files, and independent developers attached search and MCP servers to that convention. GBrain, which this blog covered in June, belongs to the third of these layers, the product layer. This report deals with the format layer beneath it.

3. What the OKF spec actually defines — one required field

The spec's opening paragraph sums up its character: "The format is intentionally minimal: a directory of markdown files with YAML frontmatter. There is no schema registry, no central authority, and no required tooling. If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it" [1].

The last two rows of the table are the point. The conformance rules are almost all of the form "do not reject," and what the spec leaves out includes search and serving. OKF is a minimal convention that writers and readers must follow, not a way to retrieve memories. So you can view a bundle in Obsidian, search it with ripgrep, or layer an embedding index on top of it without violating the spec. The announcement post's example is a data catalog: concept files sit in datasets/, tables/ and metrics/ directories under sales/, linked like [customers](/tables/customers.md) [2]. Using the same frame for a coding agent's project memory is the tools' choice, not the spec's.

4. v0.2's five trust signals and three trust tiers

The motivation for v0.2 is in §1 of the spec: "Increasingly, a knowledge corpus is not authored once and then read: it is continuously written and maintained by agents. When most concepts are machine-generated, a consumer needs answers that a plain markdown-plus-frontmatter convention does not make first-class: What was this created from, and how was it verified? How much should I trust it? Is it still true? Is it the current version? Was this number produced the way we said it must be?" [1]. The announcement post calls the mechanisms that answer these five questions the five trust signals [3]: Provenance, Trust & Verification, Freshness, Lifecycle, and Attested Computations. The first four are frontmatter fields; the last is a new concept type.

Sources: [1] §5, §10, §13; [3]. Row names follow the five questions in §1 of the spec; the labels in parentheses follow the announcement post's categories.

Trust tiers are derived from verified. No key means unverified; confirmation only by actors other than human: means machine-confirmed; confirmation by a human:<id> means human-reviewed. The spec states plainly that "Trust tiers are advisory signals, not access control," but the announcement post describes their use this way: a consumer can express "only surface human-reviewed metrics in the executive dashboard" as a single frontmatter filter [3]. This is where it connects with agents overclaiming "review complete", which this blog covered two days earlier. When a person's confirmation is recorded in a separate field on documents an agent wrote, what the agent said it checked and what a person actually checked become distinguishable at the file level.

Compatibility is explicit: "A v0.1 bundle drops in unchanged." Only two things were renamed (timestamp → generated.at, # Citations → sources), and v0.2 consumers may fall back to reading the old forms [1][3].

5. How the three approaches differ — LLM wiki, memoryfield, OKF

All three proposals can be summed up as "remember with files," but they deal with different layers.

Sources [4][5][1]. The memoryfield figures are as stated in the essay, and the essay does not mention OKF.

Paterson's essay criticizes existing memory systems on three points: the lock-in that comes with the move into a platform business; the complexity of needing pgvector, Neo4j and a dedicated model; and the slowness of calling tools many times while walking a knowledge graph. His answer is a single one: Markdown with simple embeddings [5]. The most common reaction on HN boiled that down to one line: "A whole lot of text to say 'Just use text'" (thm), and "It feels like 50% of AI 'progress' is just finding different ways to say 'tell the model things in English'" (andyfilms1). On the other side were comments that took issue with who writes the memory, such as "'harness managed' memory is utter garbage, I am convinced … auto managed memory was always the problem" (JohnMakin), and a quality concern that mistaken past explorations rank high in semantic search [7].

6. The tools and their claims — nothing verified yet

Sources [8][6][1]. Star counts from the GitHub API on 2026-09-21. Both tools were created between 2026-08 and 2026-09, so each has a little over a month of operating history.

What was valuable in the HN discussion of OKF Agent Memory was not the tool's numbers but the debate over retrieval methods. One user (vshulcz) reported success rates of 61% for BM25 and 37% for semantic search on a personal corpus and wrote: "The real cliff is reranking … and staleness. Vector search has zero concept of 'superseded info'." Another user (langs) said: "What nobody has gotten close to solving is maintenance and provenance - what goes into memory, what qualifies as truth, how stale memory gets invalidated/superseded" [10]. Both are one person's experience, but the second point is exactly what v0.2 turned into fields. The format does not supply the answers, but there is now a place to write them down.

Adoption signals are still at the margins. GitBook says "A GitBook space already looks like the directory OKF describes" and presents itself as "an OKF-ready knowledge source," but it does not describe an export feature [11]. Beyond that, there is a PR adding v0.2 support to a wiki tool (nexwiki), a static publishing engine (Kiso), and Obsidian-style plugins, each drawing a few points on HN. At the time of writing, we could not find any major agent framework or coding agent that has announced OKF as its memory format.

7. Checklist to apply today

These are operating recommendations we drew from the spec and the three proposals. None of them has had its effect verified by a controlled measurement.

• Start memory as a folder. Put a directory such as knowledge/ in the project and write a type in each file's frontmatter. That alone makes it an OKF-conformant bundle, which any tool that reads OKF must not reject. Individual tools may add conventions of their own.
• Write generated on files an agent wrote and verified on files a person checked. Keeping the two apart is the core of v0.2. If you tell the agent in its prompt, "When you create a new concept file, add generated: { by: <agent/version>, at: <ISO 8601> } and leave verified empty," the file itself records whether a person has reviewed it.
• For facts that will obviously go stale, write stale_after as an absolute time. Prices, model names and API limits are examples. On the consuming side, warn before putting a file with now >= stale_after into the context.
• Use index.md for progressive disclosure. A list with a one-line description in each directory makes it easier to have prompts and tools open only the files they need instead of reading everything. Karpathy's schema file (CLAUDE.md, AGENTS.md) should say only how to use these lists.
• Make lint a recurring job. Have the agent check for contradictions, stale claims and broken links, and record the results in log.md in date order. The format only gives stale memories a place to be marked; this job is what actually finds them, and whether to invalidate them has to be decided and applied through a separate policy.
• Search is an index, not the source. Whether it is BM25 or embeddings, keep it as something you can rebuild from the files, and put the files in git. When you switch tools, the memory stays.
• Measure figures like "Slashes token bloat by 80%" on your own repository. Run the same task with no folder, with the folder only, and with the folder plus a search tool, and compare input tokens and results. None of the material we read contains that comparison.
• Build one path that uses only human-reviewed files. For work where errors are costly, such as deployment decisions or customer support, feed in only files whose verified includes a human: actor. It is the same structure as the dashboard example in the announcement post.

8. What this is not yet

• We did no measurements of our own. This report cross-checks the spec, the announcement posts, the gist, the essay, repository READMEs and HN discussions. None of the material we read contains a controlled comparison showing that file-based memory beats memory built on a vector database.
• OKF is at 0.2. The spec itself calls it "a starting point, not a finished standard," and leaves the runtime protocol, the attester ABI, sandboxing, caching and semantic-layer templates under "Considered and deferred." Fields may change further before 1.0.
• The starting point is the data catalog. The announcement posts' examples and the reference agent describe BigQuery tables and metrics, and Google's own adoption is in Knowledge Catalog. Using OKF for a coding agent's project memory is an extension by independent tools; the spec has not validated that use.
• Every tool figure is a developer claim. 300µs, 80% and 20ms are all sentences in READMEs, with no measurement conditions. Both tools are one to two months old.
• The HN retrieval comparison is one person's experience. BM25 at 61% versus semantic search at 37% comes from a personal corpus, and the method was not published. We cite only the direction.
• The date of Karpathy's gist is as the page displays it. The GitHub API returned no metadata, so we used 2026-04-04 as shown on the page. For stars, we saw only the page's "5,000+" display.
• Repository figures are a one-day snapshot. Star counts and recent commits are values from 2026-09-21. The announcement posts' dates follow the page metadata (datePublished); because of the time zone difference, the pages display them one day later (June 13, July 25).
• What this report does not cover. Feature comparisons with managed memory services such as mem0, Letta and Zep, and results on long-term memory benchmarks such as LoCoMo and LongMemEval, are out of scope. The debate over formats and the debate over benchmarks have not come together yet.

9. Sources

Checked on 2026-09-21. [1]–[3] are the spec and the vendor's announcement posts, and [4] and [5] are the proposers' originals. [6] and [8] are the tools' descriptions of themselves, [7], [9], [10] and [12] are community discussions, and [11] is a tool vendor's blog.

Editorial standard: in each section we kept what the spec defines separate from what tools and the community claim, and we labeled every tool performance figure as a "claim." Where secondary blogs call OKF a "Google standard," we described it by the actual scope of the announcement posts instead.