MemPalace 深度实战：给AI装上「记忆宫殿」——从96.6%召回率到生产级长期记忆系统的完全指南（2026）

作者按：当你和Claude Code协作了三个月，它却忘了你项目的认证方案为什么从JWT换成了Clerk；当你在调试一个跨模块的bug，AI助手想不起上周同一个问题的讨论结论——这就是当前AI的"金鱼记忆"困境。MemPalace的出现，让AI终于拥有了可靠、可检索、结构化的长期记忆。

目录

1. 痛点：AI的记忆为什么这么差？
2. MemPalace是什么？从记忆宫殿到AI记忆系统
3. 核心架构：Wing/Room/Drawer三层结构化存储
4. 深度实战：从安装到生产级配置
5. MCP工具链：29个工具的完整指南
6. 知识图谱：时空感知的实体关系网络
7. 性能基准：96.6% R@5背后的技术细节
8. 架构分析：可插拔后端与存储合约
9. Agent集成：多Agent协作的记忆共享
10. 自动保存钩子：让记忆无感延续
11. AAAK压缩语言：把上下文塞进更小的空间
12. 与其他方案对比：为什么MemPalace得分最高
13. 生产级最佳实践
14. 总结与展望

1. 痛点：AI的记忆为什么这么差？

1.1 无状态性的本质困境

大语言模型（LLM）的每一次对话都是一次全新的开始。这种设计源于Transformer架构的本质——它擅长处理固定上下文窗口内的模式识别，但没有原生的跨会话记忆机制。

当前主流解决方案的局限：

1.2 真实场景中的记忆缺失

场景一：项目决策追溯

开发者：嘿，我记得三个月前我们讨论过为什么选PostgreSQL而不是MySQL？
AI：抱歉，我每个会话都是全新的开始，无法记住之前的讨论。
开发者：（叹气）算了，我去找Slack历史记录...

场景二：多项目上下文切换

开发者：帮我review一下api-gateway这个PR。
AI：好的，但我需要你重新解释一下你们的认证方案和错误码规范。
开发者：我上周刚跟你讲过啊！在另一个会话里...

场景三：团队协作记忆

团队成员A：我记得Priya说过不推荐用Redis做主存储？
团队成员B：对，但为什么来着？
AI：我无法访问你们的讨论历史...

1.3 现有开源记忆系统的通病

通过分析GitHub上现有的AI记忆项目（Mem0、Zep、Supermemory等），我发现几个共性问题：

1. 过度依赖摘要：用LLM提取"关键信息"，但什么关键什么不关键，模型说了算，原始上下文丢失
2. 扁平化存储：所有记忆放在一个向量空间里，缺乏层次结构，检索时无法有效缩小范围
3. 云服务依赖：多数方案需要API Key，数据离开本地，隐私和成本都是问题
4. 基准测试不透明：各家用不同指标、不同数据集宣传性能，无法直接比较

MemPalace的差异化思路：存储一切原文（Verbatim Storage），让语义搜索找到它。不摘要、不提取、不转述。

2. MemPalace是什么？从记忆宫殿到AI记忆系统

2.1 灵感来源：古希腊的记忆宫殿法

公元前500年，古希腊诗人西摩尼得斯（Simonides）在参加一场宴会时，大厅屋顶突然坍塌。死者面容全非，无法辨认。西摩尼得斯闭上眼睛，回忆每个宾客在宴会中的位置——从而成功辨认了所有死者。

这个方法后来被称为「记忆宫殿」（Method of Loci）：将需要记忆的信息放在想象的建筑空间中，通过「行走」这个空间来回忆信息。

MemPalace将这个古老方法现代化：

记忆宫殿（古代）          MemPalace（现代）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
建筑整体               →   Palace（记忆库）
翼楼（Wing）           →   项目/人物（如 wing_kai, wing_api）
房间（Room）           →   主题（如 auth-migration, graphql-switch）
抽屉（Drawer）         →   原始文本块（对话片段、代码文件）
行走检索               →   语义搜索 + 元数据过滤

2.2 创始人故事：好莱坞演员与AI记忆

MemPalace有一个有趣的后台故事：它由好莱坞演员Milla Jovovich（代表作《生化危机》系列）和开发者Ben Sigman合作完成，两人使用Anthropic的Claude Code协作开发。

这个跨学科组合带来了独特的视角：

• Milla的洞察：作为需要记忆大量台词和角色背景的演员，她对「记忆结构」有深刻理解
• Ben的技术能力：系统级的工程实现，重点关注基准测试的诚实性

2.3 核心设计哲学

MemPalace的设计决策背后有三条规定：

规则一：存储一切原文（Store Verbatim）

❌ 错误做法（其他记忆系统）：
原始对话 → LLM提取摘要 → 存储摘要
结果：细节丢失，模型决定的"关键"未必是你需要的关键

✅ MemPalace做法：
原始对话 → 分块 → 存储原文 + 向量索引
结果：检索时拿到完整原文，自己判断哪些信息有用

规则二：结构化优于魔法（Structure Over Magic）

❌ 错误做法：
把所有文本块扔进一个向量数据库，指望语义搜索解决一切

