OKF Agent Architecture Deep-Dive: Git-Native Persistent Memory with BM25 Search Instead of Vector Embeddings [2026]

The OKF (Open Knowledge Format) agent architecture represents a fundamental shift in how AI agents persist and retrieve knowledge across sessions. Launched on GitHub in early September 2026, OKF v0.2 has already attracted 597 stars by proposing a git-native knowledge management system where agent memories are stored as version-controlled, searchable text files rather than opaque vector embeddings.

This post explores the OKF architecture in depth: its git-native design, the BM25 search mechanism, how LangGraph agents integrate OKF for persistent context, and the tradeoffs compared to embedding-based memory systems.

What OKF Does Differently

Every AI agent faces the same fundamental problem: how to remember what it learned across sessions. The dominant approach uses vector embeddings — convert text to numbers, store in a vector database (Chroma, Pinecone, Weaviate), and retrieve via similarity search. OKF replaces this entirely.

OKF stores agent memories as plain Markdown files in a git repository. Each "fact" is a file. Each "update" is a git commit. Retrieval uses BM25 keyword search (the same algorithm powering Elasticsearch) instead of semantic similarity. The result is:

• Fully auditable memory — Every change has a git history with author, timestamp, and diff
• Deterministic retrieval — BM25 returns consistent results for the same query, unlike embedding models that change with model updates
• Zero external dependencies — No vector database, no embedding model, no API calls
• Human-readable storage — Open the repo in any text editor and read the agent's memory directly

Architecture: Git-Native Memory Management

OKF structures memory as a filesystem hierarchy:

okf-memory/
├── facts/
│   ├── user-Deepak-preferred-ide.md
│   ├── project-dailyai-deadline.md
│   └── api-keys-openai-rate-limit.md
├── conversations/
│   ├── 2026-09-11-code-review.md
│   └── 2026-09-12-deployment-fix.md
├── decisions/
│   ├── use-langgraph-for-workflow.md
│   └── adopt-fastmcp-for-tools.md
└── references/
    ├── obra-superpowers-guide.md
    └── mcp-specification-v1.2.md

Each file is a Markdown document with YAML frontmatter for metadata:

---
created: 2026-09-12T10:00:00Z
updated: 2026-09-12T14:30:00Z
tags: [user-preference, ide, cursor]
confidence: 0.95
source: conversation-2026-09-12
---
# User prefers Cursor IDE for Python projects

Confirmed via direct question. User stated they prefer Cursor over VS Code
for Python development because of the integrated AI features.

BM25 Search: Why Keywords Beat Vectors for Agent Memory

BM25 is a bag-of-words ranking function used by search engines. For agent memory retrieval, it has surprising advantages over embedding-based search:

The key insight: agent memories tend to be factual and keyword-heavy ("user email is X," "project deadline is Y"). For this type of structured knowledge, BM25 keyword search often outperforms semantic search because it matches on exact terminology rather than fuzzy meaning.

LangGraph Integration Pattern

OKF integrates with LangGraph through a custom MemorySaver implementation:

from okf import OKFClient
from langgraph.checkpoint import BaseCheckpointSaver

class OKFMemorySaver(BaseCheckpointSaver):
    def __init__(self, repo_path: str):
        self.okf = OKFClient(repo_path)
        
    def get(self, config: dict, query: str) -> list:
        # Search OKF repository with BM25
        results = self.okf.search(query, top_k=5)
        # Format results as context for the LLM
        return [r.content for r in results]
    
    def put(self, config: dict, memory: dict):
        # Write new fact to OKF repo
        self.okf.write_fact(
            content=memory["content"],
            tags=memory.get("tags", []),
            source=memory.get("source", "agent")
        )
        # Auto-commit with descriptive message
        self.okf.commit(f"Update: {memory['summary']}")

This pattern lets LangGraph workflows access persistent memory across sessions without any external database. Every conversation, decision, and fact is automatically version-controlled.

The Workspace Pattern: Memory Scopes

OKF supports repository-level memory scoping through its workspace system. Each workspace is a git branch that isolates agent memory for a specific project or context:

# Create a workspace for the dailyai project
okf workspace create dailyai --branch workspaces/dailyai

# Switch context
okf workspace switch dailyai

# Facts written here are only visible in this workspace
okf set "project-deadline" "September 30, 2026" --tag deadline

# Merge workspace back to main when project completes
okf workspace merge dailyai

This pattern mirrors the approach used in the OKF Agent Memory Workflow, where LangGraph agents maintain separate memory scopes for different projects and merge consolidated knowledge back to a shared repository.

