Memory MCP Server

Memory MCP

基于 SQLite 的 MCP 服务，用于持久化存储记忆、全文检索和关系图遍历。

概述

Memory MCP 为启用 MCP 的助手提供本地持久化记忆层。它使用 SQLite 存储以 SHA-256 寻址的记忆条目，并提供由 FTS5 驱动的全文搜索、有向关系图、BFS 回忆遍历和感知令牌预算的上下文检索——所有功能均通过 stdio 传输访问，且无需外部依赖。

主要功能

• 13 个 MCP 工具，支持 CRUD、批量操作、FTS5 搜索、BFS 图回忆、令牌预算上下文检索、关系和统计。
• 全文搜索：通过 SQLite FTS5 搜索内容和标签，并支持重要性和类型筛选。
• 图回忆：支持 BFS 遍历、有限前沿，以及每跳发送 MCP 进度通知。
• 令牌预算检索（retrieve_context）：选择符合调用方指定令牌预算的记忆——无需手动分页。
• 严格的 Zod 输入验证，提供类型化输出信封和 SHA-256 哈希寻址。
• 资源支持：提供 internal://instructions（Markdown 指南）和带哈希自动补全的 memory://memories/{hash} URI 模板。
• stdio 传输：支持干净关闭处理（SIGINT、SIGTERM），且不提供 HTTP 端点。 |

要求

• Node.js >=24。
• 支持 FTS5 的 SQLite（启动时验证）。
• 任何支持 stdio 命令服务的 MCP 客户端。

快速开始

直接通过 npx 使用 npm 包——无需安装：

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

提示

服务仅使用 stdio 传输；不会公开 HTTP 端点。不得让自定义日志污染 stdout。

或者使用 Docker 运行：

docker run --rm -i ghcr.io/j0hanz/memory-mcp:latest

客户端配置

{
  "servers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"memory-mcp","command":"npx","args":["-y","@j0hanz/memory-mcp@latest"]}'

code-insiders --add-mcp '{"name":"memory-mcp","command":"npx","args":["-y","@j0hanz/memory-mcp@latest"]}'

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

claude mcp add memory-mcp -- npx -y @j0hanz/memory-mcp@latest

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

# Pull and run (stdio mode)
docker run --rm -i \
  -e MEMORY_DB_PATH=/data/memory.db \
  -v memory-data:/data \
  ghcr.io/j0hanz/memory-mcp:latest

{
  "mcpServers": {
    "memory-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MEMORY_DB_PATH=/data/memory.db",
        "-v",
        "memory-data:/data",
        "ghcr.io/j0hanz/memory-mcp:latest"
      ]
    }
  }
}

文档维护

• 负责人：在 src/ 中更新 MCP 行为的维护者，必须在同一个 PR 中更新 README.md 和受影响的 mcp/ 镜像页面。
• 链接/版本策略：协议参考链接使用固定版本的 https://modelcontextprotocol.io/specification/2025-11-25/...；避免使用 latest 和混杂的旧版目标。
• 漂移检查清单：
  • 重新核对 src/server.ts 中的能力声明。
  • 将工具/资源/提示词文档与 src/tools/index.ts、src/resources/index.ts 和 src/prompts/index.ts 对照并协调一致。
  • 确认 src/instructions.md 中的限制/注意事项与运行时行为一致。
• 验证命令：npm run type-check、npm run test:fast、npm run build。

MCP 接口

工具摘要

store_memory

存储一条包含内容、标签以及可选类型和重要性的新记忆。幂等——存储相同的内容和标签时，会返回现有哈希，且 created: false。

返回：{ hash, created }

store_memories

在一个事务中存储多条记忆（最多 50 条）。

返回：{ items, succeeded, failed }

get_memory

通过 SHA-256 哈希获取一条记忆。

返回：Memory；若发生 E_NOT_FOUND，则返回 { ok: false, error }。

update_memory

更新现有记忆的内容，并可选择更新标签。返回新旧两个哈希。

返回：{ old_hash, new_hash }

delete_memory

通过哈希删除一条记忆，并级联删除相关的关系行。

返回：{ hash, deleted }

delete_memories

