fellowgeek/mcp-memory 来源：https://github.com/fellowgeek/mcp-memory

MCP-Memory：OKF 支持的代理记忆服务器

MCP-Memory 是一个模型上下文协议（MCP）服务器，为 AI 代理（如 Claude Desktop、Cursor、Antigravity、Windsurf 或 Codex）提供持久化的长期记忆能力。记忆记录使用 开放知识格式（Open Knowledge Format，OKF v0.2）（https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md）标准格式化，并通过本地 SQLite 实例（支持 FTS5 全文搜索）建立索引，以实现快速键值查找、标签过滤和内容搜索。

快速通道： 直接跳转到快速开始

主要特性

• 跨会话持久状态： 使 AI 代理能够读取、存储、搜索和删除有状态的记忆片段，这些记忆可在多次对话轮次和会话之间持久保留。
• OKF 标准合规： 每条记忆项均以 OKF v0.2 Markdown 文档格式存储，包含 YAML frontmatter（type、key、namespace、tags、generated、sources、verified、status、stale_after），严格遵守 SPEC.md 和 OKF_RULES.md。
• 双层架构：
  • 人类可浏览的 OKF 目录：自动将每条记忆以原始 .md 文件形式导出并同步到 memory/ 包目录中，并附带层级化的 index.md 渐进式披露文件（根 index.md 带有 okf_version: "0.2" 版本号）以及 log.md 更新历史追踪。
  • 高性能 SQLite 索引：SQLite FTS5（全文搜索）和自动触发器，实现亚 20 毫秒的键查找和即时关键词搜索。
• 命名空间隔离： 支持上下文分离（例如 user/preferences、project/architecture、default）。
• 零样板设置： 快速设置向导（python3 setup.py）可自动配置已安装的 MCP 工具（Antigravity、Claude、Cursor、Windsurf、Codex）。

MCP 工具

服务器向交互式代理提供四个主要的 MCP 工具：

1. memory_store

以 OKF v0.2 格式存储或更新一条记忆记录。

• 参数：
  • key （字符串，必填）：记忆的唯一标识符或路径（例如 user/preferences/coding_style 或 project/architecture）。
  • content （字符串或对象，必填）：要存储的核心信息。
  • project_root （字符串，必填）：当前活动项目根目录的绝对路径（例如 /Users/user/Projects/my-app）。
  • tags （字符串数组，可选）：用于过滤的分类标签。
  • namespace （字符串，可选，默认值："default"）：作用域/命名空间。
  • concept_type （字符串，可选，默认值："Agent Memory"）：OKF 概念类型（例如 Metric、Playbook、Attested Computation）。
  • title （字符串，可选）：显示名称。
  • description （字符串，可选）：一行摘要。
  • resource （字符串，可选）：底层资产的规范 URI。
  • status （字符串，可选，默认值："stable"）：生命周期状态（draft | stable | deprecated）。
  • stale_after （字符串，可选）：ISO 日期（YYYY-MM-DD）。
  • sources （对象数组，可选）：来源信息 [{resource, id, title, author, usage_count, last_modified}]。
  • verified （对象数组或对象，可选）：验证事件 [{by, at}]。
  • generated_by （字符串，可选）：遵循参与者约定的参与者标识符（/、human:、process:）。

2. memory_retrieve

通过键和命名空间检索特定的记忆。

• 参数：
  • key （字符串，必填）：要查找的记忆键。
  • project_root （字符串，必填）：当前活动项目根目录的绝对路径。
  • namespace （字符串，可选，默认值："default"）：作用域/命名空间。

3. memory_search

查找匹配关键词、标签或命名空间过滤条件的记忆。

• 参数：
  • project_root （字符串，必填）：当前活动项目根目录的绝对路径。
  • query （字符串，可选）：跨键、frontmatter 和内容的关键词搜索查询。
  • tags （字符串数组，可选）：按特定标签过滤。
  • namespace （字符串，可选）：将搜索范围限定到某个命名空间。
  • limit （整数，可选，默认值：10）：最大结果数量。

5. memory_get_last

代理指令（会话开始）： 检索最后记录的会话检查点（system/last_memory），使 AI 代理在打开项目或启动会话时立即知道上次工作停在哪里。

• 参数：
  • project_root （字符串，必填）：当前活动项目根目录的绝对路径。
  • namespace （字符串，可选，默认值："default"）：作用域/命名空间。

6. memory_update_last

代理指令（里程碑与进度）： 每当完成里程碑、做出关键更改或暂停工作时，更新规范的会话检查点（system/last_memory）。

• 参数：
  • content （字符串或对象，必填）：简要说明或结构化字典，总结进度并引用关键记忆文件。
  • project_root （字符串，必填）：当前活动项目根目录的绝对路径。
  • namespace （字符串，可选，默认值："default"）：作用域/命名空间。
  • summary （字符串，可选）：对所达成里程碑的一句话描述。

OKF（开放知识格式）结构

每条存储的记忆都严格遵守 OKF v0.2 规范（SPEC.md 和 OKF_RULES.md）：

---
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.

快速开始

1. 克隆仓库

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

2. 交互式设置向导

运行 setup.py 以自动检测并将 mcp-memory 注册到你的 AI 工具中：

python3 setup.py

注意： 一旦 setup.py 完成工具配置，你的 AI 客户端将在需要时自动在后台启动 mcp-memory。你不需要手动启动或保持服务器进程在终端中运行。

3. 通过 CLI 手动运行（可选/调试）

如果你想手动验证启动、检查 stdio 输出，或预初始化虚拟环境（.venv），可以直接运行 run.sh：

./run.sh

手动客户端配置

如果你更倾向于手动配置 MCP 客户端，请添加指向 run.sh 的 "memory" 服务器条目：

JSON 配置（Antigravity、Claude Desktop、Cursor、Windsurf）

添加到客户端的 mcp_config.json 或 claude_desktop_config.json：

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

TOML 配置（Codex Desktop）

添加到 ~/.codex/config.toml：

[mcp_servers.memory]
command = "/ABSOLUTE/PATH/TO/run.sh"

CLI 配置

• Claude Code CLI：

claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh

• Codex CLI：

codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh

测试

运行自动化测试套件以验证 OKF 序列化、SQLite 数据库操作和 FastMCP 工具执行：

python3 test_memory.py

存储与环境变量

默认情况下，mcp-memory 会在每个项目的根目录内创建项目隔离的记忆存储：

• OKF Markdown 文件（人类可读）：项目根目录下的 memory/ 文件夹。
• SQLite 数据库（隐藏索引）：项目根目录下的 .mcp_memory/memories.db。

你可以使用环境变量自定义此行为：

• MCP_MEMORY_PROJECT_ROOT：项目根目录（默认值：进程当前工作目录 cwd）。
• MCP_MEMORY_DB_PATH：SQLite 数据库文件路径（默认值：相对于项目根目录的 .mcp_memory/memories.db）。
• MCP_MEMORY_DIR：开放知识格式（OKF）.md 文件的目录（默认值：相对于项目根目录的 memory）。

提示： 如果你更倾向于在所有项目之间共享一个全局记忆存储，可以在客户端的 MCP 配置中设置 MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db 和 MCP_MEMORY_DIR=~/.mcp_memory/memory。