The Problem

AI coding agents lose context when conversation windows close. Architectural decisions, domain facts, and operational knowledge vanish unless persisted, and the common fallbacks are either unstructured CLAUDE.md/AGENTS.md files or heavyweight vector databases with embedding API costs and network latency. This repo targets that gap: structured, version-controlled memory that lives in the repo itself.

What This Does

okf-agent-memory is a pure-Go CLI and library implementing Google's Open Knowledge Format (OKF) v0.2. Memory lives as Markdown files with YAML frontmatter under knowledge/, indexed in-memory with BM25. The README claims sub-300µs search, ~4ms validation, and <15MB RSS — plausible for a zero-dependency compiled binary.

The core is pkg/okf/: parser.go handles Markdown/YAML parsing, search.go the BM25 index, validator.go OKF schema validation, mutate.go write operations. The CLI in cmd/okf/main.go exposes commands including okf mcp, which starts an embedded MCP server (cmd/okf/mcp.go). A separate benchmark runner lives at cmd/okf-benchmark/main.go.

How It Is Wired

Execution starts at cmd/okf/main.go, which dispatches to subcommands. The MCP path (cmd/okf/mcp.go) serves agent tool calls over the Model Context Protocol; each query routes through pkg/okf/search.go (BM25 retrieval) and pkg/okf/validator.go (bundle validation). The filesystem effect is read-only against the knowledge/ tree except for mutate.go, which writes new memory entries. There is no external database, network call, or embedding API in any path — the only I/O is local file reads and the MCP socket.

The dependency graph is flat: parser.go, search.go, and validator.go are leaf modules; bundle.go and bootstrap.go orchestrate them. The widest blast radius sits in parser.go — every search, validation, and mutation depends on its frontmatter parsing being correct. There are no cycles, so changing any leaf is cheap. The module graph for cmd/okf/mcp.go and the benchmark runner is not fully mapped from the file structure alone.

How To Use It

git clone https://github.com/moses-y/okf-agent-memory
cd okf-agent-memory
go build ./cmd/okf
./okf --help          # CLI entry: cmd/okf/main.go
./okf mcp             # start MCP server (cmd/okf/mcp.go)

A Makefile exists with build/test targets, and go.mod declares zero external dependencies. No environment variables or config files are required — configuration is the knowledge/ directory itself. Homebrew packaging is provided under packaging/homebrew/. Note: there is no go.sum, so builds are not cryptographically pinned, though with zero dependencies this is a minor risk.

Real-World Use

A coding agent tool loop: the agent calls okf mcp tools to search memory before writing. Query hits search.go, returns ranked concepts from knowledge/, and the agent loads only the relevant index.md (progressive disclosure) instead of re-reading the full corpus. New decisions are appended via mutate.go, creating a git-diffable audit trail.

Code Health & Issues

  • Low — No go.sum lockfile; builds are not reproducible-pinned (go.mod).
  • Low — Test coverage is thin: 3 test files total, concentrated in pkg/okf/ (okf_test.go, scenarios_test.go). The CLI and MCP server have no tests.
  • Low — Benchmark results are stored in benchmarks/results/ as Markdown, not machine-readable output; reproducing them requires the LLM setup documented in benchmarks/README.md.

CI exists (.github/workflows/ci.yml, release.yml). Docs are thorough: docs/GETTING_STARTED.md, docs/CLI.md, docs/OKF-COMPATIBILITY.md.

The Bottom Line

A well-scoped, honest implementation of a useful idea: zero-dependency, git-native agent memory with credible performance claims. The main risk is the OKF v0.2 spec being young and the project being unproven (0 stars, no release history). Worth evaluating if you want agent memory without vector-database overhead; test coverage needs attention before production use.