OKF Agent Memory

Overview

OKF Agent Memory is a git-native persistent memory system for AI coding agents. Launched on September 5, 2026 (81 HN points), it takes a distinctive approach to agent memory: instead of opaque vector stores or proprietary databases, memory lives as committed changes in a regular Git repository. Every memory update is diffable, reviewable, versioned, and attributable.

The pitch resonates with developers tired of treating agent memory as a black box. With OKF, "what did the agent remember last week?" is answered by git log on the memory repo — not by querying an opaque vector store.

OKF Agent Memory is intentionally framework-agnostic: it works as a backend for LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, and custom agent loops. The protocol is filesystem + git primitives; no proprietary APIs.

Features

• Git-native storage: Memory lives as committed changes in a Git repository
• Diffable memory: Every update is reviewable like code; git blame shows who/what changed what
• Versioned recall: Query memory at any historical commit; reconstruct the agent's state at any point
• Framework-agnostic: Works with LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, and custom loops
• Local-first: No cloud required; runs entirely on disk + git
• Encrypted at rest: Optional git-crypt integration for sensitive memory
• Memory categorization: Convention-based (decisions, lessons, context, preferences)
• Conflict resolution: Three-way merge for concurrent memory writes from parallel agents

Installation

# Python SDK
pip install okf-agent-memory

# TypeScript SDK
npm install @okf/agent-memory

# CLI (init a new memory repo)
npx @okf/agent-memory init

Initialize for your agent project:

okf-mem init --path .git/memory --categories decisions,lessons,context,preferences

Quick Start

from okf_agent_memory import Memory

# Initialize or load a memory repo
mem = Memory(repo_path=".git/memory")

# Store a decision
mem.record(
    category="decisions",
    title="Use LangGraph over CrewAI for state management",
    content="Chose LangGraph for state-time-travel debugging. CrewAI was easier "
            "for role-based agents but we needed deterministic replay.",
    author="agent:researcher-001",
    tags=["framework", "state-management"]
)

# Query memory semantically
results = mem.search("why did we choose LangGraph?")
# Returns [{title, content, commit, date, author, categories, tags}]

# Time-travel query: what did the agent know on 2026-09-01?
historical = mem.query_at(when="2026-09-01")

Memory Categories

By convention, OKF uses four top-level categories (configurable):

Category	Purpose	Example
decisions	Architectural, tool, and process decisions	"Use LangGraph over CrewAI"
lessons	Things learned from past failures or successes	"Retry with exponential backoff on transient API errors"
context	Persistent facts about the environment	"Deploy target is us-east-1, not eu-west-1"
preferences	User preferences for tone, style, and patterns	"User prefers concise code, no verbose comments"

Custom categories can be added via the okf-mem init --categories flag.

Retrieval

OKF combines three retrieval strategies:

1. Semantic: Embedding-based similarity over memory content (default: bge-small)
2. Keyword: BM25 full-text search
3. Graph: Category + tag traversal for related memories

Results are fused by Reciprocal Rank Fusion (RRF). The embedding model is pluggable; local models via sentence-transformers or remote via OpenAI / Cohere.

# Pure semantic
mem.search("memory strategy")

# With category filter
mem.search("framework decisions", category="decisions")

# With tag filter
mem.search("deploy", tags=["infra"])

# Strict BM25 only (no embeddings)
mem.search("LangGraph", mode="keyword")

Architecture

┌─────────────────────────────────────────┐
│       Agent (any framework)             │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│       OKF Agent Memory SDK              │
│  ┌──────────────────────────────────┐   │
│  │  Retrieval (semantic + BM25 +   │   │
│  │  graph + RRF fusion)            │   │
│  ├──────────────────────────────────┤   │
│  │  Storage adapter (filesystem)    │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│       Git Repository (.git/memory)      │
│  decisions/ lessons/ context/ prefs/    │
└─────────────────────────────────────────┘

Multi-Agent Use

OKF is designed for multi-agent setups where parallel agents write to the same memory. Conflicts are resolved via git's three-way merge:

# Agent A commits a decision
okf-mem record -c decisions -t "Use Postgres" ...
# Agent B, working in parallel, commits a conflicting decision
okf-mem record -c decisions -t "Use MySQL" ...

# Resolve with --strategy
okf-mem merge --strategy latest | oldest | ask-human

Pros

• ✅ Memory is diffable, versioned, and reviewable (no black boxes)
• ✅ Works with any agent framework — no lock-in
• ✅ Local-first; no cloud dependency
• ✅ Time-travel queries: inspect agent state at any past commit
• ✅ Multi-agent conflict resolution via git merges
• ✅ Conventional categories give memory structure

Cons

• ❌ Not the fastest retrieval (git + embeddings have overhead vs. vector DB)
• ❌ Disk usage grows over time; requires periodic compaction
• ❌ Git merge conflicts for concurrent writes require setup
• ❌ No built-in semantic clustering or auto-deduplication

When to Use

• Use when: You want auditable, versioned agent memory; multi-agent setups where memory conflicts matter; teams that prefer git as their system of record
• Avoid when: You need sub-millisecond retrieval at massive scale, or if vector-store performance is critical (use Pinecone, Qdrant, or Weaviate instead)

Resources

• GitHub Repository
• Documentation
• Protocol Spec