> Source: https://clickhouse.github.io/loom/zh-CN/reference/operations/working_memory/ (Markdown: https://clickhouse.github.io/loom/zh-CN/reference/operations/working_memory.md)

<!-- i18n: source=docs/reference/operations/working_memory.md blob=1c42739885ece1caff5a674519dc56e751fc9fcf model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://clickhouse.github.io/loom/reference/operations/working_memory/)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/working_memory/), which is authoritative.

<a id="working_memory-operations"></a>

# `working_memory` 操作

每个 `working_memory.*` 操作接受和返回的确切字段。

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

每个操作在 HTTP 上都是 `POST /v1/<op>`，在 MCP 上是工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）在传输层能够提供时，会根据令牌和 MCP 会话自动填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们保留各自所属平面的 org）之外，所有操作的 org 都取该安装的 org，而[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)的命名空间和 agent 也会如此填充；参见[身份与命名空间](https://clickhouse.github.io/loom/zh-CN/concepts/identities-and-namespaces/)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了 role、kind 以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并在 `ignored_args` 中列出。

<!-- prettier-ignore-start -->

<a id="working_memoryappend"></a>

## `working_memory.append`

向工作记忆块追加文本，块不存在时会创建。

`POST /v1/working_memory.append` · MCP `loom_working_memory_append` · 角色 `writer` · 写入

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 该调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `block_key` | `str` | `'scratchpad'` | 要追加内容的块；块不存在时会按默认大小上限创建。 |
| `addition` | `str` | 必填 | 添加到块末尾的文本。 |
| `separator` | `str` | `'\n'` | 放在现有文本与 `addition` 之间；块为新建时不使用。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `block_key` | `str` | 被写入的块。 |
| `version` | `int` | 本次写入所创建的行的版本（纳秒时间戳）。 |
| `char_limit` | `int` | 写入后该块的大小上限，以字符计。 |
| `value_length` | `int` | 写入后该块内容的长度，以字符计。 |
| `fill_ratio` | `float` | `value_length / char_limit`，保留三位小数；会超过 1.0 的写入将被拒绝。 |

<a id="working_memorydelete"></a>

## `working_memory.delete`

删除一个工作记忆块。

`POST /v1/working_memory.delete` · MCP `loom_working_memory_delete` · 角色 `writer` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许的情况下匹配任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 本次调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `block_key` | `str` | `'scratchpad'` | 要删除的块。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `deleted` | `bool` | 当该范围内此键下没有有效块时为 False。 |
| `block_key` | `str` | 原样返回输入的 `block_key`。 |

<a id="working_memoryget"></a>

## `working_memory.get`

按 key 获取一个工作记忆块。

`POST /v1/working_memory.get` · MCP `loom_working_memory_get` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许的情况下匹配任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 该调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `block_key` | `str` | `'scratchpad'` | 要读取的块，限定在调用方的 (agent, user, session, run) 范围内。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `found` | `bool` | 当该范围内没有此 key 对应的有效块时为 False，其余字段为默认值。 |
| `block_key` | `str` | 块的 key 的回显。 |
| `content` | `str` | 块的文本；未找到时为空。 |
| `char_limit` | `int` | 块的字符数上限；超出上限的写入会被拒绝并返回 422。 |
| `version` | `int` | 块当前行的版本（纳秒时间戳）；未找到时为 0。 |
| `updated_at` | `datetime \| None` | 块最后一次写入的时间；未找到时为 None。 |
| `fill_ratio` | `float` | len(content) / char_limit。 |

<a id="working_memoryrender"></a>

## `working_memory.render`

将工作记忆块渲染为 XML 或 markdown。context.pack 已包含此部分；直接调用 render 主要用于 SDK 或自定义编排代码。

`POST /v1/working_memory.render` · MCP `loom_working_memory_render` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许时匹配任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 本次调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `block_keys` | `list[str]` | *(计算得出)* | 仅渲染这些块（最多 20 个）；为空表示范围内所有有效的块。 |
| `format` | `Literal['xml', 'markdown']` | `'xml'` | `xml` 将每个块包裹在 `<working-memory block=...>` 标签中；`markdown` 将其放在 `## <block_key>` 标题下。 |
| `limit` | `int` | `20` | 最多渲染这么多个块，按 `block_key` 排序（1-100）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rendered` | `str` | 以所选 `format` 渲染的所有块组成的一段文本；范围内没有块时为空。 |
| `blocks` | `list[WorkingMemoryBlock]` | 已渲染的块及其大小上限和版本，按 `block_key` 排序。 |
| `block_count` | `int` | 渲染的块数量。 |
| `total_chars` | `int` | 各块内容长度之和，以字符计。 |

<a id="working_memoryreplace"></a>

## `working_memory.replace`

替换工作记忆块中的指定文本。

`POST /v1/working_memory.replace` · MCP `loom_working_memory_replace` · 角色 `writer` · 幂等 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 该调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `block_key` | `str` | `'scratchpad'` | 要编辑的块；块不存在时返回 404。 |
| `old` | `str` | 必填 | 要查找的文本；所有出现的位置都会被替换，文本不存在时返回 422。 |
| `new` | `str` | `''` | 替换文本；为空时删除 `old` 的所有出现位置。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `block_key` | `str` | 被写入的块。 |
| `version` | `int` | 本次写入所创建行的版本（纳秒时间戳）。 |
| `char_limit` | `int` | 写入后该块的字符数上限。 |
| `value_length` | `int` | 写入后该块内容的长度，以字符计。 |
| `fill_ratio` | `float` | `value_length / char_limit`，保留三位小数；超过 1.0 的写入会被拒绝。 |

<a id="working_memoryset"></a>

## `working_memory.set`

覆盖写入一个工作记忆块。

`POST /v1/working_memory.set` · MCP `loom_working_memory_set` · 角色 `writer` · 幂等

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（标识元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 该调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `block_key` | `str` | `'scratchpad'` | 要写入的块，位于调用方的（agent、user、session、run）范围内。 |
| `content` | `str` | `''` | 该块的全部新文本，替换其原有内容；为空则存储一个空块。 |
| `char_limit` | `int` | `4096` | 该块的字符数上限；`content` 超过该上限时会被拒绝，并返回 422。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `block_key` | `str` | 已写入的块。 |
| `version` | `int` | 本次写入所创建行的版本（纳秒时间戳）。 |
| `char_limit` | `int` | 写入后该块的字符数上限。 |
| `value_length` | `int` | 写入后该块内容的长度，以字符计。 |
| `fill_ratio` | `float` | `value_length / char_limit`，保留三位小数；若写入会超过 1.0，则会被拒绝。 |

<!-- prettier-ignore-end -->
