跳到正文
heyaican
中文EN

OKF Agent Memory

把编码 agent 学到的东西以纯 Markdown 留在仓库里——一个用进程内 BM25 检索的 OKF v0.2 知识 bundle——于是这份记忆可以被 diff、被审阅，而不必住进数据库。

打开看看 源码 提交更正
Screenshot of OKF Agent Memory
编辑截图， 30 Sep 2026OKF Agent Memory ↗

这是什么

OKF Agent Memory 是给 AI 编码 agent 用的一层记忆：agent 学到的东西以纯 Markdown 留在仓库里，而不是存进数据库。知识放在一个 OKF v0.2 bundle 里——knowledge/ 目录下带 YAML frontmatter 的概念文件、分层的 index.md 和按日期记的 log.md——并靠进程内的 BM25 检索取回，不用向量嵌入。它的对象是在一个仓库上跑编码 agent 的人（README 点名 Claude Code、Cursor、Codex 等 MCP 客户端），以及希望 agent 的决定能用 git diff 审阅的人。安装是克隆后跑 make build，产出独立可执行文件 bin/okf。随后 ./bin/okf validate knowledge --strict --drift 校验 bundle，./bin/okf search "architecture layers" knowledge 检索，./bin/okf show architecture/layers knowledge --json 打印单个概念及其关系，./bin/okf bootstrap /path/to/my-project --name "My Service" 把整套东西——bundle、AGENTS.md、agent skill 与 Makefile——铺进另一个仓库。MCP 服务器以 stdio 运行：./bin/okf mcp knowledge，在 claude_desktop_config.json 或 Cursor 的 MCP 设置里注册；make check 跑测试，make benchmark 跑本地基准，./bin/okf hub init-vault、hub push 与 hub sync 负责可选的加密同步。

谁做的一个组织账号而不是个人：仓库全名是 okf-memory/okf-agent-memory，元数据里没有所有者资料。改动严重偏一侧——167 次提交里 144 次挂在 sknr 账号下（142 次署名 sknr，2 次署名 Stephan Knauer），12 次来自 google-labs-jules[bot]，5 次来自 denis-samatov，3 次来自 dependabot[bot]，2 次来自 yakimoto，1 次来自 dajiaohuang；贡献者列表上的六个名字就是这些账号。赞助链接在 funding 文件与 README 徽章里都指向 github.com/sponsors/sknr，这是材料里唯一露出的维护者身份。

它是怎么搭起来的

组成 · 6

一个围绕 Markdown 约定搭建的 Go 库加命令行，分五层写明：最下面作为契约的 OKF v0.2 格式，其上一层项目约定，再往上是 agent skill 与一套写说明书的微语法，然后是工具本身，最上面是知识语料。工具层刻意不带依赖——go.mod 140 字节、go.sum 312 字节——所有事都在进程内做完：解析并校验 bundle、在概念上建一个内存 BM25 索引、以 stdio 提供六个 MCP 工具、把同一套目录铺进另一个仓库。两个后果塑造了树里的其余部分。因为记忆是一份纯文本 bundle，每次写入都要经过那些必须让 frontmatter、index.md 与 log.md 保持一致的函数，这就是为什么改动与校验的代码是库里最大的一块，也是为什么这个仓库里的安全工作几乎总是路径包含问题。又因为这份 bundle 要能在维护者看不见内容的情况下在机器之间往返，另有一对独立的包实现加密 Hub：一边是密钥派生与信封格式，另一边是客户端、引擎、对账与日志合并。

