OKF Agent Memory

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

---

🌟 Overview

Conversations with AI agents reset when context windows close. Valuable architectural decisions, domain discoveries, and operational facts are lost unless stored persistently.

Traditional approaches suffer from two fatal failure modes:

1. The Prompt Monolith: Stuffing all domain knowledge and rules into AGENTS.md or CLAUDE.md creates massive context bloat and causes attention drift (agents ignore critical instructions).
2. The RAG Blindspot: Dumping behavioral rules into vector databases fails because agents never semantically search for operational constraints (e.g. formatting or security rules) during general tasks.

OKF Agent Memory resolves this dilemma with the Dual-Memory Agent Architecture (DMAA):

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"]

The Universal Composition Model

In DMAA, every agent configuration is structured by a universal composition:

$$\text{AGENTS.md} = \underbrace{\text{Domain Codex (AAG)}}{\text{Project Invariants, Tone, Guardrails}} + \underbrace{\text{OKF Memory Bridge}}{\text{Standardized Triggers: Search-Before-Write}}$$

• Layer 1: Normative Working Memory (Push Layer): A permanent, ultra-compact behavioral codex (capped at 400 tokens) expressed in Agent Action Grammar (AAG). Loaded at session start, enforcing zero-tolerance invariants.
• Layer 2: Semantic Domain Memory (Pull Layer): An OKF v0.2 knowledge bundle (knowledge/) that consumes 0 tokens at baseline and is queried on-demand in microseconds.

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

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

---

⚡ Key Highlights

• Dual-Memory Cognitive Architecture (DMAA): Separates normative push working memory (AGENTS.md codex) from semantic pull domain memory (knowledge/ bundle), completely eliminating prompt bloat.
• Agent Action Grammar (AAG): Ultra-compact, deterministic ASCII micro-syntax saving ~78–85% tokens compared to natural language prompt instructions.
• Blazing Fast Performance (<300µs Search, ~4ms Graph Validation): In-memory BM25 retrieval and bundle validation execute in microseconds without VM spin-up or network roundtrips.
• 100% Git-Native & Zero Vendor Lock-in: Everything is version-controlled plain text. Inspect, audit, and review your agent's memory using standard git diff and git log. No external database required.
• Zero API Costs for Memory Retrieval: Local lexical BM25 indexing eliminates recurring vector embedding API costs and network roundtrips.
• Built on Google OKF v0.2: Uses the open standard format for agent knowledge with full support for provenance (sources), trust tiers (generated vs. verified), and lifecycle metadata (status, stale_after).
• Solves Context Bloat & Memory Rot: Employs Progressive Disclosure (hierarchical index.md files and link graphs) so agents only load the exact concepts they need.
• Search-Before-Write Principle: Mandates querying existing memory before authoring, preventing concept duplication and hallucinated divergence.
• Governance & Code-to-Knowledge Binding: Bind architecture decisions directly to source files via code_refs and query active constraints/holds via --for-path before modifying code.
• Truly Domain-Neutral: Designed for Software Engineering, Coaching, Scientific Research, Literature Reviews, and Operations.

---

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