✅ MemPalace做法：
Wing（项目/人物）→ Room（主题）→ Drawer（文本块）
检索时可限定范围：只在wing_kai中搜索「认证方案」

规则三：基准测试必须可复现（Reproducible Benchmarks）

MemPalace在仓库中提交了：
- 完整的基准测试代码
- 每个问题的详细结果文件
- 明确的训练集/测试集划分说明

目的：不让"刷榜"式的优化误导用户

3. 核心架构：Wing/Room/Drawer三层结构化存储

3.1 整体架构图

┌─────────────────────────────────────────────────────────────┐
│                        Palace                              │
│  （一个项目的完整记忆库，存储在 ~/.mempalace/）           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  Wing:      │  │  Wing:      │  │  Wing:      │      │
│  │  wing_kai   │  │  wing_api   │  │  wing_team  │      │
│  │  (Kai的项目)│  │  (API项目)  │  │  (团队协作)  │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│         │                  │                  │              │
│         ▼                  ▼                  ▼              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │   Rooms:    │  │   Rooms:    │  │   Rooms:    │      │
│  │ auth-migr.  │  │ endpoint-   │  │ meeting-    │      │
│  │ graphql-    │  │ design      │  │ notes       │      │
│  │ switch      │  │ versioning  │  │ decisions   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│         │                  │                  │              │
│         ▼                  ▼                  ▼              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │   Drawers:  │  │   Drawers:  │  │   Drawers:  │      │
│  │ [原文块1]   │  │ [原文块1]   │  │ [原文块1]   │      │
│  │ [原文块2]   │  │ [原文块2]   │  │ [原文块2]   │      │
│  │ [原文块3]   │  │ [原文块3]   │  │ [原文块3]   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  技术栈：                                                    │
│  • 向量存储：ChromaDB（默认）/ Qdrant / pgvector / SQLite  │
│  • 嵌入模型：embeddinggemma-300m（多语言）                  │
│  • 知识图谱：SQLite（本地）                                 │
│  • MCP服务：29个工具                                        │
└─────────────────────────────────────────────────────────────┘

3.2 Wing：顶层组织单元

Wing的定义：一个Wing对应一个「主体」——可以是一个人、一个项目、或一个主题。

自动检测Wing：运行 mempalace init 时，工具会扫描你的目录结构，自动建议Wing划分：

# 项目结构
~/projects/myapp/
├── frontend/     # → 建议创建 wing_myapp_frontend
├── backend/      # → 建议创建 wing_myapp_backend
├── docs/         # → 建议创建 wing_myapp_docs
└── .claude/      # → 建议创建 wing_myapp_claude（会话历史）

手动指定Wing：

# 为特定项目创建Wing
mempalace mine ~/projects/myapp --wing myapp_backend

# 为Claude Code会话创建Wing（按项目分）
mempalace mine ~/.claude/projects/ --mode convos --wing per_project

3.3 Room：主题维度的组织

Room的命名规则：Room名称应该是「有意义的主题」，而非随意的标签。

自动生成Room：MemPalace的miner会分析文件内容和路径，自动建议Room：

# 文件：~/projects/myapp/backend/auth/migration_to_clerk.py
# 自动推断Room：auth-migration

# 文件：~/projects/myapp/backend/graphql/schema.py
# 自动推断Room：graphql-switch

# 文件：~/projects/myapp/docs/api_versioning.md
# 自动推断Room：api-versioning

Hall子分类：每个Room可以包含多个Hall，代表不同的记忆类型：

3.4 Drawer：原文存储的最小单元

Drawer的内容：一个Drawer存储一块原文文本，通常来自：

• 对话的一轮交换（user message + assistant response）
• 代码文件的一个语义块
• 文档的一个章节

Drawer的元数据：

{
  "drawer_id": "abc123def456",
  "wing": "wing_myapp",
  "room": "auth-migration",
  "hall": "hall_facts",
  "content": "原始文本原文...",
  "source_file": "backend/auth/README.md",
  "added_by": "mcp",
  "timestamp": "2026-06-10T14:30:00Z",
  "embedding": [0.123, -0.456, ...]  // 向量表示
}

为什么存储原文而非摘要？

假设原始对话是：

User: 我们之前讨论过为什么从JWT换成Clerk？
Assistant: 因为JWT无法主动撤销，而Clerk提供了会话管理能力...

摘要可能丢失的关键信息：

• 具体是哪个会话讨论的
• 讨论时的上下文（当时遇到了什么具体问题）
• 讨论中否决的其他方案及原因

MemPalace存储原文，让你在检索时拥有所有信息，而非模型认为的"关键信息"。

3.5 Tunnel：跨Wing的连接

当两个Wing共享同一个Room名称时，MemPalace会在它们之间建立Tunnel（隧道）连接。

实际例子：

wing_kai / auth-migration
    ↓ Tunnel
wing_api / auth-migration
    ↓ Tunnel
wing_team / auth-migration

通过 mempalace_traverse 工具，可以从一个Room出发，发现所有相关的Wing：

# MCP工具调用
mempalace_traverse(start_room="auth-migration", max_hops=2)

