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

# Operações de `conversation`

<!-- i18n: source=docs/reference/operations/conversation.md blob=11f53adffc40df382651dd38d150af1095bef85c 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/conversation.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/conversation.md), which is authoritative.


Os campos exatos que cada operação `conversation.*` 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, é usada a org da instalação em todas as ops, exceto `code.*` e `tracker.*` (que mantêm a org do próprio 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="conversationappend"></a>

## `conversation.append`

Registra um turno de chat (role + content) em uma thread.

`POST /v1/conversation.append` · MCP `loom_conversation_append` · role `writer` · idempotente

| 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. |
| `thread_id` | `str` | obrigatório | A thread à qual adicionar; ela não precisa ter sido criada antes. |
| `msg_id` | `str` | `''` | opcional; o servidor deriva um hash do conteúdo quando omitido |
| `role` | `Literal['user', 'assistant', 'system', 'tool']` | obrigatório | Quem falou: `user`, `assistant`, `system` ou `tool`. |
| `content` | `str` | obrigatório | O texto da mensagem, armazenado literalmente; um turno de user ou assistant também recebe embedding para `conversation.search`, a menos que seu texto seja considerado high. |
| `reasoning` | `str` | `''` | O raciocínio do modelo neste turno, armazenado junto de `content`; vazio = nenhum. |
| `user_id` | `str` | `'-'` | O usuário final ao qual a linha pertence; `'-'` para nenhum. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo da tarefa) à qual a chamada pertence; `'-'` para nenhuma. |
| `metadata` | `dict[str, Any]` | *(calculado)* | JSON livre armazenado na mensagem; lido de volta por `get` e `list`. |
| `tokens` | `int` | `0` | Contagem de tokens que o chamador informa para a mensagem, armazenada como recebida; 0 = não informada. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `msg_id` | `str` | O id da mensagem: o enviado ou o hash do conteúdo derivado pelo servidor. |
| `ts` | `datetime` | Horário do servidor desta chamada; o timestamp da mensagem quando ela foi gravada. |
| `stored` | `bool` | False quando o registro está desativado ou o turno foi removido enquanto o embedding era executado. |
| `reason` | `Literal['', 'duplicate', 'logging_disabled', 'deleted']` | "" (gravada), "duplicate" (este msg_id já foi gravado; stored=True), "logging_disabled" ou "deleted" (stored=False). |

<a id="conversationcompact"></a>

## `conversation.compact`

Resume turnos antigos em um único turno de sistema com embedding e marca os originais com tombstone.

`POST /v1/conversation.compact` · MCP `loom_conversation_compact` · role `writer` · idempotente · auditado · 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, onde a op permitir. |
| `thread_id` | `str` | obrigatório | A thread a compactar. |
| `keep_recent` | `int` | `10` | Esta quantidade das mensagens mais recentes permanece literal; as mais antigas são resumidas, quantas couberem no prompt do sumarizador. |
| `min_to_compact` | `int` | `4` | Ignora quando há menos turnos novos que este valor antes das últimas keep_recent; um resumo anterior não conta. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `compacted` | `bool` | Verdadeiro quando um resumo foi gravado e os originais receberam tombstone; `reason` explica o motivo caso contrário. |
| `messages_summarized` | `int` | Quantas mensagens mais antigas o resumo substituiu, sem contar um resumo anterior; 0 quando não houve compactação. |
| `summary_msg_id` | `str` | Id da mensagem sintética de resumo `system`; vazio quando não houve compactação. |
| `tokens_in` | `int` | Tokens de prompt que a chamada de LLM do sumarizador usou; 0 quando nenhuma chamada foi feita. |
| `tokens_out` | `int` | Tokens de conclusão do resumo; 0 quando nenhuma chamada foi feita. |
| `reason` | `str` | Por que compacted=False: nothing-to-compact, below-min-to-compact, already-compacted, summarizer-empty, embed-failed (tente de novo quando o embedder responder), summary-high-sensitivity (não tente de novo: a mesma janela gera o mesmo resumo). |

<a id="conversationcreate"></a>

