MemPalace 部署与实战：打造永不遗忘的 AI 记忆系统

中等难度 · 约 20 分钟 · 你将掌握 MemPalace 完整部署流程，理解 Palace 层级结构，并学会用 MCP 将记忆系统接入任意 AI。

---

目标读者

1-3 年经验开发者，已使用 Claude Code / Cursor / Copilot 等 AI 编程工具。希望让 AI 在长期项目中保持上下文记忆，不再每次从零开始。

---

核心依赖与环境

• Python：3.9+
• 核心依赖：chromadb>=0.5.0,<0.7、pyyaml>=6.0
• 安装方式：pip install mempalace 或 uv pip install mempalace
• 操作系统：macOS / Linux / Windows（WSL 均可）
• 存储：ChromaDB（向量库）+ SQLite（知识图谱），全部本地存储，无需网络

---

完整项目结构

mempalace/
├── mempalace/                 # 核心 Python 包
│   ├── cli.py                 # CLI 入口，路由到 mine/search/init 等
│   ├── mcp_server.py          # MCP 服务端，暴露 19 个工具
│   ├── knowledge_graph.py     # 时序知识图谱（SQLite）
│   ├── palace_graph.py        # Palace 导航图（BFS 遍历、隧道发现）
│   ├── convo_miner.py         # 对话挖掘，按 Q+A 对切分
│   ├── miner.py               # 项目文件挖掘，按段落切分
│   ├── searcher.py            # 语义搜索（ChromaDB）
│   ├── normalize.py           # 5 种对话格式标准化
│   ├── dialect.py             # AAAK 压缩方言
│   ├── layers.py              # 四层记忆栈（L0-L3）
│   ├── onboarding.py          # 引导初始化
│   ├── entity_detector.py     # 自动识别人名/项目名
│   └── split_mega_files.py    # 切分合并的会话文件
├── hooks/                     # Claude Code 自动保存钩子
│   ├── mempal_save_hook.sh     # 每 15 条消息自动保存
│   └── mempal_precompact_hook.sh  # 上下文压缩前紧急保存
├── benchmarks/               # 可复现基准测试（LongMemEval / LoCoMo）
│   ├── longmemeval_bench.py
│   ├── locomo_bench.py
│   └── BENCHMARKS.md
└── examples/
    ├── basic_mining.py
    └── mcp_setup.md

---

手把手步骤

Step 1：安装

pip install mempalace

最低 Python 版本为 3.9。安装完成后确认可用：

mempalace --version

---

Step 2：初始化记忆宫殿

mempalace init ~/projects/myapp

init 命令会启动引导流程，依次询问：

• 你经常协作的人（添加到 wing 配置）
• 你在做的项目（每个项目一个 wing）
• 你的 AI 身份（写入 L0 层）

引导完成后，生成两个配置文件：

• ~/.mempalace/config.json — 全局配置（palace 路径等）
• ~/.mempalace/wing_config.json — wing 与关键词映射

生成的 wing_config.json 大致如下：

{
  "default_wing": "wing_general",
  "wings": {
    "wing_kai": { "type": "person", "keywords": ["kai", "kai's"] },
    "wing_driftwood": { "type": "project", "keywords": ["driftwood", "analytics", "saas"] }
  }
}

每次 AI 启动时，只需加载 L0 + L1（约 170 tokens），就知道你的世界长什么样。

---

Step 3：挖掘数据

MemPalace 支持两种挖掘模式，根据你的数据源选择。

模式 A：挖掘项目文件（代码、文档、笔记）

mempalace mine ~/projects/myapp

miner 会递归扫描目录，按段落切分，存入 ChromaDB，Drawer 存储原始内容。

模式 B：挖掘对话导出（Claude/ChatGPT/Slack）

# 基础用法
mempalace mine ~/chats/ --mode convos

# 指定 wing，方便后续按项目过滤
mempalace mine ~/chats/ --mode convos --wing myapp

# 开启自动分类（提取决策、偏好、里程碑、问题、情感上下文）
mempalace mine ~/chats/ --mode convos --extract general

convo_miner 按 Q+A 对切分对话，自动检测 room 归属（通过 room_detector_local.py 的 70+ 模式匹配，无需 API）。

---

Step 4：语义搜索验证

挖掘完成后，搜一下试试：

mempalace search "why did we switch to GraphQL"

