OKF Agent Memory

基于开放知识格式（OKF）v0.2 的领域中立、Git 原生 AI 代理持久化项目记忆。

🌟 概述

与 AI 代理的对话会在上下文窗口关闭时重置。宝贵的架构决策、领域发现和运维事实若不持久化存储便会丢失。

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

flowchart TD
    L1["1. OKF v0.2 规范<br/>（规范性 Markdown 与 YAML 格式）"]
    L2["2. 代理记忆约定<br/>（行为规则：搜索、评审、信任）"]
    L3["3. 代理技能<br/>（LLM 提示词与操作工作流）"]
    L4["4. 工具层：Go 库与 CLI<br/>（确定性解析、验证、搜索、MCP）"]
    L5["5. 项目知识语料库<br/>（knowledge/ OKF 包）"]

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

⚡ 核心亮点

极速性能（搜索 <300µs，图验证约 4ms）：内存中 BM25 检索与 bundle 验证在微秒级完成，无需虚拟机启动或网络往返。
100% Git 原生且零供应商锁定：一切皆为版本控制的纯文本。可使用标准的 git diff 和 git log 检查、审计并评审你的代理记忆。无需外部数据库。
记忆检索零 API 成本：本地词法 BM25 索引消除了反复的向量嵌入 API 成本与网络往返。
基于 Google OKF v0.2 构建：采用开放标准的代理知识格式，完整支持来源溯源（sources）、信任层级（generated 与 verified）以及生命周期元数据（status、stale_after）。
解决上下文膨胀与记忆腐化问题：采用渐进式披露（分层 index.md 文件与链接图），代理只加载所需的确切概念。
先搜索后写入原则：强制在撰写前查询现有记忆，防止概念重复与幻觉偏差。
零依赖 Go 工具链：单一二进制文件，零外部依赖，CLI 启动时间低于 5ms，内置 Model Context Protocol（MCP）服务器（okf mcp）。
真正的领域中立：适用于软件工程、教练辅导、科学研究、文献综述与运维。

📊 性能基准测试

以 Go 构建、零外部依赖，okf 专为高频代理工具调用循环而设计：

基准指标	Python / 向量数据库运行时（Mem0、Letta）	Deno / Node.js 工具	OKF Agent Memory（Go）
概念搜索延迟	150ms – 800ms（嵌入 API + 向量数据库）	40ms – 120ms	< 300 µs（微秒级，内存 BM25）
完整语料库解析与图验证	200ms – 1.5s	80ms – 250ms	约 4.0 ms（50+ 概念，双向图）
进程冷启动开销	250ms – 600ms（Python 虚拟机启动）	80ms – 180ms（V8 / Deno 启动）	< 4 ms（编译后的单一二进制）
每 1000 次查询检索成本	约 $0.10 – $0.50（嵌入 token）	$0.00	$0.00（零 API 成本，完全本地）
内存占用（RSS）	约 120 MB – 350 MB	约 60 MB – 140 MB	< 15 MB

[!TIP] 在本地使用你自己的 LLM 复现结果：我们提供了纯 Go 编写的自动化基准测试运行器，可在你的本地硬件上（LM Studio / Ollama 配合 Gemma、Qwen、Llama）验证 Time-To-First-Token（TTFT）加速与 -80% 的 token 缩减效果。运行 make benchmark 或查看渐进式披露基准测试套件。

🚀 快速开始

1. 构建工具

克隆仓库并编译独立的 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
./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."

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

# 仅在任意目录中初始化一个裸 OKF bundle
./bin/okf init my-project/knowledge

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

通过一条命令，将完整的 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/ —— 内嵌的代理技能定义与能力指南
AGENTS.md —— 为 AI 编码代理定制的项目操作说明
Makefile —— 用于验证（make validate）与搜索（make search q="..."）的便捷任务

4. 作为 MCP 服务器运行

okf 自带基于 stdio 的原生 Model Context Protocol（MCP）服务器，可与 Claude Code、Cursor、Codex 及其他代理平台无缝对接：

./bin/okf mcp knowledge

MCP 配置示例（`claude_desktop_config.json` 或 Cursor）：

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

📂 仓库结构

okf-agent-memory/
├── benchmarks/             # 渐进式披露基准测试套件与硬件测试数据
│   ├── data/               # 单体文档 vs OKF bundle 测试夹具
│   └── results/            # 跨 8+ 本地与云端 LLM 的可复现基准日志
├── cmd/
│   ├── okf/                # 独立 CLI 与内嵌 MCP 服务器（`stdio`）
│   └── okf-benchmark/      # 用于 LLM TTFT 与 token 测量的自动化基准运行器
├── docs/                   # 指南、规范、架构与发布手册
│   ├── AGENT_TESTING.md    # 多代理测试、提示场景与兼容性矩阵
│   ├── 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 参考包
│   ├── books/              # 文献与认知科学知识包
│   ├── coaching/           # 高管教练与客户会话包
│   └── software/           # 微服务架构与 ADR 包
├── knowledge/              # 项目自身的 OKF v0.2 持久化记忆包
│   ├── 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 编码代理操作说明
├── CONTRIBUTING.md         # 贡献指南与开发工作流
├── Makefile                # 构建、测试、lint、验证与发布目标
├── LICENSE                 # MIT 许可证
├── README.md               # 主仓库文档
└── SECURITY.md             # 安全策略与报告指南

🧪 测试与验证

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

make check

📖 更多文档

上手指南 —— 面向代理与人类的全面上手指南。
CLI 与 MCP 参考 —— 完整的命令行与协议工具参考。
贡献指南 —— 开发环境搭建、质量门禁与拉取请求标准。
安全与隐私指南 —— 数据治理、密钥防范与 PII 保护规则。
多代理测试与评估 —— 测试场景、兼容性矩阵与基准。
OKF Agent Memory 约定 v0.1 —— 行为规则与生命周期规范。
项目路线图与里程碑 —— 分阶段开发计划。
发布手册 —— 版本管理、CI/CD 流水线与分发流程。
OKF v0.2 兼容性矩阵 —— 规范验证分析。
为什么选择 OKF Agent Memory？ —— 详细的价值主张与差异化优势。
替代方案与生态对比 —— 与 Mem0、Letta 及临时 Markdown 文件的对比。

📄 许可证

MIT 许可证。详见 LICENSE。