智能体
github.com ·
@okf_memory
OKF Agent Memory：基于Git的AI编码代理持久记忆
OKF Agent Memory 提供了一种以 Git 为基础架构的持久记忆方案，使 AI 编码代理能够跨会话保存和恢复工作上下文。该工具旨在增强代理在复杂项目中的连续性和协作能力，同时保持版本控制的一致性和可追溯性。
AI推荐理由 持久记忆是AI编码代理从原型走向实际生产的关键瓶颈。基于Git的方案能无缝融入现有开发流程，提升跨会话协作的可审计性与连续性，可能显著降低采用门槛。
78
评论 14
Star 54
社区积分 32
榜单名次 4
正文
OKF 代理记忆
一种基于开放知识格式（OKF）v0.2 的领域中立、Git 原生的 AI 代理持久项目记忆。
🌟 概述
与 AI 代理的对话在上下文窗口关闭时会重置。宝贵的架构决策、领域发现和操作事实如果不持久存储就会丢失。
OKF 代理记忆提供了一种标准化、供应商中立的记忆层，直接存在于您的仓库中（knowledge/），以带有 YAML 前置元数据的纯 Markdown 文件形式存在。它弥合了非结构化的临时 Markdown 文件（如 CLAUDE.md、AGENTS.md）与复杂的黑盒向量数据库之间的差距。
流程图 TD
L1["1. OKF v0.2 规范（规范性 Markdown 和 YAML 格式）"]
L2["2. 代理记忆约定（行为规则：搜索、审查、信任）"]
L3["3. 代理技能（LLM 提示词和操作工作流）"]
L4["4. 工具层：Go 库和 CLI（确定性解析、验证、搜索、MCP）"]
L5["5. 项目知识语料库（knowledge/ OKF 包）"]
L1 --> L2
L2 --> L3
L3 --> L4
L4 --> L5
加载中
⚡ 关键亮点
极速性能（搜索 <300µs，图验证约 4ms）：内存中的 BM25 检索和包验证在微秒内完成，无需虚拟机启动或网络往返。
100% Git 原生且零供应商锁定：所有内容都是版本控制的纯文本。使用标准的 git diff 和 git log 检查、审计和审查代理的记忆。无需外部数据库。
记忆检索零 API 成本：本地词汇 BM25 索引消除了重复的向量嵌入 API 成本和网络往返。
基于 Google OKF v0.2：使用开放标准格式存储代理知识，完全支持来源（sources）、信任层级（generated 与 verified）和生命周期元数据（status、stale_after）。
解决上下文膨胀和记忆腐烂：采用渐进式披露（分层 index.md 文件和链接图），使代理只加载他们需要的精确概念。
先搜索后写入原则：强制在编写前查询现有记忆，防止概念重复和幻觉性分歧。
零依赖 Go 工具链：单一二进制文件，零外部依赖，CLI 启动时间低于 5ms，并内置模型上下文协议（MCP）服务器（okf mcp）。
真正的领域中立：专为软件工程、教练、科学研究、文献综述和运营而设计。
📊 性能基准
okf 使用 Go 编写，零外部依赖，专为高频代理工具调用循环而设计：
基准指标
Python / 向量数据库运行时（Mem0、Letta）
Deno / Node.js 工具
OKF 代理记忆（Go）
概念搜索延迟
150ms – 800ms（嵌入 API + 向量数据库）
40ms – 120ms
< 300 µs（微秒，内存 BM25）
完整语料库解析和图验证
200ms – 1.5s
80ms – 250ms
约 4.0 ms（50+ 概念，双向图）
进程冷启动开销
250ms – 600ms（Python VM 启动）
80ms – 180ms（V8 / Deno 启动）
< 4 ms（编译后的单一二进制）
每 1000 次查询的检索成本
约 $0.10 – $0.50（嵌入令牌）
$0.00
$0.00（零 API 成本，完全本地）
内存占用（RSS）
约 120 MB – 350 MB
约 60 MB – 140 MB
< 15 MB
提示
使用您自己的 LLM 在本地复现：我们提供了一个纯 Go 的自动化基准运行器，用于在您的本地硬件上验证首令牌时间（TTFT）加速和 -80% 的令牌减少（LM Studio / Ollama 搭配 Gemma、Qwen、Llama）。运行 make benchmark 或探索渐进式披露基准套件。
🚀 快速开始
1. 构建工具
克隆仓库并编译独立的 okf 可执行文件：
make build
这将在 bin/okf 生成独立二进制文件。
2. 基本 CLI 命令
# 验证包一致性、图连通性和描述漂移
./bin/okf validate knowledge --strict --drift
# 通过内存 BM25 评分搜索概念
./bin/okf search "架构层" knowledge
# 检查概念及其关系（支持 --json）
./bin/okf show architecture/layers knowledge --json
# 创建新概念，自动维护 log.md 和 index.md
./bin/okf create decisions/auth-flow knowledge \
--type Decision \
--title "OAuth2 授权流程" \
--desc "标准化使用 PKCE 进行客户端认证。"
# 更新现有概念
./bin/okf update decisions/auth-flow knowledge \
--desc "更新了 OAuth2 PKCE 令牌刷新间隔。"
# 将完整的代理记忆栈引导到任何目标项目
./bin/okf bootstrap /path/to/project --name "我的项目"
# 在任何目录中仅初始化一个裸 OKF 包
./bin/okf init my-project/knowledge
3. 在任何项目中引导代理记忆
使用单个命令将完整的 OKF 代理记忆架构搭建到任何新仓库或现有仓库中：
# 将完整记忆栈引导到目标项目
./bin/okf bootstrap /path/to/my-project --name "我的服务"
这将自动设置：
knowledge/ — 符合 OKF v0.2 的持久记忆包（index.md、log.md）
.agents/skills/okf-memory/ — 嵌入的代理技能定义和能力指南
AGENTS.md — 为 AI 编码代理定制的操作说明
Makefile — 用于验证（make validate）和搜索（make search q="..."）的便捷任务
4. 作为 MCP 服务器运行
okf 自带一个基于 stdio 的原生模型上下文协议（MCP）服务器，可无缝连接 Claude Code、Cursor、Codex 和其他代理平台：
./bin/okf mcp knowledge
示例 MCP 配置（claude_desktop_config.json 或 Cursor）：
{
"mcpServers": {
"okf-memory": {
"command": "/path/to/okf-agent-memory/bin/okf",
"args": ["mcp", "/path/to/project/knowledge"]
}
}
}
📂 仓库结构
okf-agent-memory/
├── benchmarks/ # 渐进式披露基准套件和硬件测试数据
│ ├── data/ # 单体文档与 OKF 包测试夹具
│ └── results/ # 跨 8+ 本地和云端 LLM 的可复现基准日志
├── cmd/
│ ├── okf/ # 独立 CLI 和嵌入式 MCP 服务器（`stdio`）
│
└── okf-benchmark/ # 用于 LLM TTFT 和令牌测量的自动化基准运行器
├── docs/ # 指南、规范、架构和发布手册
│ ├── AGENT_TESTING.md # 多代理测试、提示场景和兼容性矩阵
│ ├── ALTERNATIVES.md # 与 Mem0、Letta 和临时 Markdown 的比较
│ ├── CLI.md # 完整的命令行和 MCP 工具参考
│ ├── CONVENTION.md # OKF 代理记忆约定 v0.1
│ ├── GETTING_STARTED.md # 全面的入门指南
│ ├── OKF-COMPATIBILITY.md# OKF v0.2 规范兼容性分析
│ ├── RELEASE_PLAYBOOK.md # 自动化发布流程和版本标记
│ ├── ROADMAP.md # 项目路线图和里程碑
│ └── SECURITY.md # 数据治理、秘密预防和 PII 规则
├── examples/ # 领域中立的参考 OKF v0.2 包
│ ├── books/ # 文学和认知科学知识包
│ ├── coaching/ # 高管教练和客户会话包
│ └── software/ # 微服务架构和 ADR 包
├── knowledge/ # 项目自身的 OKF v0.2 持久记忆包
│ ├── index.md # 根渐进式披露索引（okf_version: "0.2"）
│ ├── log.md # 带日期的变更日志（ISO 8601 YYYY-MM-DD）
│ ├── project/ # 概述和价值主张
│ ├── architecture/ # 5 层架构和工具决策
│ ├── convention/ # 原则和生命周期工作流
│ └── roadmap/ # 里程碑
├── packaging/ # 分发打包
│ └── homebrew/ # 官方 Homebrew 配方和 tap 说明
├── pkg/okf/ # 零依赖 Go 核心库（解析器、验证器、BM25、MCP、引导）
├── AGENTS.md # AI 编码代理的操作说明
├── CONTRIBUTING.md # 贡献指南和开发工作流
├── Makefile # 构建、测试、lint、验证和发布目标
├── LICENSE # MIT 许可证
├── README.md # 主仓库文档
└── SECURITY.md # 安全策略和报告指南
🧪 测试与验证
运行完整测试套件并验证仓库的自文档知识包：
make check
📖 进一步文档
入门指南 — 面向代理和人类的全面入门指南。
CLI 和 MCP 参考 — 完整的命令行和协议工具参考。
贡献指南 — 开发设置、质量门禁和拉取请求标准。
安全与隐私指南 — 数据治理、秘密预防和 PII 保护规则。
多代理测试与评估 — 测试场景、兼容性矩阵和基准。
OKF 代理记忆约定 v0.1 — 行为规则和生命周期规范。
项目路线图和里程碑 — 分阶段开发计划。
发布手册 — 版本控制、CI/CD 管道和分发流程。
OKF v0.2 兼容性矩阵 — 规范验证分析。
为什么选择 OKF 代理记忆？ — 详细的价值主张和差异化因素。
替代方案和生态系统比较 — 与 Mem0、Letta 和临时 Markdown 文件的比较。
📄 许可证
MIT 许可证。详情请参阅 LICENSE。
查看原文（中文正文为 AI 翻译）
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.
OKF Agent Memory provides a standardized, vendor-neutral memory layer that lives directly in your repository (knowledge/) as plain Markdown files with YAML frontmatter. It bridges the gap between unstructured ad-hoc markdown files (CLAUDE.md, AGENTS.md) and complex, black-box vector databases.
flowchart TD
L1["1. OKF v0.2 Specification(Normative Markdown & YAML Format)"]
L2["2. Agent Memory Convention(Behavioral Rules: Search, Review, Trust)"]
L3["3. Agent Skill(LLM Prompts & Operational Workflows)"]
L4["4. Tooling Layer: Go Library & CLI(Deterministic Parsing, Validation, Search, MCP)"]
L5["5. Project Knowledge Corpus(knowledge/ OKF Bundle)"]
L1 --> L2
L2 --> L3
L3 --> L4
L4 --> L5
Loading
⚡ Key Highlights
Blazing Fast Performance (<300µs Search, ~4ms Graph Validation): In-memory BM25 retrieval and bundle validation execute in microseconds without VM spin-up or network roundtrips.
100% Git-Native & Zero Vendor Lock-in: Everything is version-controlled plain text. Inspect, audit, and review your agent's memory using standard git diff and git log. No external database required.
Zero API Costs for Memory Retrieval: Local lexical BM25 indexing eliminates recurring vector embedding API costs and network roundtrips.
Built on Google OKF v0.2: Uses the open standard format for agent knowledge with full support for provenance (sources), trust tiers (generated vs. verified), and lifecycle metadata (status, stale_after).
Solves Context Bloat & Memory Rot: Employs Progressive Disclosure (hierarchical index.md files and link graphs) so agents only load the exact concepts they need.
Search-Before-Write Principle: Mandates querying existing memory before authoring, preventing concept duplication and hallucinated divergence.
Zero-Dependency Go Toolchain: Single binary with zero external dependencies, sub-5ms CLI startup time, and a built-in Model Context Protocol (MCP) server (okf mcp).
Truly Domain-Neutral: Designed for Software Engineering, Coaching, Scientific Research, Literature Reviews, and Operations.
📊 Performance Benchmarks
Built in Go with zero external dependencies, okf is engineered for high-frequency 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 (Microseconds, In-Memory BM25)
Full Corpus Parse & Graph Validation
200ms – 1.5s
80ms – 250ms
~4.0 ms (50+ concepts, bidirectional graph)
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 (Zero API cost, fully local)
Memory Footprint (RSS)
~120 MB – 350 MB
~60 MB – 140 MB
< 15 MB
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
# 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
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/
├── 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
│ ├── AGENT_TESTING.md # Multi-agent testing, prompt scenarios & compatibility matrix
│ ├── ALTERNATIVES.md # Comparison against Mem0, Letta, and ad-hoc markdown
│ ├── CLI.md # Complete command-line & MCP tool reference
│ ├── CONVENTION.md # OKF Agent Memory Convention v0.1
│ ├── GETTING_STARTED.md # Comprehensive onboarding guide
│ ├── OKF-COMPATIBILITY.md# OKF v0.2 spec compatibility analysis
│ ├── RELEASE_PLAYBOOK.md # Automated release process & version tagging
│ ├── ROADMAP.md # Project roadmap & milestones
│ └── SECURITY.md # Data governance, secret prevention & PII rules
├── examples/ # Domain-neutral reference OKF v0.2 bundles
│ ├── books/ # Literature & cognitive science knowledge bundle
│ ├── coaching/ # Executive coaching & client session bundle
│ └── software/ # Microservices architecture & ADR bundle
├── 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 & tooling 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)
├── AGENTS.md # Operating instructions for AI coding agents
├── CONTRIBUTING.md # Contribution guidelines & development workflow
├── 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
Getting Started Guide — Comprehensive onboarding guide for agents and humans.
CLI & MCP Reference — Complete command-line and protocol tools reference.
Contributing Guide — Development setup, quality gates, and pull request standards.
Security & Privacy Guidelines — Data governance, secret prevention, and PII protection rules.
Multi-Agent Testing & Evaluation — Test scenarios, compatibility matrix, and benchmarks.
OKF Agent Memory Convention v0.1 — Behavioral rules and lifecycle specification.
Project Roadmap & Milestones — Phased development plan.
Release Playbook — Versioning, CI/CD pipeline, and distribution procedures.
OKF v0.2 Compatibility Matrix — Specification validation analysis.
Why OKF Agent Memory? — Detailed value proposition & differentiators.
Alternatives & Ecosystem Comparison — Comparison with Mem0, Letta, and ad-hoc markdown files.
📄 License
MIT License. See LICENSE for details.