okf-agent-memory：为AI编程代理提供Git原生持久记忆

okf-memory/okf-agent-memory

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

OKF Agent Memory 提供了一种标准化、供应商中立（vendor-neutral）的记忆层，它以纯 Markdown 文件加上 YAML frontmatter（前置元数据）的形式，直接存放在你的代码仓库中（knowledge/）。它在非结构化的临时性 markdown 文件（如 CLAUDE.md、AGENTS.md）与复杂、不透明的向量数据库之间架起了桥梁。

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

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

Loading⚡ 主要亮点极快的性能（搜索 < 300µs，图谱校验约 4ms）：内存中的 BM25 检索与 bundle 校验在微秒级完成，无需启动虚拟机，也无网络往返。

100% 原生 Git、零供应商锁定：一切都是受版本控制的纯文本。可以使用标准的 git diff 与 git log 来检视、审计和审查你代理的记忆。无需任何外部数据库。

记忆检索零 API 成本：本地词法（lexical）BM25 索引消除了反复产生的向量嵌入 API 费用与网络往返。

基于 Google OKF v0.2 构建：使用代理知识的开放标准格式，完整支持来源溯源（sources）、信任分级（generated 与 verified）以及生命周期元数据（status、stale_after）。

解决上下文膨胀与记忆腐化问题：采用渐进式披露（Progressive Disclosure），通过分层级的 index.md 文件与链接图谱，让代理只加载它们真正需要的概念。

先搜后写原则（Search-Before-Write）：要求在写入之前先查询既有记忆，防止概念重复与凭空发散。

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

真正的领域中立：面向软件开发、教练辅导、科学研究、文献综述以及运维等多种场景设计。

📊 性能基准OKF 使用 Go 编写，零外部依赖，专为高频代理工具调用循环而设计：

| 基准指标 | 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 VM 启动） | 80ms – 180ms（V8 / Deno 启动） | < 4 ms（编译后的单一二进制） |
| 每 1,000 次查询的检索成本 | 约 $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）上验证首 token 生成时间（Time-To-First-Token，TTFT）的加速效果与减少 80% 的 token 消耗。运行