# 返回结果
[
  {"room": "auth-migration", "wing": "wing_kai", "hall": "hall_events"},
  {"room": "auth-migration", "wing": "wing_api", "hall": "hall_facts"},
  {"room": "auth-migration", "wing": "wing_team", "hall": "hall_advice"}
]

4. 深度实战：从安装到生产级配置

4.1 安装方式选择

MemPalace提供多种安装方式，推荐优先级如下：

方式一：uv工具安装（推荐）

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

# 安装MemPalace
uv tool install mempalace

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

方式二：pipx安装

# 安装pipx（如果还没有）
python -m pip install --user pipx

# 安装MemPalace
pipx install mempalace

# 确保PATH中有pipx的安装目录
pipx ensurepath

方式三：Docker容器（无需本地Python）

# 构建镜像
docker build -t mempalace .

# 运行MCP服务器（stdio模式）
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

方式四：虚拟环境 + pip（用于开发）

git clone https://github.com/MemPalace/mempalace.git
cd mempalace
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

4.2 初始化第一个Palace

# 为项目创建Palace
mempalace init ~/projects/myapp

# 输出：
# ✅ Palace initialized at ~/.mempalace/myapp/
# 📁 Detected wings: myapp_backend, myapp_frontend, myapp_docs
# 📝 Next step: mempalace mine ~/projects/myapp

初始化后的目录结构：

~/.mempalace/myapp/
├── chroma/              # ChromaDB向量数据库文件
├── kg/                  # 知识图谱SQLite数据库
├── config.toml          # Palace配置文件
├── wings.json           # Wing定义和统计
└── .palace_lock         # 并发写入锁文件

4.3 配置文件详解

config.toml 是Palace的核心配置文件：

# ~/.mempalace/myapp/config.toml

[palace]
name = "myapp"
version = "3.4.0"
created_at = "2026-06-10T14:30:00Z"

[backend]
# 向量存储后端
type = "chromadb"  # 可选：chromadb, qdrant, pgvector, sqlite_exact
path = "~/.mempalace/myapp/chroma"
# 对于Qdrant：
# type = "qdrant"
# url = "http://localhost:6333"
# api_key = "${QDRANT_API_KEY}"

[embedding]
# 嵌入模型配置
model = "embeddinggemma-300m"  # 多语言，推荐
# model = "all-MiniLM-L6-v2"   # 仅英文，体积小
cache_dir = "~/.cache/mempalace/embeddings"
batch_size = 32

[mining]
# 挖掘配置
chunk_size = 2000          # 每个Drawer的字符数
chunk_overlap = 200        # 块之间的重叠字符数
exclude_patterns = [
    "*.min.js",
    "*.map",
    "node_modules/**",
    ".git/**"
]
include_languages = ["python", "javascript", "typescript", "go"]

[retrieval]
# 检索配置
default_limit = 5
similarity_threshold = 0.7
enable_keyword_boost = true
enable_temporal_boost = true

[mcp]
# MCP服务器配置
enabled = true
port = 8080  # 仅HTTP模式需要
auth_required = false

4.4 挖掘项目文件

基础挖掘：

# 挖掘整个项目
mempalace mine ~/projects/myapp

# 输出进度：
# 📂 Scanning ~/projects/myapp...
# 📊 Found 245 files (12.3 MB total)
# ⚙️  Chunking and embedding...
# [████████████████████] 100% | 1,234 drawers created
# ✅ Mining complete: 1,234 drawers in wing_myapp

限定Wing挖掘：

# 只为后端代码创建Wing
mempalace mine ~/projects/myapp/backend --wing myapp_backend

# 只为前端代码创建Wing
mempalace mine ~/projects/myapp/frontend --wing myapp_frontend

挖掘Claude Code会话历史：

# 挖掘所有会话
mempalace mine ~/.claude/projects/ --mode convos

# 按项目分Wing（从会话路径推断）
mempalace mine ~/.claude/projects/ --mode convos --wing per_project

# 输出：
# 📂 Scanning ~/.claude/projects/...
# 📊 Found 45 JSONL files (3.2 MB total)
# ⚙️  Parsing conversations...
# [████████████████████] 100% | 892 drawers created
# ✅ Conversation history mined: 892 drawers across 8 wings

4.5 语义搜索实战

基础搜索：

# 搜索"为什么切换到GraphQL"
mempalace search "why did we switch to GraphQL"

# 输出：
# 🔍 Searching across 3 wings, 12 rooms...
#
# Result 1 (similarity: 0.9234)
# Wing: wing_myapp_backend | Room: graphql-switch
# Source: backend/graphql/README.md
# Content: "我们决定从REST切换到GraphQL的主要原因是...
#          （原文片段，最多200字符预览）"
#
# Result 2 (similarity: 0.8756)
# Wing: wing_myapp_backend | Room: api-design
# Source: docs/api_comparison.md
# Content: "在评估了REST、gRPC和GraphQL之后..."

限定范围搜索：

# 只在wing_myapp_backend中搜索
mempalace search "auth clerk" --wing wing_myapp_backend

# 在特定Wing和Room中搜索
mempalace search "token refresh" \
  --wing wing_myapp_backend \
  --room auth-migration

编程场景的搜索策略：