pkg/okf/
核心库：39 个文件、343 KB，最大的是 mcp.go（21,338 字节）、mutate.go（19,300）、parser.go（13,713）、search.go（13,037）、validator.go（12,616）、bundle.go（10,377）、filter.go（8,893）、bootstrap.go（6,429）、domains.go（6,246）、symlink.go（5,676）、types.go（4,321）与 586 字节的 path.go，另有 pkg/okf/aag/linter.go（6,231）和 13,572 字节的 pkg/okf/schemas/tools.json。测试和代码一样重：mcp_test.go 51,526 字节、okf_test.go 37,059、mutate_security_test.go 33,072。
pkg/sync/ 与 pkg/vault/
Hub，也是整个项目里唯一联网的部分。十二个文件、82 KB，装着引擎、客户端、hub、服务端、对账与日志合并；另有九个文件、33 KB，装着密钥派生、信封、树与提交的机制。knowledge/architecture/zero-knowledge-vault-sync.md（5,188 字节）记录它，命令面是 hub init-vault、hub push 与 hub sync。
cmd/ 与 internal/cli/
库之上的薄入口：cmd/okf/main.go 只有 842 字节，internal/cli/ 下的 14 个命令文件共 66 KB——agents.go（10,675）、mutate.go（10,099）、search.go（7,821）、validate.go（5,787）、hub.go（5,666）、scaffold.go（3,967）、registry.go（3,698）、root.go（2,047），每个都配了测试。基准运行器单独放着，是一个文件：cmd/okf-benchmark/main.go，62,626 字节。
knowledge/
项目自己的 bundle，被当作它的工作记忆来用：index.md（1,844 字节）与 log.md（15,964），architecture/ 下十个文件共 24 KB，含 governance-model.md（5,683）、security-boundaries.md（3,899）、zero-knowledge-vault-sync.md（5,188）、layers.md（3,025）、tooling-decision.md（2,816）；convention/ 下九个文件共 31 KB，含 coding-standards.md（6,093）、dual-memory-architecture.md（5,224）、release-procedure.md（4,108）；另有 project/、roadmap/milestones.md（4,616）与 requirements/mutation-metadata.md（923）。
docs/
四份规范共 46 KB——CONVENTION.md（17,031）、AGENT_ACTION_GRAMMAR_RFC.md（16,980）、DUAL_MEMORY_AGENT_ARCHITECTURE_RFC.md（7,362）、OKF-COMPATIBILITY.md（6,241）；五份指南共 44 KB，以 CLI.md（12,540）、AGENT_INSTRUCTION_BEST_PRACTICES.md（11,767）、BENCHMARKING_METHODOLOGY.md（7,133）为首；项目文档里有 14,543 字节的路线图和一份发布手册；两份安全文档；以及从 v0.1.0 到 v0.4.4 的十六个 release note 文件。
agent 材料、示例与打包
AGENTS.md（2,191 字节）旁边是各九字节的 CLAUDE.md、.cursorrules、.windsurfrules，以及十二字节的 .github/copilot-instructions.md。agent skill 是 .agents/skills/okf-memory/ 下的六个文件，与 pkg/okf/assets/skill/ 体积逐一相同，由 make sync-assets 保持同步。三套示例语料各十三个文件，把这份 bundle 用在软件、教练与书籍上；benchmarks/ 里有一份 3,862 字节的 README、含 11,504 字节单体文档的夹具，以及七个结果文件；1,895 字节的 Homebrew formula 模板与 7,165 字节的 Makefile 负责构建与分发。

