okf-agent-memory

README

OKF Agent Memory

A Domain-Neutral, Git-Native Persistent Project Memory for AI Agents based on the Open Knowledge Format (OKF) v0.2.

---

🌟 Overview

Conversations with AI agents reset when context windows close. Valuable architectural decisions, domain discoveries, and operational facts are lost unless stored persistently.

OKF Agent Memory provides a standardized, vendor-neutral memory layer that lives directly in your repository (knowledge/) as plain Markdown files with YAML frontmatter. It bridges the gap between unstructured ad-hoc markdown files (CLAUDE.md, AGENTS.md) and complex, black-box vector databases.

flowchart TD
    L1["1. OKF v0.2 Specification<br/>(Normative Markdown & YAML Format)"]
    L2["2. Agent Memory Convention<br/>(Behavioral Rules: Search, Review, Trust)"]
    L3["3. Agent Skill<br/>(LLM Prompts & Operational Workflows)"]
    L4["4. Tooling Layer: Go Library & CLI<br/>(Deterministic Parsing, Validation, Search, MCP)"]
    L5["5. Project Knowledge Corpus<br/>(knowledge/ OKF Bundle)"]

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5

---

⚡ Key Highlights

• Blazing Fast Performance (<300µs Search, ~4ms Graph Validation): In-memory BM25 retrieval and bundle validation execute in microseconds without VM spin-up or network roundtrips.
• 100% Git-Native & Zero Vendor Lock-in: Everything is version-controlled plain text. Inspect, audit, and review your agent's memory using standard git diff and git log. No external database required.
• Zero API Costs for Memory Retrieval: Local lexical BM25 indexing eliminates recurring vector embedding API costs and network roundtrips.
• Built on Google OKF v0.2: Uses the open standard format for agent knowledge with full support for provenance (sources), trust tiers (generated vs. verified), and lifecycle metadata (status, stale_after).
• Solves Context Bloat & Memory Rot: Employs Progressive Disclosure (hierarchical index.md files and link graphs) so agents only load the exact concepts they need.
• Search-Before-Write Principle: Mandates querying existing memory before authoring, preventing concept duplication and hallucinated divergence.
• Zero-Dependency Go Toolchain: Single binary with zero external dependencies, sub-5ms CLI startup time, and a built-in Model Context Protocol (MCP) server (okf mcp).
• Truly Domain-Neutral: Designed for Software Engineering, Coaching, Scientific Research, Literature Reviews, and Operations.

---

📊 Performance Benchmarks

Built in Go with zero external dependencies, okf is engineered for high-frequency agent tool calling loops:

Benchmark Metric	Python / Vector DB Runtimes (Mem0, Letta)	Deno / Node.js Tooling	OKF Agent Memory (Go)
Concept Search Latency	150ms – 800ms (Embedding API + Vector DB)	40ms – 120ms	< 300 µs (Microseconds, In-Memory BM25)
Full Corpus Parse & Graph Validation	200ms – 1.5s	80ms – 250ms	~4.0 ms (50+ concepts, bidirectional graph)
Process Cold-Start Overhead	250ms – 600ms (Python VM boot)	80ms – 180ms (V8 / Deno boot)	< 4 ms (Compiled Single Binary)
Retrieval Cost per 1,000 Queries	~$0.10 – $0.50 (Embedding tokens)	$0.00	$0.00 (Zero API cost, fully local)
Memory Footprint (RSS)	~120 MB – 350 MB	~60 MB – 140 MB	< 15 MB

[!TIP] Reproduce Locally with your own LLM: We provide an automated benchmark runner in pure Go to verify Time-To-First-Token (TTFT) speedups and -80% token reduction on your local hardware (LM Studio / Ollama with Gemma, Qwen, Llama). Run make benchmark or explore the Progressive Disclosure Benchmark Suite.

---

🚀 Quickstart

1. Build the Tooling

Clone the repository and compile the standalone okf executable:

make build

This generates the standalone binary at bin/okf.

2. Basic CLI Commands

# Validate bundle conformance, graph connectivity, and description drift
./bin/okf validate knowledge --strict --drift

# Search concepts via in-memory BM25 scoring
./bin/okf search "architecture layers" knowledge

# Inspect a concept and its relationships (with --json support)
./bin/okf show architecture/layers knowledge --json

# Create a new concept with automated log.md and index.md bookkeeping
./bin/okf create decisions/auth-flow knowledge \
  --type Decision \
  --title "OAuth2 Authorization Flow" \
  --desc "Standardized on PKCE for client authentication."

# Update an existing concept
./bin/okf update decisions/auth-flow knowledge \
  --desc "Updated OAuth2 PKCE token refresh interval."

# Bootstrap full agent memory stack into any target project
./bin/okf bootstrap /path/to/project --name "My Project"

