okf-memory/okf-agent-memory · 上手攻略

• 仓库：okf-memory/okf-agent-memory
• 链接：https://github.com/okf-memory/okf-agent-memory
• 分类：ai（AI 编码代理 / Agent 基础设施）
• 作者：spark
• 更新：2026-09-10

是什么

okf-agent-memory 是一个面向 AI 编码代理（Claude Code、Cursor、Codex、Gemini CLI 等）的 Git 原生持久化记忆层。它把项目里的"长期知识"以符合 Google Open Knowledge Format（OKF）v0.2 规范的 Markdown + YAML frontmatter 文件形式，存在仓库的 knowledge/ 目录下，完全不用向量数据库、不用外部依赖，由 Go 实现的 okf 单文件二进制提供解析、校验、BM25 搜索和 MCP 服务。

设计上，它处于两个极端之间：

• 一端是 CLAUDE.md / AGENTS.md 之类的临时 Markdown：人类手写、零结构、零检索、零校验。
• 另一端是 Mem0、Letta 这类基于嵌入 + 向量库的运行时记忆：要 Python VM、要外部服务、要钱。

OKF Agent Memory 用"标准化 Markdown + 内嵌 BM25 + Go 二进制"这条中间路线，把"项目知识"做成可审计、可校验、可被 Git 跟踪的版本化资产。

仓库自带一个 5 层架构（L1 OKF 规范 → L2 记忆协议 → L3 Agent Skill 提示词 → L4 Go CLI/MCP → L5 项目 knowledge/ 包），并随包发布一份"自指"知识库（仓库自己的 knowledge/），因此它是个会"自吃狗粮"的项目。

解决什么问题

AI 编码代理的上下文窗口一关，重要的架构决策、领域发现、踩坑记录就丢了。再开一个 session，要么 agent 重复造轮子，要么用户得反复粘背景。OKF Agent Memory 想把这件事做成"基础设施默认行为"：

1. 跨 session / 跨 agent 厂商接续：在 Claude Code 里写到一半，跑去 Codex / Cursor，记忆仍然可用。
2. 避免幻觉式回忆：agent 在动手前必须 okf search 查现有概念，遵循 Search-Before-Write 规则。
3. 零运维：没有 daemon、没有数据库迁移、没有 API key、没有云服务——纯静态文件 + 一个二进制。
4. 可审计：所有写入都是 Git diff，符合 OKF v0.2 规范的可被 okf validate --strict --drift 校验。
5. 大幅省 token：README 自报比嵌入 + 向量库的方案省约 80% token。

快速安装

⚠️ 下面三条命令以 README 与 docs/GETTING_STARTED.md 为准；版本号请以 releases 页为准。

方案 A：Homebrew（macOS / Linux）

brew install okf-memory/tap/okf
okf version   # 验证

方案 B：直接下载二进制

# macOS Apple Silicon 示例
curl -L -o okf \
  https://github.com/okf-memory/okf-agent-memory/releases/latest/download/okf-darwin-arm64
chmod +x okf
sudo mv okf /usr/local/bin/
okf version

方案 C：从源码构建（需要 Go 1.22+）

git clone https://github.com/okf-memory/okf-agent-memory.git
cd okf-agent-memory
make build
# 产物在 bin/okf

核心用法

1) 在已有仓库里植入记忆层

cd /path/to/my-project
okf bootstrap . --name "My Project"

bootstrap 会一次性创建四个东西：

• knowledge/：OKF v0.2 知识包（含根 index.md 和 log.md）。
• .agents/skills/okf-memory/：给 agent 读的 skill 提示词。
• AGENTS.md：写好"先搜后写"等协议。
• Makefile：方便 make validate、make search q="..." 的快捷任务。

2) 校验包合规

okf validate knowledge --strict --drift
# 0 errors / 0 warnings 即合规

--strict 强制 OKF v0.2 规范；--drift 比对文件夹 index.md 的描述与概念 frontmatter 是否一致。

3) 搜索 / 检视概念

okf search "architecture layers" knowledge
okf show architecture/layers knowledge
okf show architecture/layers knowledge --json

搜索用内存 BM25，README 自报 < 300µs。show 会展示一个概念及其双向图谱关系。

4) 创建与更新概念

okf create decisions/auth-flow knowledge \
  --type Decision \
  --title "OAuth2 Authorization Flow" \
  --desc "Standardized on PKCE for client authentication."

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

okf relate decisions/cache-ttl architecture/backend knowledge \
  --desc "Backend uses Redis TTL config"

create 会自动维护 log.md（ISO 8601 日期）和对应文件夹的 index.md，开发者不用手动维护索引。

5) 启动内嵌 MCP 服务

./bin/okf mcp knowledge

在 Claude Desktop / Cursor 的 MCP 配置里注册（stdio 协议）：

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

接入后，agent 会自动获得这些工具：okf_search、okf_show、okf_create、okf_update、okf_relate、okf_validate。

6) Agent 的 4 步循环

User:  "实现 feature X / 重构模块 Y"
  ↓
Agent → okf search "feature X architecture"   ← 强制先搜
  ↓
