> Source: https://clickhouse.github.io/loom/ko/reference/operations/working_memory/ (Markdown: https://clickhouse.github.io/loom/ko/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.*`(각자의 plane 값을 유지함)를 제외한 모든 연산에서는 설치의 org가 채워지고, [일부 연산](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)에서는 네임스페이스와 에이전트도 채워집니다. 자세한 내용은 [신원과 네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)를 참고하세요. [연산 인덱스](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` · role `writer` · write

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(identity 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. |
| `user_id` | `str` | `'-'` | 해당 행이 속한 최종 사용자. 없으면 `'-'`. |
| `session_id` | `str` | `'-'` | 해당 행이 속한 세션 또는 대화. 없으면 `'-'`. |
| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위). 없으면 `'-'`. |
| `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` | 필수 | op가 읽거나 쓰는 네임스페이스입니다. |
| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트입니다. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. |
| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자입니다. 없으면 `'-'`입니다. |
| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화입니다. 없으면 `'-'`입니다. |
| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위)입니다. 없으면 `'-'`입니다. |
| `block_key` | `str` | `'scratchpad'` | 삭제할 블록입니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `deleted` | `bool` | 해당 범위에 이 키의 유효한 블록이 없으면 False입니다. |
| `block_key` | `str` | 입력 `block_key`를 그대로 반환한 값입니다. |

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

## `working_memory.get`

키로 워킹 메모리 블록 하나를 가져옵니다.

`POST /v1/working_memory.get` · MCP `loom_working_memory_get` · 역할 `viewer` · 읽기 · MCP `all` 툴셋에는 포함되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. |
| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자. 없으면 `'-'`. |
| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화. 없으면 `'-'`. |
| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위). 없으면 `'-'`. |
| `block_key` | `str` | `'scratchpad'` | 호출자의 (agent, user, session, run) 범위 안에서 읽을 블록. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `found` | `bool` | 해당 범위에 이 키의 유효한 블록이 없으면 False이며, 이 경우 나머지 필드는 기본값입니다. |
| `block_key` | `str` | 블록 키를 그대로 반환한 값. |
| `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 또는 마크다운으로 렌더링합니다. context.pack에는 이미 이 섹션이 포함되어 있으며, 직접 렌더링은 주로 SDK나 커스텀 오케스트레이션 코드에서 사용합니다.

`POST /v1/working_memory.render` · MCP `loom_working_memory_render` · role `viewer` · read

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스입니다. |
| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트입니다. `'-'` 또는 `'*'`는 op가 허용하는 경우 모든 에이전트를 뜻합니다. |
| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자입니다. 없으면 `'-'`입니다. |
| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화입니다. 없으면 `'-'`입니다. |
| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위)입니다. 없으면 `'-'`입니다. |
| `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` | 필수 | 이 op가 읽거나 쓰는 네임스페이스입니다. |
| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트입니다. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. |
| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자입니다. 없으면 `'-'`입니다. |
| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화입니다. 없으면 `'-'`입니다. |
| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위)입니다. 없으면 `'-'`입니다. |
| `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` · role `writer` · 멱등

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. |
| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자. 없으면 `'-'`. |
| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화. 없으면 `'-'`. |
| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위). 없으면 `'-'`. |
| `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 -->