## `conversation.create`

Abre um contêiner de thread.

`POST /v1/conversation.create` · MCP `loom_conversation_create` · 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, onde a op permitir. |
| `thread_id` | `str` | obrigatório | O id da thread definido pelo chamador; recriar o mesmo id substitui seu título, metadados e `run_id`. |
| `title` | `str` | `''` | Título de exibição mostrado nas listas de threads; vazio = sem título. |
| `metadata` | `dict[str, Any]` | *(calculado)* | JSON livre armazenado na linha da thread; `conversation.get` o retorna. |
| `run_id` | `str` | `'-'` | A execução do agente (escopo da tarefa) à qual a chamada pertence; `'-'` para nenhuma. |
| `user_id` | `str` | `'-'` | O usuário final ao qual a linha pertence; `'-'` para nenhum. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `thread_id` | `str` | Eco do `thread_id` de entrada. |
| `created_at` | `datetime` | Quando esta chamada gravou a linha da thread. |

<a id="conversationdelete"></a>

## `conversation.delete`

Faz o soft-delete de uma thread: suas mensagens, a linha da thread e os embeddings que nenhum outro agente mantém.

`POST /v1/conversation.delete` · MCP `loom_conversation_delete` · papel `admin` · idempotente · auditado · 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, onde a op permitir. |
| `thread_id` | `str` | obrigatório | A thread a ser removida com soft-delete. |
| `confirm_thread_id` | `str` | obrigatório | Deve ser igual a `thread_id`, ou a chamada falha com 400 e nada é excluído. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `tombstoned_at` | `datetime` | O horário do tombstone registrado em cada linha afetada. |
| `thread_id` | `str` | Eco do `thread_id` de entrada. |
| `rows_affected` | `dict[str, int]` | {table_name: linhas marcadas com tombstone}; para loom.conversation_embeddings, turnos (um por turno, independentemente de quantos modelos de embedding o mantenham). |
| `total` | `int` | Soma de `rows_affected` em todas as tabelas. |

<a id="conversationget"></a>

## `conversation.get`

Busca uma thread pelo id: metadados da thread + mensagens opcionais.

`POST /v1/conversation.get` · MCP `loom_conversation_get` · role `viewer` · leitura · 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 | "*" ou "-" lê os turnos de todos os agentes na thread (um turno que dois agentes registraram uma vez), para um chamador que só tem o id, assim como conversation.search lê "*" e "-"; qualquer outro valor lê apenas os turnos desse agente. |
| `thread_id` | `str` | obrigatório | A thread a buscar. |
| `include_messages` | `bool` | `False` | Desativado por padrão: mantém a consulta de metadados em duas leituras pontuais. |
| `limit` | `int` | `100` | No máximo esta quantidade de mensagens quando `include_messages` está ativo (1-1000). |
| `offset` | `int` | `0` | Mensagens a pular a partir da extremidade da qual `order` conta. |
| `order` | `Literal['asc', 'desc']` | `'asc'` | A partir de qual extremidade da thread a página é contada. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `found` | `bool` | False quando a thread não tem nem linha de thread nem mensagem ativa. |
| `thread_id` | `str` | Eco do `thread_id` de entrada. |
| `title` | `str` | Título de `conversation.create` ou `update`; vazio quando nenhum foi definido. |
| `metadata` | `dict[str, Any]` | JSON de metadados da thread; `{}` quando nenhum foi definido, exceto pela marca `title_refused` do gerador de títulos. |
| `run_id` | `str` | A execução do agente (escopo de tarefa) à qual a chamada pertence; `'-'` para nenhuma. |
| `user_id` | `str` | O usuário final ao qual a linha pertence; `'-'` para nenhum. |
| `agent` | `str` | O dono da thread (o agente da linha da thread); para uma thread construída apenas por appends, o último autor entre as mensagens lidas, portanto vazio sem `include_messages`. |
| `created_at` | `datetime \| None` | Quando a linha da thread foi escrita pela primeira vez; None para uma thread construída apenas por appends. |
| `updated_at` | `datetime \| None` | Quando a linha da thread mudou pela última vez; None para uma thread construída apenas por appends. |
| `msg_count` | `int` | Mensagens ativas (não marcadas como removidas) na thread, retornado mesmo sem as mensagens. |
| `messages` | `list[_ConversationEntry]` | Preenchido apenas com include_messages=True; fatiamento simples por limit/offset (percursos paginados por cursor ficam em conversation.list). |
| `next_cursor` | `str \| None` | Com `order="asc"`, o cursor de `conversation.list` para os turnos após esta página; None quando a página chega ao fim ou a ordem é `desc`. |

