MemPalace 深度实战：当 AI 学会「永不遗忘」——从宫殿记忆法到生产级 MCP 记忆系统的完全指南（2026）

写在前面

你有没有过这种体验——跟 Claude Code 聊了一个小时，它帮你重构了三个模块、做了五个关键架构决策，然后你随口问一句「我们刚才讨论的数据库方案是什么来着？」，它一脸茫然。

不是它笨。是上下文窗口就那么大，session 一关，记忆归零。

这个问题在 AI Agent 时代变得尤为尖锐：Agent 的推理能力越来越强，但它们对「昨天做了什么」的记忆力几乎为零。就好比一个天才程序员，每天早上来公司都要重新认识整个项目。

2026 年 6 月，一个叫 MemPalace 的开源项目冲上 GitHub Trending，日增 855 星，总星数突破 54K。它承诺的很简单：给你的 AI 装上永不遗忘的记忆层。

但真正让我坐下来写这篇文章的，不是它的星数，而是它做了一个违背行业直觉的决定——不摘要，不提取，原样存储。在这个所有人都在搞 LLM 摘要压缩的时代，这操作有点反常识。

今天我们就来拆解 MemPalace，从架构原理到生产部署，一行一行地讲清楚。

一、AI 记忆问题的本质

1.1 三条路都走不通

AI Agent 的记忆问题，本质上是「如何让无状态的推理引擎拥有有状态的记忆」。目前的方案主要有三条路：

路线一：上下文窗口塞满

把所有历史对话塞进 prompt。GPT-4 有 128K token 上下文，Claude 有 200K。看起来很多，但一个活跃项目的上下文——代码、决策、bug 讨论、架构演进——轻松就超了。更关键的是，token 越多，推理越慢，成本越高。这不是解决方案，这是信用卡账单。

# 典型的暴力上下文方案
context = ""
for msg in conversation_history:
    context += f"{msg.role}: {msg.content}\n"

# 当 history 超过 100K tokens...
# 1. API 调用成本暴增
# 2. 推理延迟显著上升
# 3. 关键信息被淹没在噪音中

路线二：RAG 摘要检索

先用 LLM 把对话压缩成摘要，存进向量库，检索时用摘要匹配。这是当前最主流的方案（Mem0、Zep 等都是这条路）。但摘要就是有损压缩——你代码注释里那个微妙的含义、讨论中那句看似随口却关键的「其实我们之前试过这个方案，但性能不行」……摘要会丢掉这些。

# 典型的摘要式 RAG
summary = llm.summarize(conversation)  # 信息在这里丢失
embedding = embed(summary)              # 在压缩后的文本上做 embedding
store.save(embedding, summary)          # 存的是摘要，不是原文

# 检索时
results = store.search(query_embedding)
# 你拿到的是摘要的摘要，不是原始决策

路线三：云服务托管

把记忆交给云服务。问题是：你的代码架构决策、你的技术选型讨论、你的团队人名和项目名——这些都是敏感信息。上云意味着你的 AI 记忆和你的代码一样面临隐私风险。

1.2 第四条路：原样存储 + 结构化检索

MemPalace 选了第四条路：本地原样存储，不做任何摘要或提取，用结构化的元数据过滤来弥补全量检索的精度问题。

这背后的哲学是：

AI 再怎么做摘要也赶不上原文的信息量。你写的代码注释里的那个微妙含义，摘要会丢。你讨论中那句看似随口却关键的判断，提取会漏。

这个判断在 LongMemEval 基准上得到了验证：96.6% R@5，开源记忆系统排名第一，而且这个分数完全不需要 LLM 参与，纯靠语义检索。

二、MemPalace 核心概念：宫殿记忆法

2.1 从古希腊到 AI

MemPalace 的名字来自古希腊的「宫殿记忆法」——修辞学家们想象一座建筑，把要记住的概念放在不同的房间里。需要回忆时，在脑海中走过这座建筑，找到对应的房间。

MemPalace 把这个两千多年前的想法变成了一个技术架构：

Palace（宫殿）
├── Wing（翼）：一个人或一个项目
│   ├── Room（房间）：一个具体话题
│   │   ├── Hall（厅）：概念分类
│   │   │   ├── hall_facts — 决策、选择
│   │   │   ├── hall_events — 事件、里程碑
│   │   │   ├── hall_discoveries — 发现、洞察
│   │   │   ├── hall_preferences — 偏好、习惯
│   │   │   └── hall_advice — 建议、方案
│   │   └── Drawer（抽屉）：原始文本块
│   └── Tunnel（隧道）：连接不同 Wing 的跨项目通道
└── Closet（壁橱）：摘要层（当前主要路径仍是 Drawer）

