OKF Memory

Deterministic, Sub-300µs Persistent Project Memory for AI Coding Agents

Website & Docs • Quickstart • Repositories • Architecture

---

💡 What is OKF Memory?

OKF Memory is an open-source initiative providing Git-native, deterministic project memory for AI coding agents (Claude Code, Cursor, Windsurf, Aider, OpenDevin, and local LLMs).

Instead of dumping massive, stale documentation into LLM context windows or relying on black-box vector databases that suffer from high latency and semantic hallucination, OKF implements progressive disclosure:

1. Lightweight Indexing: Agents discover knowledge concepts via fast search and short descriptions.
2. On-Demand Context Loading: Detailed concepts, code snippets, and architectural rules are pulled into context only when needed.
3. Deterministic Graph: Built-in validation ensures zero broken links, zero orphaned concepts, and zero description drift.

┌────────────────────────────────────────────────────────────────────────┐
│                        AGENT CONTEXT EVOLUTION                         │
├───────────────────────────────────┬────────────────────────────────────┤
│   Traditional RAG / Flat Dumps    │        OKF Memory Approach         │
├───────────────────────────────────┼────────────────────────────────────┤
│ • 10k–30k token context bloat     │ • <800 tokens per loaded concept   │
│ • 3–8s TTFT prefill latency       │ • <300µs in-memory BM25 retrieval  │
│ • Stale, conflicting hallucination│ • Deterministic, version-tracked   │
│ • Requires external server/db     │ • Git-native, 100% offline pure Go │
└───────────────────────────────────┴────────────────────────────────────┘

---

⚡ Quickstart

1. Install the CLI (okf)

# macOS & Linux via Homebrew
brew install okf-memory/tap/okf

# Universal 1-Liner (macOS / Linux)
curl -fsSL https://okf-memory.dev/install.sh | sh

# Go Toolchain
go install github.com/okf-memory/okf-agent-memory/cmd/okf@latest

2. Initialize in Any Project

cd your-project
okf init

This creates a conformant knowledge/ bundle and configures your agent rules (AGENTS.md) without overwriting existing guidelines.

---

📦 Ecosystem Repositories

Repository	Purpose	Status
okf-agent-memory	Pure Go reference engine, embedded stdio MCP server, and okf CLI.
homebrew-tap	Official Homebrew distribution formula for macOS and Linux.
okf-memory.github.io	Static documentation, interactive terminal simulator, and landing portal.
okf-memory-hub (Private Beta)	Zero-Knowledge E2EE knowledge vault and cross-repo federated sync.

---

🧩 Supported Agent Environments

OKF Memory works out of the box with any tool or agent supporting MCP (Model Context Protocol) or native terminal commands:

• Claude Code / Anthropic CLI (.agents/skills/okf-memory/ & stdio MCP)
• Cursor / Windsurf (Workspace rules + MCP config)
• Aider & OpenDevin
• Local Coding Agents (Ollama, Qwen-2.5-Coder, Llama-3, DeepSeek-R1)

---

🎯 Architecture & Philosophy

1. Zero External Dependencies: Pure Go. No Python runtime, no Node.js daemon, no PostgreSQL, no vector store required.
2. Git is the Database: All knowledge items are human-readable Markdown files with structured YAML frontmatter living directly in your repository.
3. Open Knowledge Format (OKF v0.2): Strict schema conformance, bi-directional relationship graphs, provenance tracking (generated vs verified), and drift detection.
4. Local-First & Privacy by Design: All core memory operations run entirely on your local machine with zero external telemetry.

---

🤝 Community & Contributing

OKF Memory is an open, community-driven standard. We welcome contributions, bug reports, and agent integrations:

• 💬 Discussions & Issues: Open an issue in okf-agent-memory.
• 🌐 Website: okf-memory.dev
• 📬 Security & Contact: mail@okf-memory.dev