Okf Agent Memory

OKF Agent Memory

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

[](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) [](pkg/okf) [](cmd/okf) [](LICENSE)

---

🌟 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 ( [!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](benchmarks/).

---

🚀 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](docs/GETTING_STARTED.md) — Comprehensive onboarding guide for agents and humans.
• [CLI & MCP Reference](docs/CLI.md) — Complete command-line and protocol tools reference.
• [Contributing Guide](CONTRIBUTING.md) — Development setup, quality gates, and pull request standards.
• [Security & Privacy Guidelines](docs/SECURITY.md) — Data governance, secret prevention, and PII protection rules.
• [Multi-Agent Testing & Evaluation](docs/AGENT_TESTING.md) — Test scenarios, compatibility matrix, and benchmarks.
• [OKF Agent Memory Convention v0.1](docs/CONVENTION.md) — Behavioral rules and lifecycle specification.
• [Project Roadmap & Milestones](docs/ROADMAP.md) — Phased development plan.
• [Release Playbook](docs/RELEASE_PLAYBOOK.md) — Versioning, CI/CD pipeline, and distribution procedures.
• [OKF v0.2 Compatibility Matrix](docs/OKF-COMPATIBILITY.md) — Specification validation analysis.
• [Why OKF Agent Memory?](knowledge/project/value-proposition.md) — Detailed value proposition & differentiators.
• [Alternatives & Ecosystem Comparison](docs/ALTERNATIVES.md) — Comparison with Mem0, Letta, and ad-hoc markdown files.

---

📄 License

MIT License. See [LICENSE](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: okf-memory
• Source: okf-memory/okf-agent-memory
• License: MIT

Install and usage instructions live in the source repository linked above.