> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/native-tools/tool-memory.md).

# 工具作用域记忆

面向安全关键指导和经验的持久化、工具作用域规则。

工具范围内的记忆层捕获 **可执行的指导** 关于代理应如何使用特定工具——与 [记忆工具](/openhuman/zh/gong-neng/native-tools/memory-tools.md) 的通用回忆以及与 `tool_effectiveness` 统计命名空间相分离。它是把“永远不要给 Sarah 发邮件”变成一条代理在后续每一轮都必须遵守的硬性约束的表层。

它实现了 [问题 #1400](https://github.com/tinyhumansai/openhuman/issues/1400) ——一个用于持久学习和高优先级规则的一等存储与检索系统。

## 它存储什么

每个工具都有自己的命名空间， **`tool-{tool_name}`**，与 `global`, `skill-{id}`以及仅用于统计的 `tool_effectiveness` 命名空间不同。在其中，每个条目都是一个 `ToolMemoryRule`:

| 字段                          | 用途                                                  |
| --------------------------- | --------------------------------------------------- |
| `id`                        | 每条规则的稳定 UUID。Upsert 会重放相同的 id。                      |
| `tool_name`                 | 该规则适用的工具（例如 `send_email`, `shell`).                 |
| `rule`                      | 代理必须遵循的自然语言指导。                                      |
| `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 规则驻留在 *系统提示词*中，推理后端的前缀缓存会在整个会话期间将其冻结。没有办法让 token 压缩悄悄丢掉一条 `critical` 规则。

## 捕获流水线

每一轮结束后都会触发两条自动捕获路径（通过 `ToolMemoryCaptureHook`):

1. **用户禁令** ——像 `never <verb> <noun>`, `don't <verb> ...`, `do not <verb> ...`，或 `stop <verb>ing ...` 这样的用户消息中的句子会被提升为匹配工具上的 **Critical** 规则。常见名词别名会映射 `“email”` 到名为 `send_email`, `“shell”` 的工具， `bash`/`exec`等；当没有别名匹配时，规则会落到该轮中第一个运行的工具上，这样它就会紧邻相关调用点。
2. **重复的工具失败** ——在单轮中失败两次或更多的工具会获得一条 **Normal**优先级的观察记录，并在行内概括失败类别，这样代理下次考虑该工具时就有上下文。

只要学习子系统开启，此钩子默认启用。可通过以下方式选择性禁用： `OPENHUMAN_LEARNING_TOOL_MEMORY_CAPTURE_ENABLED=0`.

## 在工具选择时检索

会话开始时，harness 会通过 `ToolMemoryStore::rules_for_prompt`预取所有 Critical 和 High 规则，并将它们渲染到 `## 工具范围规则` 块中，然后把该块固定进系统提示词。由于提示词在整个会话生命周期内都是冻结的，所以在每一轮的工具选择时以及任何实际工具执行之前，规则都是可见的。

较低优先级的指导不会占用提示词预算；代理会在需要时通过调用 `memory_recall` 针对 `tool-{name}` 命名空间。

## RPC 接口

在 `记忆` 命名空间下公开了六个方法：

| 方法                             | 用途                                            |
| ------------------------------ | --------------------------------------------- |
| `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 列表（供信封消费者使用）。                         |

JSON 载荷使用 snake\_case（`priority: "critical"`, `source: "user_explicit"`）。每个方法都通过与其余 memory RPC 相同的 `active_memory_client` 底层连线。

## 端到端安全案例

“永远不要给 Sarah 发邮件”这一路径被作为回归测试覆盖：

1. 用户说 *“永远不要给 <sarah@example.com> 的 Sarah 发邮件。”* 在一次调用了 `send_email`.
2. `ToolMemoryCaptureHook` 提取该禁令，映射 `email` 别名到 `send_email` 工具，并在 `tool-send_email/rule/{uuid}`.
3. 在下一个会话中， `prefetch_tool_memory_rules_blocking` 拉取所有 Critical 和 High 规则，而会话构建器会附加一个 `ToolMemoryRulesSection` 到系统提示词。
4. 代理会先看到 `### \`send\_email\``，后面跟着`- **\[critical]** Never email Sarah at <sarah@example.com>.\`，然后才会选择工具，并且该规则会在任何会话中期的 token 压缩中幸存下来。

覆盖范围和集成测试位于 `crates/openhuman-core/src/memory/tool_memory/`.

## 另请参阅

* [记忆工具](/openhuman/zh/gong-neng/native-tools/memory-tools.md) ——通用 `回忆`, `存储`, `遗忘`.
* [智能令牌压缩](/openhuman/zh/gong-neng/token-compression.md) ——系统提示词受到保护，免受什么影响。