okf-agent-memory

这是什么？适合谁？

OKF Agent Memory 是一个 Git 原生、供应商中立的 AI Agent 持久项目记忆层，基于 Google Cloud 开源的 Open Knowledge Format (OKF) v0.2 规范实现。它解决的是 AI 编码代理的核心痛点：上下文窗口一关，对话里积累的架构决策、领域发现和运维事实全部丢失。

它的定位很明确——填补两个极端之间的空白：一端是松散的 ad-hoc Markdown（CLAUDE.md、AGENTS.md，无结构无检索），另一端是黑盒向量数据库（供应商锁定、需嵌入 API、成本与延迟）。OKF Agent Memory 把记忆直接放在你的仓库里（knowledge/ 目录），纯 Markdown + YAML frontmatter，用 git diff 和 git log 就能审计 agent 的记忆变化。

核心价值：零依赖 Go 单二进制 + 内存 BM25 检索（<300µs）+ 全量图校验（~4ms）+ 内置 MCP Server，检索零 API 成本，全文本版本化。

适合人群：

• 受困于「agent 每次开新会话都失忆」的 AI 编码重度用户（Claude Code / Codex 等）
• 想给项目建立可审计、可 review 的知识库（决策/概念/流程）的工程团队
• 需要领域中立记忆层的研究、教练、文献综述、运维等非纯编程场景

使用前提：Go 1.26 工具链（构建单二进制）；可选任一支持 MCP 的 agent runtime。

准备工作

1. 环境：Go 1.26+（go version 自查）；仓库自带零外部依赖
2. 成本：MIT 开源免费；检索走本地 BM25，零嵌入 API 成本、零网络调用
3. 时间：make build 约 1 分钟；bootstrap 一个项目记忆栈约 10 秒
4. 规格背景（可选阅读）：OKF v0.2 规范——记忆条目带 sources 溯源、generated vs verified 信任分级、status/stale_after 生命周期元数据

快速上手（3 步）

第一步：构建工具

git clone https://github.com/okf-memory/okf-agent-memory.git && cd okf-agent-memory
make build    # 产出独立二进制 bin/okf

第二步：给项目装上记忆栈

# 把完整 agent memory 架构脚手架进任意新/已有仓库
./bin/okf bootstrap /path/to/my-project --name "My Service"

一条命令自动建好：knowledge/（OKF v0.2 合规记忆 bundle：index.md + log.md）、.agents/skills/okf-memory/（内嵌 agent 技能定义）、AGENTS.md（面向 AI 编码 agent 的项目级操作说明）、Makefile（make validate / make search 便捷任务）。

第三步：验证 + 创建第一个概念

# 严格模式校验 bundle 一致性、图连通性与描述漂移
./bin/okf validate knowledge --strict --drift

# 创建一个新概念（自动记 log.md 与 index.md 台账）
./bin/okf create decisions/auth-flow knowledge \
  --type Decision \
  --title "OAuth2 Authorization Flow" \
  --desc "Standardized on PKCE for client authentication."

预期结果：validate 通过（无图断链、无漂移）；knowledge/decisions/auth-flow/ 出现带 YAML frontmatter 的概念文件，log.md/index.md 自动更新。

初级用法

搜索记忆（BM25，微秒级）

./bin/okf search "architecture layers" knowledge

内存 BM25 打分，无嵌入 API、无网络往返——agent 高频工具调用循环里也不会成为瓶颈。

查看概念与关系图

./bin/okf show architecture/layers knowledge --json   # 机器可读输出

概念之间是双向链接图；validate --strict 会校验图连通性。

更新概念

./bin/okf update decisions/auth-flow knowledge \
  --desc "Updated OAuth2 PKCE token refresh interval."

高级玩法

挂成 MCP Server

okf mcp    # 内置 Model Context Protocol server

任何 MCP 就绪的 agent（Claude Code、Codex 等）都能把 okf search / okf show 当工具直接调用，记忆检索进 agent 主循环。

渐进披露（Progressive Disclosure）控制上下文膨胀

记忆 bundle 用层级 index.md + 链接图组织，agent 只加载当下需要的概念——官方基准称在本地 LLM（LM Studio / Ollama）上可复现 TTFT 提速与约 -80% token 缩减，make benchmark 可自行验证。

Search-Before-Write 防记忆腐化

Agent 记忆约定强制「先查再写」：写新概念前必须先搜既有记忆，防止概念重复与幻觉分叉。配合 --drift 漂移检测，长期项目的记忆不会烂掉。

