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)

Searching Database…

824 ·GitHub
Okf-agent-memory
Что это?OKF Agent Memory — это постоянный слой памяти для AI-агентов, построенный прямо на Git: он хранит архитектурные решения и знания о проекте в виде простых Markdown-файлов с YAML-frontmatter прямо в вашем репозитории, следуя спецификации Open Knowledge Format (OKF) v0.2, благодаря чему контекст переживает сессии, а не исчезает при закрытии окна контекста.
Это CLI-инструмент или MCP-сервер?И то, и другое: это автономный исполняемый файл 'okf' для командной строки, который создаёт каркас памяти и выполняет поиск, а тот же бинарник работает и как нативный MCP-сервер поверх stdio, чтобы агенты вроде Claude Code, Cursor и Codex могли напрямую читать и писать память.
Как запустить его в своём проекте?Склонируйте репозиторий и скомпилируйте автономный исполняемый файл 'okf' (bin/okf), затем выполните его команду инициализации в любом репозитории, чтобы создать папку knowledge/, .agents/skills/okf-memory/, AGENTS.md и Makefile с задачами validate/search.
Нужен ли API-ключ или база данных для использования?Нет — это чистый Go без внешней базы данных, векторного хранилища или API-ключа; нужно лишь, чтобы локально были установлены Go (и make) для сборки бинарника okf, а поиск целиком идёт в памяти через BM25.
Можно ли сразу доверять заявлениям о скорости и экономии токенов?README прямо говорит, что их стоит проверить самостоятельно: в комплекте есть локальный запуск бенчмарка (make benchmark), который измеряет ускорение Time-To-First-Token и сокращение токенов на ~80% на вашем собственном локальном LLM через LM Studio или Ollama.
Где на самом деле живут данные памяти?Всё остаётся в вашем собственном git-репозитории в виде простых Markdown-файлов в knowledge/ — ничего не отправляется на внешние серверы или в базы данных вендоров.
Что такое OKF?OKF (Open Knowledge Format) — независимая от вендоров спецификация (сейчас v0.2) для структурирования постоянной памяти AI-агентов; этот проект — её эталонная реализация на чистом Go.
Что именно оказывается в папке knowledge/?Соответствующий OKF v0.2 пакет памяти из index.md и log.md, создаваемый вместе со встроенным определением агентского навыка в .agents/skills/okf-memory/ и файлом AGENTS.md, адаптированным под проект.
Чем это отличается от обычного файла CLAUDE.md или AGENTS.md?Такие файлы — неструктурированные заметки на скорую руку; OKF Agent Memory оформляет ту же идею в стандартизованный, доступный для поиска пакет OKF v0.2, закрывая разрыв между вольными markdown-заметками и тяжеловесными инструментами памяти на векторных базах вроде Mem0 или Letta.
Насколько быстрый встроенный поиск?По заявлениям проекта, поиск BM25 в памяти по пакету знаний выполняется быстрее 300 мкс, без привлечения внешнего поискового индекса или базы данных.
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, search, coding-agents, agent-memory, memory, model-context-protocol, knowledge-base, golang
Creator
okf-memory
Size
0.8 MB
Stars
824
Updated
CommitOct 12Releasev0.6.1Oct 12
Age
1mo
Commits · 90 Days