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

# Operações de `context`

<!-- i18n: source=docs/reference/operations/context.md blob=093091d1e021fa46a119227148999d3ff22b0ac2 model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em inglês](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/context.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/context.md), which is authoritative.


Os campos exatos que cada operação `context.*` recebe e retorna.

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

Toda op é `POST /v1/<op>` via HTTP e a ferramenta MCP `loom_<op>`. Os campos de identidade (`org`, `namespace`, `agent`, `user_id`, `session_id`) são preenchidos a partir do token e da sessão MCP quando o transporte consegue fazer isso; em uma chamada HTTP sem token em um servidor de usuário único, é preenchida a org da instalação em todas as ops, exceto `code.*` e `tracker.*` (que mantêm a org do seu plano), e, em [algumas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request), também o namespace e o agente; veja [identidades e namespaces](/pt-BR/concepts/identities-and-namespaces). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica role, kind e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e listados em `ignored_args`.

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

<a id="contextfetch"></a>

## `context.fetch`

Lê de volta um resultado armazenado por chave: uma fatia de caracteres (offset/limit) ou apenas as linhas que correspondem a uma regex (pattern, com context_lines).

`POST /v1/context.fetch` · MCP `loom_context_fetch` · papel `viewer` · leitura · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | obrigatório | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permitir. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo da tarefa) à qual a chamada pertence; `'-'` para nenhuma. |
| `blob_key` | `str` | obrigatório | A chave que `context.offload` retornou. |
| `offset` | `int` | `0` | Deslocamento de caracteres em que a fatia começa; com `pattern`, quantas correspondências ignorar. |
| `limit` | `int` | `4000` | No máximo esta quantidade de caracteres de conteúdo por chamada (1-64000). |
| `pattern` | `str` | `''` | Regex (sintaxe RE2, sem distinção entre maiúsculas e minúsculas; sem backreferences ou lookaround). |
| `context_lines` | `int` | `0` | Com `pattern`, linhas de contexto exibidas ao redor de cada correspondência (0-10); as linhas de contexto são numeradas como `lineno-` e as correspondências como `lineno:`. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `found` | `bool` | False quando nenhum blob ativo e não expirado tem esta chave no namespace. |
| `blob_key` | `str` | Eco do `blob_key` de entrada. |
| `content` | `str` | A fatia de caracteres ou, com `pattern`, as linhas correspondentes no formato `lineno: text`. |
| `content_type` | `str` | Tipo de mídia armazenado com o blob. |
| `summary` | `str` | O resumo armazenado com o blob. |
| `total_chars` | `int` | Tamanho de todo o conteúdo armazenado, em caracteres. |
| `total_lines` | `int` | Número de linhas de todo o conteúdo armazenado. |
| `offset` | `int` | Eco do `offset` de entrada. |
| `next_offset` | `int` | -1 quando a fatia (ou a lista de correspondências) se esgotou. |
| `matched_lines` | `int` | Com `pattern`, quantas linhas de todo o conteúdo correspondem; 0 caso contrário. |
| `expires_at` | `datetime \| None` | Quando o blob deixa de poder ser lido; None quando não encontrado. |

<a id="contextoffload"></a>

## `context.offload`

Estaciona um resultado grande de ferramenta (log, página, diff, saída de consulta) fora do contexto do modelo.

`POST /v1/context.offload` · MCP `loom_context_offload` · role `writer` · idempotente · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | obrigatório | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente quando a op permite. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo da tarefa) a que a chamada pertence; `'-'` para nenhuma. |
| `content` | `str` | obrigatório | O texto a estacionar; acima de `LOOM_CONTEXT_OFFLOAD_MAX_BYTES` (bytes UTF-8) resulta em 413. |
| `blob_key` | `str` | `''` | Vazio = endereçado por conteúdo (`blob/<sha256 prefix>`): estacionar a mesma saída duas vezes gera a mesma chave e uma única linha armazenada. |
| `content_type` | `str` | `'text/plain'` | Tipo de mídia armazenado com o conteúdo e retornado por `context.fetch`. |
| `summary` | `str` | `''` | Resumo de uma linha fornecido pelo chamador (o nome da ferramenta e o que ela retornou). |
| `ttl_seconds` | `int` | `604800` | Por quanto tempo o blob continua disponível para busca, em segundos (de 1 minuto a 90 dias). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `blob_key` | `str` | A chave para buscar o conteúdo: a informada ou `blob/<sha256 prefix>`. |
| `content_bytes` | `int` | Tamanho do conteúdo armazenado em bytes UTF-8. |
| `content_chars` | `int` | Tamanho do conteúdo armazenado em caracteres. |
| `sha256` | `str` | Digest SHA-256 em hexadecimal do conteúdo. |
| `summary` | `str` | O resumo armazenado com o blob: o informado ou os primeiros 200 caracteres do conteúdo. |
| `expires_at` | `datetime` | Quando o blob deixa de estar disponível para busca. |
| `pointer` | `str` | Pronto para substituir o conteúdo na transcrição. |

<a id="contextpack"></a>

## `context.pack`

As memórias, decisões e procedimentos de uma tarefa: chame-o primeiro em cada tarefa, a menos que um hook do Loom já tenha colocado o contexto do Loom nesta sessão.