在一个事务中通过哈希删除多条记忆。

返回：{ items, succeeded, failed }

search_memories

使用 FTS5 对记忆内容和标签进行全文搜索。支持按重要性和类型筛选，并使用游标分页。

返回：{ memories, total_returned, nextCursor? }

create_relationship

在两条记忆之间创建有向关系边。此操作具有幂等性。

建议的 relation_type 值：related_to、causes、depends_on、parent_of、child_of、supersedes、contradicts、supports、references。

返回：{ created }

delete_relationship

删除一条有向关系边。

返回：{ deleted }；若出现 E_NOT_FOUND，则返回 { ok: false, error }。

get_relationships

获取某条记忆的关系，可选按方向筛选。

返回：{ relationships, count }

每条关系包含 from_hash、to_hash、relation_type、created_at、linked_hash、linked_content 和 linked_tags。

recall

通过全文查询搜索记忆，然后使用 BFS 遍历关系图，最多跳转 depth 次。每次跳转都会发出 MCP 进度通知。

返回：{ memories, graph, depth_reached, aborted?, nextCursor? }

graph 中的每个项目都采用以下结构：

{ "from_hash": "...", "to_hash": "...", "relation_type": "..." }

说明

aborted: true 表示遍历触及安全限制（RECALL_MAX_FRONTIER_SIZE、RECALL_MAX_EDGE_ROWS 或 RECALL_MAX_VISITED_NODES）。仍会返回部分结果。

retrieve_context

搜索记忆并返回按相关性排序、符合调用方指定令牌预算的结果。无需手动分页和计算令牌即可管理上下文窗口。

返回：{ memories, estimated_tokens, truncated }

提示

令牌数为近似估算（内容长度 ÷ 4）。truncated: true 表示达到预算时仍有候选项未被纳入。

memory_stats

返回记忆和关系的汇总统计信息。不接受输入。

返回：

{
  "memories": {
    "total": 0,
    "oldest": null,
    "newest": null,
    "avg_importance": null
  },
  "relationships": { "total": 0 },
  "by_type": {}
}

资源

提示词

配置

环境变量

重要

如果 MEMORY_DB_PATH 是相对路径（包括默认值 memory_db/memory.db），则相对于进程的工作目录解析。

提示

将 memory_db/ 添加到 .gitignore，以避免将数据库纳入版本控制——其中包含本地会话数据，不应共享或提交。

限制与约束

说明

游标值是不透明的 base64url 编码令牌。请将其视为不透明值，不要解析。

安全

• 传输仅使用 stdio（StdioServerTransport）——没有 HTTP 端点。
• 致命进程错误会写入 stderr；为确保 MCP 协议正常工作，stdout 必须保持干净。
• 在访问数据库前，所有输入都会通过严格的 Zod 模式和有界字段约束进行验证。
• 哈希会根据小写 64 位 SHA-256 十六进制正则表达式进行验证。
• 搜索输入会先被拆分为字母数字词项，再执行 FTS MATCH（非字母数字字符会充当分隔符，从而防止 FTS 注入）。
• SQLite 已启用外键；删除记忆时，相关关系行会级联删除。

开发

安装依赖：

npm install

核心脚本：

使用 MCP Inspector 检查：

npx @modelcontextprotocol/inspector node dist/index.js

构建与发布

GitHub Actions 发布工作流（.github/workflows/release.yml）通过单个 workflow_dispatch 触发器处理版本管理、验证和发布：

workflow_dispatch (patch / minor / major / custom)
    │
    ▼
  release — bump package.json + server.json → lint → type-check → test → build → tag → GitHub Release
    │
    ├──► publish-npm ──► publish-mcp   (npm Trusted Publishing OIDC → MCP Registry)
    │
    └──► publish-docker                (GHCR, linux/amd64 + linux/arm64)

触发发布：

gh workflow run release.yml -f bump=patch

也可以使用 GitHub 界面：Actions → Release → Run workflow。

说明

npm 发布使用 OIDC Trusted Publishing——无需 NPM_TOKEN 密钥。MCP Registry 使用 GitHub OIDC。Docker 使用内置的 GITHUB_TOKEN。

故障排查

许可证

MIT