hanafubuki-agent

记忆

记忆如何从过去的会话中提炼经验,如何启用、调整和重置,以及模型如何使用它。

记忆让 Agent 记住过去会话中学到的东西:项目的约定、你的偏好、踩过的坑。它在后台用模型读取已经结束的会话,提取值得记住的内容,再整合成一份摘要;之后的会话中,模型会看到这份摘要,并在需要时查阅细节。

记忆默认关闭。

启用

hanafubuki-agent config set memory.enabled true
hanafubuki-agent memory status
enabled: true
sessions read: 12
extracted memories: 9
running jobs: 0

会话是否贡献记忆的初始设置在创建时决定:只有当 memory.enabled 和 memory.generateMemories 都为 true 时才启用贡献。打开记忆不会自动让之前的会话参与。可以在记忆存储中 用 This session contributes 修改已有会话,但因外部内容被永久排除的会话不能重新启用。

在终端界面中,/memories 打开设置中心的 Memory 标签页,其中的 Memory 开启记忆。

记忆需要一个启用的默认 Provider。提取和整合默认使用模型策略中的模型,可以分别用 memory.extractionModel 和 memory.consolidationModel 指定其他模型(例如更便宜的模型)。

它如何工作

  1. 提取:会话空闲超过 memory.minimumIdleHours(默认 6 小时)后,Agent 用模型读取它,提取值得记住的内容。每一轮最多处理 memory.maxSessionsPerPass 个会话(默认 2 个),只考虑最近 memory.maxSourceAgeDays 天内的会话(默认 10 天)。
  2. 整合:把提取的结果(最多 memory.maxStage1Outputs 条)整合成一份记忆文件和一份摘要。
  3. 过期:memory.maxUnusedDays 天(默认 30 天)没有被使用过的提取结果会过期。

这些工作在回合结束后、Agent 启动时和设置改变时运行,需要额外的模型请求。失败的任务会退避重试,间隔从 30 秒逐渐增加到一天;最近的错误显示在 memory status 中。

模型如何使用记忆

  • 每次请求模型时,记忆的摘要都会作为背景信息提供给模型。它只是参考,不是指令。
  • 模型可以用 list_agent_memories、search_agent_memories 和 read_agent_memory 查阅更多细节,并说明它用了哪些记忆。
  • 模型也可以用 append_agent_memory_note 记下一条笔记。

记忆不授予任何权限:它只是上下文,命令和文件修改仍然按权限模式审批。

设置

键默认值作用
memory.enabledfalse启用记忆
memory.useMemoriestrue模型可以使用已有的记忆
memory.generateMemoriestrue从会话中提取新的记忆
memory.excludeExternalContextfalse会话使用过网页或 MCP 工具的结果后,不再从中提取记忆
memory.extractionModel未设置提取使用的模型
memory.consolidationModel未设置整合使用的模型
memory.maxSourceAgeDays10只读取最近这么多天内的会话
memory.minimumIdleHours6会话空闲这么久才提取
memory.maxSessionsPerPass2每一轮最多提取的会话数
memory.maxStage1Outputs256整合时最多使用的提取结果数
memory.maxUnusedDays30提取结果多久没被使用就过期

取值范围见配置参考。只想使用已有的记忆、不再提取新的,把 memory.generateMemories 设为 false;想暂时不让模型看到记忆,把 memory.useMemories 设为 false。

外部内容

网页和 MCP 工具返回的内容未经核实,可能包含错误或刻意构造的指令。开启 memory.excludeExternalContext 后,会话一旦使用了这类结果,就永久不再参与记忆。

查看和重置

hanafubuki-agent memory status
hanafubuki-agent memory reset
  • memory status:是否启用、读过的会话数、提取的记忆数、运行中的任务数和最近的错误。
  • memory reset:删除提取的结果和整合后的记忆,把所有会话标记为未提取。之后符合条件的会话会被重新提取;如果不想这样,先关闭记忆再重置。

在终端界面中,/memories 打开设置中心的 Memory 标签页:记忆的设置(Memory、Use memories、Generate memories 等),每项立即保存,以及 Memory store 页面,它显示状态(读过的会话、记忆数、最近一轮和最近的错误),并提供:

  • This session contributes:当前显示的会话是否参与记忆(还没有会话时不可修改;开启 memory.excludeExternalContext 后用过外部内容的会话不再参与);
  • Reset memory…:确认后执行 memory reset。

记忆关闭时页面会说明;标签页中的 Memory 开启记忆。

记忆保存在数据目录的 memory/ 中。关闭 memory 插件(disabledPlugins)后,模型看不到记忆,也没有记忆工具。

本页目录