2.2 为什么需要结构，而不是平铺

你可能会问：为什么不直接把所有文本扔进向量库，检索就完了？

因为平铺检索在数据量大了之后精度急剧下降。假设你有 10 个项目、50 个不同话题的讨论，每个话题可能有上百条相关记录。当你的查询是「我们为什么从 REST 迁移到 GraphQL？」时，平铺向量库会返回所有跟 GraphQL 相关的内容——包括你在项目 A 里的 GraphQL 讨论、项目 B 里的 GraphQL bug 排查、以及项目 C 里关于 GraphQL 性能的闲聊。

Wing/Room 结构的价值在于作用域过滤：

# 平铺检索：在所有内容中搜索
results = vectorstore.search("why GraphQL")  # 混杂所有项目

# 结构化检索：只搜索特定项目
results = vectorstore.search(
    "why GraphQL",
    filter={"wing": "myapp", "room": "graphql-migration"}
)  # 精准定位

这不是什么新型检索算法——就是向量数据库标准的 metadata filtering。但关键在于操作层面的价值：清晰的作用域规则，让人和 Agent 都能预测性地缩小搜索范围。

2.3 Tunnel：跨项目的知识桥梁

这是 MemPalace 最有意思的设计之一。当同一个 Room 名称出现在不同 Wing 中时，系统可以自动建立跨 Wing 连接：

wing_kai / hall_events / auth-migration → "Kai 排查了 OAuth token 刷新问题"
wing_driftwood / hall_facts / auth-migration → "团队决定把认证迁移到 Clerk"
wing_priya / hall_advice / auth-migration → "Priya 推荐 Clerk 而非 Auth0"

三个 Wing，同一个 Room 名。通过 MCP 工具 mempalace_traverse，可以从一个 Room 出发，发现所有相关 Wing 中的关联记忆：

# MCP 调用示例
result = mempalace_traverse(start_room="auth-migration")
# 返回：wing_kai, wing_driftwood, wing_priya 三个 Wing 中的相关内容

这在真实项目中非常有用——你可能在后端项目和前端项目中分别讨论过认证方案，Tunnel 能帮 AI 把这些分散在不同上下文中的讨论串联起来。

三、架构分析：逐层拆解

3.1 整体架构

┌─────────────────────────────────────────────────┐
│                   MCP Client                     │
│         (Claude Code / Cursor / Codex)           │
└──────────────────────┬──────────────────────────┘
                       │ stdio JSON-RPC
                       ▼
┌─────────────────────────────────────────────────┐
│              MCP Server (29 tools)               │
│  ┌───────────┐ ┌──────────┐ ┌────────────────┐ │
│  │ Palace RW │ │ KG Query │ │ Navigation     │ │
│  │ + Diary   │ │ + Timeline│ │ + Tunnels      │ │
│  └─────┬─────┘ └────┬─────┘ └───────┬────────┘ │
│        └─────────────┼───────────────┘          │
│                      ▼                           │
│           ┌─────────────────────┐                │
│           │  Memory Manager     │                │
│           │  (检索增强 + 协议)   │                │
│           └──────────┬──────────┘                │
│                      ▼                           │
│  ┌─────────────────────────────────────────┐    │
│  │        Pluggable Backend Interface       │    │
│  │         (backends/base.py)               │    │
│  └──┬──────┬──────────┬──────────┬─────────┘    │
│     ▼      ▼          ▼          ▼               │
│  ChromaDB Qdrant  pgvector  sqlite_exact         │
└─────────────────────────────────────────────────┘

3.2 后端抽象层：不是画个接口完事

这是 MemPalace 最值得学习的工程实践。大多数开源项目说「可插拔」就是定义个接口，然后只实现一个 ChromaDB 后端。MemPalace 的 backends/base.py 定义了完整的存储契约，然后用四个实现去验证这个契约的正确性：

这四个后端覆盖了三种不同的存储范式：

• 嵌入式库（ChromaDB、sqlite_exact）：直接在进程内运行
• REST/字典存储（Qdrant）：通过 HTTP API 访问
• SQL/JSONB 存储（pgvector）：通过 SQL 查询访问

这不是凑数——三种范式意味着接口抽象必须足够通用，不能被任何一种范式绑架。让我看看核心接口：

# mempalace/backends/base.py 核心契约（简化版）
from abc import ABC, abstractmethod
from typing import List, Optional, Dict, Any

