okf-memory/okf-agent-memory

OKF Agent Memory

🌟 Overview

The Universal Composition Model

⚡ Key Highlights

📊 Performance Benchmarks

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

make build

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

# Discover constraints and active holds governing a specific source file before editing
./bin/okf search --for-path pkg/okf/types.go 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

# Zero-Knowledge Sync: initialize vault and print Emergency Kit
./bin/okf hub init-vault knowledge

# Zero-Knowledge Sync: push or sync changes with the Hub (optional: --token or OKF_HUB_TOKEN)
./bin/okf hub push knowledge --password "pass" --secret-key "XXXX-..." --auth-token "my-token"
./bin/okf hub sync knowledge --password "pass" --secret-key "XXXX-..."

# Pull external knowledge bundles from OKF Registry (registry.okf-memory.dev) or Git
./bin/okf pull nextjs-15
./bin/okf pull peter/django-5-rules
./bin/okf pull github.com/acme/agent-rules@v1.0.0

# Restore all locked vendor bundles in fresh environments
./bin/okf restore

# Inspect and manage installed vendor bundles
./bin/okf vendor list
./bin/okf vendor remove nextjs-15

3. Multi-Scope Memory Layering & Scoped Resolution

Scope Specification Matrix

Filtering by Scope in Search & Show

# Default (--scope all): Search across all layers with automatic shadowing & priority ranking
./bin/okf search "authentication"

# Search strictly within vendor packages
./bin/okf search "routing" --scope vendor

# Search strictly within local project memory (or use alias --scope bundle)
./bin/okf search "architecture" --scope project

# Search user or system layers
./bin/okf search "style" --scope user
./bin/okf search "compliance" --scope system

# Inspect concepts across scopes
./bin/okf show decisions/auth                        # Local project concept
./bin/okf show @nextjs-15/decisions/routing         # Vendor package concept
./bin/okf show user:guidelines/style                # Personal user concept
./bin/okf show system:corp/policies                 # System compliance concept

4. Bootstrapping Agent Memory in Any Project

# Bootstrap full memory stack into target project
./bin/okf bootstrap /path/to/my-project --name "My Service"

4. Running as an MCP Server

./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/
├── .agents/                # Active agent skills and agent configuration
│   └── skills/okf-memory/  # Authoritative OKF memory skill for AI agents (Single Source of Truth)
├── 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
│   ├── README.md           # Central documentation index & navigation
│   ├── guides/             # User guides, CLI/MCP reference & AI instruction best practices
│   ├── spec/               # OKF convention v0.1, compatibility analysis & architecture RFCs
│   ├── security/           # Data governance, secret prevention & adversarial security audits
│   ├── project/            # Project roadmap, release playbook & multi-agent testing
│   └── releases/           # Versioned release notes & changelog archive (v0.1.0 - v0.6.0)
├── examples/               # Domain-neutral reference DMAA projects (AGENTS.md + OKF v0.2 knowledge/)
│   ├── books/              # Literature & editorial analysis repository
│   ├── coaching/           # Executive coaching & client session repository
│   └── software/           # Microservices architecture & ADR engineering repository
├── 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, governance model & decisions
│   ├── convention/         # Principles & lifecycle workflows
│   └── roadmap/            # Milestones
├── packaging/              # Distribution packaging
│   └── homebrew/           # Official Homebrew formula & tap instructions
├── pkg/
│   ├── lock/               # Zero-dependency okf.lock parser & serializer
│   ├── okf/                # Core library (parser, validator, BM25, MCP, bootstrap)
│   │   └── assets/         # Embedded bootstrap templates & skills mirrored via `make sync-assets`
│   ├── registry/           # Decentralized OKF Registry client & archive unpacker
│   ├── sync/               # Blind sync engine, 3-way reconcile & hub client/server
│   └── vault/              # AES-256-GCM envelope crypto, Argon2id KDF & CAS blind storage
├── scripts/                # Verification & automated audit review helpers (e.g. Jules integration)
├── AGENTS.md               # Operating instructions for AI coding agents
├── CONTRIBUTING.md         # Contribution guidelines & development workflow
├── CONTRIBUTORS.md         # Community contributors & acknowledgements
├── CODE_OF_CONDUCT.md      # Contributor Covenant v2.1 code of conduct
├── Makefile                # Build, test, lint, validation & release targets
├── LICENSE                 # MIT License
├── README.md               # Main repository documentation
└── SECURITY.md             # Security policy & reporting guidelines

🧪 Testing & Verification

make check

📖 Further Documentation

👥 Contributors

💖 Support & Sponsoring

📄 License