[opensourcedex]

okf-agent-memory is a free, open source documentation & knowledge base project written in Go and released under MIT. It has 850 GitHub stars, 69 forks and 1 open issues, and was last pushed 5 days ago. On this registry it ranks #80 of 100 tracked projects in Documentation & Knowledge Base, with 5 head-to-head comparisons available. It gained 110 stars over the last 30 tracked days.

What is okf-agent-memory?

OKF Agent Memory is a Git-native persistent memory layer for AI coding agents that stores project knowledge as Open Knowledge Format (OKF) v0.2 markdown bundles and retrieves it on demand through an embedded MCP server, written in pure Go for developers and teams who need agent context to survive a context window reset.

What it is

OKF Agent Memory implements Google's Open Knowledge Format v0.2 as a memory system for AI coding agents. Knowledge lives in a knowledge/ directory as an OKF bundle of markdown and YAML, committed to the repository alongside code, and is read back through an in-memory BM25 index and an embedded MCP server. The tooling is pure Go 1.26 with zero dependencies: a library at pkg/okf and a CLI and MCP entry point at cmd/okf. There is no external database, no vector store, and no service to operate.

The problem it solves is stated directly in the README. Agent conversations reset when context windows close, so architectural decisions, domain discoveries, and operational facts are lost. The project names two failure modes of conventional approaches. The "Prompt Monolith" stuffs all domain knowledge into AGENTS.md or CLAUDE.md, which bloats context and causes attention drift, where agents begin ignoring critical instructions. The "RAG Blindspot" dumps behavioural rules into vector databases that agents never semantically search for operational constraints such as formatting or security rules. OKF Agent Memory resolves this with the Dual-Memory Agent Architecture (DMAA), which separates a small normative push layer from a queryable semantic pull layer.

Key capabilities

  • Implements the Dual-Memory Agent Architecture: a normative push layer of about 100 to 150 tokens in AGENTS.md, plus a semantic pull layer held in the knowledge/ OKF v0.2 bundle that consumes 0 tokens at baseline.
  • Provides in-memory BM25 search with sub-300 microsecond retrieval, exposed to agents through the okf_search and okf_show tools.
  • Ships an embedded MCP server, marked MCP-Ready, so agents reach memory over the Model Context Protocol rather than through prompt injection.
  • Defines the Agent Action Grammar (AAG), an ASCII micro-syntax for invariants, tone, and guardrails that the README reports saves roughly 78 to 85 percent of tokens compared with natural-language prompt instructions.
  • Enforces a Search-Before-Write convention through the OKF Memory Bridge, standardising deterministic triggers for when an agent consults or updates memory.
  • Stores memory as Git-native OKF v0.2 files, so knowledge is diffed, reviewed, and versioned with the code it describes.
  • Supplies deterministic parsing and validation tooling in Go at pkg/okf, with an MCP-ready CLI at cmd/okf.

Who uses it and how

  • Development teams running AI coding agents on long-lived repositories, where decisions made in one session must remain available in the next.
  • Projects whose AGENTS.md or CLAUDE.md has grown large enough to cause attention drift, and which need the rules split into a compact codex plus an on-demand corpus.
  • Teams that want memory changes reviewed as pull requests, since the knowledge base is ordinary versioned markdown inside the repository.
  • Workflows where operational constraints, such as formatting or security rules, must reach the agent deterministically rather than depending on semantic search.
  • Small teams and individual developers, because the design assumes no external database and therefore no infrastructure to staff or scale.

Getting started

The README excerpt does not show a packaged install command; the shipping artefacts are the Go library at pkg/okf and the CLI and embedded MCP server at cmd/okf, built with the Go 1.26 toolchain and requiring no external dependencies. Documentation is hosted at https://okf-memory.dev.

How it compares

No comparable tools are named in the facts provided, and no list of paid products this project replaces was supplied. It therefore stands alone in this registry.

When to use it — and when not to

There is almost nothing to operate: no database, no storage service, and no SMTP dependency is mentioned, so the running cost is a Go binary and the repository that already holds the code. Do not choose it if the goal is fuzzy semantic retrieval over a large natural-language corpus, since the design deliberately rejects the vector-database approach. Note two cautions from the metadata: the supplied README is truncated, so the install and run instructions are not visible here, and the public surface is small, with 694 stars, 52 forks, and 1 open issue.

project readme (upstream, from github) — read inline

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 CI Trendshift Protocol License Sponsor

🌟 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 (~100-150 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 (~100–150 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<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

⚡ 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 ( [!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

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

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:

  • knowledge/ — OKF v0.2 compliant persistent memory bundle (index.md, log.md)
  • .agents/skills/okf-memory/ — Embedded agent skill definition and capability guides
  • AGENTS.md — Project-tailored operating instructions for AI coding agents
  • Makefile — Convenience tasks for validation (make validate) and search (make search q="...")

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/
├── .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.2.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/okf/                # Zero-dependency Go core library (parser, validator, BM25, MCP, bootstrap)
│   └── assets/             # Embedded bootstrap templates & skills mirrored via `make sync-assets`
├── 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

Run the full test suite and validate the repository's self-documenting knowledge bundle:

make check

📖 Further Documentation

👥 Contributors

Thank you to all the wonderful contributors who have helped build and refine OKF Agent Memory!

OKF Agent Memory Contributors

Contributions of all kinds are warmly welcomed! See CONTRIBUTING.md and CONTRIBUTORS.md for details.

💖 Support & Sponsoring

If you find OKF Agent Memory valuable for your autonomous agent workflows, consider sponsoring the project on GitHub to help support continuous development, security hardening, and spec compliance!

📄 License

MIT License. See LICENSE for details.

Frequently asked questions

Is okf-agent-memory free to use?

okf-agent-memory is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does okf-agent-memory do?

Git-native persistent memory for AI coding agents. Implements Google OKF v0.2 with sub-300µs in-memory BM25 search, embedded MCP server, and progressive disclos

What is okf-agent-memory written in?

okf-agent-memory is primarily written in Go. Its source is publicly available at https://github.com/okf-memory/okf-agent-memory, and it has 850 GitHub stars.