Spomory
GitHub ↗ English

本地、免费、隐私优先

这是默认推荐的接入方式：免注册，记忆图谱不出本机，默认静态加密。它是一个 stdio MCP Server，由 Claude Desktop 或 Cursor 作为子进程拉起。

1. 安装

需要 Python 3.11+，推荐用 uv：

uv pip install "memory-core[llm,embedding,mcp] @ git+https://github.com/yliuai/spomory.git"
# 或本地开发（已克隆仓库）：
uv pip install -e ".[llm,embedding,mcp]"

2. 配置

设置以下环境变量。默认走 OpenAI；换成任意 OpenAI 兼容 API（DeepSeek、通义千问等）只需改 LLM_BASE_URL / LLM_MODEL：

export LLM_API_KEY=...
export LLM_BASE_URL=https://api.deepseek.com   # 可选，默认 OpenAI
export LLM_MODEL=deepseek-v4-flash             # 可选，默认 gpt-4o-mini
export EMBEDDING_MODEL=BAAI/bge-m3             # 可选，默认 bge-m3

3. 启动

memory-core-mcp

⚠️ macOS 上不要把运行时装在 ~/Documents（或 Desktop/Downloads）下

真实踩过的坑：如果 command 路径指向 ~/Documents/<project>/.venv/... 下，Claude Desktop 启动 MCP Server 子进程时会报「Server disconnected」。真实的报错在 ~/Library/Logs/Claude/mcp-server-<name>.log 里，是一个读取 venv 自己的 pyvenv.cfg 时的 PermissionError。根因是 macOS 的 TCC 隐私保护：~/Documents、~/Desktop、~/Downloads 默认对没有被显式授权「完全磁盘访问权限」的 App 及其子进程是保护起来的——这和代码本身、和仓库放哪里没关系，纯粹是这几个特殊文件夹的系统级限制。

解决办法: 把 MCP Server 实际运行用的虚拟环境装在 ~/Documents 之外的普通目录（比如 ~/mcp-servers/），用非 editable 方式安装：

mkdir -p ~/mcp-servers
uv venv --python 3.11 ~/mcp-servers/memory-core-venv
uv pip install "/path/to/memory-core[llm,embedding,mcp]" \
    --python ~/mcp-servers/memory-core-venv/bin/python

4. 配置 Claude Desktop / Cursor

在 claude_desktop_config.json 里加一段（macOS 路径：~/Library/Application Support/Claude/claude_desktop_config.json）。mcpServers 下面这个键就是客户端界面上显示的名字，可以按喜好改，但要连带更新下面「排查方法」里的日志文件名。command 填上面那个非 Documents 路径虚拟环境里 memory-core-mcp 的绝对路径：

{
  "mcpServers": {
    "Spomory": {
      "command": "/Users/<你>/mcp-servers/memory-core-venv/bin/memory-core-mcp",
      "env": {
        "LLM_API_KEY": "...",
        "LLM_BASE_URL": "https://api.deepseek.com",
        "LLM_MODEL": "deepseek-v4-flash"
      }
    }
  }
}

如果这个文件已经有别的键，只加 mcpServers 这一项，不要动其他内容，改之前先备份。改完完全退出并重新打开 Claude Desktop 才会生效。

Cursor

同样结构的 JSON，放在 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目内）。改完重启 Cursor。这部分是根据 Cursor 官方 MCP 文档结构类比得出，没有在真实 Cursor 环境测试过，接入后请按下面的验证步骤实测一遍。

数据存放位置

本地 SQLite 文件（图谱数据+用量统计）默认存在 ~/.memory-core/（可用 MEMORY_CORE_DATA_DIR 改）——特意选在 Documents/Desktop/Downloads 之外。每条实体/关系存的都是密文，不是明文：第一次启动会在数据库旁自动生成一个 encryption.key（权限 600），之后每次启动复用同一个 key。从加密上线前的旧版本升级会在首次启动时自动就地迁移（原文件会先备份，不会被删除）。

验证是否跑通（10 分钟内应该能完成）

  1. 打开 Claude Desktop，新建对话，确认 Connectors/MCP 工具列表里 Spomory 已连接。
  2. 让 Claude 调用 add_memory：「请调用 Spomory 的 add_memory 工具，记住：我在某某公司做后端开发」。
  3. 新建对话，让 Claude 调用 search_memory 查「我在哪里工作」，确认能检索到刚写入的内容。
  4. 让 Claude 调用 forget_memory 删除这条记忆，再重复查询一次，确认已经查不到了。

排查方法

如果 Claude Desktop 提示「Server disconnected」，真实报错在 ~/Library/Logs/Claude/mcp-server-Spomory.log（文件名跟着 mcpServers 里的键名走）——先看这个文件，上面那个 TCC 权限问题就是这么诊断出来的。

五个工具

add_memory 从一段文本抽取事实，写入记忆图谱。
search_memory 先匹配三元组，再用个性化 PageRank 在图上扩展排序，组装成自然语言上下文返回。
forget_memory 找到语义最匹配的一条关系并物理删除，清理孤立实体，写入审计日志。
get_graph 返回某个实体为中心的子图，JSON 格式。
export_memory 把整个记忆图谱导出成「记忆护照」。

GitHub 上的完整快速开始文档（含更多细节）→