本地、免费、隐私优先

这是默认推荐的接入方式：免注册，记忆图谱不出本机，默认静态加密。它是一个 stdio MCP Server——下面每个客户端都是把 memory-core-mcp 当子进程拉起，传给它同样这几个环境变量，挑你用的那个看就行。

1. 安装（或者直接跳过这步）

需要 Python 3.11+。最省事的方式是完全不用提前安装——`uvx`（随 uv 一起装的工具）按需下载运行，第 3 步的客户端配置直接指向它就行。想要固定、可控的安装的话，直接装发布在 PyPI 上的包是次简单的方式，不用克隆仓库；仓库里也带了 Dockerfile，给从容器镜像部署的 MCP 目录/托管平台用。

# 最省事：不用提前安装，客户端配置直接指向这条命令
uvx --from 'spomory[llm,embedding,mcp]' spomory-mcp

# 或者，固定安装：
pip install "spomory[llm,embedding,mcp]"

# 或本地开发（已克隆仓库）：
uv pip install -e ".[llm,embedding,mcp]"

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

真实踩过的坑：如果 command 路径指向 ~/Documents/<project>/.venv/... 下，客户端启动 MCP Server 子进程时会报「Server disconnected」。真实的报错在该客户端自己的 MCP 日志里，是一个读取 venv 自己的 pyvenv.cfg 时的 PermissionError。根因是 macOS 的 TCC 隐私保护：~/Documents、~/Desktop、~/Downloads 默认对没有被显式授权「完全磁盘访问权限」的 App 及其子进程是保护起来的——这和代码本身、和仓库放哪里没关系，纯粹是虚拟环境所在路径的系统级限制，跟哪个客户端来拉起它无关。用第 1 步的 `uvx` 就完全不会踩这个坑——`uv` 的缓存目录本来就不在 `~/Documents` 下。这一条只在你自己建虚拟环境安装时才用得上。

解决办法（针对手动建虚拟环境安装）: 把 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

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

可选：让 LLM 和 embedding 也完全本地运行

embedding 默认已经是本地跑的。想让 LLM 调用也变成本地，把 LLM_BASE_URL 指向任意本地跑的 OpenAI 兼容 server 就行——vLLM、Ollama、llama.cpp、MLX 都可以。加上 EMBEDDING_PROVIDER=openai_compatible 能把 embedding 也换成同一条路，而不是本地的 sentence-transformers 模型，这样能完全去掉 torch 这个依赖（这时候 pip install spomory[llm,mcp] 就够了，不需要 [embedding] 这个依赖组）：

# 以 Ollama 为例
export LLM_BASE_URL=http://localhost:11434/v1
export LLM_API_KEY=not-needed
export LLM_MODEL=llama3.1

export EMBEDDING_PROVIDER=openai_compatible
export EMBEDDING_BASE_URL=http://localhost:11434/v1   # 不设置就沿用 LLM_BASE_URL
export EMBEDDING_MODEL=nomic-embed-text

3. 接入你的客户端

所有客户端接本地 server 的方式都一样：把它的「command」（或者等价字段）填成第 1 步 memory-core-mcp 的绝对路径，再传给它第 2 步那几个环境变量。Claude Desktop、Cursor、Codex CLI、豆包和其他 MCP 客户端的具体配置，以及怎么验证跑通了，都在「支持的平台」页面。

去「支持的平台」页面看你的客户端具体怎么配 →

数据存放位置

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

4. 让它真的被用起来

六个工具本身是纯被动的——没有任何机制让 AI 自己想起来去调用它们，连上不代表真的会被用上。仓库里的 skill/spomory/SKILL.md 是一份指令文件，教 AI「任务开始先查记忆、聊出新事实主动存下来」——不是只有被明确要求才做。怎么让客户端读到它，每个客户端不一样：Claude Code 和 Cursor 会自动扫描 .claude/skills/spomory/ 或 .cursor/skills/spomory/；Codex CLI、Gemini CLI、Zed 等好几个客户端有自己对应的目录；也有一些客户端完全没有这个功能，得把内容贴进自定义指令字段。新账号第一次用、查不到任何东西的时候，SKILL.md 还会引导着问几句话而不是干等着从零开始。

GitHub 上的 SKILL.md →

去「支持的平台」页面看你的客户端具体怎么加载 →

已经在用 Claude Code、Codex 或 Cursor？

新账号最大的问题是空的。如果你本来就在这几个客户端里有真实的会话历史，这个命令行工具能把它们读出来，走一遍和 add_memory 完全一样的抽取流程——把真实历史变成初始记忆，不用一句一句手动教。它会真的读你本地的对话内容、发给你配置好的 LLM——这是一个需要你主动执行的步骤，不是自动运行的：

spomory-import-sessions --client claude-code   # 或 codex / cursor

六个工具

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

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