OKF Agent Memory：让AI编程工具获得Git原生记忆

AI Agent 与人类对话结束后，上下文窗口关闭，其中有价值的架构决策、领域发现和运营事实就会丢失，除非将其持久化存储。

OKF Agent Memory 提供了一个标准化、厂商中立的记忆层，直接以纯 Markdown 文件（带 YAML frontmatter）的形式存在于你的仓库的 knowledge/ 目录中。它填补了非结构化的临时 Markdown 文件（如 CLAUDE.md、AGENTS.md）与复杂的黑盒向量数据库之间的空白。

flowchart TD
    L1["1. OKF v0.2 Specification<br/>(Normative Markdown & YAML Format)"]
    L2["2. Agent Memory Convention<br/>(Behavioral Rules: Search, Review, Trust)"]
    L3["3. Agent Skill<br/>(LLM Prompts & Operational Workflows)"]
    L4["4. Tooling Layer: Go Library & CLI<br/>(Deterministic Parsing, Validation, Search, MCP)"]
    L5["5. Project Knowledge Corpus<br/>(knowledge/ OKF Bundle)"]

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5

极高性能（搜索 <300µs、图验证约 4ms）：内存级 BM25 检索和 bundle 验证在微秒级完成，无需虚拟机启动或网络往返。

100% Git 原生，零厂商锁定：所有内容均为版本控制的纯文本。使用标准 git diff 和 git log 检查、审计和审查 Agent 的记忆。无需外部数据库。

记忆检索零 API 成本：本地词法 BM25 索引消除了持续的向量嵌入 API 成本和网络往返。

基于 Google OKF v0.2 构建：使用开放标准格式存储 Agent 知识，全面支持溯源（sources）、信任层级（generated vs. verified）和生命周期元数据（status、stale_after）。

解决上下文膨胀与记忆腐化：采用渐进式披露（分层的 index.md 文件和链接图），使 Agent 仅加载所需的具体概念。

Search-Before-Write 原则：要求在写入前先查询现有记忆，防止概念重复和幻觉偏移。

零依赖 Go 工具链：单一二进制文件，无外部依赖，CLI 启动时间低于 5ms，内置 Model Context Protocol（MCP）服务器（okf mcp）。

真正领域无关：适用于软件工程、教练辅导、科学研究、文献综述和运维等场景。

📊 性能基准

使用 Go 构建，零外部依赖，okf 针对高频 Agent 工具调用循环进行了工程优化：

在本地使用你自己的 LLM 进行复现：提供了纯 Go 编写的自动化基准测试运行器，可验证 Time-To-First-Token（TTFT）加速效果和本地硬件上（Gemma、Qwen、Llama，通过 LM Studio / Ollama）令牌减少 80% 的表现。运行 make benchmark 或探索渐进式披露基准测试套件。

克隆仓库并编译独立的 okf 可执行文件：

make build

这会在 bin/okf 生成独立的二进制文件。

2. 基础 CLI 命令

# 验证 bundle 合规性、图连接性和描述漂移
./bin/okf validate knowledge --strict --drift

# 通过内存级 BM25 评分搜索概念
./bin/okf search "architecture layers" knowledge

# 检查概念及其关系（支持 --json）
./bin/okf show architecture/layers knowledge --json

# 创建新概念，自动处理 log.md 和 index.md 的 bookkeeping
./bin/okf create decisions/auth-flow knowledge \
  --type Decision \
  --title "OAuth2 Authorization Flow" \
  --desc "Standardized on PKCE for client authentication."

# 更新现有概念
./bin/okf update decisions/auth-flow knowledge \
  --desc "Updated OAuth2 PKCE token refresh interval."

# 将完整 Agent 记忆栈引导到任意目标项目
./bin/okf bootstrap /path/to/project --name "My Project"

# 在任意目录初始化空的 OKF bundle
./bin/okf init my-project/knowledge

3. 在任意项目中引导 Agent 记忆

用一条命令将完整 OKF Agent Memory 架构脚手架到任意新仓库或现有仓库中：

# 将完整记忆栈引导到目标项目
./bin/okf bootstrap /path/to/my-project --name "My Service"

这会自动设置：