小技巧

1. 把 ./bin/okf validate knowledge --strict --drift 挂进 CI——记忆库和代码一样享受门禁
2. 善用信任分级：generated（agent 产出）与 verified（人核验过）分开标注，review 时只看 generated 条目
3. stale_after 元数据让过时知识自动显形，别靠人脑记
4. 记忆全在 knowledge/ 里的纯文本——code review 时把 git diff knowledge/ 纳入正常评审流
5. okf init my-project/knowledge 可以只初始化裸 bundle，不引入整套脚手架

常见踩坑

踩坑 1：期待向量语义搜索

• 现象：用同义改写搜不到概念
• 原因：检索是 BM25 词法打分，不是向量语义检索——这是刻意的取舍（零 API 成本、零网络、微秒延迟）
• 解决：搜索词用概念原文关键词；真需语义检索可自建外层，但会失去零成本优势
  • 来源：官方 README

踩坑 2：validate --strict 报图断链

• 现象：概念创建后校验失败
• 原因：手工编辑时删了被引用的概念，或 related 指向不存在的 ID
• 解决：用 okf create/okf update 而非手改文件，让台账自动维护；断链了按报错补齐或删引用

踩坑 3：Go 版本过低构建失败

• 现象：make build 报语法错误
• 原因：项目按 Go 1.26 工具链编写
• 解决：升级 Go 后重跑；二进制构建一次到处运行，CI 里可用 release 产物

踩坑 4：把 OKF 记忆当成了向量数据库的替代品去装

• 现象：想接 Pinecone/Postgres 的既有语料
• 原因：OKF Agent Memory 定位是「项目记忆层」，不是通用向量库
• 解决：既有大规模语料继续走向量库；OKF 管 agent 工作产出的结构化决策与概念

踩坑 5：多 agent 并发写冲突

• 现象：两个 agent 同时 create 概念互相覆盖
• 原因：记忆是 Git 原生纯文本，并发写遵循 Git 规则
• 解决：走正常 Git 分支/合并流程；log.md 的操作台账让冲突可追溯

常见问题 FAQ

Q1: 它和 CLAUDE.md / AGENTS.md 这类文件的区别？

A: CLAUDE.md/AGENTS.md 是无结构的单文件备忘，无检索、无校验、无生命周期。OKF Agent Memory 提供标准化条目（溯源/信任分级/状态元数据）、BM25 检索、图校验和 MCP 集成——README 明确将其定位为两者之间的中间层。

Q2: 性能真的比 Mem0/Letta 这类向量方案快吗？

A: 官方基准表：概念检索 <300µs（对比向量方案 150-800ms）、全量图校验 ~4ms、冷启动 <4ms、RSS <15MB。数据来自官方 README，本地可用 make benchmark 复现——建议以自测为准。

Q3: 免费吗？有供应商锁定吗？

A: MIT 开源，全本地运行，零嵌入 API 成本；格式是 Google Cloud 开源的 OKF v0.2 规范，纯文本可随时迁出。

Q4: 哪些场景算「领域中立」？

A: 规格设计覆盖软件工程、教练、科研、文献综述、运维等——记忆条目类型（Decision/Concept/Flow 等）不绑定编程语义。

Q5: MCP 怎么接？

A: okf mcp 启动内置 MCP Server，MCP 就绪的 agent 可直接把 search/show 当工具用；不用 MCP 也能走 CLI（.agents/skills/ 里的技能定义教 agent 用命令行）。

进阶学习建议

1. 读 OKF v0.2 规范的溯源（sources）、信任分级（generated/verified）与生命周期（status/stale_after）三组元数据——它们是这套记忆层区别于裸 Markdown 的全部结构性所在
2. 跑 make benchmark 在自己的本地 LLM（LM Studio / Ollama + Gemma/Qwen/Llama）上复现 TTFT 与 token 缩减数据，验证渐进披露的实际收益
3. 把 okf validate --strict --drift 接入 CI、把 git diff knowledge/ 纳入 code review，建立「记忆即代码」的完整门禁
4. 读 .agents/skills/okf-memory/ 里的 Agent Memory Convention（Search-Before-Write、信任规则），理解这套行为约定如何防止记忆腐化

参考链接

• 官方仓库
• OKF v0.2 规范（GoogleCloudPlatform/knowledge-catalog）
• README（性能基准 / Quickstart / Bootstrap）

最后更新：2026-09-07 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成