shodh-memory

Shodh-Memory MCP 服务

为 AI Agent 提供持久认知记忆

文档 | GitHub | Python SDK | Rust Crate

---

功能

• 认知架构：基于 Cowan 模型的三级记忆（工作记忆、会话记忆、长期记忆）
• 赫布学习：“共同激活的神经元会连接在一起”——关联会随着使用而增强
• 语义搜索：使用 MiniLM-L6 嵌入向量按含义查找记忆
• 知识图谱：实体提取与关系追踪
• 记忆整合：自动衰减、重放和强化
• 幂等：按内容哈希去重——相同的记忆绝不会存储两次
• 一键安装：自动下载适用于你平台的原生服务二进制文件
• 离线优先：首次运行时自动下载所有模型（总计约 38MB），之后无需联网
• 快速：API 响应低于 200ms，图查询低于 1 毫秒，语义搜索耗时 30–50ms
• GTD 任务管理：完整的待办事项系统，包含项目、子任务、评论和提醒

安装

添加到你的 MCP 客户端配置中：

Claude Desktop / Claude Code（claude_desktop_config.json）：

{
  "mcpServers": {
    "shodh-memory": {
      "command": "npx",
      "args": ["-y", "@shodh/memory-mcp"],
      "env": {
        "SHODH_API_KEY": "your-api-key-here"
      }
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

Codex CLI（.codex/config.toml）：

[mcp_servers.shodh-memory]
startup_timeout_sec = 60
command = "npx"
args = ["-y", "@shodh/memory-mcp"]
env = { SHODH_API_KEY = "your-api-key-here" }

默认情况下，MCP 服务通过 HTTP 与后端通信，可在所有平台上运行。若要改用经过身份验证的本地 IPC 处理普通请求，请添加 SHODH_IPC_ENDPOINT 并设置适用于相应平台的值。在 Windows 上，使用服务打印的当前用户命名管道（通常为 \\.\pipe\shodh-memory-<current-user-SID>）；在 macOS/Linux 上，使用其 Unix 套接字的绝对路径（默认位于平台数据目录下的 shodh/shodh-memory.sock）。在 macOS/Linux 上设置 \\.\pipe\... 会被拒绝，不会悄悄转发给启动的后端。自动启动路径会将明确配置的端点传递给后端，以确保两个进程使用相同的值。

注意：首次运行时会下载服务二进制文件（约 15MB）和嵌入模型（约 23MB）。startup_timeout_sec = 60 可确保初始设置有充足的时间完成。

对于 Cursor/其他 MCP 客户端：使用 npx 命令进行类似配置。

环境变量

变量	描述	默认值
SHODH_API_KEY	必需。用于身份验证的 API 密钥	-
SHODH_IPC_ENABLED	服务监听开关。自动启动的后端会遵循此值。	true
SHODH_IPC_ENDPOINT	MCP 请求的本地端点：Unix 套接字路径（macOS/Linux）或 \\.\pipe\name（Windows）。设置后，普通 MCP 请求会使用本地 IPC，而非 HTTP。macOS/Linux 上不接受 Windows 管道值。	-
SHODH_IPC_REQUIRED	如果 IPC 无法绑定或通过身份验证，则采取失败关闭策略。启用 IPC 时，TypeScript 客户端也要求设置 SHODH_IPC_ENDPOINT。	false
SHODH_API_URL	后端服务 URL	http://127.0.0.1:3030
SHODH_USER_ID	逻辑记忆命名空间；并非授权租户	claude-code
SHODH_NO_AUTO_SPAWN	设置为 true 以禁用后端自动启动	false
SHODH_STREAM	启用/禁用流式写入	true
SHODH_STREAM_WEBSOCKET	仅在 IPC 模式下，显式选择通过 SHODH_API_URL 使用 WebSocket 流式传输	false
SHODH_PROACTIVE	启用/禁用主动呈现记忆	true

本地 IPC

设置 SHODH_IPC_ENDPOINT 后，工具调用、主动呈现、运行状况检查、 资源和提示词都会使用本地 IPC。每次调用都会建立一个本地连接，并 交换一个带版本号、以换行符分隔的 JSON 请求和响应。帧大小上限为 8 MiB。首先通过空身份验证运行状况质询，验证端点是否知道配置的密钥。 随后，普通请求会使用与该服务实例和请求正文绑定的 HMAC 证明；可复用的 API 密钥绝不会通过 IPC 发送，也不会写入 MCP 标准输出。

流式写入仍通过 WebSocket 实现。由于本地协议采用有限的请求/响应模式， IPC 模式下默认禁用流式写入。若要显式启用，请设置 SHODH_STREAM_WEBSOCKET=true，并将 SHODH_API_URL 配置为服务的 HTTP WebSocket 端点。普通操作仍会使用 IPC。

如果未设置 SHODH_IPC_ENDPOINT，MCP 服务会保留原有的 HTTP 和 WebSocket 行为。设置该变量即表示明确选择传输方式：如果 IPC 端点 不可用，系统会报告错误，而不会静默改用 HTTP 重试。

与使用 REST 时一样，SHODH_USER_ID 仍是一个逻辑命名空间。配置的 API 密钥拥有跨命名空间的权限。若相互不信任的租户需要授权边界，请使用不同的 服务/密钥实例。

MCP 工具（共 51 个）

记忆 — 存储、搜索和管理记忆

工具	描述
remember	存储记忆，可选指定类型、标签和元数据
recall	语义搜索，查找相关记忆。传入 full_content: true 可在行内获取完整内容
proactive_context	自动呈现与当前上下文相关的记忆。传入 full_content: true 可在行内获取完整内容
context_summary	获取用于会话初始化的分类上下文
list_memories	列出所有已存储的记忆
read_memory	按 ID 读取特定记忆的完整内容
forget	按 ID 删除特定记忆

记忆预览和截断。 recall、recall_by_tags 和 proactive_context 会返回每条记忆正文的预览（默认上限：500 个字符）。正文超过上限时，输出会被截断，并附带明确、如实的标记，报告实际长度和后续调用方式，例如 …[truncated 500/2340 chars — read_memory("<id>") for full]。预览绝不会在没有提示的情况下被截断——没有标记就表示你看到的是完整正文。要在行内获取完整正文（无标记），可在上述三个工具中的任意一个传入 full_content: true；这会增加 token 用量，因此建议仅用于结果数量较少的情况。read_memory 始终返回完整、未经截断的内容。

待办事项（GTD） — 使用项目和子任务管理任务

工具	描述
add_todo	创建任务，可设置优先级、截止日期、项目和上下文
list_todos	使用语义或 GTD 风格筛选来列出／搜索待办事项
update_todo	更新任务属性（状态、优先级、备注）
complete_todo	将任务标记为已完成（定期任务会自动创建下一项）
delete_todo	永久删除任务
reorder_todo	在其状态组内向上或向下移动任务
list_subtasks	列出父待办事项的子任务
add_todo_comment	为任务添加评论（进度、解决情况）
list_todo_comments	列出任务的所有评论
update_todo_comment	编辑已有评论
delete_todo_comment	删除评论
todo_stats	获取按状态统计的待办事项数据和逾期项目

项目 — 将待办事项整理到各个分组中

工具	描述
add_project	创建项目，可选指定父项目（子项目）
list_projects	列出所有项目及待办事项数量
archive_project	归档项目（隐藏，但可恢复）
delete_project	永久删除项目

提醒 — 按时间、时长和上下文触发提醒

工具	描述
set_reminder	设置提醒（按时间、时长或关键词触发）
list_reminders	列出待处理／已触发／已忽略的提醒
dismiss_reminder	确认已处理已触发的提醒

系统 — 健康状态、备份和诊断

工具	描述
memory_stats	获取已存储记忆的统计信息
verify_index	检查向量索引完整性
repair_index	重新索引孤立的记忆
token_status	获取当前会话的 token 用量
reset_token_session	为新会话重置 token 计数器
consolidation_report	查看记忆整合活动
backup_create	创建所有记忆的备份
backup_list	列出可用备份
backup_verify	验证备份完整性（SHA-256）
backup_restore	从备份恢复
backup_purge	清除旧备份，保留最近的 N 个

REST API（面向开发者）

服务在 http://127.0.0.1:3030 提供 REST API：

// Store a memory
const res = await fetch("http://127.0.0.1:3030/api/remember", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key"
  },
  body: JSON.stringify({
    user_id: "my-app",
    content: "User prefers dark mode",
    memory_type: "Observation",
    tags: ["preferences", "ui"]
  })
});

// Semantic search
const results = await fetch("http://127.0.0.1:3030/api/recall", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key"
  },
  body: JSON.stringify({
    user_id: "my-app",
    query: "user preferences",
    limit: 5
  })
});

