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