MemPalace：本地优先 AI 记忆系统

项目简介

MemPalace 是一个本地优先的开源 AI 记忆系统。它把对话历史以原文形式存储，再用语义检索取回，不做摘要、抽取或改写。

索引是结构化的：人和项目成为 wings，主题成为 rooms，原始内容存放在 drawers，因此检索可以限定范围，而不是在一个扁平语料上运行。检索层可插拔，默认使用 ChromaDB，接口定义在 mempalace/backends/base.py，可以在不改动系统其余部分的情况下替换后端。除非你主动开启，数据不会离开你的机器。

主要功能

• 原文存储与语义检索：保留对话原文，通过语义搜索定位历史内容。
• 结构化索引：wings（人物/项目）、rooms（主题）、drawers（原文）三层组织，支持按范围搜索。
• 可插拔存储后端：默认 chroma，另提供 sqlite_exact、rust_exact、milvus、qdrant、pgvector；通过 --backend <name>、MEMPALACE_BACKEND=<name> 或 config.json 中的 "backend" 选择。
• 原生向量检索：rust_exact 与独立的 mempalace-native CLI 使用 Rust 引擎扫描同一份 sqlite_exact 数据库。
• MCP Server 与 CLI：可接入 Claude Code、Gemini CLI、Antigravity 等 MCP 兼容工具，也可在终端直接使用。
• 检索效果：LongMemEval（R@5，500 题）上，raw 模式为 96.6%（无需 LLM、无需 API Key）；Hybrid v4 在留出的 450 题上为 98.4%；Hybrid v4 加 LLM rerank 达到 ≥99%。

安装与使用

由 Agent 引导安装

npx skills add MemPalace/mempalace

仓库提供三个 skill：mempalace（引导安装与操作）、mempalace-recall（先检索后回答）、mempalace-task（logstream 委派）。仅安装 skill 并不会安装 CLI 或 MCP server，需要 setup skill 引导完成。

直接安装 CLI

推荐使用 uv，把 CLI 装进隔离环境：

uv tool install mempalace
mempalace init ~/projects/myapp

也可以使用 pipx install mempalace；pip 只建议在已激活的虚拟环境中使用：

python -m venv .venv && source .venv/bin/activate
pip install mempalace

Docker

docker pull ghcr.io/mempalace/mempalace:latest

所有数据（palace、配置、缓存的嵌入模型）持久化在 /data，挂载卷即可复用：

# 以 stdio 运行 MCP server（-i 必需，JSON-RPC 需要 stdin）
docker run -i --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace

# 运行任意 CLI 命令
docker run --rm -v mempalace-data:/data -v /path/to/project:/work:ro \
  ghcr.io/mempalace/mempalace mine /work
docker run --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace search "why GraphQL"

接入 MCP 客户端：

{
  "mcpServers": {
    "mempalace": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "mempalace-data:/data",
        "-v", "/absolute/path/to/.claude/projects:/transcripts:ro",
        "ghcr.io/mempalace/mempalace"
      ]
    }
  }
}

常用命令

# 挖掘内容到 palace
mempalace mine ~/projects/myapp                    # 项目文件
mempalace mine ~/.claude/projects/ --mode convos   # Claude Code 会话（可用 --wing 按项目限定范围）

# 搜索
mempalace search "why did we switch to GraphQL"

# 为新会话加载上下文
mempalace wake-up

# 评估 palace 的组织程度（只读，MCP server 运行时也可安全执行）
mempalace audit

注意事项

• 官方来源只有 GitHub 仓库、PyPI 包和 mempalaceofficial.com 文档，其他域名（包括 .tech、.net 及其他 .com 变体）均为假冒站点，可能分发恶意软件。
• Android / Termux 暂不支持原生安装（ChromaDB、ONNX Runtime 等编译依赖没有 Android wheel），可在隔离的 Debian PRoot 容器中运行常规 Linux 包，参见 Termux 安装指南。
• Docker 镜像以 uid 1000 运行，Linux 下挂载目录需对 uid 1000 可读，普通 0755 目录可用，0700 不行；不要用 --user 绕过，因为 /data 属于镜像内的 uid 1000。
• 首次需要嵌入的调用会把模型下载到 /data（默认 minilm 约 80 MB，embeddinggemma 约 300 MB），首次调用较慢且需要网络。
• 从克隆自行构建时使用当前检出的分支，develop 为默认分支；GPU 镜像仅支持 x86_64。
• 大规模 palace 建议先备份并分批挖掘，例如 mempalace mine <dir> --mode convos --limit 200，中断后可从中断处继续。

---

本作品整理自 GitHub 开源项目 MemPalace/mempalace，原作者 @MemPalace，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。