OKF Agent Memory：Agent 记忆不需要向量数据库，300 微秒的 BM25 就够了

OKF Agent Memory：Agent 记忆不需要向量数据库，300 微秒的 BM25 就够了

会话一关，Agent 就失忆。给它一个 git 仓库当大脑。

所有用过 AI 编码 Agent 的人都撞过同一堵墙：昨天聊好的架构决策、上周发现的领域知识、踩过的坑，今天全忘了——上下文窗口一关，一切归零。现有的解法各有各的别扭：CLAUDE.md、AGENTS.md 这类随手记的 Markdown 文件，能存但没有结构、没有检索、没有生命周期；Mem0、Letta 这类记忆框架，功能全但引入了向量数据库、Embedding API 和一个你看不见的黑盒。

OKF Agent Memory 给出了第三个答案：Agent 的记忆，就是一个 git 仓库。基于 Google 的 Open Knowledge Format（OKF）v0.2 规范，把持久记忆存成仓库里 knowledge/ 目录下的纯 Markdown + YAML frontmatter，用本地 BM25 检索替代向量库，Go 单二进制交付，内置 MCP 服务器。零外部依赖，零 API 成本，零厂商锁定。

本文提纲

  1. 五层架构：从规范到语料
  2. 为什么"记忆是 git 仓库"是个好主意
  3. 性能：微秒级检索怎么来的
  4. 两个关键设计：渐进式披露与先搜后写
  5. 信任分层：generated 与 verified
  6. 上手：从 build 到 MCP 五分钟
  7. 放进生态里看：和 Mem0、CLAUDE.md 的位置
  8. 客观提醒：新项目的三个注意点

五层架构：从规范到语料

项目分五层，每层职责清晰：

MERMAID_BLOCK_0

最底下是 OKF v0.2 规范——开放的 Markdown + YAML 格式标准；往上是行为约定（何时搜索、何时评审、如何定信任）；再到 Agent Skill 层（提示词与工作流，可直接被 Claude Code、Codex 等消费）；第四层是 Go 工具链（确定性解析、校验、搜索、MCP）；最上面落在每个项目自己的 knowledge/ 语料上。

这个分层本身就是卖点：格式是开放规范，行为是约定，工具是开源实现——任何一层都可以被替换，记忆语料永远是你自己的纯文本。

为什么"记忆是 git 仓库"是个好主意

传统记忆框架的记忆存在向量数据库里——你能查，但不能读；能导出，但不能 diff。OKF Agent Memory 把记忆变成 git 追踪的纯文本后，几件事自然发生了：

可审计。Agent 今天新学到了什么、改了哪条旧记忆？git log 和 git diff 直接看。Agent 幻觉一条错误知识写进记忆，code review 就能拦住——记忆变更第一次拥有了 PR 流程。

可迁移。换 Agent 平台、换模型、换厂商，knowledge/ 目录拷走就是全部记忆。没有导出脚本，没有格式转换。

零成本。检索用本地 BM25 词法索引，不需要 Embedding API。按官方数据，每千次检索成本为零——对照向量方案每千次约 $0.10-0.50 的 Embedding token 开销。

自举。这个项目自己的 knowledge/ 目录就是用它管理的：架构决策、规范分析、路线图全在里面，README 称之为"self-documenting"——吃自己的狗粮，且这份狗粮你可以直接翻看。

性能：微秒级检索怎么来的

官方基准数据（Go 零依赖实现，为高频 Agent 工具调用循环设计）：

指标 Python / 向量库（Mem0、Letta） Deno / Node.js 工具 OKF（Go）
概念检索延迟 150ms – 800ms（Embedding API + 向量库） 40ms – 120ms < 300 µs（内存 BM25）
全语料解析 + 图校验 200ms – 1.5s 80ms – 250ms ~4 ms（50+ 概念双向图）
进程冷启动 250ms – 600ms（Python VM） 80ms – 180ms < 4 ms（编译单二进制）
每千次检索成本 ~$0.10 – $0.50 $0.00 $0.00
内存占用 ~120 – 350 MB ~60 – 140 MB < 15 MB

三个数量级的差距，来源不是黑魔法，是架构选择：记忆文件本来就在本地磁盘，词法检索在进程内存里做，没有网络往返、没有 VM 启动、没有外部服务。向量方案的开销大头（Embedding 调用 + 向量库查询）在"单项目级语料"这个规模下本来就不是必需品——一个项目的知识库撑死几百个概念，BM25 完全够用。

项目还提供了可复现的基准套件（make benchmark），用 LM Studio / Ollama 跑本地模型（Gemma、Qwen、Llama），验证渐进式披露带来的首 token 延迟（TTFT）改善和约 80% 的 token 缩减。结果日志覆盖 8+ 本地与云端模型，都提交在仓库里。

两个关键设计：渐进式披露与先搜后写

渐进式披露（Progressive Disclosure）解决上下文膨胀：knowledge/ 里是分层 index.md + 概念间的链接图，Agent 启动时只加载根索引，需要哪个概念再深入哪个——而不是把整个记忆库一股脑塞进上下文。这直接对标了"把所有文档堆进 CLAUDE.md"的粗暴做法。

