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

📊 Performance Benchmarks

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.

# 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

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

4. Running as an MCP Server

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

📖 Further Documentation