okf-agent-memory README

The project's README from github.com/okf-memory/okf-agent-memory. As one markdown file: README.md.

OKF Agent Memory

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

Specification Tooling Protocol 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<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

📊 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:

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

📄 License

MIT License. See LICENSE for details.

okf-agent-memory (okf-memory/okf-agent-memory)

bm25
Searching Database…

807 ·GitHub
Okf-agent-memory
What is this?OKF Agent Memory is a Git-native persistent memory layer for AI coding agents: it stores architectural decisions and project knowledge as plain Markdown files with YAML frontmatter directly in your repository, following the Open Knowledge Format (OKF) v0.2 spec, so context survives across sessions instead of vanishing when the context window closes.
Is this a CLI tool or an MCP server?Both: it's a standalone 'okf' command-line binary for scaffolding and searching memory, and the same binary also runs as a native MCP server over stdio so agents like Claude Code, Cursor, and Codex can read/write memory directly.
How do I get it running in my project?Clone the repo and compile the standalone 'okf' executable (bin/okf), then run its bootstrap command in any repository to scaffold the knowledge/ folder, .agents/skills/okf-memory/, AGENTS.md, and a Makefile with validate/search tasks.
Do I need an API key or database to use it?No — it's pure Go with no external database, vector store, or API key; you just need Go (and make) installed locally to build the okf binary, and search runs entirely in-memory via BM25.
Can I trust the speed and token-savings claims out of the box?The README is upfront that you should verify them yourself: it ships a local benchmark runner (make benchmark) that measures Time-To-First-Token speedup and the ~80% token reduction against your own local LLM via LM Studio or Ollama.
Where does my memory data actually live?Everything stays inside your own git repository as plain Markdown files under knowledge/ — nothing is sent to an external server or vendor database.
What is OKF?OKF (Open Knowledge Format) is a vendor-neutral spec, currently at v0.2, for structuring persistent AI agent memory; this project is a reference implementation of it written in pure Go.
What exactly ends up in the knowledge/ folder?An OKF v0.2 compliant memory bundle made of index.md and log.md, bootstrapped alongside an embedded agent skill definition in .agents/skills/okf-memory/ and a project-tailored AGENTS.md file.
How is this different from just using a CLAUDE.md or AGENTS.md file?Those are unstructured ad-hoc notes; OKF Agent Memory formalizes the same idea into a standardized, searchable OKF v0.2 bundle, bridging the gap between loose markdown notes and heavyweight vector-database memory tools like Mem0 or Letta.
How fast is the built-in search?The project claims sub-300μs in-memory BM25 search over the knowledge bundle, with no external search index or database involved.
What are similar projects?ownmem, leviathan, graphicle, EverOS, agent-memory, aoci-code, jevmem, xerj
Which topics is it in?persistent-memory, llm-memory, bm25, knowledge-management, knowledge-graph, coding-agents, search, agent-memory, memory, model-context-protocol, knowledge-base, golang
Creator
okf-memory
Size
0.8 MB
Stars
807
Updated
CommitOct 12Releasev0.6.1Oct 12
Age
1mo
Commits · 90 Days