持久存储记忆服务

存储器MCP

支持SQLite的MCP服务器，用于持久内存存储、全文检索和关系图遍历。

概述

内存MCP为启用MCP的助手提供本地持久存储层。它通过FTS5支持的全文搜索、有向关系图、BFS召回遍历和令牌预算感知上下文检索在SQLite中存储SHA-256寻址的内存项，所有这些都可以通过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客户端。

快速开始

直接使用npm包 npx --无需安装：

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

[！提示] 服务器仅使用stdio传输；没有暴露HTTP端点。Stout不得被自定义日志污染。

或者使用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"
      ]
    }
  }
}

文件维护

• 所有者：维护人员更新MCP行为 src/ 必须更新 README.md 并受到影响 mcp/ 镜像同一PR中的页面。
• 链接/版本策略：使用固定 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

存储包含内容、标签和可选类型/重要性的新内存。Idempotent——存储相同的内容+标签会返回现有的哈希值 created: false.

退货： { hash, created }

store_memories

在一次交易中存储多个内存（最多50个项目）。

退货： { items, succeeded, failed }

get_memory

通过SHA-256哈希值检索一个内存。

退货： Memory 或 { ok: false, error } 上 E_NOT_FOUND.

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 } 或 { ok: false, error } 上 E_NOT_FOUND.

get_relationships

使用可选的方向过滤器检索内存的关系。

退货： { relationships, count }

每种关系包括 from_hash, to_hash, relation_type, created_at, linked_hash, linked_content，以及 linked_tags.

recall

通过全文查询搜索内存，然后遍历关系图，直到 depth 通过BFS跳转。每跳发送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检查员一起检查：

npx @modelcontextprotocol/inspector node dist/index.js

构建与发布

GitHub操作发布工作流(.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 UI： 行动→ 发布→ 运行工作流.

[！注意] npm发布使用OIDC可信发布——否 NPM_TOKEN 需要保密。MCP注册表使用GitHub OIDC。Docker使用内置 GITHUB_TOKEN.

故障排除

许可证

麻省理工学院