• knowledge/ — 符合 OKF v0.2 的持久记忆 bundle（index.md、log.md）
• .agents/skills/okf-memory/ — 内置 Agent 技能定义和能力指南
• AGENTS.md — 针对 AI 编码 Agent 量身定制的操作指南
• Makefile — 便捷的验证任务（make validate）和搜索任务（make search q="..."）

4. 作为 MCP 服务器运行

okf 原生支持通过 stdio 的 Model Context Protocol（MCP）服务器，无缝连接 Claude Code、Cursor、Codex 等 Agent 平台：

./bin/okf mcp knowledge

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

📂 仓库结构

okf-agent-memory/
├── benchmarks/             # 渐进式披露基准测试套件和硬件测试数据
│   ├── data/               #  monolith docs vs OKF bundle 测试夹具
│   └── results/            # 8+ 本地和云端 LLM 的可复现基准日志
├── cmd/
│   ├── okf/                # 独立 CLI 和嵌入式 MCP 服务器（`stdio`）
│   └── okf-benchmark/      # 用于 LLM TTFT 和令牌测量的自动化基准运行器
├── docs/                   # 指南、规范、架构和发布手册
│   ├── AGENT_TESTING.md    # 多 Agent 测试、提示场景和兼容性矩阵
│   ├── ALTERNATIVES.md     # 与 Mem0、Letta 和临时 markdown 的对比
│   ├── CLI.md              # 完整的命令行和 MCP 工具参考
│   ├── CONVENTION.md       # OKF Agent Memory 约定 v0.1
│   ├── GETTING_STARTED.md  # 全面的入门指南
│   ├── OKF-COMPATIBILITY.md# OKF v0.2 规范兼容性分析
│   ├── RELEASE_PLAYBOOK.md # 自动化发布流程和版本标签
│   ├── ROADMAP.md          # 项目路线图和里程碑
│   └── SECURITY.md         # 数据治理、密钥防护和 PII 规则
├── examples/               # 领域无关的参考 OKF v0.2 bundle
│   ├── books/              # 文学与认知科学知识 bundle
│   ├── coaching/           # 高管教练和客户会话 bundle
│   └── software/           # 微服务架构和 ADR bundle
├── knowledge/              # 项目自身的 OKF v0.2 持久记忆 bundle
│   ├── index.md            # 根级渐进式披露索引（okf_version: "0.2"）
│   ├── log.md              # 每日变更日志（ISO 8601 YYYY-MM-DD）
│   ├── project/            # 概览和价值主张
│   ├── architecture/       # 五层架构和工具决策
│   ├── convention/         # 原则和生命周期工作流
│   └── roadmap/            # 里程碑
├── packaging/              # 分发包
│   └── homebrew/           # 官方 Homebrew formula 和 tap 说明
├── pkg/okf/                # 零依赖 Go 核心库（解析器、验证器、BM25、MCP、bootstrap）
├── AGENTS.md               # AI 编码 Agent 的操作指南
├── CONTRIBUTING.md         # 贡献指南和开发工作流
├── Makefile                # 构建、测试、lint、验证和发布目标
├── LICENSE                 # MIT 许可证
├── README.md               # 主仓库文档
└── SECURITY.md             # 安全策略和报告指南

🧪 测试与验证

运行完整测试套件并验证仓库的自文档知识 bundle：

make check

📖 进一步文档

入门指南 — Agent 和人类的全面入门指南。

CLI 与 MCP 参考 — 完整的命令行和协议工具参考。

贡献指南 — 开发环境设置、质量门和 Pull Request 标准。

安全与隐私指南 — 数据治理、密钥防护和 PII 保护规则。

多 Agent 测试与评估 — 测试场景、兼容性矩阵和基准测试。

OKF Agent Memory 约定 v0.1 — 行为规则和生命周期规范。

项目路线图与里程碑 — 分阶段开发计划。

发布手册 — 版本管理、CI/CD 流水线和服务分发流程。

OKF v0.2 兼容性矩阵 — 规范验证分析。

为什么选择 OKF Agent Memory？ — 详细的价值主张和差异化特性。

替代方案与生态对比 — 与 Mem0、Letta 和临时 Markdown 文件的对比。

MIT 许可证。见 LICENSE 了解详情。