class MemoryBackend(ABC):
    """所有存储后端必须实现此接口"""
    
    # --- 能力声明 ---
    @property
    @abstractmethod
    def capabilities(self) -> set[str]:
        """声明后端支持的能力，如 namespace_isolation、batch_write 等"""
        ...
    
    # --- 增删查改 ---
    @abstractmethod
    def add_drawers(self, wing: str, room: str, 
                    drawers: List[DrawerEntry]) -> List[str]:
        """批量写入抽屉，返回 ID 列表"""
        ...
    
    @abstractmethod
    def search(self, query_embedding: List[float], 
               top_k: int = 10,
               wing: Optional[str] = None,
               room: Optional[str] = None) -> List[SearchResult]:
        """语义检索，支持 wing/room 过滤"""
        ...
    
    @abstractmethod
    def get_drawer(self, drawer_id: str) -> Optional[DrawerEntry]:
        """按 ID 获取单个抽屉"""
        ...
    
    @abstractmethod
    def delete_drawer(self, drawer_id: str) -> bool:
        """删除抽屉"""
        ...
    
    # --- 命名空间隔离 ---
    @abstractmethod
    def supports_namespace_isolation(self) -> bool:
        """是否支持命名空间隔离（多租户）"""
        ...

这个接口的设计有几个关键点：

1. 能力声明而非继承判断：不是用 isinstance 来判断后端能力，而是让后端自己声明 capabilities。这避免了运行时的反射黑魔法。
2. 批量操作优先：add_drawers 是批量接口，不是单条插入。这确保了索引构建的性能。
3. 命名空间隔离：Qdrant 和 pgvector 后端通过命名空间实现多租户隔离，ChromaDB 和 sqlite_exact 则不需要。

3.3 Miner 模块：从文件到记忆

Miner 是 MemPalace 的数据入口，负责把各种来源的原始内容变成结构化的记忆：

# 三种挖掘模式
mempalace mine ~/projects/myapp                    # 项目文件
mempalace mine ~/.claude/projects/ --mode convos   # Claude 对话
mempalace mine ~/chats/ --mode convos --extract general  # 带分类的对话挖掘

Miner 的工作流程：

原始文件/对话
    │
    ▼
[分块器] ──── 按语义边界切分，不是简单按字数切
    │
    ▼
[分类器] ──── --extract general 时启用
    │           ├── decision（决策）
    │           ├── preference（偏好）
    │           ├── milestone（里程碑）
    │           ├── problem（问题）
    │           └── emotional_context（情绪上下文）
    │
    ▼
[Room 分配] ── 根据文件路径和内容自动分配 Room
    │
    ▼
[Embedding] ── 本地 embedding 模型（无需 API Key）
    │
    ▼
[写入后端] ── 存入 ChromaDB / Qdrant / pgvector

分块策略的关键区别：传统的 RAG 系统通常按固定 token 数切分（比如每 512 token 一块），这在代码场景下效果很差——一个函数可能被切成两半。MemPalace 的分块器会识别代码结构边界（函数、类、块注释），在语义完整点切分。

3.4 Hybrid 检索流水线

MemPalace 的检索不是简单的向量相似度，而是一个多阶段流水线：

查询 "为什么从 REST 迁移到 GraphQL"
    │
    ▼
[阶段 1: 语义检索] ──── ChromaDB 向量相似度
    │                    默认 top_k=20
    ▼
[阶段 2: 关键词增强] ── 关键词匹配加分
    │                    提升包含 "REST" "GraphQL" "迁移" 的结果
    ▼
[阶段 3: 时间近因增强] ─ 最近的内容加分
    │                    2 周内的内容权重更高
    ▼
[阶段 4: 偏好模式提取] ─ 用户偏好加权
    │                    用户频繁查询的主题权重更高
    ▼
[阶段 5: LLM 重排（可选）]
    │                    用任意 LLM 对 top-20 重排
    │                    需要 API Key，但不是必需的
    ▼
最终结果

各阶段的分数叠加：

# 简化的评分公式
final_score = (
    semantic_score * 0.4 +       # 语义相似度
    keyword_boost * 0.2 +        # 关键词匹配
    recency_boost * 0.2 +        # 时间近因
    preference_boost * 0.2       # 偏好模式
)
# 如果启用 LLM 重排，则 final_score 被 LLM 排序替换

基准数据：

96.6% 不需要任何 API Key。这是 MemPalace 「本地优先」理念的核心底气。

四、代码实战：从零搭建生产级记忆系统

4.1 安装与环境准备

推荐使用 uv（Astral 出品，比 pip 快 10 倍）：

