OKF Agent Memory A Domain-Neutral, Git-Native Persistent Project Memory for AI Agents based on the Open Knowledge Format (OKF) v0.2. 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
(Normative Markdown & YAML Format)"] L2["2. Agent Memory Convention
(Behavioral Rules: Search, Review, Trust)"] L3["3. Agent Skill
(LLM Prompts & Operational Workflows)"] L4["4. Tooling Layer: Go Library & CLI
(Deterministic Parsing, Validation, Search, MCP)"] L5["5. Project Knowledge Corpus
(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: 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.