OKF Agent Memory

Overzicht

Gesprekken met AI-agenten worden gereset zodra de contextvensters sluiten. Waardevolle architecturale beslissingen, domeinontdekkingen en operationele feiten gaan verloren, tenzij ze persistent worden opgeslagen.

OKF Agent Memory biedt een gestandaardiseerde, vendor-neutrale geheugenlaag die direct in je repository leeft (knowledge/) als platte Markdown-bestanden met YAML-frontmatter. Het overbrugt de kloof tussen ongestructureerde ad-hoc markdown-bestanden (zoals CLAUDE.md of AGENTS.md) en complexe, 'black-box' vector-databases.

Architectuur-stroomschema

1. OKF v0.2 Specificatie (Normatief Markdown & YAML-formaat)
2. Agent Memory Conventie (Gedragsregels: Zoeken, Beoordelen, Vertrouwen)
3. Agent Skill (LLM-prompts & operationele workflows)
4. Tooling Laag: Go Library & CLI (Deterministische parsing, validatie, zoeken, MCP)
5. Project Knowledge Corpus (knowledge/ OKF-bundel)

Belangrijkste Kenmerken

• Razendsnelle Prestaties: Zoekopdrachten in het geheugen via BM25 (<300µs) en bundle-validatie (~4ms) worden in microseconden uitgevoerd, zonder dat er een VM hoeft op te starten of netwerkverzoeken nodig zijn.
• 100% Git-Native & Geen Vendor Lock-in: Alles is versiebeheerde platte tekst. Inspecteer, controleer en beoordeel het geheugen van je agent met standaard git diff en git log. Er is geen externe database vereist.
• Geen API-kosten voor Geheugenopvraging: Lokale lexicale BM25-indexering elimineert terugkerende kosten voor vector-embedding API's en netwerkvertragingen.
• Gebouwd op Google OKF v0.2: Maakt gebruik van het open standaardformaat voor agent-kennis met volledige ondersteuning voor herkomst (bronnen), vertrouwensniveaus (gegenereerd versus geverifieerd) en lifecycle-metadata (status, stale_after).
• Bestrijdt Context-bloat & Memory Rot: Maakt gebruik van Progressive Disclosure (hiërarchische index.md-bestanden en link-grafieken), zodat agenten alleen de exacte concepten laden die ze op dat moment nodig hebben.
• Search-Before-Write Principe: Verplicht het raadplegen van het bestaande geheugen voordat er nieuwe informatie wordt geschreven, wat concept-duplicatie en hallucinaties voorkomt.
• Zero-Dependency Go Toolchain: Een enkel binair bestand zonder externe afhankelijkheden, een opstarttijd van de CLI van minder dan 5ms en een ingebouwde Model Context Protocol (MCP) server (okf mcp).
• Echt Domein-neutraal: Ontworpen voor software engineering, coaching, wetenschappelijk onderzoek, literatuuronderzoeken en operationele processen.

Prestatie-benchmarks

Gebouwd in Go zonder externe afhankelijkheden, is okf ontworpen voor hoogfrequente 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 (In-Memory BM25)
Full Corpus Parse & Graph Validation	200ms – 1.5s	80ms – 250ms	~4.0 ms (50+ concepten, bidirectionele graaf)
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 (Volledig lokaal)
Memory Footprint (RSS)	~120 MB – 350 MB	~60 MB – 140 MB	< 15 MB

Tip: Je kunt dit lokaal reproduceren met je eigen LLM. Er is een geautomatiseerde benchmark-runner in pure Go beschikbaar om de Time-To-First-Token (TTFT) snelheidswinst en de reductie van tokens met 80% te verifiëren op je eigen hardware (bijv. via LM Studio / Ollama met Gemma, Qwen, Llama). Voer make benchmark uit of bekijk de Progressive Disclosure Benchmark Suite.

Snelstart

1. De Tooling Bouwen

Kloon de repository en compileer het standalone okf executable:

make build

Dit genereert het binaire bestand in bin/okf.

2. Basis CLI Commando's

# Valideer bundle-conformiteit, grafiek-connectiviteit en beschrijvingsdrift
./bin/okf validate knowledge --strict --drift

# Zoek concepten via in-memory BM25 scoring
./bin/okf search "architecture layers" knowledge

# Inspecteer een concept en diens relaties (ondersteunt --json)
./bin/okf show architecture/layers knowledge --json

# Maak een nieuw concept aan met automatische log.md en index.md bijhouding
./bin/okf create decisions/auth-flow knowledge \
--type Decision \
--title "OAuth2 Authorization Flow" \
--desc "Standardized on PKCE for client authentication."

# Update een bestaand concept
./bin/okf update decisions/auth-flow knowledge \
--desc "Updated OAuth2 PKCE token refresh interval."

# Bootstrap de volledige agent memory stack in een doelproject
./bin/okf bootstrap /path/to/project --name "My Project"

# Initialiseer enkel een kale OKF-bundel in een willekeurige directory
./bin/okf init my-project/knowledge

