OKF Agent Memory：用 Git 给 AI 编程助手装上”永不遗忘”的项目记忆，检索快到 300 微秒

AI 编程助手最大的痛点不是不够聪明，而是记不住。上下文窗口一关，昨天刚讨论清楚的架构决策、踩过的坑、定下的约定，下一次开新会话就全部归零。你只能一遍遍地把项目背景塞回去，或者眼看着它把同一个错误重犯第三遍。

CLAUDE.md、AGENTS.md 这类文件是大家目前的土办法——简单、透明，但会随着一轮轮对话无限膨胀，最后把上下文窗口塞爆；而 Mem0、Letta 那一类”记忆框架”又走向另一个极端：要跑向量数据库、要调 Embedding API、存下来的是一堆你根本没法用肉眼审阅的向量，改起来还得靠厂商 SDK。

OKF Agent Memory 给出了第三条路：把项目记忆写成 Git 仓库里纯 Markdown 的开放标准文件，配一个零依赖的 Go 工具链做检索和校验，概念搜索耗时压到 300 微秒以内。 项目 9 月 5 日建仓，几天内就冲到 500+ Star。

它到底解决什么问题

传统做法和 OKF Agent Memory 的差别，一张表就能看明白：

存储位置：向量数据库 / 远程服务器 → Git 仓库（knowledge/ 目录）

数据格式：私有 JSON / 嵌入向量 → Google OKF v0.2 标准（Markdown + 严格 YAML frontmatter）

搜索延迟：150ms – 800ms（API 调用 + 向量检索）→ < 300 微秒（纯内存 BM25）

运行成本：Embedding token 按次计费 → $0.00（完全本地、离线、零 token 开销）

透明度：不透明的向量，无法 diff → 完整可见：git diff、PR 流程、人工复核

依赖：Python venv 或外部数据库 → 零运行时依赖（纯 Go 静态二进制）

上下文导航：近似向量相似度 → 渐进式披露（分层索引 + 图谱链接）

一句话总结：本来 Mem0/Letta 用重基础设施换来的”自动记忆”，它用一个静态二进制 + 一堆 Markdown 就做到了，而且快到不需要网络往返。

核心设计：五层架构

项目的分层非常干净，把”规范”、”行为”、”工具”、”数据”拆得互不耦合：

1. OKF v0.2 规范        （标准化的 Markdown + YAML 格式）
        ↓
2. Agent Memory 约定    （行为规则：先搜索、后写入、信任分级）
        ↓
3. Agent Skill          （给 LLM 的提示词与操作工作流）
        ↓
4. 工具层：Go 库与 CLI  （确定性解析、校验、搜索、MCP）
        ↓
5. 项目知识语料          （knowledge/ 下的 OKF 知识包）

这个设计的精髓在于职责分离：让 LLM 负责”思考知识内容”，让确定性的工具负责”保证格式正确”。模型不再需要自己维护格式，也就不会把 YAML 缩进搞坏、把链接写断。

六个亮点

快到离谱的检索：内存 BM25 检索 < 300µs，整个语料解析 + 图谱校验（50+ 概念、双向图）约 4ms，冷启动 < 4ms。没有 VM 启动、没有网络往返。

100% Git 原生，零厂商锁定：一切都是受版本控制的纯文本。用 git diff、git log 就能审计 AI 的记忆，也不需要任何外部数据库。

检索零 API 成本：本地词法 BM25 索引，彻底告别反复支付的向量嵌入费用和网络往返。

构建在 Google OKF v0.2 之上：支持来源溯源（sources）、信任分级（generated 生成 vs verified 已核验）、以及生命周期元数据（status、stale_after）。

解决上下文膨胀与”记忆腐烂”：用渐进式披露（分层 index.md + 链接图谱），让 agent 只加载它真正需要的那几个概念，而不是一股脑全塞进去。

“先搜索再写入”原则：强制 agent 写新记忆前先查已有记忆，从源头杜绝概念重复和幻觉式的分叉。

跑起来只要几条命令

工具用 Makefile 构建，编出一个独立的 okf 可执行文件：

make build

然后就能用一套顺手的命令来管理记忆：

# 校验知识包一致性、图谱连通性，以及描述漂移
./bin/okf validate knowledge --strict --drift

# 用内存 BM25 打分搜索概念
./bin/okf search "architecture layers" knowledge

# 查看某个概念及其关系（支持 --json）
./bin/okf show architecture/layers knowledge --json

# 新建概念，自动维护 log.md 与 index.md
./bin/okf create decisions/auth-flow knowledge \
  --type Decision \
  --title "OAuth2 Authorization Flow" \
  --desc "Standardized on PKCE for client authentication."

# 一键把完整的 agent 记忆栈注入任意项目
./bin/okf bootstrap /path/to/project --name "My Project"

其中 bootstrap 尤其省事——它会自动在目标仓库里铺好 knowledge/ 知识包、.agents/skills/okf-memory/ 技能定义、量身定制的 AGENTS.md，以及一个 Makefile，make validate 和 make search 就位。

内置 MCP，直接接进你的编辑器

okf 自带一个基于 stdio 的原生 Model Context Protocol（MCP）服务器，可以直接连 Claude Code、Cursor、Codex 等平台：

./bin/okf mcp knowledge

配置也简单，一个 JSON 片段即可：

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

性能是怎么量出来的

项目在仓库里附带了完整的基准测试套件，可以用你自己的本地模型复现——用 LM Studio 或 Ollama 跑 Gemma、Qwen、Llama，实测首 token 时间（TTFT）的提速和约 80% 的 token 削减。跑 make benchmark 就能出结果，硬件和模型的结果日志都公开在 benchmarks/results/ 里。

基准指标	Python / 向量库（Mem0、Letta）	Deno / Node.js 方案	OKF Agent Memory（Go）
概念搜索延迟	150ms – 800ms	40ms – 120ms	< 300 微秒（内存 BM25）
全语料解析 + 图谱校验	200ms – 1.5s	80ms – 250ms	约 4.0ms（50+ 概念双向图）
进程冷启动开销	250ms – 600ms（Python VM）	80ms – 180ms（V8/Deno）	< 4ms（编译后的单二进制）
每 1000 次检索成本	约 $0.10 – $0.50	$0.00	$0.00（纯本地）
内存占用（RSS）	约 120MB – 350MB	约 60MB – 140MB	< 15MB