# 安装 uv（如果还没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 MemPalace CLI（隔离环境，不污染全局）
uv tool install mempalace

# 验证安装
mempalace --version
# 输出：mempalace 3.1.0

为什么强调用 uv tool install 而不是 pip install？因为 MemPalace 依赖了 chromadb、numpy、grpcio 等重量级包，直接 pip 装全局环境很容易跟其他项目冲突。uv tool install 会创建一个隔离的虚拟环境，CLI 挂在 PATH 上，但依赖互不干扰。

如果你更喜欢 Docker：

# CPU 版本
docker build -t mempalace .

# GPU 加速版本（CUDA embedding）
docker build -f Dockerfile.gpu -t mempalace:gpu .

4.2 初始化你的第一个 Palace

# 创建项目目录
mkdir -p ~/projects/my-saas-app
cd ~/projects/my-saas-app

# 初始化 Palace
mempalace init .

# 输出示例：
# Scanning project structure...
# Detected 3 potential wings:
#   - my-saas-app (main project)
#   - frontend (React app)
#   - backend (Go API server)
# Created 12 rooms from folder structure
# Palace initialized at ~/.mempalace/

init 做了什么？

1. 扫描项目目录结构
2. 从文件内容检测相关人物和项目
3. 从文件夹结构创建 Room
4. 确保 ~/.mempalace/ 配置目录存在

初始化后的目录结构：

~/.mempalace/
├── config.yaml          # 全局配置
├── palaces/
│   └── default/
│       ├── wings.yaml   # Wing 定义
│       ├── rooms.yaml   # Room 定义
│       └── chroma/      # ChromaDB 数据
└── cache/
    └── embedding/       # Embedding 模型缓存

4.3 挖掘项目记忆

# 最基本的挖掘：扫描项目文件
mempalace mine ~/projects/my-saas-app

# 输出示例：
# Mining 247 files...
# [████████████████████] 100%
# Created 1,832 drawers across 12 rooms
# Indexing complete (took 34s)

挖掘 Claude Code 对话历史：

# 挖掘 Claude Code 的对话导出
mempalace mine ~/.claude/projects/ --mode convos --wing my-saas-app

# 带自动分类的对话挖掘
mempalace mine ~/.claude/projects/ --mode convos --extract general --wing my-saas-app

# 输出示例：
# Mining 89 conversations...
# Classified:
#   23 decisions | 15 preferences | 31 milestones | 12 problems | 8 emotional contexts
# Created 1,456 drawers across 8 rooms

--extract general 的分类结果会映射到 Hall 体系：

• decision → hall_facts
• preference → hall_preferences
• milestone → hall_events
• problem → hall_advice
• emotional_context → hall_discoveries

4.4 搜索与唤醒

# 语义搜索
mempalace search "为什么选择 PostgreSQL 而不是 MySQL"

# 输出示例：
# [wing: my-saas-app / room: database-decisions]
# "2026-05-20: 团队决定使用 PostgreSQL，主要原因是：
#  1. 需要更好的 JSON 支持（JSONB）
#  2. PostGIS 地理查询需求
#  3. 性能测试中 PG 在复杂查询下优于 MySQL 30%"

# 限定 Wing 搜索
mempalace search "认证方案" --wing my-saas-app

# 限定 Room 搜索
mempalace search "性能优化" --wing my-saas-app --room api-performance

wake-up 命令用于新 session 启动时加载上下文：

mempalace wake-up

# 输出：最近的关键决策和上下文摘要
# 这不是 LLM 摘要——是从 Drawer 元数据中提取的结构化信息

4.5 接入 Claude Code：MCP 模式

这是 MemPalace 杀手级功能。通过 MCP 协议，Claude Code 可以直接读写你的记忆库。

方式一：本地 Python

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

方式二：Docker（推荐，更隔离）

在你的 Claude Code MCP 配置文件中添加：

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

方式三：自定义 Palace 路径

claude mcp add mempalace -- python -m mempalace.mcp_server --palace /path/to/palace

配置完成后，Claude Code 自动获得 29 个 MCP 工具。你不需要手动调用——当你问 Claude 任何关于过去决策的问题时，它会自动调用 mempalace_search。

4.6 29 个 MCP 工具全解析

MemPalace 通过 MCP 暴露了 29 个工具，按功能分组：

Palace 读取（7 个）

# 获取 Palace 状态 + 记忆协议
mempalace_status()
# 返回：Wing 列表、Room 统计、AAAK 规范、记忆行为协议

# 列出所有 Wing
mempalace_list_wings()
# 返回：[{"name": "my-saas-app", "room_count": 12, "drawer_count": 1832}]