# Initialize only a bare OKF bundle in any directory
./bin/okf init my-project/knowledge

3. Bootstrapping Agent Memory in Any Project

Scaffold the complete OKF Agent Memory architecture into any new or existing repository with a single command:

# Bootstrap full memory stack into target project
./bin/okf bootstrap /path/to/my-project --name "My Service"

This automatically sets up:

• knowledge/ — OKF v0.2 compliant persistent memory bundle (index.md, log.md)
• .agents/skills/okf-memory/ — Embedded agent skill definition and capability guides
• AGENTS.md — Project-tailored operating instructions for AI coding agents
• Makefile — Convenience tasks for validation (make validate) and search (make search q="...")

4. Running as an MCP Server

okf ships with a native Model Context Protocol (MCP) server over stdio to seamlessly connect with Claude Code, Cursor, Codex, and other agent platforms:

./bin/okf mcp knowledge

Example MCP Configuration (claude_desktop_config.json or Cursor):

{
  "mcpServers": {
    "okf-memory": {
      "command": "/path/to/okf-agent-memory/bin/okf",
      "args": ["mcp", "/path/to/project/knowledge"]
    }
  }
}

---

📂 Repository Structure

okf-agent-memory/
├── benchmarks/             # Progressive disclosure benchmark suite & hardware test data
│   ├── data/               # Monolith docs vs OKF bundle test fixtures
│   └── results/            # Reproducible benchmark logs across 8+ local & cloud LLMs
├── cmd/
│   ├── okf/                # Standalone CLI and embedded MCP server (`stdio`)
│   └── okf-benchmark/      # Automated benchmark runner for LLM TTFT & token measurements
├── docs/                   # Guides, specifications, architecture & release playbook
│   ├── AGENT_TESTING.md    # Multi-agent testing, prompt scenarios & compatibility matrix
│   ├── ALTERNATIVES.md     # Comparison against Mem0, Letta, and ad-hoc markdown
│   ├── CLI.md              # Complete command-line & MCP tool reference
│   ├── CONVENTION.md       # OKF Agent Memory Convention v0.1
│   ├── GETTING_STARTED.md  # Comprehensive onboarding guide
│   ├── OKF-COMPATIBILITY.md# OKF v0.2 spec compatibility analysis
│   ├── RELEASE_PLAYBOOK.md # Automated release process & version tagging
│   ├── ROADMAP.md          # Project roadmap & milestones
│   └── SECURITY.md         # Data governance, secret prevention & PII rules
├── examples/               # Domain-neutral reference OKF v0.2 bundles
│   ├── books/              # Literature & cognitive science knowledge bundle
│   ├── coaching/           # Executive coaching & client session bundle
│   └── software/           # Microservices architecture & ADR bundle
├── knowledge/              # Project's own OKF v0.2 persistent memory bundle
│   ├── index.md            # Root progressive disclosure index (okf_version: "0.2")
│   ├── log.md              # Dated change log (ISO 8601 YYYY-MM-DD)
│   ├── project/            # Overview & value propositions
│   ├── architecture/       # 5-tier architecture & tooling decisions
│   ├── convention/         # Principles & lifecycle workflows
│   └── roadmap/            # Milestones
├── packaging/              # Distribution packaging
│   └── homebrew/           # Official Homebrew formula & tap instructions
├── pkg/okf/                # Zero-dependency Go core library (parser, validator, BM25, MCP, bootstrap)
├── AGENTS.md               # Operating instructions for AI coding agents
├── CONTRIBUTING.md         # Contribution guidelines & development workflow
├── Makefile                # Build, test, lint, validation & release targets
├── LICENSE                 # MIT License
├── README.md               # Main repository documentation
└── SECURITY.md             # Security policy & reporting guidelines

---

🧪 Testing & Verification

Run the full test suite and validate the repository's self-documenting knowledge bundle:

make check

---

📖 Further Documentation

• Getting Started Guide — Comprehensive onboarding guide for agents and humans.
• CLI & MCP Reference — Complete command-line and protocol tools reference.
• Contributing Guide — Development setup, quality gates, and pull request standards.
• Security & Privacy Guidelines — Data governance, secret prevention, and PII protection rules.
• Multi-Agent Testing & Evaluation — Test scenarios, compatibility matrix, and benchmarks.
• OKF Agent Memory Convention v0.1 — Behavioral rules and lifecycle specification.
• Project Roadmap & Milestones — Phased development plan.
• Release Playbook — Versioning, CI/CD pipeline, and distribution procedures.
• OKF v0.2 Compatibility Matrix — Specification validation analysis.
• Why OKF Agent Memory? — Detailed value proposition & differentiators.
• Alternatives & Ecosystem Comparison — Comparison with Mem0, Letta, and ad-hoc markdown files.

---

📄 License

MIT License. See LICENSE for details.