3. Agent Memory Bootstrappen in Elk Project

Richt de volledige OKF Agent Memory architectuur in elk nieuw of bestaand repository in met één commando:

./bin/okf bootstrap /path/to/my-project --name "My Service"

Dit stelt automatisch het volgende in:

• knowledge/: Een OKF v0.2 compliant persistent geheugenbundel (index.md, log.md).
• .agents/skills/okf-memory/: Ingebedde agent-skill definities en capability guides.
• AGENTS.md: Projectspecifieke operationele instructies voor AI-coding agents.
• Makefile: Handige taken voor validatie (make validate) en zoeken (make search q="...").

4. Draaien als MCP Server

okf wordt geleverd met een native Model Context Protocol (MCP) server via stdio om naadloos te verbinden met Claude Code, Cursor, Codex en andere agent-platformen:

./bin/okf mcp knowledge

Voorbeeld MCP Configuratie (claudedesktopconfig.json of Cursor):

{
  "mcpServers": {
    "okf-memory": {
      "command": "/path/to/okf-agent-memory/bin/okf",
      "args": ["mcp", "/path/to/project/knowledge"]
    }
  }
}

Structuur van de Repository

• benchmarks/: Progressive disclosure benchmark suite & testdata voor hardware.
• data/: Monolith docs versus OKF-bundel testfixtures.
• results/: Reproduceerbare benchmark-logs over 8+ lokale & cloud LLM's.
• cmd/:
• okf/: Standalone CLI en embedded MCP server (stdio).
• okf-benchmark/: Geautomatiseerde benchmark-runner voor LLM TTFT & token-metingen.
• docs/: Handleidingen, specificaties, architectuur & release playbook.
• AGENT_TESTING.md: Multi-agent testen, prompt-scenario's & compatibiliteitsmatrix.
• ALTERNATIVES.md: Vergelijking met Mem0, Letta en ad-hoc markdown.
• CLI.md: Complete referentie voor command-line & MCP tools.
• CONVENTION.md: OKF Agent Memory Convention v0.1.
• GETTING_STARTED.md: Uitgebreide onboarding-gids.
• OKF-COMPATIBILITY.md: OKF v0.2 spec compatibiliteitsanalyse.
• RELEASE_PLAYBOOK.md: Geautomatiseerd releaseproces & versie-tagging.
• ROADMAP.md: Project roadmap & mijlpalen.
• SECURITY.md: Datagovernance, preventie van geheimen & PII-regels.
• examples/: Domein-neutrale referentie OKF v0.2 bundels.
• books/: Kennisbundel voor literatuur & cognitieve wetenschap.
• coaching/: Bundel voor executive coaching & clientsessies.
• software/: Bundel voor microservices architectuur & ADR.
• knowledge/: De eigen OKF v0.2 persistente geheugenbundel van het project.
• index.md: Wortel van de progressive disclosure index (okf_version: "0.2").
• log.md: Gedateerd wijzigingslogboek (ISO 8601 YYYY-MM-DD).
• project/: Overzicht & waardeproposities.
• architecture/: 5-tier architectuur & tooling beslissingen.
• convention/: Principes & lifecycle workflows.
• roadmap/: Mijlpalen.
• packaging/: Distributie-packaging (bijv. Homebrew formula).
• pkg/okf/: Zero-dependency Go core library (parser, validator, BM25, MCP, bootstrap).
• AGENTS.md: Operationele instructies voor AI-coding agents.
• CONTRIBUTING.md: Richtlijnen voor bijdragen & development workflow.
• Makefile: Build, test, lint, validatie & release targets.
• LICENSE: MIT Licentie.
• README.md: Hoofddocumentatie van de repository.
• SECURITY.md: Beveiligingsbeleid & rapportage-richtlijnen.

Testen & Verificatie

Voer de volledige testsuite uit en valideer de zelf-documenterende kennisbundel van de repository:

make check

Aanvullende Documentatie

• Getting Started Guide — Uitgebreide onboarding-gids voor agenten en mensen.
• CLI & MCP Reference — Complete referentie voor command-line en protocol tools.
• Contributing Guide — Setup voor ontwikkeling, kwaliteitscontroles en standaarden voor pull requests.
• Security & Privacy Guidelines — Regels voor datagovernance, preventie van geheimen en PII-bescherming.
• Multi-Agent Testing & Evaluation — Testscenario's, compatibiliteitsmatrix en benchmarks.
• OKF Agent Memory Convention v0.1 — Gedragsregels en lifecycle specificatie.
• Project Roadmap & Milestones — Gefaseerd ontwikkelingsplan.
• Release Playbook — Versioning, CI/CD-pipeline en distributieprocedures.
• OKF v0.2 Compatibility Matrix — Validatieanalyse van de specificatie.
• Why OKF Agent Memory? — Gedetailleerde waardepropositie & differentiators.
• Alternatives & Ecosystem Comparison — Vergelijking met Mem0, Letta en ad-hoc markdown-bestanden.

Licentie

MIT Licentie. Zie LICENSE voor details.