# 场景：调试一个之前见过的错误
search_query = """
以前见过这个Prisma错误：
"Unique constraint failed on the fields: (`id`)"
当时是怎么解决的？
"""

# MemPalace会找到相关的Drawer，其中包含：
# 1. 原始错误日志
# 2. 当时的调试过程
# 3. 最终解决方案
# 4. 相关的代码片段

5. MCP工具链：29个工具的完整指南

MemPalace通过MCP（Model Context Protocol）协议暴露29个工具，让AI Agent能够直接操作记忆库。

5.1 配置Claude Code集成

方式一：通过Claude Code插件市场

# 添加MemPalace插件
claude plugin marketplace add MemPalace/mempalace

# 安装到用户级（所有项目可用）
claude plugin install --scope user mempalace

# 重启Claude Code
# 然后输入 /skills 验证 "mempalace" 是否出现

方式二：手动配置MCP服务器

// ~/.claude/mcp_servers.json
{
  "mcpServers": {
    "mempalace": {
      "command": "mempalace",
      "args": ["mcp-server"],
      "env": {
        "MEMPALACE_PALACE": "~/.mempalace/myapp"
      }
    }
  }
}

方式三：Docker方式（推荐用于生产环境）

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

5.2 Palace读取工具（7个）

mempalace_status - 获取Palace概览

# MCP工具调用
mempalace_status()

# 返回
{
  "total_drawers": 1234,
  "wings": {
    "wing_myapp_backend": 856,
    "wing_myapp_frontend": 378
  },
  "rooms": 12,
  "protocol": "aaak-v2",
  "aaak_dialect": "concise"
}

mempalace_search - 语义搜索（最核心的工具）

# 搜索认证相关讨论
mempalace_search(
    query="Clerk authentication setup and configuration",
    limit=5,
    wing="wing_myapp_backend",
    room="auth-migration"
)

# 返回结果结构
{
  "query": "Clerk authentication setup...",
  "filters": {"wing": "wing_myapp_backend", "room": "auth-migration"},
  "results": [
    {
      "text": "完整原文内容...",
      "wing": "wing_myapp_backend",
      "room": "auth-migration",
      "source_file": "backend/auth/clerk_setup.py",
      "similarity": 0.9234,
      "drawer_id": "abc123..."
    },
    # ... 最多limit个结果
  ]
}

mempalace_list_wings - 列出所有Wing

mempalace_list_wings()
# 返回：{"wings": {"wing_myapp_backend": 856, "wing_myapp_frontend": 378, ...}}

mempalace_list_rooms - 列出Wing下的Room

mempalace_list_rooms(wing="wing_myapp_backend")
# 返回：{"wing": "wing_myapp_backend", "rooms": {"auth-migration": 45, "graphql-switch": 32, ...}}

mempalace_get_taxonomy - 获取完整分类树

mempalace_get_taxonomy()
# 返回完整的 wing → room → drawer count 树

mempalace_check_duplicate - 检查内容是否已存在

# 在写入前检查是否已有相似内容
mempalace_check_duplicate(
    content="我们决定使用Clerk来做认证",
    threshold=0.85
)
# 返回：{"is_duplicate": true, "matches": [{"drawer_id": "...", "similarity": 0.89, ...}]}

mempalace_get_aaak_spec - 获取AAAK压缩语言规范

mempalace_get_aaak_spec()
# 返回AAAK方言的详细规范，用于生成紧凑的上下文

5.3 Palace写入工具（8个）

mempalace_add_drawer - 手动添加内容

# 将重要决策记录到Palace
mempalace_add_drawer(
    wing="wing_myapp_backend",
    room="auth-migration",
    content="""
关键决策：从JWT切换到Clerk
日期：2026-06-05
原因：
1. JWT无法主动撤销，存在安全隐患
2. Clerk提供完善的会话管理和SSO支持
3. 团队已经熟悉Clerk的API
实施：预计两周内完成迁移
负责人：@kai
""",
    source_file="decisions/2026-06-05-auth-migration.md",
    added_by="kai"
)
# 返回：{"success": true, "drawer_id": "abc123...", "wing": "...", "room": "..."}

mempalace_mine - MCP中的挖掘操作

# 通过MCP工具挖掘目录
mempalace_mine(
    source="~/projects/myapp/backend",
    mode="projects",
    wing="wing_myapp_backend",
    limit=0,  # 0 = 无限制
    dry_run=False
)
# 返回：{"success": true, "output": "Mining complete: 856 drawers created"}

mempalace_sync - 同步Palace与源文件

# 检查哪些Drawer的源文件已被删除
mempalace_sync(
    project_dir="~/projects/myapp",
    wing="wing_myapp_backend",
    apply=False  # dry-run模式
)
# 返回：{"scanned": 1234, "kept": 1100, "missing": 134, "dry_run": true}

# 应用删除
mempalace_sync(
    project_dir="~/projects/myapp",
    wing="wing_myapp_backend",
    apply=True
)

mempalace_delete_drawer / mempalace_get_drawer / mempalace_list_drawers / mempalace_update_drawer

# 获取单个Drawer的完整内容
mempalace_get_drawer(drawer_id="abc123...")