<a id="conversationlist"></a>

## `conversation.list`

Enumera as threads de conversa armazenadas para um agente / namespace.

`POST /v1/conversation.list` · MCP `loom_conversation_list` · role `viewer` · leitura · 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 | "*" ou "-" lê os turnos de todos os agentes na thread (um turno que dois agentes registraram uma vez), para um chamador que tem apenas o seu id, assim como conversation.search lê "*" e "-"; qualquer outro valor lê apenas os turnos desse agente. |
| `thread_id` | `str` | obrigatório | A thread a ser percorrida página por página, da mensagem mais antiga para a mais recente. |
| `run_id` | `str \| None` | `None` | filtro opcional; None ou "-" = todas as execuções |
| `limit` | `int` | `100` | No máximo este número de mensagens por página (1-1000). |
| `cursor` | `str \| None` | `None` | (ts, msg_id) opaco |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[_ConversationEntry]` | A página de mensagens em ordem cronológica. |
| `next_cursor` | `str \| None` | Passe como `cursor` para a próxima página; None quando esta for a última página. |

<a id="conversationlist_saved_messages"></a>

## `conversation.list_saved_messages`

Percorre as mensagens que um usuário salvou, da mais recente para a mais antiga, sem consulta: a primeira visualização de um painel "Salvas" antes de qualquer digitação.

`POST /v1/conversation.list_saved_messages` · MCP `loom_conversation_list_saved_messages` · role `viewer` · leitura · 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 escreve. |
| `agent` | `str` | obrigatório | O agente que escreve ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permite. |
| `user_id` | `str` | obrigatório | Somente as mensagens salvas por este usuário são listadas. |
| `conversation_id` | `str \| None` | `None` | Opcional: somente as mensagens salvas de uma conversa. |
| `limit` | `int` | `50` | No máximo esta quantidade de mensagens por página (1-200). |
| `cursor` | `str \| None` | `None` | Opaco; passe o `next_cursor` da página anterior. |
| `fields` | `list[str] \| None` | `None` | Os campos de saída que o chamador lê (uma lista de permissão resolvida com base no modelo de linha; um nome desconhecido resulta em 422); se não definido, todos os campos. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[_SavedMessageHit]` | A página, da mais recentemente salva para a mais antiga. |
| `next_cursor` | `str \| None` | Passe como `cursor` para obter a próxima página; None quando esta for a última página. |

<a id="conversationsave_message"></a>

## `conversation.save_message`

Salva uma mensagem de chat que um usuário escolheu para a busca, independentemente de o namespace registrar transcrições ou não.

`POST /v1/conversation.save_message` · MCP `loom_conversation_save_message` · 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 operação lê ou grava. |
| `agent` | `str` | obrigatório | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente onde a operação permitir. |
| `conversation_id` | `str` | obrigatório | O id da conversa do cliente; ele continua sendo o id da thread no Loom. |
| `message_id` | `str` | obrigatório | O id estável da mensagem do cliente. |
| `role` | `Literal['user', 'assistant']` | obrigatório | Somente mensagens selecionáveis de usuário e de assistente são incorporadas (embedded). |
| `content` | `str` | obrigatório | O texto da mensagem; ignorado quando a transcrição já contém a mensagem. |
| `user_id` | `str` | obrigatório | O proprietário é um filtro rígido na operação de busca pareada. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `conversation_id` | `str` |  |
| `message_id` | `str` |  |
| `indexed` | `bool` | True quando o turno está salvo e tem um vetor que a busca de salvos ranqueia: uma nova gravação, um novo salvamento (concluindo o que um salvamento interrompido deixou pendente) e um turno da transcrição que agora está marcado como salvo. |
| `reason` | `Literal['', 'duplicate', 'owner_mismatch', 'deleted', 'unsupported_role', 'embed_failed', 'high_sensitivity']` | "duplicate": já salvo, nada mudou. "owner_mismatch": o turno armazenado pertence a outro usuário. "deleted": o turno armazenado foi marcado com tombstone. "unsupported_role": o turno armazenado é um turno de sistema ou de ferramenta, que não é incorporado.… |
| `ts` | `datetime` | O timestamp do turno armazenado; o momento da recusa quando ela ocorre. |

