← Back to feed

OKF Agent Memory (v0.1.0) landed on Hacker News front page September 6 as a direct response to what the authors describe as a two-bad-options problem in agent memory: flat files that bloat, or vector databases that sprawl.

The project is a single Go binary with zero runtime dependencies. It uses Google’s Open Knowledge Format (OKF v0.2 specification) to turn a project’s existing Git repository into a structured, self-validating knowledge corpus. The tool exposes that corpus to Claude Code, Cursor, Windsurf, and local models via a built-in MCP server.

The Problem It’s Solving

The flat-file approach to agent memory — CLAUDE.md, AGENTS.md, .cursorrules — has a well-documented failure mode in large projects. Context files that start at a few hundred lines accumulate architectural decisions, domain rules, and operational notes until they hit 20,000 tokens or more. At that size, attention degradation kicks in: models consistently underweight content in the middle of long contexts. A 20K-token CLAUDE.md is technically loaded and practically ignored.

The vector database alternative solves the retrieval problem but introduces a different set of constraints: Python or Node runtimes, Docker containers for Mem0 or Letta or Zep, proprietary storage formats that exist outside the repository’s normal audit trail, and embedding API latency of 200–800ms per retrieval call. For a coding agent that queries memory dozens of times per session, that adds up.

OKF’s position is the gap between those two points. It uses in-memory BM25 search — lexical ranking across titles, YAML metadata, tags, and bodies — to answer queries in under 300 microseconds. No embedding API call. No network hop. No external process. Cold start is sub-4ms at under 15MB RSS.

How It Works

Memory lives in a knowledge/ directory inside the project repository as plain Markdown files. Each file follows the OKF schema: frontmatter with metadata, body content, trust tier annotation. The binary indexes those files in memory at startup and exposes four MCP tools: okf_search, okf_show, okf_create, and okf_validate.

The trust tier system distinguishes between human-authored authoritative context (verified: human:...) and agent-generated drafts (generated: agent:...). An agent can write to its own memory during a session and those writes persist as git-tracked files, but they carry a different trust marker than entries a human engineer has reviewed. The audit trail for what an agent has decided and stored is git diff and git blame — the same tooling engineers already use.

Progressive disclosure is the retrieval mechanism: instead of loading the entire knowledge corpus into the system prompt, the agent searches the bundle index and pulls only the relevant 300-token concept for the current task. The claimed prompt overhead reduction is up to 90%.

The MCP Integration

The MCP server mode runs as a stdio server: okf mcp knowledge. Claude Code and Cursor both support MCP natively. Connecting OKF to either IDE takes a one-line config entry. The agent then has access to search, read, create, and validate tools that operate on the project’s knowledge/ directory without leaving the repository.

The timing is relevant. GitHub Copilot shipped persistent memory for JetBrains the same week, retaining context across agent chat sessions. Both approaches land on the same problem — agents that forget — via different architectures. Copilot’s memory is cloud-hosted and managed by GitHub. OKF’s is repository-local and managed by the developer team via standard Git workflows.

That architectural choice has compliance implications in regulated industries. Source code and architectural context that would need to be cleared through data governance before leaving the organization stays in the repository under OKF. It is a different surface area for the security review than a cloud-hosted memory service.

Positioning Against Embeddings

The explicit design choice against embedding-based retrieval deserves attention. BM25 is fast, deterministic, and requires no API budget. It also has well-understood failure modes: it cannot surface conceptually similar content that uses different vocabulary, and it is sensitive to term frequency distributions in the corpus.

For a coding agent’s project memory — where relevant content is usually tied to specific file paths, component names, API surface terms, and architectural decision records — BM25 performs well precisely because the vocabulary is constrained and consistent. The tradeoff is less suitable for agents that need to reason across domains with natural language variation.

Installation

brew install okf-memory/tap/okf
cd your-project && okf bootstrap .

The bootstrap command initializes the knowledge/ directory with the OKF schema. From there, okf mcp knowledge starts the MCP server for IDE integration.

Source: github.com/okf-memory/okf-agent-memory