【实战】MemPalace 完整安装与使用指南

未来已来只需一句指令养龙虾专栏导航持续更新ing…什么是 MemPalaceMemPalace 是由好莱坞演员 Milla Jovovich《生化危机》《第五元素》主演与开发者 Ben Sigman 共同开发的本地 AI 记忆管理系统。它解决了传统 AI 对话中每次新开会话就失忆的核心痛点。核心理念不同于 Mem0、Zep 等系统让 AI 决定什么值得记住往往会丢弃推理过程和上下文MemPalace 选择存储所有对话原文通过向量搜索在需要时精准检索。这借鉴了古希腊记忆宫殿Method of Loci技巧——将信息按空间结构组织大幅提升检索效率。 前置环境条件1. Python 版本要求要求版本最低要求Python 3.9推荐版本Python 3.11性能最佳检查命令python--version# 或python3--version2. 包管理工具选择方案 Auv强烈推荐特点由 Astral 开发的现代 Python 包管理器速度极快支持自动 Python 版本管理安装curl-LsSfhttps://astral.sh/uv/install.sh|sh验证uv --version方案 Bpip venv传统方案Python 内置无需额外安装适合习惯传统工作流的用户3. 系统要求项目要求操作系统Linux / macOS / WindowsWindows 需设置PYTHONIOENCODINGutf-8内存至少 2GB 可用内存磁盘空间至少 500MB用于模型和向量数据库网络首次安装需下载 ONNX 嵌入模型约 80MB4. 模型下载说明首次运行时会自动下载all-MiniLM-L6-v2嵌入模型模型大小~79MB下载位置~/.cache/chroma/onnx_models/all-MiniLM-L6-v2/onnx.tar.gz作用将文本转换为 384 维向量用于语义相似度搜索 安装步骤方法一使用 uv推荐# 1. 创建虚拟环境自动安装 Python 3.11 如果未安装uv venv--pythonpython3.11 ~/.mempalace-venv# 2. 激活虚拟环境source~/.mempalace-venv/bin/activate# 3. 安装 MemPalaceuv pipinstallmempalace# 4. 验证安装mempalace--helpuv 的优势自动处理 Python 版本依赖解析速度比 pip 快 10-100 倍原子化安装失败自动回滚方法二使用 pip venv# 1. 创建虚拟环境python3.11-mvenv ~/.mempalace-venv# 2. 激活虚拟环境source~/.mempalace-venv/bin/activate# 3. 升级 pippipinstall--upgradepip# 4. 安装 MemPalacepipinstallmempalace# 5. 验证安装mempalace--help方法三全局安装⚠️ 不推荐pip3installmempalace为什么不推荐会污染系统 Python 环境可能导致依赖冲突且不利于后续卸载或版本管理。如下图所示 预下载模型网络慢的情况如果首次运行时下载模型超时可手动预下载# 1. 创建模型缓存目录mkdir-p~/.cache/chroma/onnx_models/all-MiniLM-L6-v2# 2. 下载模型cd~/.cache/chroma/onnx_models/all-MiniLM-L6-v2curl-L-oonnx.tar.gz https://chroma-onnx-models.s3.amazonaws.com/all-MiniLM-L6-v2/onnx.tar.gz# 3. 解压模型tar-xzfonnx.tar.gz️ 初始化与核心概念1. 初始化记忆宫殿# 激活环境source~/.mempalace-venv/bin/activate# 初始化项目扫描目录结构创建房间mempalace init /path/to/your/project初始化过程原理扫描目录结构识别项目文件、代码、文档实体检测自动识别人名、项目名如 “Kai”、“Driftwood”创建配置文件~/.mempalace/config.json全局配置~/.mempalace/wing_config.json翼楼映射~/.mempalace/identity.txt身份层L0记忆宫殿架构Wing 翼楼项目/人物Hall 大厅记忆类型Room 房间具体主题Closet 壁橱AAAK压缩摘要Drawer 抽屉原文存储核心概念解释概念说明类比Wing翼楼顶级容器每个项目或人物一个翼楼图书馆的不同分馆Hall大厅记忆类型走廊facts事实、events事件、discoveries发现、preferences偏好、advice建议图书馆的分类标签Room房间翼楼内的具体主题如 “auth-migration”、“pricing”图书馆的书架Closet壁橱存储 AAAK 压缩摘要指向原始内容书籍的索引卡片Drawer抽屉原始文件存储永不删除书籍本身2. 挖掘数据Mining项目文件挖掘# 挖掘代码、文档、笔记mempalace mine /path/to/your/project对话记录挖掘# 挖掘 Claude、ChatGPT、Slack 导出文件mempalace mine /path/to/chats--modeconvos# 自动分类为决策、里程碑等mempalace mine /path/to/chats--modeconvos--extractgeneral三种挖掘模式projects代码和文档按段落分块convos对话导出按问答对分块general自动分类为 decisions决策、milestones里程碑、problems问题、preferences偏好、emotional context情感上下文3. 搜索记忆# 基础搜索mempalace search为什么我们切换到 GraphQL# 在特定翼楼搜索mempalace search定价讨论--wingmy_app# 在特定房间搜索mempalace search定价讨论--wingmy_app--roomcosts# 查看状态mempalace status4. 唤醒上下文Wake-up# 显示 L0 L1 唤醒上下文约 170 tokensmempalace wake-up# 特定项目的唤醒上下文mempalace wake-up--wingmy_app四层记忆栈原理四层记忆栈主题匹配需要更多上下文语义搜索L0: Identity 身份层~50 tokens始终加载L1: Critical Facts 关键事实~120 tokens始终加载L2: Room Recall 房间回忆按需加载L3: Deep Search 深度搜索按需加载用户提问ChromaDB层级内容大小加载时机L0身份定义你是谁、AI 是谁~50 tokens始终加载L1关键事实团队、项目、偏好~120 tokensAAAK 压缩始终加载L2房间回忆当前主题相关会话可变主题匹配时L3深度语义搜索全文检索可变显式请求时成本对比基于 6 个月对话历史约 1950 万 tokens方案加载 Tokens年成本粘贴全部19.5M超出上下文窗口不可行LLM 摘要~650K~$507MemPalace wake-up~170~$0.70MemPalace 5 次搜索~13,500~$10 与 AI 集成Claude Code推荐方式 1插件市场安装claude plugin marketplaceaddmilla-jovovich/mempalace claude plugininstall--scopeuser mempalace方式 2手动 MCP 配置claude mcpaddmempalace -- python-mmempalace.mcp_server重启 Claude Code输入/skills验证 “mempalace” 是否出现。其他 MCP 兼容工具ChatGPT、Cursor、Gemini# 通用 MCP 配置命令claude mcpaddmempalace -- python-mmempalace.mcp_server配置后AI 可自动调用19 个 MCP 工具读取工具mempalace_status宫殿概览mempalace_list_wings列出翼楼mempalace_list_rooms列出房间mempalace_search语义搜索mempalace_kg_query知识图谱查询写入工具mempalace_add_drawer添加原文mempalace_diary_write写入代理日记本地模型Llama、Mistral 等方式 1唤醒命令mempalace wake-upcontext.txt# 将 context.txt 粘贴到本地模型的系统提示中方式 2命令行搜索mempalace searchauth decisionsresults.txt# 将结果包含在提示词中方式 3Python APIfrommempalace.searcherimportsearch_memories resultssearch_memories(auth decisions,palace_path~/.mempalace/palace)# 将结果注入本地模型上下文 目录结构详解安装后生成的文件结构~/.mempalace/ # 全局记忆宫殿 ├── palace.db # SQLite 元数据数据库 ├── chroma/ # ChromaDB 向量数据库 ├── config.json # 全局配置 ├── wing_config.json # 翼楼映射配置 ├── identity.txt # 身份层L0 └── wings/ # 翼楼目录 ├── wing_kai/ # 人物翼楼示例 │ ├── hall_facts/ │ ├── hall_events/ │ ├── hall_discoveries/ │ ├── hall_preferences/ │ └── hall_advice/ └── wing_driftwood/ # 项目翼楼示例 └── ... /path/to/your/project/ # 项目目录 ├── mempalace.yaml # 项目特定配置可选 └── .mempalace_entities.json # 项目实体检测缓存️ 常见问题与解决方案Q: pip: command not found解决方案# 使用 pip3pip3installmempalace# 或安装 uv推荐curl-LsSfhttps://astral.sh/uv/install.sh|shQ: Python 版本过低 3.9解决方案# 使用 uv 安装新 Pythonuv pythoninstall3.11uv venv--pythonpython3.11 ~/.mempalace-venvQ: 下载模型超时解决方案手动预下载模型见上方预下载模型部分Q: No palace found解决方案# 必须先初始化mempalace initdir# 然后挖掘数据mempalace minedirQ: 如何重置/删除记忆宫殿解决方案# 删除宫殿目录rm-rf~/.mempalace/palace# 然后重新初始化mempalace initdirQ: Windows 下 Unicode 编码错误GitHub issue #47解决方案# Windows PowerShell$env:PYTHONIOENCODING utf-8mempalace initQ: ChromaDB 依赖构建失败解决方案# macOSxcode-select--install# Ubuntu/Debiansudoapt-getinstallbuild-essential python3-dev# 然后重试安装pipinstallmempalace 性能参考与基准测试操作性能指标初始化扫描 100 个文件约 10-30 秒挖掘每分钟处理 10-50 个文件取决于大小搜索 1 秒返回结果首次运行额外 2-5 分钟下载模型基准测试成绩基准测试模式成绩API 调用LongMemEval R5Raw纯本地96.6%零LongMemEval R5Hybrid Haiku 重排序100%(500/500)~500 次LoCoMo R10Raw会话级别60.3%零与竞品对比系统LongMemEval R5成本本地运行MemPalace (hybrid)100%免费是Supermemory ASMR~99%付费否MemPalace (raw)96.6%免费是Mastra94.87%API 费用否Mem0~85%$19-249/月否Zep~85%$25/月否 官方资源资源链接GitHubhttps://github.com/milla-jovovich/mempalacePyPIhttps://pypi.org/project/mempalace/Discordhttps://discord.com/invite/ycTQQCu6kn基准测试https://github.com/milla-jovovich/mempalace/blob/main/benchmarks/BENCHMARKS.md官方网站https://www.mempalace.tech⚠️ 重要说明来自官方根据 Milla Jovovich 和 Ben Sigman 在 2026 年 4 月 7 日的声明AAAK 压缩是实验性的目前 LongMemEval 成绩 96.6% 来自Raw 模式原文存储而非 AAAK 压缩模式84.2%。AAAK 在大量重复实体场景下才能体现压缩优势。30x 无损压缩表述过度AAAK 是有损缩写系统通过实体编码和句子截断实现压缩并非无损压缩。34% 宫殿提升说明该数字比较的是无过滤搜索 vs 翼楼房间元数据过滤这是 ChromaDB 的标准元数据过滤功能并非全新的检索机制。矛盾检测fact_checker.py工具存在但尚未自动集成到知识图谱操作中。总结MemPalace 是一个真实、可用的开源项目其核心优势在于本地运行、零 API 成本、原文存储、高检索准确率。96.6% 的 LongMemEval 原始成绩零 API 调用是可信的代表了当前免费本地 AI 记忆系统的最高水平。