# 列出某 Wing 下的 Room
mempalace_list_rooms(wing="my-saas-app")
# 返回：[{"name": "database-decisions", "drawer_count": 89}, ...]

# 获取完整分类树
mempalace_get_taxonomy()
# 返回：完整的 Wing → Room → Count 树形结构

# 语义搜索（核心工具）
mempalace_search(
    query="为什么选择 PostgreSQL",
    wing="my-saas-app",      # 可选：限定 Wing
    room="database-decisions", # 可选：限定 Room
    top_k=10                  # 可选：返回条数
)
# 返回：原始文本片段 + 元数据

# 检查重复（写入前调用）
mempalace_check_duplicate(content="团队决定使用 PostgreSQL")
# 返回：是否已存在相似内容

# 获取 AAAK 规范
mempalace_get_aaak_spec()
# 返回：AAAK 日记方言参考

Drawer 读写（5 个）

# 写入原始内容
mempalace_add_drawer(
    wing="my-saas-app",
    room="database-decisions",
    content="2026-06-14: 性能测试结果——PG 复杂查询 30% 快于 MySQL",
    hall="hall_facts",           # 可选：指定 Hall
    metadata={"source": "benchmark"} # 可选：自定义元数据
)

# 更新 Drawer
mempalace_update_drawer(
    drawer_id="dr_abc123",
    content="更新后的内容",     # 可选
    metadata={"verified": true}  # 可选
)

# 删除 Drawer
mempalace_delete_drawer(drawer_id="dr_abc123")

# 获取单个 Drawer
mempalace_get_drawer(drawer_id="dr_abc123")

# 列出 Drawer（分页）
mempalace_list_drawers(
    wing="my-saas-app",
    room="database-decisions",
    page=1,
    page_size=20
)

知识图谱（5 个）

# 查询实体关系
mempalace_kg_query(
    entity="PostgreSQL",
    relation="chosen_for",
    time_filter={"after": "2026-01-01"}  # 可选：时间过滤
)

# 添加事实
mempalace_kg_add(
    subject="my-saas-app",
    predicate="uses_database",
    object="PostgreSQL",
    confidence=0.95
)

# 使旧事实失效
mempalace_kg_invalidate(fact_id="fact_xyz")

# 时间线查询
mempalace_kg_timeline(entity="PostgreSQL")
# 返回：该实体相关的所有事实，按时间排序

# 图谱统计
mempalace_kg_stats()
# 返回：节点数、边数、连通性等

导航（3 个）

# 从一个 Room 出发，发现跨 Wing 连接
mempalace_traverse(start_room="auth-migration")
# 返回：所有包含 "auth-migration" Room 的 Wing 及其内容

# 查找两个 Wing 之间的共享 Room
mempalace_find_tunnels(
    wing_a="wing_backend",
    wing_b="wing_frontend"
)
# 返回：["auth-migration", "deploy-process", "ci-pipeline"]

# 图谱连接性概览
mempalace_graph_stats()

Tunnel 管理（4 个）

# 创建显式跨 Wing 隧道
mempalace_create_tunnel(
    wing_a="wing_backend",
    wing_b="wing_frontend",
    room="auth-migration"
)

# 列出所有显式隧道
mempalace_list_tunnels()

# 删除隧道
mempalace_delete_tunnel(tunnel_id="tunnel_xyz")

# 沿隧道追踪
mempalace_follow_tunnels(room="auth-migration")

Agent 日记（2 个）

# 写日记（AAAK 格式）
mempalace_diary_write(
    content="今天帮用户重构了认证模块，从 JWT 迁移到 session-based",
    tags=["auth", "refactor"]
)

# 读最近日记
mempalace_diary_read(limit=10)

系统工具（3 个）

# 获取/设置 Hook 行为
mempalace_hook_settings(action="get")

# 检查最近一次 checkpoint 是否已保存
mempalace_memories_filed_away()

# 强制重连数据库
mempalace_reconnect()

五、生产级部署方案

5.1 单机开发环境

适合个人开发者，一台机器搞定：

# docker-compose.dev.yml
version: "3.8"
services:
  mempalace:
    build: .
    volumes:
      - mempalace-data:/data
      - ~/projects:/work:ro  # 只读挂载项目目录
    environment:
      - MEMPALACE_LOG_LEVEL=info
    
volumes:
  mempalace-data:

# 启动
docker compose -f docker-compose.dev.yml up -d

# 挖掘项目
docker compose run --rm mempalace mine /work/my-saas-app

# MCP 模式（给 Claude Code 用）
docker compose run --rm mempalace  # -i flag 在 MCP 配置中指定