# 列出Drawer（分页）
mempalace_list_drawers(wing="wing_myapp_backend", room="auth-migration", limit=20, offset=0)

# 更新Drawer
mempalace_update_drawer(
    drawer_id="abc123...",
    content="新内容...",
    wing="wing_myapp_backend",
    room="auth-migration-updated"
)

# 删除Drawer（不可逆）
mempalace_delete_drawer(drawer_id="abc123...")

5.4 知识图谱工具（5个）

见第六章详细介绍。

5.5 导航工具（7个）

mempalace_traverse - 遍历Palace图

# 从"auth-migration"房间出发，找到所有相关的Wing
mempalace_traverse(
    start_room="auth-migration",
    max_hops=2
)
# 返回连通图：wing_kai, wing_api, wing_team 都通过 auth-migration 连接

mempalace_find_tunnels - 找到连接两个Wing的Room

mempalace_find_tunnels(
    wing_a="wing_myapp_backend",
    wing_b="wing_myapp_frontend"
)
# 返回两个Wing共享的Room：["auth-migration", "api-design", "deployment"]

mempalace_create_tunnel - 手动创建跨Wing连接

mempalace_create_tunnel(
    source_wing="wing_myapp_api",
    source_room="endpoint-design",
    target_wing="wing_myapp_database",
    target_room="schema-design",
    label="API endpoints depend on DB schema"
)

mempalace_follow_tunnels - 跟随Tunnel发现相关内容

# 从后端的"auth-migration"房间出发，找到前端相关的认证讨论
mempalace_follow_tunnels(
    wing="wing_myapp_backend",
    room="auth-migration"
)
# 返回：前端Wing中相关的Room和Drawer预览

5.6 Agent日记工具（2个）

# Agent写入自己的日记
mempalace_diary_write(
    agent_name="backend-agent",
    entry="""
@decision: 决定用Prisma的transaction API来处理批量操作
@reason: 比手动管理rollback更清晰，且性能相当
@date: 2026-06-10
""",
    topic="database"
)

# 读取Agent的日记
mempalace_diary_read(
    agent_name="backend-agent",
    last_n=10
)

6. 知识图谱：时空感知的实体关系网络

6.1 为什么需要知识图谱？

向量检索擅长找到「语义相似」的内容，但在处理「精确关系」时有局限：

向量检索的问题：
Query: "Kai负责哪个模块？"
可能返回：包含"Kai"和"模块"的所有Drawer，但不一定能精确找到关系

知识图谱的优势：
Query: kg_query(entity="Kai", direction="outgoing")
返回：[{subject: "Kai", predicate: "负责", object: "auth模块", valid_from: "2026-03-01"}]

6.2 知识图谱的数据模型

MemPalace的知识图谱基于时态三元组（Temporal Triple）：

# 三元组结构
{
    "subject": "Kai",           # 主体
    "predicate": "负责",         # 谓词（关系类型）
    "object": "auth模块",        # 客体
    "valid_from": "2026-03-01", # 关系生效时间
    "valid_to": None,            # 关系失效时间（None表示当前有效）
    "source_closet": "abc123..." # 来源Drawer的ID
}

时间维度的价值：

# 添加事实：Kai负责auth模块
mempalace_kg_add(
    subject="Kai",
    predicate="负责",
    object="auth模块",
    valid_from="2026-03-01"
)

# 后来Kai转去负责API网关
# 先失效旧关系
mempalace_kg_invalidate(
    subject="Kai",
    predicate="负责",
    object="auth模块",
    ended="2026-06-01"
)

# 添加新关系
mempalace_kg_add(
    subject="Kai",
    predicate="负责",
    object="API网关",
    valid_from="2026-06-01"
)

# 查询：Kai当前负责什么？（自动过滤掉已失效的关系）
mempalace_kg_query(entity="Kai", as_of="2026-06-13")
# 返回：[{subject: "Kai", predicate: "负责", object: "API网关", current: true}]

6.3 知识图谱工具实战

构建项目知识图谱

# 从已挖掘的Drawer中提取实体关系
# 这一步可以通过Claude Code自动完成

# 示例：添加项目关键事实
facts = [
    ("MyApp", "使用技术", "Python + FastAPI"),
    ("MyApp", "使用数据库", "PostgreSQL + Prisma"),
    ("MyApp", "部署在", "AWS ECS"),
    ("Kai", "负责", "后端开发"),
    ("Priya", "负责", "前端开发"),
    ("团队", "决定采用", "Clerk认证", "2026-06-05"),
]

for s, p, o, *rest in facts:
    mempalace_kg_add(
        subject=s,
        predicate=p,
        object=o,
        valid_from=rest[0] if rest else None
    )

时间线查询

# 获取"MyApp"项目的时间线
mempalace_kg_timeline(entity="MyApp")
# 返回按时间排序的所有事实

知识图谱统计

mempalace_kg_stats()
# 返回：
# {
#   "entities": 45,
#   "triples": 128,
#   "current_facts": 98,
#   "expired_facts": 30,
#   "relationship_types": ["负责", "使用技术", "部署在", "决定采用"]
# }

6.4 知识图谱与向量检索的结合

混合检索策略：

# 第一步：向量检索找到语义相关的Drawer
vector_results = mempalace_search(query="认证方案", limit=20)