<a id="conversationsaved_status"></a>

## `conversation.saved_status`

Quais mensagens de uma conversa um usuário salvou, em uma única chamada: um cliente de chat desenha o estado de salvamento de cada mensagem quando abre a conversa.

`POST /v1/conversation.saved_status` · MCP `loom_conversation_saved_status` · role `viewer` · leitura · 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, onde a op permitir. |
| `user_id` | `str` | obrigatório | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `conversation_id` | `str` | obrigatório | A conversa à qual as mensagens pertencem; os ids de mensagem são únicos dentro dela. |
| `message_ids` | `list[str]` | obrigatório | As mensagens a verificar (1-500). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `saved` | `list[str]` | O subconjunto de `message_ids` que este usuário salvou, na ordem em que foram pedidos. |

<a id="conversationsearch"></a>

## `conversation.search`

Classifica as mensagens de uma conversa por similaridade de embedding com `query`.

`POST /v1/conversation.search` · MCP `loom_conversation_search` · role `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 | "*" ou "-" busca nos turnos de todos os agentes; qualquer outro valor busca apenas nos turnos desse agente. |
| `query` | `str` | obrigatório | Texto comparado ao conteúdo das mensagens, por similaridade de embedding, ou por substring quando o embedder não está disponível. |
| `thread_id` | `str \| None` | `None` | opcional: restringe a uma thread |
| `run_id` | `str \| None` | `None` | opcional: filtra por run_id; None ou "-" = todas as execuções |
| `role` | `Literal['user', 'assistant', 'system', 'tool'] \| None` | `None` | Filtra por autor da mensagem; turnos de system que não sejam resumos de compactação, e turnos de tool, não têm embedding, então só correspondem no fallback de substring. |
| `user_id` | `str \| None` | `None` | Filtro opcional por proprietário; None ou "-" = todos os usuários. |
| `top_k` | `int` | `20` | No máximo esta quantidade de resultados (1-200). |
| `namespace_scope` | `Literal['this', 'all_mine']` | `'all_mine'` | "all_mine" também lê os namespaces do próprio chamador, até `memory_search_fanout_max_namespaces`, como o knowledge.search faz. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `hits` | `list[_ConversationHit]` | Mensagens correspondentes, das mais similares para as menos similares, e vazio quando nenhuma atinge o piso de similaridade; no fallback de substring, das mais recentes para as mais antigas, sem piso. |
| `namespaces_skipped` | `list[str]` | Namespaces do chamador que uma busca all_mine não leu porque ela para em `memory_search_fanout_max_namespaces`; indique um deles pelo nome para pesquisá-lo. |

<a id="conversationsearch_saved_messages"></a>

## `conversation.search_saved_messages`

Busca híbrida apenas nas mensagens que um usuário salvou com conversation.save_message, não em toda a transcrição.

`POST /v1/conversation.search_saved_messages` · MCP `loom_conversation_search_saved_messages` · role `viewer` · leitura · 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` | obrigatório | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `query` | `str` | obrigatório |  |
| `conversation_id` | `str \| None` | `None` |  |
| `role` | `Literal['user', 'assistant'] \| None` | `None` |  |
| `top_k` | `int` | `20` |  |
| `search_mode` | `Literal['hybrid', 'semantic', 'lexical']` | `'hybrid'` | hybrid: a perna vetorial e uma perna BM25 sobre o texto completo de cada mensagem, combinadas por reciprocal rank; semantic: somente vetorial; lexical: somente BM25. |
| `lexical_weight` | `float` | `1.0` | Peso da perna BM25 na fusão (modo hybrid); 1.0 = peso igual. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `hits` | `list[_SavedMessageHit]` |  |

