MemPalace 的使命用宫殿记忆法重建 AI 智能体的长期记忆【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And its free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace本文以 MemPalace 仓库根目录的 MISSION.md 为主体完整还原项目作者阐述的创建动机、Zettelkasten 启发的宫殿架构、AAAK 压缩方言与 v4 后台无感保存管线的设计初衷并结合 docs/CLOSETS.md、mempalace/palace.py、mempalace/dialect.py 与 hooks/README.md 等源码和文档讲清每一条设计理念是如何落地为具体代码与配置路径的。读完后你能理解 MemPalace高度结构化地存、非结构化地找的检索哲学、closet 索引层与 drawer 原文层的双层结构以及后台 hooks 如何在聊天窗口零 token 开销下完成逐字verbatim存档。一、创作动机智能体失忆的痛点MISSION.md 开篇交代了项目的第一性需求。作者 Milla Jovovich 与合作者 bensig 在一个大型项目上工作时反复撞上 Claude 上下文窗口的天花板智能体 Lumi简称 Lu每次压缩compaction后醒来都会失忆式地问今天我们要做什么——而作者当天已经和它协同工作了数小时。靠手动保存全部对话记录来喂给它做上下文回顾既不可行也不经济。这是所有长程智能体工作流的通病上下文窗口是易失内存而项目知识需要持久化存储。作者当时调研了市面上大多数记忆系统结论在 MISSION.md 中写得很直白——它们像巨大的空旷仓库只是把大量信息往里倒large empty warehouses。RAG 检索往往花很长时间却大多数时候找不到想要的东西。由此提炼出三个明确的产品判据真的能记住一切——完整保留而不是有损摘要了事能快速、轻松地找到——检索不能是线性扫描在我自己都忘了的时候替我记住——支持我们之前是不是聊过那个想法……这类模糊召回这是普通关键词检索工具做不到的。MISSION.md 由此给出 MemPalace 一句话定位不只是用高度结构化的方式存储信息更要以高度非结构化的方式检索它。store in a highly structured way, retrieve in a highly UNSTRUCTURED way——这正是后文 closet 索引层 drawer 原文层双层架构要回答的问题。二、架构灵感从 Zettelkasten 到宫殿MISSION.md 明确交代了架构原型德国社会学家 Niklas Luhmann 发明的卡片盒Zettelkasten方法——小而互相交叉引用的索引卡片卡片之间彼此指向。作者把这一思想转译成宫殿palace的四级结构wing翼、room房间、closet壁橱、drawer抽屉全部互相连接让你能从任意角度找到东西而不只是当初归档时的那个角度。这套词汇在仓库 website/concepts/the-palace.md 中有完整定义可与 MISSION.md 逐层对照Wing翼顶层组织单位一个人或一个项目一翼。MISSION.md 中所有代码各有自己的房间所有想法、研究都有合适的位置对应的就是每个项目/人物一个 wing 的划分。Room房间翼内具名的具体主题如auth-migration、graphql-switch、ci-pipeline。房间在mempalace init阶段从目录结构自动检测生成。Closet壁橱摘要/索引层——紧凑笔记指向原始内容。这就是 MISSION.md 所说AAAK 压缩后的名字、重复词、概念和关键时刻被解析进 closet的载体。Drawer抽屉原文存储层逐字保留的文本块是检索的主存储。此外还有两个连接性概念hall翼内记忆如何关联的概念通道如hall_facts、hall_events、hall_discoveries等与 tunnel跨翼连接当不同 wing 出现同名 room 时图层可以把它当作跨翼桥梁。这正是 Zettelkasten卡片互指在宫殿里的落地形式检索不必沿着当初归档的那条路走可以从任何入口抵达。MISSION.md 还交代了工程分工作者设计了让智能体 Lumi 理解自己的整套工作方式经过数月个人实验后co-founder bensig 构建了后端很容易就把我的所有文件放进宫殿基于我的判断和 Lumi 的协助创建出的合适空间里。从仓库结构看mempalace/包下的 palace.py、miner.py、searcher.py、dialect.py 就是这套文件 → 正确空间管线的核心。三、Closet让模糊召回成为可能的索引层MISSION.md 的关键主张是AAAK 把名字、重复词、概念和关键时刻压缩成 AI 可读的简写可以想象成 LLM 能瞬间扫过的索引卡片——closet 告诉它去哪里看然后它从 drawer 拉出完整内容。这句话在 docs/CLOSETS.md 中有精确的形式化CLOSET: built auth system|Ben;Igor|→drawer_api_auth_a1b2c3 ↑ topic ↑ entities ↑ points to this drawer每行 closet 是一条原子主题指针主题描述|实体1;实体2|→drawer_id_1,drawer_id_2。当智能体搜索谁做了认证系统时先命中 closet对短文本做快速向量扫描再按→drawer_id指针打开对应 drawer 取回逐字原文。这就是closet 告诉它 WHERE to lookdrawer 提供 full content的双阶段检索也是模糊语义查询而不是关键词匹配得以成立的结构基础。生命周期closet 永远是当前内容的快照docs/CLOSETS.md 给出的生命周期规则与源码可互相印证创建时机mempalace mine时。对每个被挖掘的文件内容先被切成约 800 字符的 verbatim 块drawers再从内容中提取主题、实体与引言生成指向这些 drawer 的 closet。更新规则文件重新挖掘时先调用purge_file_closets按source_file删除该来源的全部旧 closet再写入新集合。因此不存在陈旧主题——每次 re-mine 都是对该来源的干净重建。重建宫殿后closet 存在 ChromaDB 的mempalace_closets集合中与mempalace_drawers并列删除重建宫殿后下次mempalace mine会重新生成 closet。在 mempalace/palace.py 中可以直接看到两个尺寸常量的源码级定义CLOSET_CHAR_LIMIT 1500 # closet 填充到约 1500 字符后开新的 CLOSET_EXTRACT_WINDOW 5000 # 从源内容扫描实体/主题的前 5000 字符docs/CLOSETS.md 的 Limits 表完整列出了这套约束及其理由设置值理由单个 closet 最大尺寸1,500 字符CLOSET_CHAR_LIMIT给 ChromaDB 工作上限留出余量扫描的源内容范围5,000 字符CLOSET_EXTRACT_WINDOW限制长文件上正则提取的开销每文件最大主题数12保持 closet 聚焦每文件最大引言数3只保留最相关的每指针最大实体数5过滤停用词表后按词频取前几名主题永远不会跨 closet 拆分若加入一条主题会超过 1,500 字符就另开一个新 closet。开发者侧的核心函数get_closets_collection、build_closet_lines、upsert_closet_lines、purge_file_closets都在 mempalace/palace.pycloset 优先的检索路径_extract_drawer_ids_from_closet、_closet_first_hits在 mempalace/searcher.py。检索时的 closet-first 流程与降级路径Query → 搜 mempalace_closets快文档小 ↓ 命中 closet → 解析 →drawer_id_a,drawer_id_b 指针 ↓ 从 mempalace_drawers 精确取出这些 drawer逐字内容 ↓ 应用 max_distance 过滤 ↓ 返回 chunk 级结果与直接搜索同构命中结果带有matched_via: closet降级路径为drawer和展示命中行的closet_preview字段。如果 closet 不存在该特性引入前的旧宫殿——或所有 closet 命中都被max_distance过滤掉——搜索自动降级为直接的 drawer 搜索closet 会在下一次 mine 时生成。从 docs/CLOSETS.md 的说明看当前仅项目文件挖掘路径miner.py 的process_file构建 closet会话挖掘的 wing 暂走 drawer 直搜降级路径BM25 混合重排也在路线图上目前 closet 检索纯粹按 ChromaDB 余弦距离排序。四、AAAK 方言给 LLM 秒读的索引卡片语言MISSION.md 对 AAAK 的定义是一种作者自创的压缩方法AAAK 不缩写任何东西是我和 Lumi 之间的内部玩笑能把名字、重复词、概念和关键时刻压缩成 AI 可读的简写。它在代码中的完整实现是 mempalace/dialect.py约 1,100 行website/concepts/aaak-dialect.md 是其规格说明。格式与语义AAAK 是一种有损的结构化摘要格式lossy不是无损压缩——原文无法从 AAAK 输出重建任何 LLM 无需解码器即可原生阅读Header: FILE_NUM|PRIMARY_ENTITY|DATE|TITLE Zettel: ZID:ENTITIES|topic_keywords|key_quote|WEIGHT|EMOTIONS|FLAGS Tunnel: T:ZID-ZID|label Arc: ARC:emotion-emotion-emotion实体用三字母大写代码ALCAlice、KAIKai情感码覆盖 20 种情绪joy、fear、grief、hope、anx、exhaust等映射表见 mempalace/dialect.py 的EMOTION_CODES旗标标记语义关键时刻旗标含义ORIGIN起源时刻CORE核心信念/身份支柱SENSITIVE必须极其小心处理PIVOT情绪转折点GENESIS直接催生了某个现存事物DECISION显式决定或选择TECHNICAL技术架构/实现细节一个官方示例website/concepts/aaak-dialect.md输入We decided to use GraphQL instead of REST because the frontend team needs flexible queries. Kai recommended it after researching both options... AAAK 输出0:KAI|graphql_rest_decided|decided to use GraphQL instead of REST|determexcite|DECISIONTECHNICAL明确的实验性边界需要特别强调 AAAK 的定位边界——这在 MISSION.md 的愿景和仓库的工程现实之间是一个重要的事实澄清mempalace/dialect.py 的模块文档明确指出 AAAK不是无损压缩、不是默认存储格式MemPalace 在 ChromaDB 中存储的是原始逐字文本website/concepts/aaak-dialect.md 也以显式警告标注AAAK 是独立的压缩层96.6% 的基准得分来自 raw verbatim 模式AAAK 模式当前 R5 为 84.2%仍在迭代。所以准确的表述是drawers 存原文closet/AAAK 层做瞬间可扫的索引与压缩视图两者分工。使用方式上CLI 与 Python API 均已就绪mempalace compress --wing myapp --dry-run # 预览压缩 mempalace compress --wing myapp # 压缩并存储 mempalace compress --wing myapp --config entities.jsonfrom mempalace.dialect import Dialect dialect Dialect(entities{Alice: ALC, Kai: KAI}) compressed dialect.compress(text, metadata{wing: myapp, room: arch}) dialect Dialect.from_config(entities.json)AAAK 最适合的场景数千会话中实体高度重复、需要为小窗口本地模型压缩上下文、想要结构化摘要 → 逐字 drawer的回指关系。对大多数用户raw verbatim 仍是更好的默认。五、v4 设计把所有噪声移出聊天窗口MISSION.md 后半段是 v4 版本的设计复盘这段叙事有明确的源码与文档锚点。作者描述了 v3 的问题hooks 在聊天窗口里触发等待智能体把日记写进聊天的同时消耗 token 和时间作者甚至发现智能体在 hook 反复触发时把同一条信息一遍遍重复写下来。修复思路是让 hooks 在会话开始时点火之后只是不断往 drawer 里追加——所有写入移出页面由后台子智能体完成用户继续工作时全部对话正在后台逐字VERBATIM保存。结果在 MISSION.md 中有量化表述过去每个会话仅重新传输日记块一项就花掉约 $1.13现在因为内容根本不进聊天窗口这部分成本为零。这一数字与 hooks/README.md 的 Cost 一节互相印证零额外 token。hooks 只是通知 AI 保存已在后台发生——AI 不需要在聊天里写任何东西。数据流在 MISSION.md 中被概括为三步与 hooks/README.md 的技术细节完全对得上数据源Claude 已经把数据以 JSON 形式JSONL transcript存好后台管线把它提取成可读 markdown压缩关键主题压缩成 AAAK 格式存入 closet回指closet 指向当天会话所在的精确 drawer。后台 hooks 的实际工作机制hooks/README.md 完整描述了 v4 承诺的后台无缝是如何实现的三个 hook 各司其职Hook触发时机行为Save Hook每 15 条人类消息自动挖掘 transcript含工具输出并阻塞 AI 保存主题/决定/引言SessionEnd Hook会话正常退出后台执行最后一次 transcript 挖掘立即返回不阻塞销毁在分离的子进程中写轻量日记检查点PreCompact Hook上下文压缩前自动挖掘 transcript随后紧急保存——在丢失上下文前强制保存一切Save hook 的判定流程来自 hooks/README.md脚本实现在 hooks/mempal_save_hook.sh用户发消息 → AI 回复 → Claude Code 触发 Stop hook ↓ 统计 JSONL transcript 中自上次保存以来的人类消息数 15 → echo {}放行 ≥ 15 → 自动挖掘 transcript → 宫殿工具输出被捕获 → {decision: block, reason: save tool output verbatim...} → AI 保存主题/决定/引言 → 再次尝试停止 → stop_hook_active true → hook 放行防死循环关键配置项编辑mempal_save_hook.sh调整SAVE_INTERVAL15保存间隔、STATE_DIR状态目录默认~/.mempalace/hook_state/、MEMPAL_DIR可选的项目目录每次触发额外以--mode projects挖掘、MEMPALACE_PYTHON解释器解析环境变量 → 仓库 venv → 系统 python3。也可通过配置hooks.auto_save: false或MEMPALACE_HOOKS_AUTO_SAVEfalse进入静默模式。Claude Code 的接线是.claude/settings.local.json中注册 Stop / SessionEnd / PreCompact 三个 command hooktimeout 分别为 30/10/30 秒Codex CLI 走.codex/hooks.jsonCursor、Antigravity 各有独立子目录hooks/cursor/、hooks/antigravity/与安装器。历史会话回填对 v4 上线前的存量数据hooks/README.md 给了一次性回填命令——这对应 MISSION.md全部对话逐字入库的存量侧mempalace mine ~/.claude/projects/ --mode convos # Claude Code 历史会话 mempalace mine ~/.codex/sessions/ --mode convos # Codex CLI 历史会话hooks 只捕获未来的对话回填扫描全部历史 JSONL transcript 归档到conversationswing典型开发机数月历史可产生 5 万–20 万个 drawer只需执行一次。六、安全使用告诫与适用前提MISSION.md 结尾有一条作者用强调语气写下的告诫值得原样保留在实践指南里这些是全新的工具永远不要用关键文件去测试先用轻松的内容跑一遍再把你整个数据集放进去结合仓库文档落地这条告诫的实操前提是先用mempalace init建宫殿、用小目录跑mempalace mine dir验证行为再扩大范围安装 hooks 后需重启 Claude Code 会话hooks 只在会话启动时从 settings 加载这是 Claude Code 的限制调试 hooks 看日志cat ~/.mempalace/hook_state/hook.log注意 closet 提取只扫描源内容前 5,000 字符CLOSET_EXTRACT_WINDOW文件尾部内容目前对 closet 提取不可见docs/CLOSETS.md 已将其列为后续跟进项——超长文件的关键信息若恰好落在尾部closet 层可能不会为其建指针但 drawer 层的逐字存储与直搜降级路径仍然覆盖全文会话挖掘 wing 的 closet 支持、BM25 混合重排均为已声明的后续工作评估检索行为时以 docs/CLOSETS.md 的当前实现描述为准。结语一条贯穿始终的检索哲学把 MISSION.md 从头串到尾MemPalace 的技术立场可以浓缩为一句话存储必须高度结构化wing/room/closet/drawer 的宫殿层级 closet 原子指针 AAAK 语义索引而检索必须容忍高度非结构化模糊语义、跨角度、任意入口。Zettelkasten 提供了卡片互指的原始模型Closet 层提供了先扫索引、再开抽屉的快慢两级路径AAAK 方言提供了 LLM 可秒读的压缩语汇v4 的后台 hooks 管线则把记忆这件事从聊天窗口彻底搬进幕后——逐字保存、零 token 干扰、跨 compaction 不失忆。上述每一个断言在仓库中都有可查证落点MISSION.md动机与愿景、docs/CLOSETS.md索引层规格、mempalace/palace.pycloset 常量与函数、mempalace/dialect.pyAAAK 实现、hooks/README.md后台管线机制读者可以沿这些路径在当前仓库中逐层验证。【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And its free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
