MCP-Memory 快速入门

这是什么？适合谁？

MCP-Memory 是一个 OKF 标准加持的 MCP server，给 AI Agent（Claude Desktop、Cursor、Antigravity、Windsurf、Codex 等）装上持久化长期记忆。记忆条目按 Open Knowledge Format（OKF v0.2）格式化存储，并用本地 SQLite（FTS5 全文搜索）做索引：亚 20ms 的键值查找、标签过滤、内容搜索。它填补了 MCP 生态长期记忆的空白。

适合人群：想让 Agent 跨会话记住项目上下文的开发者、用多个 MCP 客户端并希望记忆共享的用户、研究 Agent 记忆架构的工程师。 使用前提：Python 环境、一个支持 MCP 的客户端（Claude Desktop / Cursor 等）。

快速上手（3 步）

第一步：安装 server

# 按仓库 Quick Start 章节安装（Python 实现）
git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory
pip install -r requirements.txt

第二步：注册到 MCP 客户端

在 Claude Desktop（或 Cursor 等）的 MCP 配置中添加 server 条目，指向本地启动命令。

第三步：存第一条记忆并检索

在对话里让 Agent”记住：本项目部署脚本是 deploy.sh，入口在 src/main.py”，新开一个会话再问”这个项目的部署脚本是什么”——Agent 通过记忆工具检索并回答，跨会话记忆生效。

初级用法

• 双层架构：一层是人类可浏览的 OKF 目录（每条记忆同步落盘为 .md，带分层 index.md 渐进披露与 log.md 更新历史），一层是高性能 SQLite 索引（FTS5 + 触发器）。
• 命名空间隔离：不同项目/客户端用不同 namespace，记忆互不污染。
• 生命周期管理：OKF frontmatter 里的 stale_after 等字段支持记忆过期与状态管理。

高级玩法

1. 多客户端共享记忆：Claude Desktop 与 Cursor 指向同一个 server 实例，两边共享同一份记忆库（namespace 区分），告别每个工具各记各的。
2. 记忆即知识库：利用人类可浏览的 OKF 目录，把团队经验（踩坑、约定、决策）通过 Agent 沉淀成结构化知识库，直接用 Git 管理 memory/ 目录。
3. FTS5 深度检索：对长记忆库做全文搜索 + 标签过滤组合查询，把 Agent 的”回忆”变成可运维的检索系统。

常见踩坑（5 条）

踩坑 1：记忆没被检索到

• 现象：Agent 回答”我不记得”
• 原因：存储与检索用了不同 namespace，或客户端没加载记忆工具
• 解决：检查 namespace 配置一致性与工具注册状态

踩坑 2：把记忆当万能上下文

• 现象：塞入海量低价值记忆后检索质量下降
• 原因：记忆库也需要治理，噪声条目稀释检索结果
• 解决：定期清理过期/低价值条目（stale_after 与状态字段）

踩坑 3：SQLite 文件被多进程锁

• 现象：并发写入报锁错误
• 原因：多个 server 实例指向同一 SQLite 文件
• 解决：单实例共享（多客户端连同一 server），或按客户端分库

踩坑 4：OKF 目录与索引不同步

• 现象：磁盘上的 .md 与搜索结果不一致
• 原因：手动编辑了 OKF 目录文件绕过触发器
• 解决：所有记忆操作走工具接口，手动改动后重建索引

踩坑 5：客户端兼容性差异

• 现象：一个客户端好用另一个不行
• 原因：各客户端 MCP 实现细节不同
• 解决：按仓库的客户端配置说明逐项检查（支持 Claude Desktop、Cursor、Antigravity、Windsurf、Codex）

FAQ（5 个常见问题）

Q1：MCP-Memory 免费吗？ A：MIT 开源免费，本地运行，无云服务费用。

Q2：和 Claude 自带的 Memory 功能区别？ A：Claude 的记忆绑定其自家产品；本方案走 MCP 标准协议，跨客户端共享、数据在本地、格式按 OKF 标准可迁移。

Q3：数据存哪里？ A：全部本地：OKF Markdown 目录（人类可读）+ SQLite 索引（机器高性能检索），不上云。

Q4：支持多少条记忆？ A：SQLite + FTS5 的容量远超个人使用量级；官方宣称亚 20ms 键查找（具体规模未实测）。

Q5：什么是 OKF？ A：Open Knowledge Format（v0.2），GoogleCloudPlatform knowledge-catalog 发布的开源知识格式标准：YAML frontmatter（type/key/namespace/tags/verified/status 等）+ Markdown 正文。

小技巧（5 条）

1. namespace 按项目划分：project-a、project-b、team-notes，检索与隔离都干净。
2. 记忆写”可验证事实”：路径、命令、决策及理由，比模糊描述检索价值高。
3. 定期 review log.md：更新历史是发现 Agent 胡记东西的第一现场。
4. verified 字段用起来：把人工确认过的记忆标记为已验证，检索优先级更高。
5. 把 memory/ 目录纳入 Git：OKF 目录本身就是 Markdown，版本化 + 团队共享零成本。

进阶学习建议

• 精读 OKF v0.2 规范 与仓库的 OKF_RULES.md，理解记忆标准化的设计意图
• 研究 SQLite 触发器自动同步 OKF 目录与索引的实现，借鉴到自己的双写系统
• 对比向量检索式记忆方案（embedding + 相似度），明确”结构化键值 + 全文搜索”路线的适用边界
• 尝试给记忆条目建立团队审核流（PR 到 memory/ 目录），把 Agent 记忆变成团队资产

参考链接

• MCP-Memory GitHub 仓库
• OKF v0.2 规范

本文基于公开资料于 2026-08-17 整理，社区指标反映 GitHub 公开数据。独立实测未进行，功能和配置项可能随版本更新而变化，请以官方文档为准。