> 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 发邮件”变成一条硬约束的表层，代理在后续每一轮都必须遵守。

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

## 它存储什么

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

| 字段                          | 目的                                                    |
| --------------------------- | ----------------------------------------------------- |
| `id`                        | 每条规则稳定的 UUID。Upsert 会复用同一个 id。                        |
| `tool_name`                 | 该规则适用的工具（例如 `send_email`, `shell`).                   |
| `rule`                      | 代理必须遵循的自然语言指导。                                        |
| `priority`                  | `critical`, `高`，或 `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`. | **是** ——系统提示词在每个会话中是冻结的，不会被会话中期的压缩器重写。 |
| `高`        | 相同的系统提示词块，排名低于 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 会通过以下接口预先获取每一条 Critical 和 High 规则： `ToolMemoryStore::rules_for_prompt`，将它们渲染进 `## 工具范围规则` 块中，并把该块固定到系统提示词里。由于该提示词在整个会话生命周期中是冻结的，所以这些规则会在每一轮的工具选择时以及任何实际工具执行之前可见。

较低优先级的指导不会占用提示词预算；代理可按需通过调用 `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]** 在选择任何工具之前就会看到“绝不要给 <sarah@example.com>.\` 的 Sarah 发邮件”，而且该规则不会在任何会话中期的 token 压缩中丢失。

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

## 另请参阅

* [记忆工具](/openhuman/zh/gong-neng/native-tools/memory-tools.md) ——通用 `回忆`, `存储`, `忘记`.
* [智能 Token 压缩](/openhuman/zh/gong-neng/token-compression.md) ——系统提示词所受到保护的对象。