mcp-memory OKF 是什么

mcp-memory 用 OKF v0.2 存 agent 长期记忆，SQLite FTS5 检索，setup.py 可配 Cursor 与 Claude Code。

mcp-memory OKF 是什么

Agent 换会话就忘偏好和架构决定，靠 CLAUDE.md 手写又难检索。mcp-memory okf 是什么：fellowgeek/mcp-memory（Show HN 约 2026-08-13）把每条记忆写成 Open Knowledge Format v0.2 Markdown，再用项目内 SQLite FTS5 做毫秒级搜索，通过 MCP 暴露 store/retrieve/search 等工具。

作者：CodePass 技术编辑

OKF v0.2 在记忆里长什么样

OKF 是一套带 YAML frontmatter 的知识文档规范，和 MCP 传输协议无关。mcp-memory 默认 type: Agent Memory，必填字段包括 key、namespace、tags、status、generated 等，正文是人类可读的 Markdown 段落。Google Cloud 知识目录里的 OKF 规范偏企业治理；mcp-memory 把它缩成 agent 可写的记忆卡片，字段仍足够做检索与生命周期标记。

仓库 README 给的样例：

---
type: Agent Memory
title: Coding Style
key: user/preferences/coding_style
namespace: default
tags:
- preferences
- style
status: stable
generated:
  by: mcp-memory/0.2.0
  at: '2026-08-12T19:23:35Z'
---

User prefers functional programming style with explicit type annotations.

每条 store 会同步两份：磁盘上 memory/ 目录里的 .md（含层级 index.md 与 log.md 更新史），以及隐藏索引 .mcp_memory/memories.db。你可以用编辑器直接打开 md 审计内容，不必只靠 MCP 工具读回。namespace 支持 user/preferences、project/architecture 等路径式隔离，避免不同项目记忆串台。

memory/ 下的 index.md 按 OKF 渐进披露组织，根 index 带 okf_version: "0.2"，方便将来 spec 升级时批量迁移。log.md 记录写入时间线，适合人类复盘「哪次 session 改了哪条偏好」。SQLite 侧用 trigger 保持 FTS 与主表一致，agent 调用 memory_search 时无需理解底层 schema。

双写架构与 SQLite FTS5

人类层与机器层分工明确。OKF 目录负责可读、可 diff、可 git 忽略策略自定义；SQLite 负责 memory_search 的关键词、tag、namespace 过滤，README 称 key lookup 与全文搜索在亚 20ms 量级。FTS5 触发器自动维护索引，agent 不必手写 SQL。

默认路径相对项目根（工具参数里的 project_root）：

层 默认路径
OKF Markdown {project_root}/memory/
SQLite {project_root}/.mcp_memory/memories.db

环境变量可改：MCP_MEMORY_DIR、MCP_MEMORY_DB_PATH、MCP_MEMORY_PROJECT_ROOT。若希望全仓库共享一份记忆，可在 MCP 配置里把 DB 与目录指到 ~/.mcp_memory/，README 有示例。这与 Skills 和 MCP 有什么区别 里讲的 MCP「连接外部状态」一致：skill 固化流程，MCP 拿可检索的持久化记录。

MCP 工具面：store 到 session 检查点

服务器通过 FastMCP 暴露六类工具（完整列表见 GitHub README）：

  • memory_store / memory_retrieve / memory_search：常规 CRUD 与搜索，store 时必填 key、content、project_root。
  • memory_get_last / memory_update_last：读写 system/last_memory 检查点，README 标为 session 起止时的 agent 指令，用于「上次停在哪」。

memory_store 还支持 concept_type（如 Playbook、Metric）、stale_after、sources、verified 等 OKF 扩展字段，方便以后做过期提醒或溯源。所有工具都要求 agent 传绝对路径的 project_root，避免 cwd 漂移写到错误目录。和纯文件 skill 相比，MCP 返回值进上下文仍受客户端输出上限约束，长记忆应写摘要进 OKF、细节放链接或分 key。

