okf-memory/okf-agent-memory

OKF Agent Memory – What It Is

OKF Agent Memory is a Go‑based toolkit that lets you give an AI‑driven coding assistant a persistent, version‑controlled knowledge base. It follows the Open Knowledge Format (OKF) v0.2 specification, storing facts, decisions, run‑books and other “domain knowledge” as plain‑text Markdown/YAML files inside a knowledge/ folder that lives in the same Git repository as your code.

Why it matters

• No more context loss – When a chat with an LLM ends, the model forgets everything you told it. By keeping a structured knowledge bundle in Git, the agent can retrieve exactly the concepts it needs for the next request.
• Avoid prompt bloat – Instead of stuffing huge AGENTS.md files into every prompt, the system splits the agent’s “working memory” (a tiny 400‑token codex) from a larger semantic memory that is queried on‑demand.
• Zero‑vendor lock‑in – All data are plain text; you can inspect changes with git diff, audit provenance, and never depend on a remote vector database.
• Fast, cheap retrieval – The built‑in BM25 engine does lexical search in‑memory (< 300 µs) and costs nothing in API fees.

Core Concepts

Concept	What it does
Dual‑Memory Agent Architecture (DMAA)	Separates a push layer (normative rules in AGENTS.md, limited to ~400 tokens) from a pull layer (the knowledge/ bundle queried only when needed).
Agent Action Grammar (AAG)	A compact ASCII micro‑syntax for writing deterministic agent instructions, saving ~80 % of tokens compared with free‑form prose.
Four‑tier memory hierarchy	project (local bundle) → vendor (pulled bundles) → user (personal notes) → system (enterprise policies). Higher tiers shadow lower ones.
OKF v0.2 bundle	A set of Markdown/YAML files with built‑in provenance (sources), trust tiers (generated vs verified), and lifecycle metadata (status, stale_after).
Search‑Before‑Write principle	Agents must query the existing bundle before adding new concepts, preventing duplication and hallucination.

What You Get (the toolbox)

• okf CLI – a single compiled binary (bin/okf) that can:
  • Validate a bundle’s schema, graph integrity and quality scorecard.
  • Search concepts with BM25 (okf search "…" knowledge).
  • Show a concept and its relationships (okf show <id> knowledge).
  • Create, update, or bootstrap bundles (okf create …, okf bootstrap …).
  • Run as an MCP (Model Context Protocol) server so agents like Claude, Cursor, or Codex can call it over stdio.
• Zero‑dependency Go library (pkg/okf) – can be embedded in other tools if you want to build custom integrations.
• Vendor bundle handling – pull ready‑made knowledge bundles from an OKF registry or Git, with optional quality gating (--min-score).
• Benchmark suite – reproducible performance tests showing sub‑millisecond search and a few‑millisecond full‑bundle validation.

Quick‑Start Walk‑through

1. Build the binary:

   make build   # produces bin/okf
   

2. Validate the existing bundle (fails CI if score < 80):

   ./bin/okf validate knowledge --min-score 80
   

3. Search for a concept:

   ./bin/okf search "authentication" knowledge
   

4. Bootstrap the whole memory stack into a new project:

   ./bin/okf bootstrap /path/to/my‑project --name "My Service"
   

   This creates the knowledge/ folder, a project‑specific AGENTS.md, and helper Makefile targets.
5. Connect an agent via MCP (example for Claude Desktop):

   {
     "mcpServers": { "okf-memory": { "command": "./bin/okf", "args": ["mcp", "./knowledge"] } }
   }
   

   The agent can now issue search or show calls during a coding session.

Performance & Cost Highlights (from the README)

Metric	OKF Agent Memory (Go)	Typical alternatives
Concept search latency	< 300 µs (in‑memory BM25)	40 ms – 800 ms (embedding + vector DB)
Full bundle parse & graph validation	~4 ms (50+ concepts)	80 ms – 1.5 s
Cold‑start overhead	< 4 ms (single binary)	80 ms – 600 ms (Python/Node runtimes)
Retrieval cost per 1 000 queries	$0.00 (local)	$0.10 – $0.50 (embedding API)
Memory footprint	< 15 MB	60 MB – 350 MB

Who Might Use It?

• Software teams that rely on LLM‑powered code assistants and want a reliable, auditable source of project‑specific rules, architecture decisions, and run‑books.
• Research or coaching projects where the same LLM is repeatedly consulted and needs a stable “knowledge base” that evolves with Git.
• Enterprises that need to enforce compliance policies (security, style, licensing) across many agents without paying for external vector services.

Where to Learn More

• Docs index – docs/README.md
• Getting Started guide – docs/guides/GETTING_STARTED.md
• Agent Action Grammar spec – docs/spec/AGENT_ACTION_GRAMMAR_RFC.md
• Dual‑Memory Architecture RFC – docs/spec/DUAL_MEMORY_AGENT_ARCHITECTURE_RFC.md
• Scorecard & quality gating – docs/guides/CLI.md (see --scorecard flag)

---

In short: OKF Agent Memory gives you a Git‑native, token‑efficient, and ultra‑fast way to store and retrieve the knowledge an AI coding agent needs, eliminating prompt bloat and costly vector‑DB calls while keeping everything auditable and version‑controlled.