MCP-Memory: 使用 OKF 和 SQLite FTS5 实现快速 Agent 记忆
快速概览
MCP-Memory 为 AI Agent 提供持久化、符合 OKF‑v0.2 标准的记忆，并通过本地 SQLite FTS5 数据库进行索引，在提供低于 20 ms 键值查询和即时全文搜索的同时，保留了人类可读的 Markdown 目录。
什么是 MCP-Memory
MCP-Memory 是一个 Model Context Protocol (MCP) server，它为 Claude Desktop、Cursor、Antigravity、Windsurf 或 Codex 等 Agent 提供长期、可搜索的记忆。每个记忆记录都存储为带有丰富 YAML front‑matter 的 OKF v0.2 Markdown 文档，并且相同的数据也会在 SQLite FTS5 中进行索引，以便快速检索。
核心设计选择
双层架构
- 人类可读的 OKF 目录 – 每个记忆都会以
.md文件形式转储到memory/目录中，并配有层级化的index.md文件，提供了一个版本化、可读的知识库。 - 高性能 SQLite 索引 – 一个带有 FTS5 触发器的 SQLite 数据库，能够实现低于 20 ms 的键值查询以及跨键、front‑matter 和内容的关键词搜索。
命名空间隔离
记忆可以按命名空间（例如 user/preferences、project/architecture、default）进行划分，从而防止跨项目污染。
零样板代码设置
运行 python3 setup.py 会自动检测支持的 Agent 并注册 memory MCP server，因此 Agent 启动时会自动启动 server，无需持久的终端进程。
MCP Tools 对 Agent 暴露的工具
| Tool | Purpose | Key Parameters |
|---|---|---|
memory_store |
创建或更新记忆记录 | key, content, project_root, 可选的 tags, namespace, concept_type, title, description, resource, status, stale_after, sources, verified, generated_by |
memory_retrieve |
通过键值获取单个记录 | key, project_root, 可选的 namespace |
memory_search |
全文或基于标签的搜索 | project_root, 可选的 query, tags, namespace, limit |
memory_get_last |
启动时获取会话检查点 (system/last_memory) |
project_root, 可选的 namespace |
memory_update_last |
在里程碑之后更新检查点 | content, project_root, 可选的 namespace, summary |
OKF v0.2 规范在实践中的应用
每个记忆遵循 OKF front‑matter 模式，例如：
---
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'
created_at: '2026-08-12T19:23:35Z'
updated_at: '2026-08-12T19:23:35Z'
---
User prefers functional programming style with explicit type annotations.
相同的文件存在于 memory/ 目录中，而其可搜索的表示形式存储在 .mcp_memory/memories.db 中。
安装与快速开始
- Clone 仓库：
git clone https://github.com/fellowgeek/mcp-memory cd mcp-memory - 运行设置向导 以自动注册 server 与支持的 Agent：
完成后，Agent 会按需启动python3 setup.pymcp-memory。 - 可选的手动启动 用于调试：
./run.sh
手动客户端配置
如果你更倾向于显式配置，可以添加一个指向 run.sh 的 memory 条目：
JSON (Antigravity, Claude Desktop, Cursor, Windsurf)
{
"mcpServers": {
"memory": {
"command": "/ABSOLUTE/PATH/TO/run.sh"
}
}
}
TOML (Codex Desktop)
[mcp_servers.memory]
command = "/ABSOLUTE/PATH/TO/run.sh"
CLI 示例
claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh
codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh
存储布局与环境变量
- OKF markdown –
memory/目录位于项目根目录内。 - SQLite index –
.mcp_memory/memories.db(隐藏)。 - 环境变量允许自定义位置：
MCP_MEMORY_PROJECT_ROOT– 默认为当前工作目录。MCP_MEMORY_DB_PATH– 默认为.mcp_memory/memories.db。– 默认为memory`。
- 要在项目之间共享单个存储库，请设置
MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db和MCP_MEMORY_DIR=~/.mcp_memory/memory。
社区反馈亮点
@myshapeprotocol – “使用 SQLite FTS5 进行快速 Agent 记忆是如此务实的设计架构选择。很棒的 Show HN 项目。”
@bearjaws – “又一周，又一个 Agent 记忆系统，其功能与在
memory/目录中使用grep差不多一样。”
@healthycoder – “这与我们现有的所有其他 Memory 相关的东西有什么区别？比如 mem0 等做同样事情的东西？”
@jrflo – “为什么这比直接使用 Markdown 文件并允许 Agent 使用
grep更有利？我发现 MCP tools 可以让 Agent 变慢并浪费 tokens。”
@FitchApps – “你能为新手解释一下，为什么使用 Google 的 OKF 格式而不是纯 MD 文件吗？”
@rcarmo – “很高兴看到更多基于 OKF 的方法。我的项目是 https://rcarmo.github.io/projects/memento/。”
这些评论反映了两个反复出现的主题：结构化 OKF 元数据相对于纯 Markdown 的价值，以及与简单 grep 相比的 SQLite 索引的性能权衡。
MCP-Memory 与现有解决方案的区别
标准化元数据 – OKF v0.2 强制执行统一的模式（type, tags, status, provenance），这是纯 Markdown 所缺乏的，从而能够实现更丰富的过滤和自动化的生命周期管理。
低于 20 ms 的索引化查询 – SQLite FTS5 提供确定性的延迟，而
grep的规模随文件大小线性增长，在大项目中可能会成为瓶颈。双重持久化 – Agent 获得通过数据库实现的即时、机器可读的访问，而开发者保留了人类可读的 Markdown 归档，以便进行审查和版本控制。
命名空间隔离 – 内置支持独立的知识领域，从而防止了无关项目之间的意外“对话”。
何时使用 MCP-Memory
- 需要对数十到数千个知识片段进行快速、确定性的检索的项目。
- 希望实现可审计性的团队：Markdown 目录可以进行版本控制，而数据库为 Agent 驱动。
- 工作流中受益于结构化来源证明（sources, verification, status）以满足合规性或文档化需求的场景。
限制与开放性问题
- 没有内置的向量搜索；记忆是通过精确的键值、标签或全文匹配检索的。
- 性能增益取决于 SQLite 的 FTS5 配置；极大型的语料库可能仍需要分片。
- 一些用户报告，如果 Agent 反复查询 server，MCP tooling 可以增加 token 消耗；需要进行仔细的 prompt 设计。
结论
MCP-Memory 通过将 Google 的 Open Knowledge Format 与 SQLite FTS5 相结合，弥补了人类可读的知识库与高性能 Agent 记忆之间的差距。其双层设计、命名空间隔离和零样板代码设置，使其成为开发者为 AI Agent 寻求结构化、快速且持久化上下文的极佳选择。
Sources
相关
- 项目
- 项目
- Dispatch
- 项目
- 项目