取舍，以及它替代了什么

  • 用 git 里的纯 Markdown，而不是数据库或向量库 替代 一个嵌入索引或托管记忆 API

    这被写成设计的性质，并且是拿被点名的替代方案论证的：「100% Git-Native & Zero Vendor Lock-in」，一切以纯文本进版本控制，「No external database required」；以及「Zero API Costs for Memory Retrieval」，因为「Local lexical BM25 indexing eliminates recurring vector embedding API costs and network roundtrips」。被否掉的那条路在 README 开头就被点名：它把「把行为规则倒进向量数据库」称作「The RAG Blindspot」，理由是 agent 在普通任务里根本不会去语义检索操作约束。

  • 两层记忆加一个 token 预算，而不是一个巨大的说明书文件 替代 把一切都塞进 AGENTS.md——README 管它叫「The Prompt Monolith」

    预算被写了下来：推送层「Strictly capped at 100–150 tokens」，拉取层因为按需取用而是「0 tokens in initial system prompt」。组合规则被写成一条等式「AGENTS.md = Domain Codex + OKF Memory Bridge」，其中 codex 用一种紧凑微语法写，README 说它比自然语言说明书省「~78–85% tokens」。

  • 先检索再写入，并且不许直接扫这个 bundle 替代 让 agent 想怎么读这个知识目录就怎么读

    README 写出原则与目的——「Search-Before-Write Principle: Mandates querying existing memory before authoring, preventing concept duplication and hallucinated divergence」——而项目自己的 AGENTS.md 把它变成 agent 必须遵守的规则：提架构或依赖前先用 limit=3 检索，并且绝不用 list_dir、grep_search、find 或裸读取器去读 knowledge/。

  • 人工校验不允许被一次工具调用声明 替代 让 agent 把某个概念标成已人工核验

    规则写在 AGENTS.md 里——「NEVER forge human verification (verified: is human-only)」——而仍未合并的 pull request 43 显示它在代码里被追着落实：此前「there was no logic preventing an agent from inserting a human: prefix in the Verified array within a tool payload」。同一种直觉也把 agent 排除在贡献者名单外：「NEVER credit dedicated agent accounts in CONTRIBUTORS or release notes (human-only).」

  • 在每个边界上给输入设限 替代 信任 MCP 工具参数与检索参数

    限制是被明确写出来的：pkg/okf/search.go 里最多 100 条结果、查询在 1,000 个字符处截断、token 上限 50；MCP 工具输入有 1 KB 字符串约束与 1 MB 体积上限；概念 ID 在 SaveConcept 内部先校验；又用跨平台的绝对路径判断替换 filepath.IsAbs，因为那个标准函数是按运行所在的操作系统来判断什么叫绝对路径的。

依据报告完整打印的三份架构文档——knowledge/project/overview.md（2,485 字符）、knowledge/convention/dual-memory-architecture.md（5,218 字符）与 AGENTS.md（2,191 字节），以及被点名为第四份候选但未打印的 CLAUDE.md——外加 README（15,905 字符，因报告只打印前 6,000 字符而从句柄处取回；文件树记它为 16,267 字节）、README 自带的仓库结构说明，以及完整的 229 个文件树及其体积。

制作过程

