PiClaw长期记忆的秘密:Dream记忆与AutoDream夜间维护机制深度解析
PiClaw长期记忆的秘密:Dream记忆与AutoDream夜间维护机制深度解析
PiClaw 是一款 Web 形态的 AI 编程智能体(coding agent),而它最被低估的"杀手锏"是长期记忆系统。PiClaw 通过两个核心机制让智能体"记住"你的项目:手动触发的 Dream 记忆维护,以及每晚自动执行的 AutoDream 夜间维护。本文将带你从零看懂这套机制——它如何让 AI 助手跨会话保持记忆一致、自动备份、自动清理陈旧信息,新手也能轻松上手。
先来看看 PiClaw 智能体在 Web 界面中工作的实际效果:
为什么 AI 助手需要"长期记忆"?
大多数 AI 对话工具都有一个通病:关掉会话就失忆。你上周告诉它"项目用 pnpm 而不是 npm",这周它又给你推荐 npm 了。
PiClaw 的解法是:把工作区的记忆当作可维护的 Markdown 文件层,由模型在专门的维护周期里"整理大脑"。这个维护周期就叫 Dream(梦境),灵感来自人类睡眠时大脑整理白天的记忆——只是 PiClaw 的智能体是凌晨自动"做梦"的。🌙
两种触发方式:Dream 与 AutoDream
PiClaw 提供两条路径来维护记忆,行为模型完全一致,只是触发时机不同:
| 机制 | 触发方式 | 默认时间窗口 | 是否打扰用户 |
|---|---|---|---|
| Dream | 手动命令 /dream、/dream 7、/dream 30 |
最近 7 天 | 运行结束后回传摘要 |
| AutoDream | 内置定时任务,默认 cron 0 1 * * *(运行时区 01:00) |
最近 2 天 | 静默运行,不发消息 |
几个值得新手注意的细节:
- 完全隔离:两者都运行在专用的临时
dream:频道上,属于"带外"(out-of-band)智能体回合,结束后频道即被清理。也就是说,记忆维护过程不会污染你的正常聊天记录。 - 不阻塞聊天:Dream 任务被放入独立的
dream:<chatJid>队列泳道,你深夜 01:00 在聊天,也不会被夜间维护卡住。 - 防无效运行:AutoDream 有"门控"逻辑——如果自上次整理以来没有任何新会话,且没有遗留的未完成笔记,就直接跳过,不浪费 token。
想看更多配置项长什么样,PiClaw 的 Web 设置界面长这样(Scheduled Tasks、Environment 等分组里可以找到相关配置):
Dream 的四阶段流程:智能体如何"做梦"
Dream 是模型驱动的(model-driven),不是僵死的规则过滤器。智能体按四个阶段工作,就像人睡觉时的记忆整理流程:
- Orient(定向) —— 加载启动记忆索引,检查现有的每日笔记与记忆文件状态,搞清楚"我上次整理到哪了"。
- Signal(信号) —— 只收集必要的确认证据。它先检查已有的 daily/memory 文件,再检查看起来"漂移"或自相矛盾的记忆,最后才做窄范围的对话记录检索——绝不把全部历史扫一遍。
- Consolidate(整合) —— 合并、归一化日期(把"昨天""今天"换算成绝对日期)、在源头修正矛盾信息。
- Prune and Index(修剪与索引) —— 删除陈旧指针,为新增的重要记忆添加引用,保持紧凑索引干净。
完整提示词可以直接阅读 runtime/src/agent-memory/dream-prompt.ts,它明确告诉智能体:"你是判断相关性的人,不要用固定长度启发式"。
记忆文件长什么样:两层结构
PiClaw 把记忆分成人类可读层和智能体持久层:
| 文件 | 角色 |
|---|---|
notes/daily/*.md |
人类可读的"每日叙事"摘要 |
notes/memory/MEMORY.md |
紧凑的启动索引(一行一条目,越小越好) |
notes/memory/current-state.md |
近期 Dream 状态快照 |
notes/memory/recent-context.md |
给智能体快速定向的摘要 |
notes/memory/user.md |
持久的用户偏好 |
notes/memory/feedback.md |
纠正与引导线索 |
notes/memory/project.md |
进行中的工作与成果 |
notes/memory/reference.md |
笔记索引与外部指针 |
notes/memory/days/*.md |
可选的稀疏"情景记忆",只在某天有值得长期记住的信号时才创建 |
会话启动时,PiClaw 只先加载紧凑的索引层(MEMORY.md 等),需要时才打开深层文件——这是控制上下文开销的关键设计。各文件的用途说明见 skel/notes/memory/README.md。
⚠️ 重要边界:Dream 被明确禁止修改项目代码、测试或无关配置,工具访问也被刻意收窄为
read/edit/write/grep等少数只读为主的能力。见 runtime/src/dream.ts。
自动备份与故障恢复:记忆不怕丢
这是新手最容易忽略、却最让人安心的部分:
- 每次 Dream 前自动打包:运行时先把
notes/daily/和notes/memory/压缩成.zip备份(默认保留最近 10 份),然后才让模型动手改文件。 - 状态标记文件:
notes/memory/.dream-state记录version / initialized / recovery三行状态。如果派生记忆文件丢失,运行时能区分"全新工作区"和"老工作区丢文件"——前者会静默排队一次模型引导,后者确定性重建三个派生文件,不发起任何模型请求。 - 恢复不了也不慌:若证据不足以完整恢复,标记为
backfill_required,等待下一次 AutoDream 或手动/dream完成有界的回填,期间反复重启不会重复空跑。
详细规范见 runtime/docs/dream-memory.md 的"Startup bootstrap and state-loss recovery"一节。
维护完成后:记忆立即可搜索
Dream 结束时,运行时会自动刷新工作区 FTS 全文索引,意味着刚更新的记忆文件可以立刻被 search_workspace 工具检索到,无需任何手动操作。默认索引根是 notes 和 .pi/skills,可通过配置自定义。
如何开始使用:3 步上手
第 1 步:什么都不用做。AutoDream 是内置定时任务(任务 ID builtin-dream-midnight),默认每天凌晨 01:00(运行时区)自动运行,默认整理最近 2 天的会话。
第 2 步:想立即整理?发一条命令:
/dream
/dream 7
/dream 30
运行结束后,PiClaw 会把一份简短摘要发回你的聊天窗口,包括四阶段各做了什么、是否有未解决的日期积压。
第 3 步:按需调参。主要参数(均可在配置中设置):
| 参数 | 默认值 | 说明 |
|---|---|---|
dream.cron |
0 1 * * * |
AutoDream 的 cron 表达式 |
dream.backupKeep |
10 | 保留多少份 Dream 前备份 |
dream.model |
空(跟随当前) | 指定 Dream 使用的模型 |
dream.agentTimeoutMs |
360000 | Dream 智能体回合超时 |
定义见 runtime/src/core/config-runtime.ts。
总结:这套机制好在哪?
- 跨会话不失忆:你的偏好、纠正、项目进展会沉淀进持久记忆文件,新会话自动加载索引。
- 静默且不打扰:夜间自动运行,临时频道即用即删,聊天历史干干净净。
- 安全兜底:改前必备份、丢失可重建、失败可回填,三层保险。
- 成本可控:窄范围检索 + 防空跑门控 + 紧凑索引预算,不会无谓消耗 token。
对于想要一份"越用越懂你"的编程智能体来说,PiClaw 的 Dream/AutoDream 机制给出了一个相当优雅的答案:让 AI 自己"睡觉整理记忆",而你只需要安心使用。🧠
延伸阅读:docs/dream-memory.md 提供了该机制的用户向完整说明,包括触发模式、内存文件清单与搜索索引行为。