加 wing 过滤，只在特定项目中搜索：

mempalace search "auth decision" --wing driftwood

再精确一点，加上 room 过滤：

mempalace search "auth decision" --wing driftwood --room auth-migration

返回的是 Drawer 中的原文（verbatim），没有摘要、没有信息损失。ChromaDB 做向量检索，Closet 做结构化摘要。

---

Step 5：接入 MCP 服务

MCP（Model Context Protocol）让 MemPalace 作为工具暴露给任意 AI。一次配置，永久生效。

接入 Claude Code：

claude mcp add mempalace -- python -m mempalace.mcp_server

配置完成后，Claude Code 自动获得 19 个工具，AI 会在需要时自己调用 mempalace_search，你不需要手动搜。

接入 Gemini CLI：

# 参考 examples/gemini_cli_setup.md
claude mcp add mempalace -- python -m mempalace.mcp_server

Gemini CLI 对 MCP 支持更完善，save hooks 也可以自动配置。

MCP 工具清单（19 个）：

AI 从 mempalace_status 返回中自动学会 AAAK 语法和记忆协议，无需你手动配置 prompt。

---

Step 6：配置 Claude Code Auto-Save Hooks

Claude Code 的 Hooks 可以让 MemPalace 在每次对话过程中自动保存记忆。

修改 ~/.claude/settings.json（Claude Code 全局配置），添加：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"
          }
        ]
      }
    ]
  }
}

两个钩子的区别：

• Stop：每 15 条消息触发一次，结构化保存——主题、决策、引用、代码变更全部记录，同时重建 L1 层（关键事实层）。
• PreCompact：上下文压缩前触发，紧急抢救尚未保存的记忆，避免压缩过程中丢失重要上下文。

---

Step 7：理解 Palace 结构

MemPalace 的核心抽象是「记忆宫殿」——借鉴古希腊演说家的记忆术，用空间结构替代扁平的搜索索引。

  WING: kai (person)

    ┌──────────┐  ──hall──  ┌──────────┐
    │ auth-mig │            │ security  │
    └────┬─────┘            └──────────┘
         │
         ▼
    ┌──────────┐      ┌──────────┐
    │  Closet  │ ───▶ │  Drawer  │  ← 原文存在这里
    └──────────┘      └──────────┘

  TUNNEL（跨 wing 连接）:
  kai/auth-mig  ←→  driftwood/auth-mig  ←→  priya/auth-mig

Wings：一个人或一个项目，记忆的主分类。每个 wing 下可以有多个 rooms。

Rooms：wing 内的具体主题，如 auth-migration、ci-pipeline、pricing。同名 room 出现在不同 wing 时，自动生成 tunnel。

Halls：记忆类型的走廊，每个 wing 都有相同的 hall 集合：

• hall_facts — 已锁定的决策
• hall_events — 会话、里程碑、调试过程
• hall_discoveries — 突破和新洞察
• hall_preferences — 习惯、偏好、意见
• hall_advice — 推荐和解决方案

Closets：摘要层，指向原始内容所在的位置（Drawer）。原文不会丢失，只是多了一层可导航的结构。

Drawers：原文存放处。MemPalace 的 raw verbatim 模式正是从这里读原始内容做向量检索，达到了 96.6% R@5。

---

Step 8：使用 Knowledge Graph 时序关系

ChromaDB 存储的是原文向量，Knowledge Graph（SQLite）存储的是结构化事实三元组，两者互补。

from mempalace.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()

# 添加事实，带有效期
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
kg.add_triple("Maya", "completed", "auth-migration", valid_from="2026-02-01")

# 查询 Kai 现在在做什么
print(kg.query_entity("Kai"))
# → [Kai → works_on → Orion (current)]

# 查询 2026-01-20 的情况（这时 Maya 还没完成 auth-migration）
print(kg.query_entity("Maya", as_of="2026-01-20"))
# → [Maya → assigned_to → auth-migration]

# 查看 Orion 项目的时间线
print(kg.timeline("Orion"))
# → 按时间顺序排列的事实链

# Maya 换项目了，让旧事实失效
kg.invalidate("Maya", "assigned_to", "auth-migration", ended="2026-02-01")
# 现在 query_entity("Maya") 不再返回 auth-migration

Facts 的有效期窗口（valid_from / ended）是 MemPalace 的核心能力——查询历史状态时，告诉你「当时发生了什么」，而不是「现在发生了什么」。