memory_get_last 适合 session 开头让 agent 自问「上次停在哪」；memory_update_last 适合 merge 前、长时间 refactor 中段、或你要关电脑前写一句 checkpoint。两者都走 system/last_memory 特殊 key，与普通 memory_store 并存，不会替代按主题拆分的长期记忆。搜索时 memory_search 的 query 走 FTS5，tag 过滤适合「只要 architecture 类」这类硬筛。

setup.py 与 Claude Code / Cursor 接入

零配置路径是克隆后跑交互向导：

git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory
python3 setup.py

setup.py 会探测本机已装的 Antigravity、Claude Desktop、Cursor、Windsurf、Codex 等，把 run.sh 写进各自 MCP 配置。完成后客户端按需拉起 stdio 子进程，一般不必手驻终端。调试时可 ./run.sh 看 stdio 日志；验收跑 python3 test_memory.py。首次 store 后检查项目根是否出现 memory/ 与 .mcp_memory/，确认 project_root 传对。

手动配置时，JSON 客户端（含 Cursor）添加：

{
  "mcpServers": {
    "memory": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

Claude Code CLI 等价于 claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh。Cursor 扫描路径与加载时机见 Cursor 怎么加载 Claude Skills；mcp-memory 是 MCP server，不是 skill，但常与之并用：skill 定「何时写记忆」，MCP 执行写入。跨工具换 agent 时，OKF 文件仍在磁盘上，可配合 agent-hop 跨工具续会话 换运行时后继续用同一 memory/ 目录。

Codex Desktop 用 TOML：[mcp_servers.memory] command = "/ABSOLUTE/PATH/TO/run.sh"。多客户端共用同一 global DB 时，把 MCP_MEMORY_DB_PATH 指到 home 目录，但 project_root 参数仍决定「这条记忆算哪个项目」；混用 global DB 与 per-project DB 容易搜到过期上下文，团队应写清 convention。

边界、隐私与何时值得装

适合：长周期项目要记住架构决策、偏好、未完成里程碑；需要全文搜旧记忆而不是翻整份 CLAUDE.md；团队希望 md 可审计。不适合：一次性脚本任务（维护 OKF 字段 overhead 大于收益）；不能把 memory/ 或 .mcp_memory/ 放进备份与 .gitignore 策略的仓库（误提交含敏感摘要时泄露）；期望云端多机自动同步（默认是项目本地 store，多机要靠 git 同步 md 或共享 DB 路径）。

Show HN 2026-08-13 附近 fellowgeek/mcp-memory 帖把 OKF 记忆推到 HN 首页，Star 过百但 fork 仍少，说明需求热、生产落地还在早期。装完后让 agent 先 memory_get_last 再干活，比一上来塞长 CLAUDE.md 更省窗口；结束 session 前 memory_update_last 一句，第二天 memory_search 关键词能找回决策原因。python3 test_memory.py 可在 CI 验 SQLite 与 OKF 序列化，适合 fork 后自改存储路径的团队。

和 CLAUDE.md 的分工：CLAUDE.md 适合稳定、人人要读的仓库规则；OKF 记忆适合会话间积累的偏好、未完成决策、某次 spike 的结论。前者进 git，后者默认在项目 memory/ 与 .mcp_memory/，通常应写进 .gitignore，除非团队刻意 audit。多开发者共用一仓时，namespace 用 user/<handle>/... 减少互相覆盖。

Antigravity、Windsurf 也在 setup.py 探测列表里，说明作者按「多 MCP 客户端」设计，而不是只服务 Claude Desktop。若你同时在 Cursor 与 Claude Code 开同一 repo，两边 MCP 配置各写一份 run.sh 绝对路径即可，共享同一 memory/ 目录；注意两个 agent 同时 memory_store 同一 key 会按 OKF 更新规则覆盖，关键决策可加 verified 字段标记人工确认时间。

参考资料