Agent 在持久上下文里执行任务
  ↓
Agent → okf create / update 记录决策与发现
  ↓
Agent → okf validate knowledge --strict      ← 收尾校验

典型适用场景

• 跨 session 续命：Claude Code 会话被压缩 / 关闭后，新 session 仍能读到上次的关键决策。
• 跨厂商接续：在 Claude Code、Cursor、Codex 之间无缝切换而不丢上下文（项目里同一份 knowledge/）。
• 多人 + 多 agent 协作：所有 agent 共享同一份可 diff 的知识库，PR review 可以审"记忆变更"。
• 长周期项目：架构 ADR、合规规则、领域 schema、踩坑记录，全部沉淀成 Git-tracked Markdown。
• 预算敏感场景：不想付 Mem0 / Letta 的嵌入 token 成本，又嫌裸 Markdown 没结构。
• 本地优先 / 离线开发：无网络也能跑（搜索、校验都不需要外部 API）。

坑与注意

⚠️ 几条实际使用中需要小心的点：

1. BM25 ≠ 语义检索：是经典词频 + 字段加权，没有向量语义。对"近义词、改写、跨语言"召回不如嵌入方案；遇到查不到时建议用 okf show 直接按 ID 翻。
2. 写"记忆"前必搜：协议里 Search-Before-Write 是硬规则。直接 create 重复内容会产生大量"v2、v3"变体；务必先 okf search，命中就 update，不要新建。
3. frontmatter 不要伪造人类署名：generated: { by: "agent/", at: "..." } 必须是 agent 自填，不要写假的人类验证。
4. 校验频率：--strict --drift 在 session 结尾跑一次是基线；中途改完 knowledge/ 后建议本地再跑一遍，避免 PR 出现不一致。
5. 二进制依赖：okf 必须能在 agent 启动时调到（PATH 或绝对路径）。Windows 下 make build 输出位置与 Unix 不同，建议直接用 Release 页下载。
6. OKF 版本演进：仓库目前对齐 OKF v0.2；上游 Google Cloud knowledge-catalog 规范未来若升 v0.3+，需要看 docs/OKF-COMPATIBILITY.md 跟版本。
7. 不要把会话原文塞进 knowledge/：协议禁止存聊天记录、临时 scratch、未经消化的猜测——只沉淀决策、schema、业务规则、API 契约这类"耐用事实"。
8. 大规模语料性能：README 给的 < 300µs 是小语料（~50 concepts）下量级；上千概念后的延迟曲线建议自己跑 make benchmark。

与同类对比

维度	OKF Agent Memory	Mem0 / Letta	裸 Markdown（CLAUDE.md / AGENTS.md）
检索	内存 BM25，< 300µs	嵌入 + 向量库，150-800ms	无
依赖	一个 Go 二进制	Python VM + 向量库 + API key	无
Token 成本（每 1k 次检索）	$0	$0.10–0.50	$0
RSS 内存	< 15 MB	120-350 MB	< 1 MB
冷启动	< 4 ms	250-600 ms	0
校验	okf validate --strict	无	无
跨 agent 接续	✅（同 knowledge/）	部分	文件级复制
Git 可审计	✅（纯文本 diff）	❌	✅

定位很清晰：只要不想养数据库、又要有点结构化，就比裸 Markdown 强；只要需要"语义级"召回（近义、改写、跨语言），还是得回 Mem0 / 向量方案。

一句话推荐结论

如果你厌倦了在 Claude Code / Cursor / Codex 之间反复解释项目背景，又不想给 Mem0 付嵌入 token、也不想自己搭向量库——okf bootstrap . 一条命令把"项目级持久记忆"装进 Git，是目前最轻量、最可审计的方案。强烈推荐给任何中型以上、跨 session / 跨 agent 协作的工程项目。

---

来源

• GitHub README：https://github.com/okf-memory/okf-agent-memory （fetched 2026-09-10）
• Getting Started：https://github.com/okf-memory/okf-agent-memory/blob/main/docs/GETTING_STARTED.md （fetched 2026-09-10）
• 项目定位 + 安装命令基于 docs/GETTING_STARTED.md 与 README Installation 段；具体版本号与二进制命名以官方 Releases 页为准
• 对比表数据来自 README 内的 "Blazing Fast Performance" benchmark 表
• Hacker News 发布帖：https://news.ycombinator.com/item?id=49581249 （验证 Homebrew tap 与 README 一致）

不确定处

• ⚠️ 当前 okf 的最新版本号：未直接抓 releases 页，README 示例中只看到 v0.1.0（HN 帖）与 0.5.0（ai4s-research/open-science 那个无关项目的 CITATION 引用混淆来源）；本仓库的版本号请以 https://github.com/okf-memory/okf-agent-memory/releases 为准
• ⚠️ Windows 安装路径：make build 在 Windows 上需要 MinGW / WSL；建议直接走 Release 二进制，未单独验证
• ⚠️ Cursor / Windsurf / Antigravity 的 MCP 配置段摘自 docs/GETTING_STARTED.md，但具体 UI 路径会随 IDE 版本变化