okf-memory/okf-agent-memory

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. Slashes token bloat by 80% with zero external databases or dependencies. Built in pure Go.

OKF Agent Memory – 它是什么

OKF Agent Memory 是一个基于 Go 的工具包，让您可以为 AI 驱动的编码助手提供一个持久化、版本控制的知识库。它遵循 开放知识格式 (OKF) v0.2 规范，将事实、决策、运行手册和其他“领域知识”存储为纯文本 Markdown/YAML 文件，放在与代码位于同一 Git 仓库中的 knowledge/ 文件夹内。

为什么重要

不再丢失上下文 – 当与 LLM 的聊天结束时，模型会忘记您告诉它的一切。通过在 Git 中维护结构化的知识包，代理可以在下一次请求时精确检索所需的概念。
避免提示词膨胀 – 系统不是将庞大的 AGENTS.md 文件塞入每个提示词，而是将代理的“工作记忆”（一个约 400 令牌的小型代码库）与按需查询的更大语义记忆分开。
零供应商锁定 – 所有数据均为纯文本；您可以使用 git diff 检查更改、审计来源，并且永远不依赖远程向量数据库。
快速、廉价的检索 – 内置的 BM25 引擎在内存中执行词法搜索（< 300 µs），且不产生任何 API 费用。

核心概念

概念	作用
双记忆代理架构 (DMAA)	将推送层（`AGENTS.md` 中的规范性规则，限制在约 400 令牌）与拉取层（仅在需要时查询的 `knowledge/` 包）分开。
代理动作语法 (AAG)	一种紧凑的 ASCII 微语法，用于编写确定性的代理指令，与自由形式的散文相比节省约 80% 的令牌。
四级记忆层次	`project`（本地包）→ `vendor`（拉取的包）→ `user`（个人笔记）→ `system`（企业策略）。较高层级会遮蔽较低层级。
OKF v0.2 包	一组 Markdown/YAML 文件，带有内置来源（`sources`）、信任层级（`generated` 与 `verified`）和生命周期元数据（`status`、`stale_after`）。
先搜索后写入原则	代理在添加新概念之前必须查询现有包，以防止重复和幻觉。

您获得的内容（工具箱）

okf CLI – 一个编译好的二进制文件（bin/okf），可以：
- 验证包的架构、图完整性和质量记分卡。
- 使用 BM25 搜索概念（okf search "..." knowledge）。
- 显示概念及其关系（okf show <id> knowledge）。
- 创建、更新或引导包（okf create ...、okf bootstrap ...）。
- 作为 MCP（模型上下文协议）服务器运行，使 Claude、Cursor 或 Codex 等代理可以通过 stdio 调用它。
零依赖 Go 库（pkg/okf）– 如果您想构建自定义集成，可以嵌入到其他工具中。
供应商包处理 – 从 OKF 注册表或 Git 拉取现成的知识包，并带有可选的质量门控（--min-score）。
基准测试套件 – 可重现的性能测试，显示亚毫秒级搜索和几毫秒级的完整包验证。

快速入门演练

构建二进制文件：
```
make build   # 生成 bin/okf
```
验证现有包（如果分数 < 80，CI 失败）：
```
./bin/okf validate knowledge --min-score 80
```

搜索概念：

./bin/okf search "authentication" knowledge

引导整个记忆栈到新项目：
```
./bin/okf bootstrap /path/to/my-project --name "My Service"
```
这会创建 knowledge/ 文件夹、项目特定的 AGENTS.md 和辅助 Makefile 目标。
通过 MCP 连接代理（Claude Desktop 示例）：
```
{
  "mcpServers": { "okf-memory": { "command": "./bin/okf", "args": ["mcp", "./knowledge"] } }
}
```
代理现在可以在编码会话期间发出 search 或 show 调用。

性能与成本亮点（来自 README）

指标	OKF Agent Memory (Go)	典型替代方案
概念搜索延迟	< 300 µs（内存 BM25）	40 ms – 800 ms（嵌入 + 向量数据库）
完整包解析与图验证	~4 ms（50+ 概念）	80 ms – 1.5 s
冷启动开销	< 4 ms（单个二进制文件）	80 ms – 600 ms（Python/Node 运行时）
每 1000 次查询的检索成本	$0.00（本地）	$0.10 – $0.50（嵌入 API）
内存占用	< 15 MB	60 MB – 350 MB

谁可能使用它？

软件团队依赖 LLM 驱动的代码助手，并希望为项目特定规则、架构决策和运行手册提供可靠、可审计的来源。
研究或辅导项目反复咨询同一个 LLM，需要一个随 Git 演进的稳定“知识库”。
企业需要在多个代理之间强制执行合规策略（安全、风格、许可），而无需支付外部向量服务费用。

了解更多

文档索引 – docs/README.md
入门指南 – docs/guides/GETTING_STARTED.md
代理动作语法规范 – docs/spec/AGENT_ACTION_GRAMMAR_RFC.md
双记忆架构 RFC – docs/spec/DUAL_MEMORY_AGENT_ARCHITECTURE_RFC.md
记分卡与质量门控 – docs/guides/CLI.md（参见 --scorecard 标志）

简而言之： OKF Agent Memory 为您提供一种 Git 原生、令牌高效且超快速的方式来存储和检索 AI 编码代理所需的知识，消除提示词膨胀和昂贵的向量数据库调用，同时保持一切可审计和版本控制。