先搜后写（Search-Before-Write）解决记忆腐烂：行为约定强制 Agent 在写入新记忆前先检索现有记忆，命中就更新，未命中才创建。防止的正是 Agent 记忆最常见的病——同一个概念被反复创建成五个略有出入的版本，然后每个都不对。

每个概念还带生命周期元数据：status（状态）、stale_after（过期时限）——记忆有了保质期，过期知识会被标记而不是永远冒充事实。

信任分层：generated 与 verified

OKF v0.2 规范里我认为最被低估的设计：每条知识都标注信任层级——

  • generated：Agent 自己推断、生成的知识，未经确认
  • verified：经过人工或流程确认的知识

加上 sources 字段记录来源，Agent 的记忆第一次有了"这条结论是怎么来的、可不可信"的元信息。这在 Agent 自主性越来越强的当下尤其重要：当 Agent 基于记忆做决策时，它能区分"这是用户确认过的约束"和"这是我上次自己猜的"。很多向量记忆方案根本不存这个维度——检索出来的是知识，分不出成色。

上手：从 build 到 MCP 五分钟

# 1. 编译单二进制
git clone https://github.com/okf-memory/okf-agent-memory
cd okf-agent-memory && make build

# 2. 给任意项目装上完整记忆栈
./bin/okf bootstrap /path/to/my-project --name "My Service"

bootstrap 一条命令铺好四样东西：knowledge/ 记忆语料（含 index.md、log.md）、.agents/skills/okf-memory/ Agent 技能定义、定制化的 AGENTS.md 操作说明、带校验和搜索任务的 Makefile。

日常 CRUD 全靠 CLI：

# 校验规范符合性、图连通性、描述漂移
./bin/okf validate knowledge --strict --drift

# BM25 搜索
./bin/okf search "architecture layers" knowledge

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

接入 Claude Code、Cursor、Codex 则用内置 MCP 服务器：

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

okf mcp 走 stdio 协议，无需常驻服务——Agent 调用时拉起，用完即走，配合 <4ms 冷启动毫无感。

放进生态里看：和 Mem0、CLAUDE.md 的位置

把三类方案摆在一起，定位就清楚了：

随手 Markdown（CLAUDE.md / AGENTS.md） 向量记忆框架（Mem0 / Letta） OKF Agent Memory
存储 纯文本，git 友好 向量数据库 纯文本，git 原生
检索 靠模型自己读全文 语义检索，需 API 本地 BM25 词法检索
结构 无 有 schema OKF 规范 + 链接图
可审计 人工 diff 黑盒 git diff / PR 流程
成本 零 Embedding API 持续开销 零
适用 小项目速记 海量跨项目记忆 单项目级持久记忆

它卡在中间那个空档上：比随手记的 Markdown 多了结构、检索和生命周期，比向量框架少了黑盒、成本和运维。官方也直言不讳这个定位——docs/ALTERNATIVES.md 里自己把 Mem0、Letta 和 ad-hoc Markdown 拉来对比过一轮。

这个项目还能嵌进我们之前聊过的几条线里：它印证了 Spotify 那篇文章的教训——CLAUDE.md 式的自由文本不可靠，结构性约束（先搜后写、信任分层）才是规模化的前提；它的 Agent Skill 分发方式与 Nature Skills 同一浪潮——技能作为 Agent 的可安装能力；而内置 MCP 服务器则与 microsoft/mcp 代表的方向合流——记忆作为一种标准化的 Agent 工具服务。Agent 基础设施的各个零件，正在各自完成"从随用到标准化"的进程。

客观提醒：新项目的三个注意点

热情之外，三点需要说在前面：

这是一个非常新的项目。仓库主分支目前只有一个 commit，MIT 协议，文档和基准数据齐全但社区还在起步阶段。生产采用前需要自己评估维护风险。

词法检索不等于语义检索。BM25 靠词项匹配，"部署失败"搜不到写的是"发布回滚"的内容。单项目语料规模下问题不大（术语相对统一），但跨领域、多语言混写的记忆库会有召回盲区——这是架构选择的固有取舍，不是实现瑕疵。

价值依赖流程 adoption。渐进式披露、先搜后写这些约定，需要 Agent 平台真正遵守行为规范才生效。项目提供了 Skill 和 AGENTS.md 来引导，但"约定"的执行力终究弱于"强制"——这和 Spotify 用 Hook 而不是 CLAUDE.md 管控路由，是同一个道理。

但方向是对的：Agent 记忆的下一步，不是更大的向量库，而是更透明、可审计、可迁移的知识管理。OKF Agent Memory 把这条路走到了一个完整的开源实现——就算你不用它，它对"记忆应该是 git 仓库"这个命题的论证，也值得每一个做 Agent 工程的人读一遍。

作者: itech001
来源: 公众号：AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。

posted @ 2026-09-06 09:32  iTech  阅读(15)  评论(0)    收藏  举报