工具作用域记忆

工具作用域记忆层捕获关于 agent 如何使用特定工具的 可操作指导——与通用 记忆工具 的记忆检索不同，也与 tool_effectiveness 统计命名空间不同。它是将"永不给 Sarah 发邮件"转变为 agent 在每个后续轮次都必须遵守的硬约束的表面。

存储内容

每个工具都有自己的命名空间 tool-{tool_name}，与 global、skill-{id} 和仅统计的 tool_effectiveness 命名空间不同。其中每个条目是一个 ToolMemoryRule：

字段	用途
id	稳定的每个规则的 UUID。Upserts 重放相同的 id。
tool_name	规则适用的工具（如 send_email、shell）
rule	agent 必须遵循的自然语言指导
priority	critical、high 或 normal。驱动检索 + 压缩。
source	user_explicit、post_turn 或 programmatic——来源
tags	自由形式的标签（safety、permission 等）
created_at / updated_at	RFC3339 时间戳

统计（tool_effectiveness/tool/{name}）和规则（tool-{name}/rule/{id}）按设计生活在不同的命名空间中——一个追踪"发生了什么"，另一个追踪"要做什么"。

优先级级别

优先级	存储位置	抗压缩？
critical	通过 ToolMemoryRulesSection 固定到 系统提示	是 - 系统提示在会话期间冻结，从不被中途压缩器重写
high	相同的系统提示块，排在 critical 之后	是 - 相同机制
normal	存储在命名空间；通过 memory_recall 按需检索	否 - 与任何其他命名空间记忆一样符合压缩条件

抗压缩属性是结构性的：critical 和 high 规则搭乘在系统提示上，推理后端的 prefix cache 为整个会话保持冻结。没有办法让 token 压缩静默删除 critical 规则。

捕获管道

两个自动捕获路径在每个轮次后触发（通过 ToolMemoryCaptureHook）：

1. 用户法令 - 用户消息中类似 never <verb> <noun>、don't <verb> ...、do not <verb> ... 或 stop <verb>ing ... 的句子被提升为匹配工具上的 Critical 规则
2. 重复工具失败 - 在单个轮次中失败两次或更多的工具获得 Normal 优先级观察，总结内联以便 agent 下次考虑该工具时有上下文

工具选择时的检索

在会话开始时，harness 通过 ToolMemoryStore::rules_for_prompt 预取每个 Critical 和 High 规则，将它们渲染到 ## Tool-scoped rules 块，并将其固定到系统提示。因为提示在会话生命周期内被冻结，规则在每次工具选择时和任何实际工具执行之前都可见。

较低优先级的指导保持在提示预算之外；agent 通过调用 memory_recall 针对 tool-{name} 命名空间按需获取。

RPC 接口

六个方法暴露在 memory 命名空间下：

方法	用途
memory.tool_rule_put	Upsert 规则。使用 priority='critical' 用于安全关键条目
memory.tool_rule_get	通过 (tool_name, id) 获取规则
memory.tool_rule_list	列出工具的所有规则，按优先级 + 新鲜度排序
memory.tool_rule_delete	删除规则
memory.tool_rules_for_prompt	返回渲染的 Markdown 块 + 结构化快照
memory.tool_rules_json	原始 JSON 列表

端到端安全案例

"永不给 Sarah 发邮件"路径作为回归测试覆盖：

1. 用户在说出一个调用了 send_email 的轮次中说 "永不给 Sarah at sarah@example.com 发邮件"
2. ToolMemoryCaptureHook 提取法令，将 email 别名映射到 send_email 工具，并在 tool-send_email/rule/{uuid} 下写入 Critical 规则
3. 在下一个会话中，prefetch_tool_memory_rules_blocking 拉取每个 Critical 和 High 规则，会话构建器将 ToolMemoryRulesSection 附加到系统提示
4. agent 在选择工具之前看到 ### \send_email`后跟- [critical] 永不给 Sarah at sarah@example.com 发邮件。`，该规则在任何中途 token 压缩中存活

下一步

• 记忆工具 - 通用 recall、store、forget
• Token 压缩 - 系统提示受到什么保护