MemPalace 专属 Agent 日记：用 MCP 工具为每个 AI 智能体建立跨会话持久记忆-育师

MemPalace 专属 Agent 日记：用 MCP 工具为每个 AI 智能体建立跨会话持久记忆

【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And it's free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace

在 MemPalace 中，"Agent 记忆"并不是独立的用户体系，而是一套建立在宫殿（Palace）层级之上的具名日记工作流：为每个智能体分配一个稳定的名字，通过mempalace_diary_write/mempalace_diary_read两个 MCP 工具，将观察、发现、决策与模式写入该智能体专属的 wing 下的diary房间，并跨会话长期读取。读完本文，你将掌握 MemPalace 当前提供的 Agent 日记完整用法、其在宫殿结构中的落位方式，以及它背后的源码实现细节（大小写归一化、超长分块、WAL 日志与读取过滤），从而让 reviewer、architect、ops 等不同分工的智能体各自持有互不串扰的长期记忆流。

范围声明：MemPalace 目前没有"Agent 注册表"

agents.md 首先澄清了当前能力的边界：本文档描述的日记工作流是当下已经存在并可用的功能，而 MemPalace目前并未提供以下设施：

一个正式的 agent registry（注册中心）；
~/.mempalace/agents/*.json这类按 agent 落盘的配置文件；
mempalace_list_agents之类的"列出全部 agent"工具。

这意味着 Agent 的身份与归属完全由约定驱动：谁使用了agent_name，谁就拥有了自己的日记流。实践模型非常简单——给智能体一个稳定名字，然后在它的 wing 下读写日记条目即可。MCP 工具注册表中也只有与日记直接相关的两个工具（见 mcp_server.py 的mempalace_diary_write与mempalace_diary_read声明）。

Agent 在 MemPalace 中做什么

每个智能体在日记模型中承担三件事：

Has a focus（有专注点）——它关注什么；
Keeps a diary（写日记）——条目可跨会话持久保存；
Can read recent history（回读最近历史）——用于发现模式、保持连续性以及承接后续工作。

这三者对应到产品价值上，就是"把一次会话的上下文沉淀为可检索的长期资产"。一个做了大量代码评审的 reviewer，不必在每次新会话里重新摸索项目中的反复问题——它可以直接读取自己的日记，回忆上次发现的 bug 模式（详见 website/concepts/agents.md）。

Agent Diary：轻量记忆流

日记（diary）被定义为"一位具名智能体的轻量记忆流"：观察（observations）、发现（findings）、决策（decisions）与反复出现的模式（recurring patterns）。它不是面向最终用户的精加工叙事，而是高度压缩、面向 LLM 自身复读的结构化速记。

写入条目：`mempalace_diary_write`

原文档给出的调用形状如下：

MCP tool: mempalace_diary_write arguments: { "agent_name": "reviewer", "entry": "PR#42|auth.bypass.found|missing.middleware.check|pattern:3rd.time.this.quarter|★★★★" }

两个核心参数：

参数	说明
`agent_name`	必填，你的名字——每个 agent 拥有自己的日记 wing（即`wing_<agent_name>`）
`entry`	必填，AAAK 格式的日记条目正文

此外，函数签名tool_diary_write(agent_name, entry, topic="general", wing="")（见 mcp_server.py）还支持两个可选参数：

topic（默认general）：条目的主题标签，会随条目一起持久化到元数据中，后续可按主题检索归类；
wing（默认空）：目标 wing 覆盖项。省略时自动使用wing_<agent_name>；传入具体值（例如某个项目 wing）时，日记会被写入项目空间而不是 agent 专属空间。

读取历史：`mempalace_diary_read`

MCP tool: mempalace_diary_read arguments: { "agent_name": "reviewer", "last_n": 10 } → returns last 10 findings, compressed in AAAK

读取时按时间倒序返回最近last_n条记录，条目内容保持写入时的 AAAK 压缩形态。last_n的默认值为 10，源码中会被夹取（clamp）到1到100之间，避免一次拉取过多内容撑爆上下文窗口（见 mcp_server.py）。

可用 MCP 工具一览

Tool	Description
`mempalace_diary_write`	Write an AAAK diary entry
`mempalace_diary_read`	Read recent diary entries

在 MCP 工具注册表（mcp_server.py）中，mempalace_diary_write的语义描述进一步说明了 entry 的写法要求："Write to your personal agent diary in AAAK format. Your observations, thoughts, what you worked on, what matters."，并给出了一个可直接参考的 AAAK 示例：SESSION:2026-04-04|built.palace.graph+diary.tools|ALC.req:agent.diaries.in.aaak|★★★。其中ALC是对 Alice 的三字母实体码（详情见 AAAK 方言文档）。

工作原理：Agent 即 Wing，条目即 Diary 房间

日记并非散落在某处的键值对，而是严格映射到宫殿的层级结构中。每个具名 agent 对应宫殿里属于自己的一个 wing：

wing_reviewer— the reviewer's diary, findings, patterns
wing_architect— the architect's decisions, tradeoffs
wing_ops— the ops agent's incidents, deploys

所有条目都进入该 wing 下的diary房间，并打上 topic、时间戳（timestamp）和 agent 名三类标记。这正好复用了 the-palace.md 中描述的宫殿模型：wing 是顶层组织单元（对应一个人/一个项目），room 是 wing 内的具体主题，而 wing 与 room 标识最终会成为向量检索时的元数据过滤条件。

源码将这套约定落得非常具体。tool_diary_write中，当调用方未显式给出 wing 时：

wing = f"wing_{agent_name.replace(' ', '_')}" room = "diary"

即 wing 命名规则是wing_前缀 + agent 名（空格转下划线），房间名固定为diary，对应的分类大厅为hall_diary，条目类型标记为diary_entry（mcp_server.py）。写入时生成的元数据完整集为：

wing（如wing_reviewer）、room（固定diary）、hall（固定hall_diary）；
topic（默认为general）、type（diary_entry）；
agent（归一化后的小写 agent 名）；
filed_at（ISO 时间戳）与date（YYYY-MM-DD）；
chunk_index（未超长时为 0）。

在此基础上，每次diary_write都会先行进入 WAL（Write-Ahead Log），记录工具名、agent、topic、entry_id 与最多 200 字符的 entry 预览（mcp_server.py），保证写入的可恢复与可审计性。而col.add（而非upsert）是有意为之的：entry_id基于微秒级时间戳与内容哈希生成，天然唯一，一旦发生同微秒级冲突应当作为错误暴露，而不是静默覆盖先前条目。

超长条目的自动分块

diary_write在写入前会比较条目长度与配置项chunk_size。若单条 entry 超过chunk_size，源码不会截断丢弃，而是按chunk_size切分成多个子块，每个块携带chunk_index、parent_entry_id、parent_drawer_id等关联键，保证"一条日记 = 一个逻辑组、多个物理 drawer"；整批使用单次 batchedadd提交，使 embedding 过程要么全部成功、要么全部失败，避免写一半留下半个条目（mcp_server.py）。这保证了读取路径与未来的语义搜索都能无损重组完整条目。

读取路径与身份归一化

tool_diary_read的查询过滤（mcp_server.py）默认恒等叠加两个条件：room = diary且agent = <agent_name>；若显式指定了wing，则在最前面追加wing条件。反过来，当wing为空时，读取会跨越该 agent 写过的所有 wing汇总返回——这正是 hooks 写日记时落点在项目级 wing（如wing_<project>）之后，agent 仍能读回自己记录的原因。

两点值得注意的工程细节：

大小写不敏感（issue #1243）：agent_name在写入与过滤前都被归一化为小写，因此Claude、claude、CLAUDE会解析为同一个 agent。需要特别说明的是：在修复前已用混合大小写写入的旧数据，无法被小写过滤器匹配，这类历史数据需通过mempalace repair迁移（这是源码注释明确给出的建议路径）。
错误语义分层：若写入时正有另一场 mine 在进行，函数会返回带error_class的拒绝结果（LOCK_REFUSAL_ERROR_CLASS），让守护进程（daemon）选择"延后重试"而非"死信丢弃"（issue #2014），而不是把锁冲突误报成写入失败。

读取返回体包含agent、entries（按时间倒序，每项含date/timestamp/topic/content）、total（该 agent 全部日记条数）与showing（本次实际返回条数），便于调用方感知还有多少历史未读。

Specialization：用分流保持分工

日记工作流最直接的收益是专长分流（specialization）：把不同工作上下文隔离到独立的日记流里，避免全部挤进一条共享日志造成互相污染。

reviewer 维护 bug patterns；
architect 维护 decisions / tradeoffs；
ops agent 维护 incident notes。

三者各自在wing_reviewer、wing_architect、wing_ops下演进，互不混淆。更进一步，当这些 wing 之间存在相同 room 名时，宫殿的知识图谱层还能把它们当作跨 wing 桥接（tunnel），形成"同一个问题多视角"的关联检索能力（可参考 the-palace.md 中关于跨 wing 连接的说明）。

原文档给出的唯一实践建议值得引用：如果你使用多个 specialist prompts 或 toolchain，请保持 agent 名字稳定，这样每个智能体才会持续写回同一个日记 wing，随时间积累出真正连贯的个人档案——名字一变，历史记忆就会变成"另一人"的。

相邻能力：Checkpoint 与 Hook 写入

日记并不孤立存在。仓库中还提供了三个与日记协同的入口：

mempalace_checkpoint（会话一键存档）：把"逐条check_duplicate→add_drawer→diary_write"压缩成单次 MCP 调用。它对每个 item 做语义去重、把非重复项存为 drawers，随后写一条日记。diary参数可传{ agent_name, entry, topic?, wing? }，其中 entry 同样要求 AAAK 格式；added_by的解析顺序为"显式值 > diary 的 agent_name >checkpoint"（mcp_server.py，工具说明见 mcp-tools.md）。
Hook 自动写日记：MCP 服务器会在会话结束等时机提示调用方call mempalace_diary_write to record what happened, what you learned, what matters（mcp_server.py）。日记写入被归为"修改性工具"（modifying tools），在服务端运行库版本与磁盘安装版本不一致时会按 JSON-RPC-32005拒绝，并建议重启 MCP 服务器（mcp-tools.md）。
wing参数打通项目空间：hooks 的日记写入落在wing_<project>这类项目级 wing，而diary_read在 wing 为空时跨全部 wing 返回，确保"hook 记录的 + agent 主动记录的"都能被同一位 agent 完整回读。

理解误区与边界

结合 agents.md 与源码，有几个边界需要澄清，避免过度推广：

当前日记不构成"多 Agent 状态机"或"Agent 间通信总线"——它只是一位 agent 面向自己的持久化记忆通道。需要跨 wing 关联时，走的是宫殿图谱层的 tunnel/room 桥接，而非日记本身的广播。
agent_name目前没有独立的注册、枚举或权限体系；工具语义上它更像一个命名空间标签。这与原文档"MemPalace does not ship an agent registry"的声明一致。
日记条目建议采用 AAAK 压缩格式以节省 token；而 AAAK 方言文档也提示，AAAK 是有损压缩、适合大量重复实体的规模化场景；日常短文本场景下，宫殿的主存储仍是原始逐字文本。写入时条目原样保留（documents），压缩格式本身作为内容进入向量库，语义搜索质量上限受 AAAK 影响——源码 TODO 亦注明未来版本应在 embedding 前展开 AAAK 以提升检索效果（mcp_server.py）。

MemPalace 专属 Agent 日记：用 MCP 工具为每个 AI 智能体建立跨会话持久记忆