别再把“AI 记忆”理解成向量库了MemPalace 源码级架构深拆

引言很多人一提到“AI 记忆系统”第一反应就是把历史对话存进向量库等需要的时候再检索出来。这个思路当然没错但它只碰到了问题表面。当我真正把MemPalace的核心源码一路读下来之后我越来越强烈地意识到AI 的长期记忆根本不是“存一下文本”这么简单。这个项目当前以 Python 为主核心依赖很少默认使用 ChromaDB 作为 palace 存储使用 SQLite 作为知识图谱存储并通过 MCP Server 把能力暴露给 Claude Code 一类客户端。它在包元数据里把自己描述为“给 AI 一套记忆系统”而核心包说明也把模块分工写得非常完整。真正让我觉得这个项目值得认真研究的不是某个 benchmark 数字有多高而是它在认真回答一个更难的问题如果不依赖云端不依赖外部 API也不把所有上下文一股脑塞进 promptAI 要怎样拥有一套可持续、可组织、可维护、可被代理主动使用的长期记忆README、核心模块说明和 MCP Server 的协议设计几乎都在围绕这个问题展开。这篇文章我不准备只讲“怎么安装、怎么运行”而是想从源码层面把 MemPalace 真正拆开看看它到底是怎样把“长期记忆”这件事一步步落地的。一、MemPalace 到底是什么从表面上看MemPalace 像一个“本地 AI 记忆工具”。但如果你顺着它的核心模块往下看会发现它其实更接近一套Memory Runtime。它有明确的分层cli.py负责命令入口与调度miner.py负责项目文件入库convo_miner.py负责会话入库normalize.py负责多平台聊天导出归一化searcher.py负责语义检索layers.py负责四层记忆栈knowledge_graph.py负责时序知识图谱palace_graph.py负责主题导航图mcp_server.py负责把整套系统变成 MCP 工具服务这意味着MemPalace 想做的根本不只是“本地存聊天记录”。它在尝试构建的是一套完整链路输入进入系统 → 内容被组织成统一记忆单元 → 检索层把相关内容找回来 → 调度层控制哪些记忆先进入上下文 → 结构化层维护事实与主题关系 → 服务层把这些能力交给 AI 代理持续调用。这就是它和普通本地 RAG 工具最大的区别。二、这个项目最关键的一句话在mcp_server.py里有一句非常有代表性的话Storage is not memory — but storage this protocol memory.如果你真的做过 AI Agent 或长期上下文系统就会知道这句话有多准确。因为很多人误以为只要把内容放进数据库AI 就“有记忆”了。但 MemPalace 的做法不是这样。它真正强调的是三件事必须同时成立第一内容要被合理组织。第二系统要能在需要时把相关内容找回来。第三代理本身要形成一套稳定行为回答前先查、会话后会写、事实变化时会更新。mcp_server.py里通过PALACE_PROTOCOL把这种行为约束直接写进了系统协议。所以 MemPalace 的核心不是“存储本身”而是存储 检索 行为协议 记忆系统。这就是它比很多“向量库封装器”更值得研究的地方。三、项目资料是怎么被放进记忆宫殿的在项目资料这条链路上核心文件是miner.py。它不是简单地遍历目录、读文件、做 embedding然后完事。它走的是一条明显带工程思维的路径先读项目根目录的mempalace.yaml配置然后扫描目录尊重.gitignore过滤掉.git、node_modules、__pycache__、dist、build等常见噪声目录只保留可读扩展名再根据目录结构、文件名和内容关键词把文件路由到某个 room最后按字符和换行边界切成 chunk写入 palace。每个 chunk 都会成为一个 drawer并带上wing、room、source_file、chunk_index、added_by、filed_at、source_mtime等 metadata。这里最值得注意的不是“它会切 chunk”而是它的整体思路优先相信项目本身已有的结构而不是一开始就把所有理解都交给模型。这是非常成熟的工程判断。因为真实项目里的知识并不是平铺的它天然带着目录、模块、文件名、文档分区、约定俗成的结构信号。MemPalace 在这一层做的事情本质上是在说先用最稳定、最便宜、最可解释的方式把内容初步归位再用语义检索去补足规则无法覆盖的模糊区。这种路线并不炫技但非常适合做长期记忆系统。四、聊天记录又是怎么进入系统的另一条核心链路是会话入库也就是normalize.py和convo_miner.py。normalize.py做的第一件事不是理解内容而是做协议兼容。它支持Claude.ai JSONChatGPTconversations.jsonClaude Code JSONLOpenAI Codex CLI JSONLSlack JSON普通文本 transcript它的目标很明确把这些不同来源、不同结构的聊天导出统一转成一种内部 transcript 表示。更有意思的是它并没有只保留“用户说了什么、AI 回了什么”。对于 Claude Code 这类会话它还会保留tool_use和tool_result的痕迹只不过不会原样保留完整 JSON而是做了轻量格式化和裁剪比如[Bash] ...[Read path][Grep] pattern in target同时会对 Bash 输出、Grep 结果做限量保留避免工具输出过长把记忆库变成日志仓库。这一点特别关键。因为在真正的 Agent 场景里最有价值的往往不是最后一句答案而是它读了哪些文件它执行了哪些命令它 grep 了什么它遇到了什么错误它是通过什么路径定位到问题的换句话说MemPalace 不只是保存“对话结果”它还在尽量保存解决过程的痕迹。接下来convo_miner.py会把这些归一化后的 transcript 进一步切成 drawer。默认模式下它按“一个用户问题 后续 AI 响应”作为一个 exchange chunk如果不是标准 transcript就退化到按段落或行组切块。它还支持一个general模式把会话直接抽取成 decision、preference、milestone、problem、emotional 这几类记忆。写入时还会额外打上ingest_modeconvos和extract_modeexchange/general的 metadata。这说明 MemPalace 的会话处理并不是“简单存档”而是在尝试把会话真正变成可组织、可检索、可继续加工的记忆对象。五、理解 MemPalace必须先理解 drawer无论是项目资料还是聊天记录最终都会被收敛成一种统一对象drawer。这是整个系统最重要的抽象。drawer 不是一段普通文本它是某段原文或半结构化内容归属于某个 wing落在某个 room来自某个 source file具有写入时间、来源、切片序号等 metadata 的最小记忆单元一旦你理解了 drawer整个系统的设计就会突然变得很清晰miner.py负责生产 drawerconvo_miner.py负责生产 drawersearcher.py负责回收 drawerlayers.py负责选择 drawermcp_server.py负责暴露 drawer 的增删改查和检索能力换句话说MemPalace 的本质不是“文件库”也不是“聊天库”而是一个以 drawer 为核心对象的本地记忆系统。这就是它统一异构输入的方式。六、它的检索为什么比普通“向量搜索”更像记忆系统searcher.py的定位很克制它做 semantic search但明确强调返回的是verbatim text不是摘要。它的典型路径是获取 collection根据wing/room构造 where filter调用 Chromaquery()返回 drawer 原文、metadata 和 distance展示相似度与来源信息这看起来像是普通向量搜索但它有两个重要差异。第一它并不是只靠向量。它先做wing/room收窄再做 embedding query。也就是说它天然就是metadata filter 向量检索这种方式虽然不算花哨却极其实用。很多检索效果提升本质上就来自正确的检索范围约束而不是某个神奇模型。第二它明确把自己的职责限制在“找回原文”而不是提前替你总结答案。这非常重要。因为长期记忆系统最怕的一件事就是在检索阶段就把原始上下文损耗掉。MemPalace 在这一层非常克制尽量只负责“把过去的东西找回来”。当然它当前还不是完美检索系统。路线图已经明确提到 hybrid search、time-decay scoring 等增强能力说明作者也很清楚目前这套检索体系的主轴还是“向量 metadata”对精确术语、错误码、代码符号、路径这类内容仍有进一步升级空间。七、四层记忆栈才是这个项目真正的灵魂如果说 drawer 是存储抽象那layers.py就是 MemPalace 的上下文调度抽象。它把记忆分成四层L0IdentityL1Essential StoryL2On-Demand RecallL3Deep SearchL0 很简单从~/.mempalace/identity.txt读取“我是谁”L1 会从 palace 里抽出一批高权重 drawer按 room 组织成较短的 wake-up textL2 用于按 wing / room 快速召回局部内容L3 则是真正的深度语义搜索。这里真正厉害的地方不在于“分了四层”而在于它承认了一个现实上下文窗口是稀缺资源。真正的长期记忆系统不可能每次都把几年历史、所有文档、全部对话塞进 prompt。它必须学会按成本逐层装载先用很少的 token 让模型“醒过来”再按当前话题召回局部记忆真要查证时再做深搜这其实比“能不能搜到”更重要。因为长期记忆系统一旦无法控制装载成本再好的存储和检索也会在真实使用中失去意义。从这个角度看layers.py才是 MemPalace 最接近“产品思想”的部分。八、为什么它还要做知识图谱和主题图如果 MemPalace 只做 drawer 向量检索其实已经能跑起来了。但它没有停在这里。它还做了两套额外的结构化层1. 时序知识图谱knowledge_graph.py用 SQLite 存实体、关系三元组、valid_from、valid_to支持查询某个实体当前或某个时间点的事实标记事实失效查看时间线查看图谱统计信息这层的意义在于有些记忆不是“找文本”而是“确认某个事实在什么时间成立”。比如项目负责人变了、偏好变了、关系变了、状态变了这些都更适合进 KG而不是只靠向量库模糊搜索。2. Palace Graph 主题导航图palace_graph.py做的不是实体图而是 room 图。它把 room 当节点把跨 wing 共享的 room 当连接通道允许从一个主题出发找到与之相邻的房间或者发现连接不同领域的“隧道”。这层非常有意思因为它表达的是记忆不只是“能不能搜到”还包括“能不能顺着主题走过去”。很多系统只能回答“给我找相关文本”但 MemPalace 在尝试更进一步地支持“这个主题还能连到哪些领域”。这条路线未必已经打磨到最强但方向非常有辨识度。九、MCP Server 为什么像一个“记忆中台”mcp_server.py是整个系统最像“中台服务”的部分。它做的事情很多解析 MCP 请求协商协议版本暴露工具列表按 schema 分发tools/call对输入参数做白名单过滤和类型转换管理 Chroma client / collection 缓存维护 metadata cache做 WAL 写前审计在搜索前做 query sanitize对外统一暴露 palace、KG、graph、diary、hook 等能力这里有两个点特别值得强调。第一个点它对脏查询并不天真query_sanitizer.py的存在非常说明问题。源码里明确提到AI 代理有时会把大段 system prompt 或杂乱上下文一起塞进搜索 query导致 embedding 被前缀污染检索效果可能从 89.8% 掉到 1.0%。sanitize 的目的就是尽可能从长 query 里提取真正的检索意图至少避免“悬崖式失败”。这说明 MemPalace 不是默认上层 agent 总会“正确调用工具”而是在服务层主动做了抗脏输入缓冲。第二个点它对写入风险有审计意识mcp_server.py会把所有写操作先记进 WAL写 drawer、删 drawer、改 drawer、写 diary、加 KG 事实、使 KG 事实失效都会先记录 JSONL 日志。目录和文件权限也会尽可能收紧。源码注释还直接提到 memory poisoning 风险。这一点特别像真正要长期运行的系统而不是“写完就算”的 demo。十、它最有野心的一块其实是 diary 和 hook很多人第一次看 MemPalace注意力都会被 palace、KG、graph 吸引。但如果你往后看会发现它最有想象力的一块可能反而是让 agent 自己也形成连续经验。mcp_server.py里提供了mempalace_diary_write和mempalace_diary_read。每个 agent 都可以拥有自己的 diary wing记录工作、观察、判断和重要发现。与此同时hooks_cli.py实现了session-start、stop、precompact三类 hook支持在会话进行到一定长度时自动提醒保存在上下文即将 compaction 时强制提醒“把重要内容沉淀进记忆系统”还支持通过MEMPAL_DIR自动触发本地mempalace mine。这说明 MemPalace 想解决的已经不只是“记住过去”而是让代理能够持续维护自己的长期记忆状态。这一步非常难但也非常值钱。因为真正长期使用 Agent 的人都知道最痛的并不是“有没有存储能力”而是我会不会忘了保存上下文压缩前能不能及时沉淀学到的新信息能不能进入长期记忆旧事实变了之后有没有地方维护MemPalace 已经开始碰这些问题了。十一、这个项目现在最强的地方如果我要总结它最强的地方我会说有三点。第一它抓住了“长期记忆系统”真正难的部分真正难的从来不是“接一个向量库”而是异构输入怎么统一内容怎么组织检索怎么控制成本代理怎样形成先查后说的习惯事实如何随时间维护自动写入怎样防污染、可审计、可回溯MemPalace 在这些点上都已经有了明确实现。第二它不是概念先行而是代码跟得上概念很多项目包装很好但落地后本质上仍是“向量库 搜索接口”。MemPalace 不一样。它的 palace、wing、room、drawer、L0~L3、KG、graph、protocol、diary这些概念在代码里都有对应实现。第三它已经开始为平台化演进做准备palace.py已经不是把 Chroma 写死在所有模块里而是通过 backend seam 统一收口路线图也明确写了 PostgreSQL backend、LanceDB backend、PalaceStore 等方向。这意味着它不满足于永远做一个“本地脚本工具”而是在为未来的多后端、多场景演进留空间。十二、它现在最大的短板也很明确当然MemPalace 绝不是没有问题。1. 检索层还不够 hybrid当前主干仍是“向量 metadata filter”对精确术语、错误码、路径、代码符号这类关键词检索理论上还有提升空间。路线图已经把 hybrid search 写进去了说明作者自己也认同这一点。2. room 模型偏单标签无论项目文件还是会话当前都更接近“主归属到一个 room”这对复杂多主题内容不够友好。3. chunking 还不够结构感知项目文件主要按字符和换行切会话在 exchange 模式下甚至只保留 AI 回答前 8 行这对某些长回答和代码型内容并不理想。4. 有些设计理念已经成熟但实现还没完全追平比如 L1 注释里说会兼顾近期性与重要性但当前实现主要还是按 importance 系列字段排序KG 虽然有时序建模但自动抽取与冲突治理闭环仍不完整。所以它现在更像一套方向非常正确、核心骨架已经搭起来、但仍在快速打磨中的强原型。十三、最后的判断如果你只是想找一个“本地存聊天”的工具MemPalace 可能显得有点重。但如果你真正关心的是AI 如何拥有可持续、可组织、可维护、可服务化、可被代理主动使用的长期记忆那 MemPalace 绝对值得认真读一遍。它最厉害的地方不是它已经完美而是它几乎把这件事里最难、最关键、最容易被忽略的环节都碰到了原文保留drawer 抽象项目与会话统一入库分层上下文装载时序知识图谱主题导航图MCP 工具体系hook 自动沉淀查询污染防护写入审计与风险意识很多项目停留在“本地向量库工具”这一步而 MemPalace 已经开始认真回答一个更本质的问题AI 的长期记忆到底该如何工作。这才是它真正值得被研究的原因。