---

Step 9：记忆栈四层架构

MemPalace 的检索策略分四层，越往上越轻量，越往下越精准：

每次 AI 启动，先加载 L0 + L1（mempalace wake-up），170 tokens 就能建立完整的上下文背景。只有当话题触发特定 room 时，才加载 L2；只有显式提问时，才触发 L3 的全量 ChromaDB 搜索。

这正是 MemPalace 成本极低的原因——$10/年的搜索开销 vs $507/年的摘要方案。

---

常见问题排查

Q1：搜索结果为空，但确信内容存在

分三步排查：

# 1. 确认 wing 和 room 名称正确
mempalace list-wings
mempalace list-rooms --wing myapp

# 2. 放宽范围，不指定 wing/room 全量搜
mempalace search "关键词"   # 不带 --wing

# 3. 检查 ChromaDB 是否真的写入了
mempalace status            # 看 drawer 总数是否为 0

如果 mempalace status 显示 0 drawer，说明挖掘步骤没成功，可能是对话文件格式不被支持（目前支持 Claude Code JSONL、Claude.ai JSON、ChatGPT JSON、Slack JSON、plain text）。

Q2：ChromaDB 集合名冲突

默认集合名为 mempalace_drawers。如果多次 init 或在不同目录下运行，可能遇到冲突。在 ~/.mempalace/config.json 中显式指定路径：

{
  "palace_path": "/custom/path/to/palace",
  "collection_name": "mempalace_drawers"
}

然后用 --palace <path> 覆盖：

mempalace search "query" --palace /custom/path/to/palace

Q3：MCP 连接失败

先手动验证 MCP 服务能正常启动：

python -m mempalace.mcp_server
# 正常情况下不输出任何内容，保持前台运行
# Ctrl+C 退出

如果报错 ModuleNotFoundError，检查是否正确安装：

pip show mempalace

如果用的是虚拟环境，确认 Claude Code 的 MCP 配置中写的是正确的 Python 路径：

which python   # 获取正确的 python 路径
claude mcp add mempalace -- /path/to/python -m mempalace.mcp_server

Q4：MCP 工具调用正常但结果不符合预期

AI 调用 mempalace_search 时，wing/room 参数需要精确匹配才能发挥 Palace 结构的最大效果。在 prompt 中引导 AI 使用正确的过滤：

When searching for project-specific memories, always pass --wing <project>.
When searching for a specific topic, always pass --room <room-name>.

Q5：Hook 脚本没有触发

# 检查 Claude Code 的 hooks 是否启用
claude doctor

确认 settings.json 中 hooks 路径为绝对路径。相对路径在 Claude Code 不同工作目录下会解析失败。

Q6：知识图谱时序查询返回意外结果

时序查询依赖 as_of 参数格式，日期必须是 YYYY-MM-DD：

# 错误格式
kg.query_entity("Kai", as_of="2026/03/01")

# 正确格式
kg.query_entity("Kai", as_of="2026-03-01")

另外，确认用 add_triple 添加事实时 valid_from 也用了正确格式，否则时序窗口不生效。

---

扩展阅读 / 进阶方向

AAAK 实验性压缩层

AAAK 是一种有损的缩写方言，通过正则替换将重复实体压缩为代码。在大规模（同一项目被提及数百次）场景下可节省 token 成本，但目前 raw verbatim 模式（96.6%）仍优于 AAAK 模式（84.2%）。适用场景是长时间、多会话、重复实体密集的项目。

Specialist Agents 多 Agent 记忆隔离

每个 Agent 有独立的 wing 和 AAAK 日记：

~/.mempalace/agents/
  ├── reviewer.json    # 代码质量、模式、bug
  ├── architect.json   # 架构决策、权衡
  └── ops.json         # 部署、故障、基础设施

AI 从 palace 运行时动态发现 agent，不需要在 CLAUDE.md 里写任何配置。

基准测试复现

benchmarks/ 目录下有完整的 LongMemEval、LoCoMo 复现脚本：

python benchmarks/longmemeval_bench.py

全程不需要 API key，在 M2 Ultra 上 5 分钟内跑完 500 题，验证 96.6% 的可复现性。

与其他系统的横向对比

MemPalace 是唯一在零 API 调用下达到最高分的方案。