5.2 团队生产环境

适合需要共享记忆库的团队，用 Qdrant 或 pgvector 替代 ChromaDB：

# docker-compose.prod.yml
version: "3.8"
services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - qdrant-data:/qdrant/storage
    environment:
      - QDRANT__SERVICE__GRPC_PORT=6334
    
  mempalace-mcp:
    build: .
    volumes:
      - mempalace-config:/data
      - ~/projects:/work:ro
    environment:
      - MEMPALACE_QDRANT_URL=http://qdrant:6333
      - MEMPALACE_QDRANT_NAMESPACE=team-alpha
      - MEMPALACE_QDRANT_API_KEY=${QDRANT_API_KEY}
    depends_on:
      - qdrant

volumes:
  qdrant-data:
  mempalace-config:

# 用 Qdrant 后端挖掘
MEMPALACE_QDRANT_URL=http://localhost:6333 \
  mempalace mine ~/projects/my-saas-app --backend qdrant

# 搜索
MEMPALACE_QDRANT_URL=http://localhost:6333 \
  mempalace search "认证方案" --backend qdrant

5.3 PostgreSQL + pgvector 方案

如果你的团队已经有 PG 基础设施：

# 安装 pgvector 驱动
pip install mempalace[pgvector]

# 确保数据库有 vector 扩展
psql -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 挖掘
MEMPALACE_PGVECTOR_DSN=postgresql://user:pass@localhost:5432/mempalace \
  mempalace mine ~/projects/my-saas-app --backend pgvector

# 搜索
MEMPALACE_PGVECTOR_DSN=postgresql://user:pass@localhost:5432/mempalace \
  mempalace search "API 性能优化" --backend pgvector

5.4 自定义 Wing 配置

MemPalace 允许你手动定义 Wing 结构，而不是完全依赖自动检测：

# mempalace.yaml
wings:
  - name: my-saas-app
    description: "主项目 - SaaS 应用"
    rooms:
      - auth-migration
      - database-decisions
      - api-performance
      - frontend-react
      - deploy-process
      - ci-pipeline
      
  - name: team-decisions
    description: "团队级别决策记录"
    rooms:
      - tech-stack
      - architecture-review
      - onboarding
      
  - name: learning
    description: "个人学习笔记"
    rooms:
      - rust-learning
      - distributed-systems
      - ml-fundamentals

六、记忆协议：让 AI 学会「先查后说」

6.1 Memory Protocol

MemPalace 最精妙的设计不是存储结构，而是记忆协议（Memory Protocol）。当 AI 首次调用 mempalace_status 时，它会收到一份行为指南：

Memory Protocol:
1. On wake-up: Call mempalace_status to load palace overview
2. Before responding about any person, project, or past event: 
   search first, never guess
3. If unsure: Say "let me check" and query the palace
4. After each session: Write diary entries to record what happened
5. When facts change: Invalidate old facts, add new ones

这五条规则把「存储」变成了「记忆」。区别在哪？

• 存储：数据放在那里，等人来查
• 记忆：AI 主动去查，查完再回答，答案变了主动更新

这跟人类的好习惯一样：不确定的事情先查笔记，而不是凭记忆瞎说。

6.2 AAAK 日记系统

AAAK（Agent's Annotated Autobiographical Knowledge）是 MemPalace 的日记格式：

# AI 在 session 结束时自动写日记
mempalace_diary_write(
    content="""
    ## Session 2026-06-14
    
    ### 完成的工作
    - 重构了认证模块，从 JWT 迁移到 session-based
    - 修复了 token 刷新竞态条件 bug
    
    ### 关键决策
    - 选择 session-based 而非 refresh token rotation（原因：简单性优先）
    - 认证中间件放在 API gateway 层而非业务服务层
    
    ### 待办
    - [ ] 给 session 添加 TTL 过期
    - [ ] 迁移存量 JWT 用户
    """,
    tags=["auth", "refactor", "decision"]
)

下次 session 启动时，mempalace_wake_up 会加载最近的日记，AI 就知道上次做了什么、还有什么没做完。

6.3 事实失效机制

传统知识库最头疼的问题：旧信息永远不会自动失效。你三月份决定用 MongoDB，五月份改成了 PostgreSQL，但知识库里两条记录都在，AI 不知道哪条是当前有效的。

MemPalace 的知识图谱有 invalidate 机制：

# 添加事实：项目使用 MongoDB
mempalace_kg_add(
    subject="my-saas-app",
    predicate="uses_database",
    object="MongoDB",
    valid_from="2026-03-01"
)