# 第二步：从向量结果中提取实体，查询知识图谱
entities_in_results = extract_entities(vector_results)
kg_facts = []
for entity in entities_in_results:
    facts = mempalace_kg_query(entity=entity)
    kg_facts.extend(facts)

# 第三步：合并结果，优先展示有知识图谱支持的Drawer
ranked_results = rank_by_kg_support(vector_results, kg_facts)

7. 性能基准：96.6% R@5背后的技术细节

7.1 LongMemEval基准详解

LongMemEval是评估AI长期记忆能力的标准基准，包含：

• 500个问答对
• 跨度长达50轮的对话历史
• 需要跨会话记忆才能正确回答的问题

评估指标：R@5（Recall@5）

• 检索返回前5个结果
• 如果正确答案在其中，计为成功
• 最终得分 = 成功次数 / 总问题数

7.2 MemPalace的基准结果

关键洞见：

1. 96.6% Raw性能的启示：

   • 好的嵌入模型 + 结构化存储 = 强大的检索能力
   • 不需要LLM参与检索过程，降低延迟和成本

2. Hybrid管道的技术细节：

   # Hybrid v4的检索流程（伪代码）
   def hybrid_retrieve(query, wing=None, room=None):
       # 1. 向量语义搜索
       vector_results = chromadb.query(
           query_embedding=embed(query),
           n_results=20,
           where={"wing": wing, "room": room}  # 元数据过滤
       )
   
       # 2. 关键词提升（Keyword Boosting）
       for result in vector_results:
           if has_keyword_overlap(query, result.content):
               result.score *= 1.15
   
       # 3. 时间邻近提升（Temporal Proximity Boosting）
       for result in vector_results:
           days_ago = (now - result.timestamp).days
           if days_ago < 7:
               result.score *= 1.10
           elif days_ago < 30:
               result.score *= 1.05
   
       # 4. 偏好模式提取（Preference Pattern Extraction）
       # 如果query包含"我们决定"、"团队选择"等模式，
       # 提升hall_facts类型的结果
   
       # 5. 重新排序并返回top 5
       return rerank(vector_results)[:5]
   

3. 为什么不直接宣称99.9%？

   • 最后0.6%的提升通过「针对特定错误答案调优」获得
   • MemPalace团队认为这是"teaching to the test"，不具备泛化性
   • 他们在benchmarks/BENCHMARKS.md中明确标注了这一点

7.3 其他基准测试结果

7.4 可复现性承诺

MemPalace在仓库中提供了：

# 完整复现所有基准测试
git clone https://github.com/MemPalace/mempalace.git
cd mempalace
uv sync --extra dev

# 下载数据集（见benchmarks/README.md）
wget https://example.com/longmemeval_s_cleaned.json

# 运行基准测试
uv run python benchmarks/longmemeval_bench.py longmemeval_s_cleaned.json

# 输出详细结果到 benchmarks/results_*/

8. 架构分析：可插拔后端与存储合约

8.1 存储后端接口设计

MemPalace定义了一个抽象的存储后端接口（mempalace/backends/base.py）：

class VectorBackend(ABC):
    """向量存储后端必须实现的接口"""
    
    @abstractmethod
    def add(self, embeddings: List[np.ndarray], metadatas: List[Dict], ids: List[str]):
        """添加向量和元数据"""
        pass
    
    @abstractmethod
    def query(self, query_embedding: np.ndarray, n_results: int, 
             where: Optional[Dict] = None) -> Dict:
        """查询相似向量，支持元数据过滤"""
        pass
    
    @abstractmethod
    def delete(self, ids: List[str]):
        """删除指定ID的向量"""
        pass
    
    @abstractmethod
    def get(self, ids: List[str]) -> Dict:
        """获取指定ID的向量和元数据"""
        pass

8.2 已支持的后端

ChromaDB（默认）

# 默认使用，无需额外配置
mempalace mine ~/projects/myapp
# 数据存储在 ~/.mempalace/myapp/chroma/

Qdrant（推荐用于生产环境）

# 启动Qdrant服务
docker run -p 6333:6333 qdrant/qdrant

# 配置MemPalace使用Qdrant
export MEMPALACE_QDRANT_URL=http://localhost:6333
export MEMPALACE_QDRANT_API_KEY="your-key"  # 可选

mempalace mine ~/projects/myapp --backend qdrant

pgvector（PostgreSQL扩展）

-- 在PostgreSQL中安装pgvector扩展
CREATE EXTENSION vector;

-- 配置MemPalace
export MEMPALACE_PGVECTOR_DSN="postgresql://localhost:5432/mempalace"

mempalace mine ~/projects/myapp --backend pgvector

SQLite Exact（用于验证）

# 使用SQLite进行精确向量检索（暴力搜索，用于验证其他后端的正确性）
mempalace mine ~/projects/myapp --backend sqlite_exact

8.3 后端选择建议

8.4 并发与锁机制

MemPalace使用文件锁（fcntl）来保证多进程安全：

