fable-memory

Fable Memory

只保留值得跨会话留存的事实，并确保其来源可追溯、矛盾处理机制足够健全，避免旧记忆悄然变成新的错误来源。

使命

记忆不是聊天记录。它应减少重复探索，同时避免把临时猜测固化成永久指令。

持久记录需要注明适用范围、来源、置信度、时效性，并能在用户或仓库发生变化时被取代。

适用情形

• 用户明确要求记住一项持久偏好或约束；
• 稳定的项目约定或架构决策会实质性影响后续工作；
• 跨会话的连续性反复依赖同一事实；
• 需要更正、取代或检索先前的持久事实。

不适用情形

• 信息属于临时执行状态（.fable/state、台账、交接记录）；
• 这是一次性的对话细节，不太可能影响未来决策；
• 这是尚不够稳定、不适合持久保存的猜测或推断；
• 信息包含密码、令牌、私钥、会话 Cookie 或其他秘密。

记忆分类

类型	示例	持久性规则
用户偏好	偏好的包管理器	明确且稳定时持久保存
项目约束	运行时 Bun >=1.3	绑定到项目或来源
架构决策	使用 outbox 处理事件	保存理由和取代路径
重复出现的工作流规则	发布前验证包能否全新安装	若为项目特有且持久，则保存
外部事实	API 行为或版本	通常在使用时引用或调查；避免作为永恒事实存储
临时状态	当前失败的测试	记入交接记录或状态，不记入记忆
敏感凭据	API 令牌	绝不写入记忆

协议

阶段 1 — 判断是否值得记忆

询问：

• 这在其他会话中可能仍然重要吗？
• 这是否稳定、明确，或有来源佐证？
• 是否有更具体的现有记录可供更新？
• 持久保存是否会带来隐私或安全风险？

如果不具持久性，只保留在当前上下文或交接记录中。

阶段 2 — 规范化事实

将一项连贯的决策或事实保存为：

• 标准表述；
• 适用范围（用户／项目／仓库／子系统）；
• 类型；
• 来源或出处；
• 置信度／状态；
• 创建／更新时间戳（如受支持）；
• 相关时标注取代／被取代关系。

阶段 3 — 写入前检查冲突

搜索主题相同的现有记录。比较：

• 完全一致 → 更新来源和时效性，而非重复记录；
• 范围更窄／更广 → 仅当适用范围确实不同时才保留两条记录；
• 相互矛盾 → 不要保留两条同时生效的事实；应解决矛盾或明确标记冲突。

阶段 4 — 原子写入并建立索引

更新一条规范事实记录，并同步索引／目录。保留无关记录。

阶段 5 — 验证检索后的含义

像未来的 Agent 那样读回记录。确保它没有过度概括：

• use Bun in get-fable 不等于 user always uses Bun everywhere；
• API v4 did X in Aug 2026 不等于永久有效的 API 保证。

阶段 6 — 检索时审慎应用记忆

当记忆中的事实会影响当前工作时：

• 确认适用范围是否匹配；
• 优先采用用户或仓库的当前证据，而非旧记忆；
• 重新验证有时效性的外部事实；
• 在适用情况下，将明确的新指令视为取代旧偏好。

决策规则

• 用户当前的明确陈述优先于已存储的偏好。
• 仓库／配置／源代码证据优先于与之矛盾的仓库状态记忆。
• 对时效性较强的外部事实，应重新调查，而不是无限期地予以信任。
• 记忆可以是历史信息，但不再保持生效；历史背景重要时，应标记为已取代，而不是删除。
• 不要根据单个项目选择推断出广泛的个人偏好。
• 即使用户要求“记住令牌”，也绝不要存储凭据；应改为建议使用安全的凭据管理方式。
• 每条记录只包含一项事实是一条可维护性规则，但可以附上相关理由／来源。

不变量

• 机密信息不得进入持久记忆。
• 活跃记忆中不得存在尚未解决且未明确标记冲突状态的矛盾事实。
• 明确限定范围，避免意外泛化。
• 保留重要约束／决策的来源信息。
• 当前证据／指令可以取代记忆。
• 索引与底层记录保持一致。

失败分类

重复记忆

同一事实以略有差异的措辞出现两次。合并／更新为规范记录。

范围泄漏

将特定项目的选择当作全局用户偏好。缩小其范围。

过时记忆

仓库／用户／外部现实发生了变化。使用前应将其标记为已取代或重新验证。

相互矛盾的活跃事实

两条记录给出了不兼容的活跃指导。根据当前来源／用户证据解决冲突。

将推断固化为事实

Agent 将假设存储为持久事实。应降低其可信程度／移除，并要求提供证据。

机密信息持久化

记忆中出现敏感值。移除暴露内容，并酌情处理凭据轮换／安全问题。

反模式

• “以防万一”而保存每段对话的所有细节；
• 将临时错误／当前待办事项存储为持久偏好；
• 将 in this repo 扩大为 always；
• 持久保存没有过期时间／来源信息的当前 API／版本声明；
• 不更新存在冲突的文件，反而新建事实文件；
• 因为未来自动化可能会用到令牌而将其存储；
• 将记忆视为比当前仓库证据更权威的信息；
• 当取代背景很重要时，悄悄删除历史决策。

记忆记录

Subject/fact:
Scope:
Type:
Status: active | superseded | conflicted
Source/provenance:
Confidence:
Rationale/context:
Supersedes / superseded by:
Freshness/revalidation note:

完成标准

满足以下条件时，记忆工作即告完成：

• 事实确实持久且范围限定得当；
• 已检查重复／冲突；
• 记录包含足够的来源信息，以便日后评估；
• 索引已同步；
• 已排除敏感／临时数据；
• 未来的 Agent 能够检索并应用该事实，同时避免过度泛化。

渐进式资源

• 深入指南：references/durable-fact-lifecycle.md
• 现有协议：references/memory-management-protocol.md
• 模板：templates/memory-fact.template.md
• 示例：examples/recording-user-preference.md