# 后来改了：事实失效
mempalace_kg_invalidate(fact_id="fact_mongodb")

# 添加新事实
mempalace_kg_add(
    subject="my-saas-app",
    predicate="uses_database",
    object="PostgreSQL",
    valid_from="2026-05-15"
)

# 查询时间线
mempalace_kg_timeline(entity="my-saas-app")
# 返回：
# 2026-03-01 ~ 2026-05-14: uses MongoDB (已失效)
# 2026-05-15 ~ present: uses PostgreSQL (当前有效)

七、性能优化：从毫秒到微秒

7.1 Embedding 模型选择

MemPalace 默认使用本地 embedding 模型（无需 API Key），但不同模型的检索质量差异显著：

# 默认配置（英文为主，质量中等）
# model: all-MiniLM-L6-v2

# 推荐中文场景配置
# 在 config.yaml 中：
embedding:
  model: BAAI/bge-m3  # 多语言，中文效果显著更好
  device: cuda         # 有 GPU 的话

# 或者用 OpenAI embedding（需要 API Key）
embedding:
  provider: openai
  model: text-embedding-3-small

中文场景下，bge-m3 的检索质量比默认模型高 20-30%。如果你主要用中文，强烈建议切换。

7.2 首次 Mine 加速

大项目首次 mine 的瓶颈在 embedding 计算。几个加速策略：

# 策略 1：跳过 .git、node_modules 等目录
mempalace mine ~/projects/myapp --ignore ".git,node_modules,__pycache__,.venv"

# 策略 2：只挖掘特定目录
mempalace mine ~/projects/myapp/src --wing myapp-core

# 策略 3：增量挖掘（只处理变更文件）
mempalace mine ~/projects/myapp --incremental

# 策略 4：GPU 加速
docker run --rm --gpus all -v mempalace-data:/data -v ~/projects:/work \
  mempalace:gpu mine /work/myapp

7.3 搜索延迟优化

# 优化 1：严格作用域过滤
# 不好的做法：全局搜索
mempalace_search(query="认证方案")

# 好的做法：限定 Wing + Room
mempalace_search(
    query="认证方案",
    wing="my-saas-app",
    room="auth-migration"
)
# 延迟降低 5-10x（取决于数据量）

# 优化 2：减少 top_k
mempalace_search(query="认证方案", top_k=3)  # 默认 10，如果只需要 3 个结果

# 优化 3：使用 sqlite_exact 后端做精确匹配（小数据量场景）
mempalace mine ~/projects/myapp --backend sqlite_exact

7.4 混合检索调优

Hybrid v4 流水线的参数可以微调：

# config.yaml - hybrid 检索配置
hybrid:
  semantic_weight: 0.4      # 语义相似度权重
  keyword_boost_weight: 0.2  # 关键词增强权重
  recency_weight: 0.2        # 时间近因权重
  preference_weight: 0.2     # 偏好模式权重
  
  recency_half_life_days: 14  # 时间衰减半衰期（天）
  
  keyword_extract_top_n: 5    # 提取前 N 个关键词

八、与竞品对比

8.1 MemPalace vs Mem0 vs Zep vs basic-memory

核心差异总结：

• MemPalace 的核心赌注：原样存储优于摘要存储。LongMemEval 96.6% 的 R@5 支持了这个赌注。
• Mem0/Zep 的优势：摘要后存储量更小，适合超大规模场景（百万级对话）。
• basic-memory 的优势：极简——就是 Markdown 文件 + git，零依赖。但检索精度有限。

8.2 什么时候不该用 MemPalace

说了这么多优点，也得说说局限：

1. 中文支持偏弱：默认 embedding 模型对中文语义检索不如英文。需要手动切换到 bge-m3 等多语言模型。

2. 没有多设备同步：数据存在本地，没有内置同步机制。多设备用户需要自己用 Git 或云存储同步。

3. 大规模场景：MemPalace 的原样存储意味着数据量会持续增长。百万级对话场景下，Mem0 的摘要压缩可能更合适。

4. 首次索引慢：大项目首次 mine 需要跑完所有 embedding，可能要几十分钟。增量挖掘可以缓解，但初次体验不够流畅。

九、进阶玩法

9.1 多项目联邦

一个 Palace 可以包含多个 Wing，但如果你有多个 Palace，可以用联邦模式：

# 为不同团队创建不同 Palace
mempalace init ~/projects/team-alpha --palace ~/palaces/alpha
mempalace init ~/projects/team-beta --palace ~/palaces/beta