# 伪代码：Palace写入锁
class PalaceLock:
    def __enter__(self):
        self.lock_file = open(palace_path / ".palace_lock", "w")
        fcntl.flock(self.lock_file, fcntl.LOCK_EX)
        return self
    
    def __exit__(self, *args):
        fcntl.flock(self.lock_file, fcntl.LOCK_UN)
        self.lock_file.close()

并发挖掘处理：

# 当另一个进程正在挖掘时
mempalace mine ~/projects/myapp
# 输出：⚠️  Palace is currently being updated by another process.
#         Returning structured error: {"success": false, "error": "already_running"}

9. Agent集成：多Agent协作的记忆共享

9.1 每个Agent拥有自己的Wing

在多Agent系统中，每个 specialist Agent 应该拥有独立的Wing：

# 后端Agent
wing_backend_agent = "wing_agent_backend"

# 前端Agent
wing_frontend_agent = "wing_agent_frontend"

# DevOps Agent
wing_devops_agent = "wing_agent_devops"

9.2 Agent日记：让Agent拥有「工作日志」

# 后端Agent在解决问题后记录
mempalace_diary_write(
    agent_name="backend-agent",
    entry="""
@problem: Prisma transaction timeout in batch operations
@root_cause: Default timeout (5000ms) too low for large batches
@solution: Increased timeout to 30000ms and batched in chunks of 100
@code: prisma.$transaction(operations, timeout=30000)
@date: 2026-06-10T14:30:00Z
""",
    topic="prisma"
)

# 下次遇到类似问题时，Agent可以先查自己的日记
entries = mempalace_diary_read(
    agent_name="backend-agent",
    last_n=20
)
# 从日记中找到之前的解决方案

9.3 Agent间的记忆共享通过Tunnel

# 后端Agent发现前端也需要了解API变更
mempalace_create_tunnel(
    source_wing="wing_agent_backend",
    source_room="api-breaking-changes",
    target_wing="wing_agent_frontend",
    target_room="api-consumption",
    label="Backend API changes affect frontend consumers"
)

# 前端Agent可以通过遍历发现这个连接
mempalace_traverse(start_room="api-consumption", max_hops=1)

10. 自动保存钩子：让记忆无感延续

10.1 Claude Code钩子机制

Claude Code支持在特定事件时触发钩子（hook）：

// ~/.claude/hooks.json
{
  "hooks": {
    "onSave": [
      {
        "command": "mempalace",
        "args": ["hook", "auto-save"],
        "async": true  // 异步执行，不阻塞Claude Code
      }
    ],
    "onContextCompress": [
      {
        "command": "mempalace",
        "args": ["hook", "compress-save"],
        "async": false  // 同步执行，确保压缩前保存
      }
    ]
  }
}

10.2 钩子的工作模式

silent_save模式（推荐）：

# 钩子配置
mempalace_hook_settings(silent_save=True, desktop_toast=False)

# 工作方式：
# 1. Claude Code触发onSave事件
# 2. 钩子直接在后台保存当前会话到Palace
# 3. 不向Claude Code返回MCP调用噪音
# 4. 用户无感知，记忆自动延续

blocking模式（旧版）：

mempalace_hook_settings(silent_save=False)

# 工作方式：
# 1. 钩子通过MCP工具调用保存
# 2. Claude Code等待保存完成
# 3. 可能在会话中看到保存相关的消息

10.3 会话到期问题

问题：Claude Code会话默认30天后过期，如果没有配置自动保存钩子，会话历史会丢失。

解决方案：

