# 工具作用域记忆

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

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

## 它存储什么

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

| 字段                          | 用途                                                    |
| --------------------------- | ----------------------------------------------------- |
| `id`                        | 每条规则稳定的 UUID。重复写入会复用相同的 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}`）按设计存放在 *不同的* 命名空间中 - 一个记录“发生了什么”，另一个记录“对此该怎么做”。

## 优先级别

| Priority   | 所在位置                                               | 抗压缩？                                          |
| ---------- | -------------------------------------------------- | --------------------------------------------- |
| `critical` | 固定到 **system prompt** 通过 `ToolMemoryRulesSection`. | **是** - system prompt 按会话冻结，并且永远不会被会话中期压缩器重写。 |
| `high`     | 同一个 system prompt 区块，排名低于 critical。                | **是** - 同样的机制。                                |
| `normal`   | 存储在命名空间中；按需通过 `memory_recall`.                     | 否 - 可像任何其他命名空间记忆一样被压缩。                        |

抗压缩属性是结构性的：critical 和 high 规则位于 *system prompt*中，而推理后端的前缀缓存会在整个会话期间保持其冻结。不存在令牌压缩悄悄丢弃一个 `critical` rule

## 捕获流水线

每一轮结束后会触发两条自动捕获路径（通过 `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 规则，并将其渲染到 `## 工具作用域规则` 区块中，然后将该区块固定到 system prompt。由于 prompt 在整个会话生命周期内都被冻结，这些规则会在每一轮的工具选择时以及任何实际工具执行之前可见。

更低优先级的指导不会占用 prompt 预算；代理在需要时会通过调用 `memory_recall` 针对 `tool-{name}` 命名空间来获取它。

## RPC 表面

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

| 方法                             | 用途                                          |
| ------------------------------ | ------------------------------------------- |
| `memory.tool_rule_put`         | 写入或更新一条规则。对安全关键条目使用 `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 列表（供 envelope 消费者使用）。               |

JSON 负载使用 snake\_case（`priority: "critical"`, `source: "user_explicit"`）。所有方法都通过与其余内存 RPC 相同的 `active_memory_client` 管线。

## 端到端安全案例

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

1. 用户说 *“永远不要给 <sarah@example.com> 的 Sarah 发邮件。”* 在一个调用了 `send_email`.
2. `ToolMemoryCaptureHook` 的轮次中 `email` 别名映射到 `send_email` 工具，并将一条 Critical 规则写入 `tool-send_email/rule/{uuid}`.
3. 在下一次会话中， `prefetch_tool_memory_rules_blocking` 拉取所有 Critical 和 High 规则，而会话构建器会追加一个 `ToolMemoryRulesSection` 到 system prompt。
4. 代理会看到 `### \\`send\_email\``后跟`- **\[critical]** 在选择任何工具之前就会看到“永远不要给 <sarah@example.com> 的 Sarah 发邮件。”，并且该规则会在会话中途的任何令牌压缩中幸存下来。

覆盖和集成测试位于 `src/openhuman/memory/tool_memory/`.

## 另见

* [记忆工具](/openhuman/zh/gong-neng/native-tools/memory-tools.md) - 通用的 `回忆`, `存储`, `遗忘`.
* [智能 Token 压缩](/openhuman/zh/gong-neng/token-compression.md) - system prompt 受到保护以抵御什么。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/native-tools/tool-memory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.