# Claude Code 中切换
claude mcp add mempalace-alpha -- python -m mempalace.mcp_server --palace ~/palaces/alpha
claude mcp add mempalace-beta -- python -m mempalace.mcp_server --palace ~/palaces/beta

9.2 Hook 自动化

MemPalace 支持 Hook，在特定事件时自动触发操作：

# config.yaml
hooks:
  on_session_start:
    - action: wake_up          # 自动加载最近上下文
    - action: diary_read       # 读取最近日记
      limit: 5
      
  on_session_end:
    - action: diary_write      # 自动写日记
    - action: mine_incremental # 增量挖掘新文件
      
  on_fact_invalidate:
    - action: notify           # 通知用户事实变更
      channel: webhook
      url: "https://hooks.slack.com/..."

9.3 自定义 Embedding 后端

如果你有自研的 embedding 服务：

# mempalace/backends/custom_embedding.py
from mempalace.backends.base import EmbeddingProvider

class MyEmbeddingProvider(EmbeddingProvider):
    def __init__(self, endpoint: str):
        self.endpoint = endpoint
    
    def embed(self, texts: list[str]) -> list[list[float]]:
        import httpx
        response = httpx.post(
            self.endpoint,
            json={"texts": texts}
        )
        return response.json()["embeddings"]
    
    def embed_query(self, query: str) -> list[float]:
        return self.embed([query])[0]

# config.yaml
embedding:
  provider: custom
  class: mempalace.backends.custom_embedding.MyEmbeddingProvider
  endpoint: http://localhost:8080/embed

9.4 与 CI/CD 集成

把记忆挖掘加入 CI 流水线，确保知识库始终最新：

# .github/workflows/mempalace-mine.yml
name: Update MemPalace Index

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 点

jobs:
  mine:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install MemPalace
        run: pip install mempalace
      
      - name: Incremental Mine
        env:
          MEMPALACE_QDRANT_URL: ${{ secrets.QDRANT_URL }}
          MEMPALACE_QDRANT_API_KEY: ${{ secrets.QDRANT_API_KEY }}
        run: |
          mempalace mine . --backend qdrant --incremental
          mempalace search "recent changes" --backend qdrant --top_k 1

十、总结与展望

10.1 MemPalace 的核心创新

MemPalace 做对了三件事：

1. 原样存储优于摘要存储。在 LLM 时代，所有人都在用 LLM 做摘要压缩，但 MemPalace 用数据证明：不做摘要，检索精度反而更高。96.6% R@5，不需要 API Key，不需要云服务。

2. 结构化作用域优于平铺检索。Wing/Room/Hall 的三层结构不是花架子——它让搜索可以在语义匹配之前先做元数据过滤，这在数据量增长后是质变级的精度提升。

3. 记忆协议优于被动存储。29 个 MCP 工具 + Memory Protocol，让 AI 学会「先查后说」——这不是存储系统，是真正的记忆系统。

10.2 AI 记忆的未来方向

MemPalace 还在快速迭代中，以下几个方向值得持续关注：

• 多设备同步：目前数据完全本地，没有同步机制。官方路线图中有基于 CRDT 的多设备同步计划。
• 中文优化：默认 embedding 模型对中文不够友好，社区正在推进 bge-m3 作为默认中文模型。
• 多模态记忆：当前只支持文本，图像和代码 AST 的记忆还在实验阶段。
• Agent 间记忆共享：不同 Agent（Claude Code、Cursor、Copilot）之间共享同一份记忆库——这需要更成熟的并发控制。

10.3 我的建议

如果你是以下用户，现在就应该试试 MemPalace：

• 重度 Claude Code / Cursor 用户，受够了 AI 失忆
• 对数据隐私敏感，不想把代码决策上传到云服务
• 需要给 AI Agent 持久化记忆的 MCP 使用者

如果你需要以下功能，可以再等等：

• 中文为主的场景（等 bge-m3 成为默认或官方优化中文支持）
• 多设备协作（等 CRDT 同步机制）
• 百万级超大规模场景（等更成熟的分片机制）

MemPalace 不是完美的，但它是 2026 年 AI 记忆赛道最有意思的项目。它的核心哲学——原样存储，结构化检索，本地优先——可能会成为 AI Agent 记忆系统的主流范式。

毕竟，最好的记忆不是被压缩过的记忆，而是原封不动的记忆。你大脑里的回忆从来不是摘要，是吧？

参考资料

• MemPalace GitHub
• MemPalace 官方文档 - The Palace
• MemPalace 官方文档 - MCP Integration
• MemPalace 官方文档 - Getting Started
• LongMemEval Benchmark