MemPalace/mempalace · 上手攻略

  • 仓库：MemPalace/mempalace
  • 链接：https://github.com/MemPalace/mempalace
  • 分类：skill
  • 作者：Jay
  • 更新：2026-07-10

这是什么

MemPalace 是一个本地优先的 AI 记忆系统，核心卖点是：原文逐字存储（不摘要、不压缩）、可插拔向量后端、96.6% R@5（LongMemEval 基准）以及完全零 API 调用。数据永远留存在本机，通过语义搜索而非总结来召回历史上下文。

它的组织模型借用了"记忆宫殿"的隐喻： - Wing（侧厅）：一个人物或一个项目 - Room（房间）：具体话题（如 auth-migration、ci-pipeline） - Drawer（抽屉）：原始存储的文本片段 - Hall（走廊）：概念分类（facts/events/discoveries/preferences/advice） - Tunnel（通道）：跨 Wing 的连接关系

官方文档：https://mempalaceofficial.com | PyPI：mempalace

⚠️ 防骗警告：MemPalace 官方仅在 GitHub、PyPI 和 mempalaceofficial.com 有存在，任何其他域名均为假冒。

解决什么问题

  1. 对话历史被 LLM 摘要后丢失细节：传统 RAG 或记忆系统会对历史做压缩/摘要，导致精确细节丢失。MemPalace 坚持原文存储，召回时靠向量检索而非总结。
  2. 上下文窗口不够用：Claude Code 等工具的上下文有限，历史全量塞入不现实。MemPalace 通过语义检索在需要时召回相关片段。
  3. 跨项目、跨人物的上下文无法共享：Wing/room 结构让你可以按人物或项目隔离搜索，也可以跨 Wing 走 Tunnel 发现关联。
  4. API 调用成本和隐私问题：完全本地运行，不依赖任何外部 API，数据不离本机。

快速安装

推荐方式：uv（隔离环境）

uv tool install mempalace
mempalace init ~/palace-demo   # 初始化一个 palace 目录

备选：pipx（同样隔离）

pipx install mempalace
mempalace init ~/palace-demo

备选：虚拟环境 + pip

python -m venv .venv && source .venv/bin/activate
pip install mempalace
mempalace init ~/palace-demo

Docker（无需本地 Python）

# 构建镜像（CPU）
docker build -t mempalace .

# MCP server over stdio（Claude Code 接入用）
docker run -i --rm -v mempalace-data:/data mempalace

# CLI 命令
docker run --rm -v mempalace-data:/data -v /path/to/project:/work mempalace mine /work
docker run --rm -v mempalace-data:/data mempalace search "why GraphQL"

GPU 加速版：docker build -f Dockerfile.gpu -t mempalace:gpu . + --gpus all

核心用法

初始化与挖掘（Mine）

# 初始化 palace（指定项目目录）
mempalace init ~/projects/myapp

# 向 palace 写入（挖掘）项目内容
mempalace mine ~/projects/myapp

语义搜索

mempalace search "why GraphQL"

切换向量后端

# 默认 ChromaDB（本地）
mempalace mine ~/projects/myapp

# 使用 SQLite exact 向量（无外部服务依赖）
mempalace mine ~/projects/myapp --backend sqlite_exact

# Qdrant 后端
MEMPALACE_QDRANT_URL=http://localhost:6333 \
  mempalace mine ~/projects/myapp --backend qdrant

# Postgres + pgvector 后端
# （需先 pip install mempalace[pgvector] 并确保数据库有 vector 扩展）
MEMPALACE_PGVECTOR_DSN=postgresql://localhost:5432/mempalace \
  mempalace mine ~/projects/myapp --backend pgvector

MCP 协议接入 Claude Code

在 Claude Code 的 MCP 配置文件（~/.claude/settings.json 或项目级）添加：

{
  "mcpServers": {
    "mempalace": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "mempalace-data:/data", "mempalace"]
    }
  }
}

注意：Claude Code 会话 30 天无自动保存钩子会过期，参考官方恢复指南：https://mempalaceofficial.com/guide/claude-code-retention.html

跨 Wing 导航

# 发现同一 room 在哪些 Wing 中存在
mempalace traverse --start_room auth-migration

# 发现两个 Wing 之间的 Tunnel（共同 room）
mempalace find_tunnels --wing_a wing_code --wing_b wing_team

典型适用场景

  1. 长期 Claude Code 用户：积累大量对话历史，用 MemPalace 召回任意项目/话题的历史上下文
  2. 多项目并行开发者：每个项目一个 Wing，搜索时可限定范围（wing + room 过滤）
  3. 隐私敏感用户：数据完全本地，不走任何 API，适合处理内部代码或敏感业务
  4. AI Agent 记忆层：作为 Agent 的外部记忆组件，通过 MCP 协议与 Agent 通信
  5. 知识密集型研究：论文阅读、代码审查笔记，通过 halls 分类（facts/discoveries/advice）

坑与注意

  1. 假冒网站：务必确认访问的是 mempalaceofficial.com，任何 .tech/.net 等变体均为恶意，详见 docs/HISTORY.md
  2. Docker 端侧注意：MCP server 模式需要 -i 参数（JSON-RPC 依赖 stdin）；数据持久化需挂载 mempalace-data:/data 卷
  3. Colab/云端 GPU 嵌入：Docker 镜像默认 CPU embedding，如需 CUDA 加速嵌入需构建 GPU 变体
  4. ChromaDB 冷启动：ChromaDB 是默认后端，首次 mine 需要构建向量索引，大型项目耗时较长；sqlite_exact 后端无需外部服务但检索质量可能略低
  5. 会话过期：Claude Code 30 天无 auto-save 钩子会丢失，建议配置 retention hooks
  6. pgvector 扩展：使用 pgvector 后端需自行确保 PostgreSQL 开启 CREATE EXTENSION vector

与同类对比

仓库 定位 优势 不足
MemPalace/mempalace 本地记忆宫殿，结构化 Wing/Room 完全本地、原文存储、架构最清晰 需要手动管理，生态相对新
mem0ai/mem0 多层次记忆层 支持用户/会话/代理记忆分层 默认调用 API，非纯本地
RAGFlow/DIFY RAG 知识库 可视化程度高 更偏知识库，非 Agent 个人记忆
Notion AI 笔记记忆 生态完善 非本地，数据走第三方
context7/context7 最新代码上下文 专注代码检索 不管理长期记忆，只做单次检索

如果你追求数据主权和本地化，且需要结构化地管理跨项目/跨人物的历史记忆，MemPalace 是目前开源领域最完整的方案。

一句话推荐

不摘要、不过滤、零 API——MemPalace 把 AI 的"记忆宫殿"变成现实，适合认真对待长期上下文管理力的开发者。