6 个阶段
  1. 01

    一个自称实现了 Google OKF v0.2 的记忆层

    仓库在自己的元数据里这样描述自己：「Git-native persistent memory for AI coding agents. Implements Google OKF v0.2 with sub-300µs in-memory BM25 search, embedded MCP server, and progressive disclosure.」README 的开头是「A Domain-Neutral, Git-Native Persistent Project Memory for AI Agents based on the Open Knowledge Format (OKF) v0.2」，第一枚徽章把这几个字链接到 GoogleCloudPlatform/knowledge-catalog 的 okf/SPEC.md。项目自己的知识 bundle 里重复着同一个引用：knowledge/project/overview.md（2,485 字符）把一条来源记作「Open Knowledge Format (OKF) v0.2 Specification」，指向那个路径。以上全都是项目在描述自己，材料里没有任何来自 Google 或第三方的说法确认这个实现。唯一把「是否合规」当成需要论证而非断言的地方，是它自己那份 docs/spec/OKF-COMPATIBILITY.md（6,241 字节），README 把它列为「OKF v0.2 Compatibility Matrix — Specification validation analysis」。一个已关闭的 issue 显示这份文档真的在被使用：报告者引用它，说明规范允许的某种链接写法却被校验器判错；维护者随后以 v0.4.4 的提交 9146138 修复并关闭了它。

  2. 02

    性能数字是作者自述的，其中一个连他自己都在质疑

    本记录里的速度与体积数字都是作者自述。README 的基准表把「Concept Search Latency ... < 300 µs (Microseconds, In-Memory BM25)」和「Python / Vector DB Runtimes (Mem0, Letta)」的「150ms – 800ms (Embedding API + Vector DB)」并列，另给出整库解析与图校验「~4.0 ms (50+ concepts, bidirectional graph)」、冷启动「< 4 ms (Compiled Single Binary)」、每 1,000 次检索「$0.00 (Zero API cost, fully local)」、常驻内存「< 15 MB」。元数据摘要把检索这一条复述为「sub-300µs in-memory BM25 search」，把省下的 token 说成「80%」，而 README 自己的亮点写的是 Agent Action Grammar「~78–85% tokens compared to natural language prompt instructions」。表里没有硬件、语料规模，也没有测量步骤，只指向 make benchmark 和一个「Progressive Disclosure Benchmark Suite」；仓库里确实有 docs/guides/BENCHMARKING_METHODOLOGY.md（7,133 字节）、benchmarks/README.md（3,862 字节）、668 字节的 pkg/okf/search_benchmark_test.go，以及若干标出所用模型与运行时的结果文件。这些文件都不在材料里，所以 sub-300µs 这个数字背后怎么测的，此处无法核对。而维护者自己开的 issue 42 说，同一个 BM25 实现有「three structural weaknesses in document frequency and term frequency calculation」：缩写会在更长的词里被匹配到、把 IDF 压向零，前缀又会命中短词干，于是 log 命中 login、auth 命中 author。

  3. 03

    头二十三天里发了十五个 release

    元数据记录仓库创建于 2026-09-05，而到 2026-09-27 之间共有十五个 release：v0.1.0 在 2026-09-05，v0.1.1 在 2026-09-06，v0.1.2 在 2026-09-07，v0.1.3 与 v0.1.4 同在 2026-09-08，v0.1.5 在 2026-09-09，v0.2.0 在 2026-09-12，v0.3.0 在 2026-09-15，v0.3.1 在 2026-09-16，v0.4.0-rc.1 与 v0.4.0 同在 2026-09-17，v0.4.1 在 2026-09-18，v0.4.2 在 2026-09-19，v0.4.3 在 2026-09-23，v0.4.4 在 2026-09-27。其中十二个落在头十四天里，最后三个摊在之后的九天。十五个 release 全部既非 prerelease 也非 draft，包括那个候选版本，它在 2026-09-17 的 08:26:58Z 发布，比它所指向的正式版本早约五小时。十五个 tag 与十五个 release 一一对应。提交历史同样是压缩过的形状：167 次提交全部落在 2026-09，从最早的（「feat: initial commit of OKF Agent Memory v0.1.0」，2026-09-05T21:10:22Z）到最新的（「chore(release): prepare release notes and knowledge for v0.4.4」，2026-09-27T20:20:10Z）。其中 12 次由 google-labs-jules[bot] 署名、3 次由 dependabot[bot]，那些安全相关的 pull request 还带着一行自动说明，写着它们由 Jules 为某个由人发起的任务创建。仓库周围是 740 个星、57 个 fork、4 个 watcher 与 4 个未关闭 issue，而 docs/releases/ 里放着十六个文件——每个版本一份，外加一个索引。

  4. 04

    四份架构候选文档，其中三份被完整打印并摘句

    报告找到四份候选架构文档，完整打印了三份，并在「未打印的那一份」那一行点名 CLAUDE.md——它在文件树里是九字节，与 .cursorrules、.windsurfrules 同样大小。第一份打印出来的是 knowledge/project/overview.md（2,485 字符）：「The OKF Agent Memory project provides an open, vendor-neutral, and domain-agnostic persistent memory layer for AI agents, built directly on Google’s Open Knowledge Format (OKF) v0.2.」以及关于记忆该放在哪里的「OKF Agent Memory solves this by treating an OKF knowledge bundle inside the repository (knowledge/) as the single source of persistent truth.」第二份是 knowledge/convention/dual-memory-architecture.md（5,218 字符）：「The Dual-Memory Agent Architecture (DMAA) v0.1 resolves the context-bloat and attention-drift dilemma across AI agents in all domains through a 2-layer cognitive model.」，其中推送层「Strictly capped at 100–150 tokens」，拉取层「0 tokens in initial system prompt」，两层之间的组合被写成一条等式：「AGENTS.md = Domain Codex + OKF Memory Bridge」。第三份是仓库自己的 AGENTS.md（2,191 字节），用项目称为 Agent Action Grammar 的微语法写成：「- MUST execute okf_search(query=keywords, limit=3) before proposing architecture, dependencies, or changes.」与「- NEVER scan knowledge/ via list_dir, grep_search, find, or raw readers.」。README 把同一套模型画成五层图，从 OKF v0.2 规范，经约定、skill 与语法、Go 工具层，最后到知识语料。

  5. 05

    一个月的路径穿越修复，以及 agent 伪造不了的人工校验

    三十个 issue 与 pull request 里有九个是安全加固，而它们大多追到同一类错误。pull request 26 报告说，在 POSIX 系统上 filepath.Clean 把反斜杠当作普通文件名字符，于是像 .... ile.md 这样的载荷能通过包含性检查；27 把根因讲得很直白：「On POSIX platforms (Linux/macOS), Go’s filepath.ToSlash is a no-op because filepath.Separator is /」；32、33、34 继续这一串工作，36 又补上一句：「The standard filepath.IsAbs() function relies on the runtime OS architecture to determine absolute paths」——于是 Windows 绝对路径在 POSIX 上识别不出来。同一批 pull request 也加固了 YAML frontmatter：36 把问题叫作「YAML Frontmatter Smuggling」，仍未合并的 43 解释 sanitizeConceptMetadata 用 strings.HasPrefix 检查，可以靠空格、引号或类 JSON 语法绕过。那条 pull request 还指出同一个文件里的第二个问题：「There was no logic preventing an agent from inserting a human: prefix in the Verified array within a tool payload, resulting in a false-sense of human provenance.」而项目早已把规则写进自己的说明书里——AGENTS.md 写着「NEVER forge human verification (verified: is human-only; declare generated: { by: "<actor>", at: "<iso-time>" })」以及「NEVER credit dedicated agent accounts in CONTRIBUTORS or release notes (human-only)」。更早的 pull request 21 则给检索面上了限：最多 100 条结果，查询在 1,000 个字符处截断，token 上限 50。

  6. 06

    命令行之外：一个 Hub、一个语法 linter 与三套示例语料

    文件树比「解析器加命令行」要大。两个包承载着一个加密 Hub，README 称它为 Zero-Knowledge Sync：pkg/sync/（12 个文件、82 KB——engine.go 16,002 字节，另有 client.go、hub.go、server.go、reconcile.go、log_merge.go）与 pkg/vault/（9 个文件、33 KB——envelope.go、tree.go、kdf.go、commit.go），由 ./bin/okf hub init-vault、hub push 与 hub sync 驱动，接受密码、密钥与可选 token。pkg/okf/aag/ 里是一个 6,231 字节的 linter，检查项目自创的 Agent Action Grammar，其规范写在 docs/spec/AGENT_ACTION_GRAMMAR_RFC.md（16,980 字节）。基准运行器是单个 62,626 字节的文件 cmd/okf-benchmark/main.go，benchmarks/results/ 里是七个结果文件（116 KB），文件名点出 claude-opus-5、gpt-5.6-sol、qwen3-coder-30b 等模型，而 README 把这个目录描述为「across 8+ local & cloud LLMs」的日志。三套示例语料——examples/software、examples/coaching、examples/books，各十三个文件——展示同一个 bundle 被用于架构决策、教练会谈与书评。分发靠一份 Homebrew formula 模板（1,895 字节）与一个 9,113 字节的发布工作流。项目也用这套方式保存自己的记忆：knowledge/log.md 有 15,964 字节，其中一个测试文件就叫 dogfood_test.go（3,304 字节）。

相关档案

全部档案 →

第 059 号

GSD Core

「Git. Ship. Done.」——一个元提示、上下文工程与规格驱动开发的框架，每个里程碑都重复同一条五步回路：讨论、计划、执行、验证、发版。重活被推给上下文全新的子 agent，主会话因此保持轻量；每一项决定都写进规划目录下的 Markdown 与 JSON，而不是留在对话里。

第 070 号

OpenChatCut

一个本地优先的视频剪辑器，剪辑方式是跟它说话：内置 agent 与外部 Codex、Claude Code 会话调用的是界面自己在用的同一套剪辑工具，于是每一处改动都落在一条真实的多轨时间线上——是片段、转场、字幕、特效或音频，仍然能拖、能撤销、能导出。工程与素材留在本机，预览与最终渲染都出自 Remotion。

第 061 号

Reticle

一个 MCP 服务器加一个只在开发期生效的 SDK：让编码 agent 从应用内部去读、去操作一个正在运行的 web 或桌面应用，然后给出判词和该改的文件与行号，而不是一张截图。