`POST /v1/context.pack` · MCP `loom_context_pack` · role `viewer` · leitura

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | obrigatório | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permitir. |
| `user_id` | `str` | `'-'` | O usuário para o qual o pack lê; "-" lê todos os usuários nas seções de memórias, perfil, procedimentos e execuções, e as linhas registradas sem usuário nas seções de stack e de memória de trabalho. |
| `session_id` | `str` | `'-'` | A sessão para a qual o pack lê; "-" lê todas as sessões na seção de memórias, e as linhas registradas sem sessão nas seções de stack e de memória de trabalho. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo da tarefa) à qual a chamada pertence; `'-'` para nenhuma. |
| `query` | `str` | `''` | Tarefa/pergunta opcional usada para selecionar memórias e documentos relevantes. |
| `situation` | `str` | `''` | Descrição opcional da situação usada para encontrar procedimentos correspondentes. |
| `procedure_explore_rate` | `float \| None` | `None` | Taxa de exploração da seção de procedimentos; None = 0 (nunca). |
| `token_budget` | `int` | `2000` | Limite de tamanho do pack renderizado inteiro, em tokens (cerca de 4 caracteres cada); um pack maior é cortado e `truncated` é definido. |
| `top_k` | `int` | `5` | Quantos resultados cada seção baseada em busca pede (procedimentos e a camada de conhecimento do stack limitam isso a 5). |
| `read_scope` | `Literal['namespace', 'own_user', 'own_session']` | `'namespace'` | Mesma semântica de memory.search.read_scope; vincula-se ao user_id / session_id desta op. |
| `mode` | `Literal['startup', 'task', 'debug', 'handoff']` | `'task'` | Orçamentos das seções e receita de busca, sem chamada a LLM em nenhum modo: `startup` (recuperação rápida; sem query, serve pins e memórias recentes), `task` e `handoff` (equilibrado), `debug` (qualidade). |
| `include_knowledge` | `bool` | `False` | Adiciona uma seção `knowledge` com trechos de documentos correspondentes; exige uma `query`. |
| `include_conversations` | `bool` | `False` | Adiciona uma seção `conversations` com mensagens passadas correspondentes; exige uma `query`. |
| `include_runs` | `bool` | `False` | O manifesto de execuções: uma linha por sessão recente desta identidade (data, status e objetivo da execução, chamadas de ferramenta por tipo com erros, arquivos tocados, resumo), da mais nova para a mais antiga, `runs_limit` linhas. |
| `runs_limit` | `int` | `12` | Quantas sessões recentes o manifesto de execuções lista quando `include_runs` está definido (1-50). |
| `include_chunks` | `bool` | `False` | Amplia o pool do reranker da busca de memórias com 20 candidatos recentes; sem efeito sem um reranker. |
| `section_token_budgets` | `dict[str, int]` | *(calculado)* | Orçamentos de tokens por seção que substituem os padrões do modo, indexados pelo nome da seção; uma seção nunca recebe menos de 80 tokens. |
| `block_order` | `list[str]` | *(calculado)* | Ordenação de blocos opcional, definida pelo chamador. |
| `session_block` | `str` | `''` | O marcador de sessão do próprio chamador (`session:<project>`, a nota do hook Stop do plugin). |
| `only_sections` | `list[Literal['working_memory', 'memory_stack', 'profile', 'memories', 'procedures', 'decisions', 'knowledge', 'conversations', 'runs', 'namespace_health', 'namespace_guide', 'mentor']]` | *(calculado)* | Restringe o pack a estas seções. |
| `include_decisions` | `bool` | `True` | Os resultados do tipo decisão saem do bloco de memórias e são renderizados em sua própria seção etiquetada <decisions>, com o registro estruturado (cenário, resultado, resultado realizado). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `rendered` | `str` | O pack como um único texto: cada seção não vazia dentro de uma tag `<name>`, na ordem dos blocos, cortado em `token_budget`. |
| `sections` | `dict[str, str]` | O corpo de cada seção por nome, na ordem dos blocos; seções que não renderizaram nada ficam ausentes. |
| `blocks` | `list[ContextBlock]` | Uma entrada por seção não vazia: rótulo, corpo, estimativa de tokens, citações, contagem de fontes e `priority` (sua posição na ordem dos blocos). |
| `section_meta` | `dict[str, dict[str, Any]]` | Detalhes por seção, por nome: contagem de fontes, citações, se foi cortada, seu tamanho, seu orçamento de tokens e a taxa de preenchimento (acima de 1.0 significa que foi cortada). |
| `section_count` | `int` | Quantas seções renderizaram algo. |
| `truncated` | `bool` | True quando qualquer seção, ou o pack inteiro, foi cortado até o seu orçamento. |
| `token_budget` | `int` | Eco do `token_budget` de entrada. |
| `mode` | `str` | Eco do `mode` de entrada. |
| `tokens_estimate` | `int` | Pressão sobre o orçamento. |
| `fill_ratio` | `float` | `tokens_estimate / token_budget`, com três casas decimais. |
| `stable_sections` | `list[str]` | A sequência inicial de `rendered` que não depende de `query` nem de `situation`: os mesmos bytes para toda pergunta que esta identidade faz, até que sua memória de trabalho, perfil ou pins mudem. |
| `stable_prefix_chars` | `int` | Comprimento, em caracteres, desse prefixo de `rendered`; 0 quando a primeira seção depende da query. |
| `stable_hash` | `str` | SHA-256 do prefixo estável; vazio quando `stable_prefix_chars` é 0. |
| `procedure_keys` | `list[str]` | Procedimentos que o pack colocou diante do agente: o lado "mostrado" do registro de que uma utility precisa. |
| `procedure_keys_withheld` | `list[str]` | Procedimentos que o pack encontrou e deliberadamente reteve: o lado "não mostrado" do mesmo registro. |

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