5分钟上手OKF Agent Memory:从零搭建AI智能体持久记忆系统的快速教程
5分钟上手OKF Agent Memory:从零搭建AI智能体持久记忆系统的快速教程
OKF Agent Memory 是一款专为 AI 编码智能体设计的 Git 原生持久记忆系统,基于 Google OKF v0.2 规范,用纯 Go 实现零外部依赖,内存 BM25 搜索延迟低于 300 微秒,并内置 MCP 服务器。它能让你的 AI 智能体跨会话记住架构决策、领域事实和运维规则,减少约 80% 的上下文 Token 浪费。本教程带你 5 分钟内从零搭建完整的智能体持久记忆系统。
为什么 AI 智能体需要持久记忆?🤔
和 AI 智能体对话时,上下文窗口一关闭,之前讨论的架构决策、踩坑经验就全部丢失。常见的两种补救方案都有致命缺陷:
| 方案 | 痛点 |
|---|---|
| 提示词巨石 | 把所有规则塞进 AGENTS.md,上下文膨胀导致智能体"注意力漂移",忽略关键指令 |
| RAG 向量库盲区 | 智能体做常规任务时根本不会主动去语义搜索操作约束(如安全规则) |
OKF Agent Memory 用 双记忆智能体架构(DMAA) 解决这个难题:
- 推送层(Push):超紧凑的行为准则(
AGENTS.md,上限 400 tokens),会话启动时加载,强制智能体遵守不可违背的规则 - 拉取层(Pull):
knowledge/知识库,基线占用 0 tokens,需要时以微秒级速度按需检索
📖 架构细节可阅读 Dual-Memory Agent Architecture RFC
安装 OKF Agent Memory:3 种方式任选
方式一:Homebrew 一键安装(推荐)
brew install okf-memory/tap/okf
# 验证安装
okf version
方式二:从源码构建
需要 Go 1.22+ 环境:
git clone https://gitcode.com/gh_mirrors/ok/okf-agent-memory
cd okf-agent-memory
make build
# 二进制文件生成于 bin/okf
方式三:下载预编译二进制
从 Release 页面下载对应架构的二进制文件,赋予执行权限后放入 PATH 即可。
📖 完整安装说明见 Getting Started Guide
一条命令为项目注入持久记忆
这是本教程的核心一步。在任意现有项目上运行:
okf bootstrap /path/to/my-project --name "My Project"
一条命令自动搭建 4 个组件:
knowledge/— 符合 OKF v0.2 规范的持久记忆知识库(含index.md和log.md).agents/skills/okf-memory/— 供 AI 智能体读取的技能定义AGENTS.md— 为智能体量身定制的操作指令(含"写前搜索"规则)Makefile— 常用快捷任务(make validate、make search q="...")
验证项目配置是否合规:
okf validate knowledge --strict
新建项目则直接:
mkdir my-new-project && cd my-new-project
git init
okf bootstrap . --name "My New Project"
5 条核心命令:搜索、记忆、校验
掌握这 5 条命令,就能覆盖日常 90% 的使用场景:
# 1️⃣ 搜索概念(内存 BM25 评分,微秒级响应)
okf search "architecture layers" knowledge
# 2️⃣ 查看概念详情及其关联关系
okf show architecture/layers knowledge --json
# 3️⃣ 创建新概念(自动维护 log.md 和 index.md)
okf create decisions/auth-flow knowledge \
--type Decision \
--title "OAuth2 Authorization Flow" \
--desc "Standardized on PKCE for client authentication."
# 4️⃣ 更新已有概念
okf update decisions/auth-flow knowledge \
--desc "Updated OAuth2 PKCE token refresh interval."
# 5️⃣ 严格校验知识库合规性
okf validate knowledge --strict --drift
💡 实用技巧:修改源码前,用 --for-path 查询该文件受哪些约束管辖:
okf search --for-path pkg/okf/types.go knowledge
结果会按治理等级排序:[hold](冻结,禁止修改)> [constraint](强制规则)> [context](背景信息)。
📖 全部命令与参数详解见 CLI & MCP Reference
接入 AI 智能体:配置 MCP 服务器
okf 内置 Model Context Protocol(MCP)服务器,通过 stdio 协议无缝对接 Claude Code、Cursor、Codex 等主流平台:
okf mcp knowledge
在 claude_desktop_config.json 或 Cursor 设置中添加:
{
"mcpServers": {
"okf-memory": {
"command": "okf",
"args": ["mcp", "knowledge"]
}
}
}
配置完成后,智能体自动获得 6 个记忆工具:okf_search(BM25 概念搜索)、okf_show(查看详情与链接图)、okf_create、okf_update、okf_relate、okf_validate。
以 examples/software/ 为例,接入后的 AGENTS.md 会强制智能体执行"写前搜索"协议:
MUST execute okf_search before proposing architecture or substantial changes.
NEVER scan knowledge/ via list_dir, grep, or raw file readers.
日常工作流:读-做-记 四步循环
每次与智能体协作都遵循同一个闭环:
- 写前搜索 — 智能体先执行
okf search "<关键词>",查清既有的架构决策与约束 - 执行任务 — 基于完整持久上下文开发,不再"凭空臆造"过去的决策
- 持久化发现 — 新的架构决策、非显而易见的修复方案,用
okf create/okf update记录 - 校验审计 — 会话结束前运行
okf validate knowledge --strict,确保 100% 符合 OKF v0.2 规范
最佳实践清单 ✅
- 只存持久事实,不存聊天记录或临时草稿——存架构决策、数据模式、API 契约
- 更新优于重复——先搜索,已有
architecture/auth.md就扩展它,别再建auth-v2.md - 尊重溯源——智能体写入必须声明
generated: { by: "agent/<name>", at: "<timestamp>" },伪造人工审核是大忌 - 保持索引新鲜——定期加
--drift参数,确保index.md描述与概念元数据一致
总结
OKF Agent Memory 用 纯 Go 单二进制 + Git 原生 Markdown 的方式,解决了 AI 智能体"失忆"和"上下文膨胀"两大难题:推送层保证智能体时刻遵守行为准则,拉取层让知识按需取用、零基线 Token 成本。你现在可以:
- 用 Getting Started Guide 深入完整上手流程
- 参考 examples/ 中 books、coaching、software 三个领域的示例项目
- 阅读 知识库目录 了解 OKF v0.2 知识包的内部结构
- 通过
make benchmark在本地复现 benchmarks/ 中的性能基准测试
5 分钟就能让 AI 智能体拥有"过目不忘"的项目记忆,还不快给你的项目装上一个?🚀