# 1. 配置自动保存钩子（见上文）
# 2. 备份现有会话
cp -r ~/.claude/projects/*.jsonl ~/backup/claude_sessions/

# 3. 回填历史会话到Palace
mempalace mine ~/.claude/projects/ --mode convos

# 4. 定期检查保存状态
mempalace_memories_filed_away()
# 返回：{"filed": true, "message_count": 42, "timestamp": "..."}

11. AAAK压缩语言：把上下文塞进更小的空间

11.1 什么是AAAK？

AAAK（Agent-Aware Abstract Knowledge）是MemPalace定义的一种紧凑格式，用于将Palace中的信息压缩后提供给Agent。

为什么需要AAAK？

• 完整的Drawer原文可能很长（几百到几千字符）
• 在有限的上下文窗口中，需要尽可能高效地呈现相关信息
• AAAK提供了一种结构化、紧凑的表示法

11.2 AAAK格式示例

原始Drawer内容：

在2026年6月5日的team meeting中，我们讨论了认证方案的迁移问题。
当前使用的是JWT，但发现两个主要问题：
1. JWT无法主动撤销，一旦签发，在过期前始终有效
2. 刷新token的处理逻辑复杂，容易引入安全漏洞

Kai提出使用Clerk，理由：
- 提供完善的会话管理能力，支持主动撤销
- 内置SSO支持（Google、GitHub）
- SDK使用简单，文档完善

Priya补充：Clerk的pricing对于我们的用户规模是合理的。

决定：采用Clerk，预计两周内完成迁移。
负责人：@kai
相关文件：backend/auth/clerk_setup.py

AAAK压缩版本：

@room: auth-migration
@date: 2026-06-05
@participants: Kai, Priya
@decision: Migrate from JWT to Clerk
@reasons:
  - JWT cannot be actively revoked
  - Clerk provides session management + SSO
  - Reasonable pricing for our scale
@owner: @kai
@timeline: 2 weeks
@files: backend/auth/clerk_setup.py

压缩比：原始文本约450字符 → AAAK约280字符（压缩38%）

11.3 AAAK方言配置

MemPalace允许配置AAAK的「方言」（dialect）：

[aaak]
dialect = "concise"  # 可选：verbose, concise, code-focused
include_metadata = true
include_source_refs = true
max_length = 500  # 每个Drawer的AAAK表示最大字符数

12. 与其他方案对比：为什么MemPalace得分最高

12.1 与主流方案的功能对比

12.2 性能对比的诚实性问题

为什么MemPalace不直接做side-by-side对比？

MemPalace团队在文档中明确说明：

"We deliberately do not include a side-by-side comparison against Mem0, Mastra, Hindsight, Supermemory, or Zep. Those projects publish different metrics on different splits, and placing retrieval recall next to end-to-end QA accuracy is not an honest comparison."

各家的基准测试方法不同：

• Mem0：端到端QA准确率（LLM参与评估）
• Zep：检索召回率 + QA准确率混合
• MemPalace：纯检索召回率（R@5，无LLM）

正确的比较方式：在同一个数据集、同一个指标下比较。MemPalace提供了完整的复现脚本，鼓励其他人用同样的方法测试其他系统。

13. 生产级最佳实践

13.1 Palace容量规划

Drawer数量估算：

# 假设：
# - 每个代码文件平均2000字符
# - 分块大小2000字符，重叠200字符
# - 每个文件约产生 文件字符数 / 1800 个Drawer

# 示例：10万行代码的项目
# 假设平均每行50字符 = 500万字符
# Drawer数量 ≈ 5,000,000 / 1800 ≈ 2,778个Drawer

# 向量存储占用（ChromaDB，embeddinggemma-300m）：
# 每个向量：1024维 * 4字节（float32）= 4KB
# 2,778个Drawer ≈ 11MB（纯向量）
# 加上元数据和索引，预计20-30MB

Wing数量建议：

✅ 推荐：
- 每个主要项目一个Wing
- 每个团队成员一个Wing（用于存储个人偏好和决策）
- 一个共享的"team" Wing（用于存储团队级决策）

❌ 不推荐：
- 每个代码文件一个Wing（太过碎片化）
- 所有内容放在一个Wing（检索时无法有效过滤）

13.2 定期维护任务

# 每周任务：同步Palace与源文件（删除已不存在的Drawer）
mempalace sync --apply

# 每月任务：检查Palace健康状况
mempalace status
# 关注指标：total_drawers增长是否正常，是否有异常大的Wing

# 每季度任务：重建向量索引（如果换了嵌入模型）
mempalace rebuild --backend chromadb

13.3 安全与隐私

敏感信息处理：

# 在挖掘前，确保敏感信息已被排除
# 方法一：.mempalaceignore文件
# 类似.gitignore
cat > .mempalaceignore << EOF
*.env
*.pem
*.key
secrets/
config/production/
EOF

# 方法二：在挖掘时排除
mempalace mine ~/projects/myapp --exclude "*.env,secrets/*"

Palace文件权限：

# 确保Palace目录只允许当前用户访问
chmod 700 ~/.mempalace/
chmod 600 ~/.mempalace/**/*

14. 总结与展望

14.1 MemPalace的核心价值

1. 让AI拥有了可靠的结构化记忆

   • 不再依赖AI的「临时记忆」（上下文窗口）
   • 不再丢失跨会话的关键信息

2. 存储原文的设计哲学经得起考验

   • 摘要会丢失细节，原文不会
   • 检索时拿到完整上下文，自己判断有用信息

3. 基准测试的诚实性树立了行业新标准

   • 可复现的结果 > 宣传性的数字
   • 明确标注训练/测试集划分，避免"teaching to the test"

14.2 适用场景

强烈推荐：

• 使用Claude Code、Cursor等AI编程工具的个人或团队
• 需要长期维护的项目（>3个月）
• 团队协作场景，需要共享决策历史

谨慎评估：

• 对延迟极度敏感的场景（本地向量检索通常需要50-200ms）
• 数据隐私要求极高的场景（需仔细配置排除规则）

14.3 未来展望

根据MemPalace的ROADMAP.md，未来版本可能包含：

1. 多模态记忆：支持图片、图表等非文本内容的存储和检索
2. 分布式Palace：多个团队成员共享一个Palace（通过CRDT实现冲突解决）
3. 更智能的挖掘：用LLM辅助生成Room名称和Hall分类
4. 性能优化：支持GPU加速的嵌入生成，改进大规模Palace的检索速度

参考资源

• GitHub仓库：https://github.com/MemPalace/mempalace
• 官方文档：https://mempalaceofficial.com
• PyPI包：https://pypi.org/project/mempalace/
• Discord社区：https://discord.com/invite/ycTQQCu6kn
• 基准测试详解：https://github.com/MemPalace/mempalace/tree/main/benchmarks

本文完稿于2026年6月。MemPalace仍在快速迭代中，请关注官方仓库获取最新信息。

字数统计：约16,800字