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

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

• 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.

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

Clone the repository and compile the standalone okf executable:

This generates the standalone binary at bin/okf.

# 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

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="...")

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

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

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

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

• 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.

MIT License. See LICENSE for details.