<a id="conversationset_logging"></a>

## `conversation.set_logging`

Ativa ou desativa o registro de transcrições de conversas neste namespace.

`POST /v1/conversation.set_logging` · MCP `loom_conversation_set_logging` · role `admin` · idempotente · auditada · 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. |
| `enabled` | `bool` | obrigatório | True registra transcrições neste namespace; False faz com que `append` não armazene nada. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `namespace` | `str` | O namespace que a op lê ou grava. |
| `enabled` | `bool` | O estado atual da chave de registro. |

<a id="conversationthreads"></a>

## `conversation.threads`

Threads de conversa recentes de um namespace, das mais novas para as mais antigas.

`POST /v1/conversation.threads` · MCP `loom_conversation_threads` · role `viewer` · read

| 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` | `'*'` | "*" ou "-" lista as threads de todos os agentes |
| `window_days` | `int` | `30` | Apenas threads com uma mensagem ativa nos últimos tantos dias (1-365). |
| `limit` | `int` | `30` | No máximo este número de threads (1-200). |
| `offset` | `int` | `0` | Threads a ignorar antes da página (0-100,000); o padrão é 0, a primeira página. |
| `fields` | `list[str] \| None` | `None` | Os campos de saída que o chamador lê (uma lista de permissão resolvida contra o modelo de linha; um nome desconhecido gera um 422); se não definido, todos os campos. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `threads` | `list[ConversationThreadSummary]` | Threads, da atividade mais recente para a mais antiga, cada uma com sua contagem e o trecho da última mensagem. |

<a id="conversationunsave_message"></a>

## `conversation.unsave_message`

Remove uma mensagem da busca de mensagens salvas de um usuário.

`POST /v1/conversation.unsave_message` · MCP `loom_conversation_unsave_message` · 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. |
| `conversation_id` | `str` | obrigatório | O id da conversa do cliente, como informado em conversation.save_message. |
| `message_id` | `str` | obrigatório | O id da mensagem do cliente, como informado em conversation.save_message. |
| `user_id` | `str` | obrigatório | Somente a linha salva deste usuário é removida. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `conversation_id` | `str` |  |
| `message_id` | `str` |  |
| `found` | `bool` | False quando não existe nenhuma linha salva deste usuário: nunca foi salva, já foi removida ou foi salva por outro usuário (o que não é confirmado). |
| `removed` | `bool` | True quando o próprio turno foi removido: o namespace não registra transcrições, então a linha existia apenas por causa do salvamento. |
| `ts` | `datetime` |  |

<a id="conversationupdate"></a>

## `conversation.update`

Atualiza o título, os metadados ou o run_id de uma thread.

`POST /v1/conversation.update` · MCP `loom_conversation_update` · papel `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, onde a op permite. |
| `thread_id` | `str` | obrigatório | A thread a atualizar; uma thread desconhecida retorna `updated=False`. |
| `title` | `str \| None` | `None` | O handler lança 400 se os três campos estiverem ausentes (uma chamada sem efeito indica um bug do chamador). |
| `metadata` | `dict[str, Any] \| None` | `None` | Novo JSON de metadados, que substitui o objeto antigo por inteiro; None mantém o valor atual. |
| `run_id` | `str \| None` | `None` | A nova execução da thread; None ou "-" mantém o valor atual, "" desvincula a thread da execução. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `updated` | `bool` | False quando a thread não tem linha de thread (nunca foi criada); nada é gravado nesse caso. |
| `thread_id` | `str` | Eco do `thread_id` de entrada. |
| `updated_at` | `datetime \| None` | O novo `updated_at` da thread; None quando nada foi atualizado. |

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