Tradeoffs vs. Embedding-Based Memory

OKF is not always the right choice. The tradeoffs are clear:

Choose OKF when:

• Agent memory must be auditable and human-readable
• You need deterministic, reproducible retrieval
• Facts are structured and keyword-searchable
• You operate in air-gapped or offline environments
• You want zero vector-database operational costs

Choose embedding-based memory when:

• Your agent handles open-ended creative tasks (writing, brainstorming)
• Queries are semantic rather than keyword-based
• You need fuzzy matching on paraphrased content
• Your facts are long-form documents (5,000+ words)
• You already operate a vector database infrastructure

The Obra Superpowers Agentic Workflow combines both approaches: it uses OKF for structured project memory and a lightweight embedding store for conversation context, getting the benefits of both systems.

Implementation: Minimal Viable Setup

Getting started with OKF requires no external services:

pip install okf-client
git init agent-memory
okf init agent-memory
okf set "my-name" "Deepak" --tag personal
okf get "name"  # Returns: "Deepak"

The git-based approach means you can push memory to GitHub for backup, collaborate with other agents on shared knowledge, and use standard git tooling (diff, blame, merge) for debugging agent behavior.

The Road Ahead

OKF v0.3 (expected October 2026) will introduce memory encryption at the file level, allowing agents to store sensitive credentials with per-field access control. The Qanat Agent-Native Alpha Workflow is already testing encrypted memory compartments for trading strategy knowledge that must remain confidential.

OKF represents a bet that the best way to build persistent agent memory is not more complex AI, but more disciplined use of existing developer tools: git, Markdown, and keyword search. Sometimes the most advanced solution is the one that already works.

Production Deployment Considerations

Running OKF in production requires attention to three areas:

Repository Size Management

Without pruning, agent memory grows unbounded. OKF recommends:

• Workspace lifecycle: Delete workspace branches after project completion (keep only merged facts in main)
• Tiered storage: Hot facts (accessed daily) stay in git; cold facts (accessed monthly) are archived to compressed tar
• Automatic summarization: When a directory exceeds 100 files, OKF triggers an agent to write a summary and archive individual files

Production deployments at companies like ACK (using OKF for customer support agent memory) report repository sizes of 50MB after 6 months of continuous operation with pruning enabled.

Concurrency and Locking

OKF uses git's native locking for write operations. Concurrent agent writes are serialized through git merge commits:

# Agent A writes
okf set "customer-preferred-contact" "email" --tag customer-123
# Agent B writes simultaneously
okf set "customer-billing-status" "paid" --tag customer-123
# OKF creates a merge commit automatically

In practice, write conflicts are rare because agents typically write to different files. The Obra Superpowers Agentic Workflow uses OKF's workspace isolation to prevent sub-agents from conflicting on shared knowledge.

Backup and Recovery

Since OKF uses git, recovery is trivial:

git reset --hard HEAD@{1}  # Revert last memory write
git reflog                  # Find any deleted memory
git push origin main        # Backup to remote

This is a significant advantage over vector databases, where recovery from corruption requires rebuilding the entire index from source documents.

Failure Modes and Mitigations

Keyword Blindness

BM25 cannot find information when the query uses synonyms that don't appear in the stored fact. For example, if a fact says "preferred IDE" and the agent asks "what editor do they like," BM25 returns nothing. Mitigation: OKF auto-generates keyword synonyms during write based on the fact content, storing them in a hidden _synonyms file per directory.

Cold Start Problem

An empty OKF repository provides no memory. The first interaction with a user starts with zero context. Mitigation: OKF supports a seed mode that pre-populates a repository with common facts from a template library (user preferences, project conventions, team structures).

Stale Facts

Memory becomes outdated when facts change. OKF's confidence scoring system lets agents flag facts as "needs verification" after a configurable TTL (default 30 days), triggering the agent to re-confirm with the user before acting on stale information. The OKF Agent Memory Workflow implements this as a LangGraph checkpointer that asks the user before using any fact older than 30 days.

Performance Benchmarks

Fact retrieval under OKF v0.2 on Apple M4 Pro:

These benchmarks show OKF is viable for real-time agent operations. The 8ms BM25 search against 100K facts compares favorably to embedding API calls that typically take 50-200ms including network latency.

The Verdict

OKF trades semantic flexibility for determinism and auditability. For most production agent workflows — customer support, code review, project management, data analysis — this tradeoff favors OKF because the memory queries are factual rather than creative. The combination of git-native storage, BM25 retrieval, and LangGraph integration makes OKF the most practical persistent memory solution for agents that need to remember structured facts across sessions. By @deepakb.