关键端点

端点	方法	描述
/health	GET	健康检查
/api/remember	POST	存储一条记忆
/api/recall	POST	语义搜索
/api/recall/tags	POST	按标签搜索
/api/recall/date	POST	按日期范围搜索
/api/memories	POST	列出所有记忆
/api/memory/{id}	GET/PUT/DELETE	CRUD 操作
/api/context_summary	POST	获取上下文摘要
/api/relevant	POST	主动呈现上下文
/api/batch_remember	POST	存储多条记忆
/api/upsert	POST	按 external_id 创建或更新
/api/graph/{user_id}/stats	GET	知识图谱统计信息
/api/consolidation/report	POST	记忆整合报告
/api/index/verify	POST	验证索引完整性
/metrics	GET	Prometheus 指标

认知功能

Hebbian 学习

经常同时访问的记忆会形成更强的关联。系统会自动：

• 在共同检索到的记忆之间建立边
• 通过重复共同激活来增强关联
• 通过长时程增强（LTP）实现永久关联

记忆整合

后台进程会维护记忆状态：

• 衰减：未使用的记忆会逐渐降低激活度
• 重放：定期重放高价值记忆
• 修剪：移除较弱的关联
• 晋升：将重要记忆移至长期存储

三级架构

基于 Cowan 的工作记忆模型：

