OKF Agent Memory

flowchart TD
    subgraph PUSH["1. Normative Working Memory (Push Layer)"]
        direction TB
        C1["Canonical AGENTS.md (capped at 400 tokens)"]
        C2["Domain Codex (Invariants, Ethics, Tone)"]
        C3["OKF Memory Bridge (Deterministic Triggers)"]
        C4["Agent Action Grammar (AAG) Micro-Syntax"]
    end

    subgraph PULL["2. Semantic Domain Memory (Pull Layer)"]
        direction TB
        O1["OKF v0.2 Knowledge Bundle (knowledge/)"]
        O2["0 Tokens baseline in system prompt"]
        O3["Selective Retrieval via okf_search / okf_show"]
        O4["Persistent Graph of Decisions, Facts & Runbooks"]
    end

    INPUT["User Request"] --> PUSH
    PUSH -->|Enforces Domain Codex & Triggers| AGENT["AI Agent (LLM)"]
    AGENT -->|Selective Retrieval| PULL
    PULL -->|Context & Facts| AGENT
    AGENT --> OUTPUT["Deterministic Response"]

flowchart TD
    L1["1. OKF v0.2 Specification<br/>(Normative Markdown & YAML Format)"]
    L2["2. Agent Memory Convention & DMAA<br/>(Dual-Memory Model, Search-Before-Write, Trust)"]
    L3["3. Agent Skill & AAG Codex<br/>(Agent Action Grammar, Workflows, Triggers)"]
    L4["4. Tooling Layer: Go Library & CLI<br/>(Deterministic Parsing, Validation, BM25, MCP)"]
    L5["5. Project Knowledge Corpus<br/>(knowledge/ OKF Bundle)"]

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5

make build

# Validate bundle conformance, graph connectivity, and description drift
./bin/okf validate knowledge --strict --drift

# Evaluate bundle quality scorecard (3 pillars: maintenance, stewardship, integrity)
./bin/okf validate knowledge --scorecard

# Gate bundle quality in CI or pre-commit pipelines (fails if score < 80)
./bin/okf validate knowledge --min-score 80

# 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 nextjs-15 --min-score 80   # Gate bundle quality before installation
./bin/okf pull peter/django-5-rules
./bin/okf pull github.com/acme/[email protected]

# Restore all locked vendor bundles in fresh environments
./bin/okf restore
./bin/okf restore --min-score 80          # Gate all restored bundles

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

flowchart TD
    subgraph Scopes ["OKF 4-Tier Memory Hierarchy"]
        P["<b>Project</b> (Priority 100)<br/>Prefix: <i>none</i> (e.g. decisions/auth)<br/>Location: ./knowledge/"]
        V["<b>Vendor</b> (Priority 70)<br/>Prefix: @bundle/... (e.g. @nextjs-15/routing)<br/>Location: .okf/vendor/"]
        U["<b>User</b> (Priority 50)<br/>Prefix: user:... (e.g. user:guidelines/style)<br/>Location: ~/.okf/"]
        S["<b>System</b> (Priority 10)<br/>Prefix: system:... (e.g. system:corp/policy)<br/>Location: /etc/okf/"]
    end

    P -->|shadows| V
    V -->|shadows| U
    U -->|shadows| S

# 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
./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

---
okf_version: "0.2"
scopes: [project, vendor]
---

# Human-readable scorecard breakdown with Grade (A-F)
./bin/okf validate knowledge --scorecard

# Machine-readable JSON output
./bin/okf validate knowledge --scorecard --json

# Quality gating in CI (fails with exit code 1 if score < 80)
./bin/okf validate knowledge --min-score 80

# Pre-pull quality gating (aborts installation & rolls back if score < 80)
./bin/okf pull nextjs-15 --min-score 80

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

./bin/okf mcp knowledge

{
  "mcpServers": {
    "okf-memory": {
      "command": "/path/to/okf-agent-memory/bin/okf",
      "args": ["mcp", "/path/to/project/knowledge"]
    }
  }
}

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.8.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
├── 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

make check