OKF Agent Memory – Git-native persistent memory for AI coding agents | AI Paper Digest

TL;DR Highlight

Git-markdown memory with in-memory BM25 search claims 80% fewer tokens and sub-300µs lookups

Who Should Read

A developer using coding agents whose CLAUDE.md/AGENTS.md keeps ballooning until the agent ignores instructions

Core Mechanics

Memory is split into two layers
- The always-loaded Push layer keeps only rules in AGENTS.md, capped at 400 tokens.
- The on-demand Pull layer lives in knowledge/ and costs 0 tokens in the base system prompt.
Two failure modes of current setups
- Stuffing everything into AGENTS.md/CLAUDE.md bloats context and the agent ignores key instructions, per the README.
- Putting rules in a vector DB fails because agents never semantically search for constraints like formatting or security.
In-memory BM25 instead of vectors
- BM25 is keyword-based ranking, so no embedding API or external DB is needed.
- The README table lists search under 300µs versus 150–800ms for Mem0/Letta-style runtimes.
Go single binary with built-in MCP server
- `okf mcp knowledge` starts a stdio MCP server for Claude Code, Cursor and others.
- Tools are okf_search, okf_show, okf_create and okf_validate.

Community Reactions

Critique: only latency is benchmarked
- One commenter said measuring latency without recall/precision is meaningless next to LLM call times.
- Another asked whether any capture/retrieval quality benchmarks exist.
Doubts about needing an MCP server
- A commenter asked why an MCP server is needed when the spec is so simple.
- Another wondered how well the model follows OKF in harnesses like Codex that have built-in memory tools.
Memory itself may be a burden
- One commenter argued memory wastes context like skills and a few hand-written md files suffice.
Enterprise use needs separate testing
- One commenter separates planning and implementation sessions and hoped domain memory would keep unit-level work smooth.
- They said practical risk remains and they would test it on a personal project first.

How to Apply

Measure your current AGENTS.md size
- Count tokens in your CLAUDE.md/AGENTS.md today and mark anything past 400 tokens.
- Split it into must-always-follow rules and look-up knowledge.
Bootstrap OKF in a scratch project
- Run brew install okf-memory/tap/okf, then okf bootstrap . in the project.
- Inspect the generated knowledge/ and AGENTS.md with git diff.
Connect the MCP server to your agent
- Register command okf with args ["mcp", "path/to/knowledge"] in Claude Code or Cursor config.
- Check logs to see whether the agent calls okf_search before working.
Add path-based constraint lookup to your workflow
- Add code_refs to your key decision documents.
- Have the agent run okf search --for-path <file> knowledge before editing.

Try It

copy & run

# Paste into Claude Code or ChatGPT (simplified version of the OKF Agent Memory approach)

You are a coding agent. Split the AGENTS.md below into two layers.

1) Push layer: compress only always-on invariant rules into 400 tokens or fewer.
2) Pull layer: split the rest into topic-based markdown concept docs. Each has a title, one-line description, tags and a body under 300 tokens. Also create index.md listing every doc with a one-line description.

[AGENTS.md]
{{AGENTS.md content}}

Next step: when I give a new task {{task description}}, make the agent read only index.md first and then open just the concept docs it needs.

Terminology

BM25A classic search ranking that scores documents by how often and how distinctively keywords appear. It works like a library index, with no embeddings needed.

Progressive DisclosureShow the table of contents first and open only the chapters you need. The agent reads index.md and pulls only relevant docs.

OKF (Open Knowledge Format)An open format for writing agent knowledge as markdown with YAML metadata. The README describes v0.2 as a Google spec.

MCPA standard for plugging external tools into LLM apps. Like a USB port, you wire it once and many agents can use it.

Agent Action Grammar (AAG)Writing agent instructions in a compact ASCII micro-syntax instead of natural language. The README claims it saves about 78–85% of tokens.

OKF Agent Memory – Git-native persistent memory for AI coding agents