1. 工作记忆：近期且高度活跃的记忆
2. 会话记忆：当前会话的上下文
3. 长期记忆：带有向量索引的持久存储

工作原理

1. 安装：npx -y @shodh/memory-mcp 会下载软件包
2. 自动启动：首次运行时，会下载原生服务二进制文件（约 15MB）和嵌入模型（约 23MB）
3. 连接：MCP 客户端通过 stdio 连接到此 MCP 服务；当设置了 SHODH_IPC_ENDPOINT 时，后端请求使用本地 IPC，否则使用 HTTP
4. 就绪：开始使用 remember 和 recall 工具
5. 会话结束：当宿主关闭 stdin 时（例如，Claude Desktop 切换线程），shim 会完成所有正在执行的工具调用，并在退出前将响应写入仍保持打开状态的 stdout，因此不会静默丢弃正在处理的请求。排空过程受宽限时间限制；若超时，调用方会收到明确错误，而不是一直等待宿主超时。

后端服务在本地运行，所有数据都存储在你的计算机上。无需依赖云服务。

使用示例

"Remember that the user prefers Rust over Python for systems programming"
"Recall what I know about user's programming preferences"
"What context do you have about this project?"
"List my recent memories"
"Show me the consolidation report"

平台支持

平台	架构	状态
Linux	x64	支持
macOS	x64	支持
macOS	ARM64 (M1/M2)	支持
Windows	x64	支持

相关软件包

• Python SDK：pip install shodh-memory - 原生 Python 绑定
• Rust Crate：cargo add shodh-memory - 作为库使用

链接

• 文档
• GitHub 仓库
• 问题跟踪器

许可证

Apache-2.0