Pular para o conteúdo
ClickHouse Loom
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Conversas e sessões

Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.

O Loom mantém três tipos de estado de sessão, cada um em seu próprio plano:

Plano Armazena Embedding e busca Escrito por
Plano de conversa Os turnos literais de uma thread (loom.conversations) Turnos do usuário e do assistente e resumos de compactação, por conversation.search conversation.append, os hooks de captura dos plugins, loom ingest-transcript
Briefs de sessão O estado condensado e retomável de uma linha de trabalho (loom.session_briefs) Não session.brief_save, os plugins de codificação na compactação e no fim da sessão
Memória Fatos duráveis extraídos do que foi dito Sim, por memory.search memory.set, memory.set_from_messages

Armazenar um turno não cria uma memória; para transformar uma conversa em fatos, envie-a para memory.set_from_messages. Um proprietário pode desativar o registro de transcrições sem perder a memória extraída, e um brief nunca compete com fatos na recuperação.

Conversas

A gravação é escolha do proprietário

conversation.append armazena um turno somente quando o namespace tem o registro de conversas ativado. A chave (conversation_logging_enabled em loom.namespaces) vem desativada por padrão e falha de forma fechada: um namespace sem linha não é gravado. O proprietário a ativa com conversation.set_logging(enabled=true) (admin) ou com a chave Record conversations na página Conversas do painel.

Quando o registro está desativado, o append é aceito e nada é mantido: a resposta traz stored: false, reason: "logging_disabled". Um cliente não pode sobrescrever a escolha do proprietário. Se o turno for removido enquanto seu embedding é calculado, o append descarta o vetor tardio e responde stored: false, reason: "deleted".

Escrevendo turnos

conversation.append recebe thread_id, role (user, assistant, system ou tool), content e, opcionalmente, msg_id, reasoning (o raciocínio do modelo mantido em sua própria coluna), user_id, run_id, metadata e tokens. A thread é criada no primeiro append; conversation.create apenas anexa antecipadamente um title, metadata ou run_id.

  • Idempotente em msg_id. Um turno cujo (thread_id, msg_id) já foi gravado não é escrito de novo (reason: "duplicate"). Sem um msg_id, o servidor deriva um a partir de um hash da thread, do papel e do conteúdo, de modo que um cliente que registra um turno de novo não duplica a transcrição.
  • Turnos de user e assistant têm embedding, até os primeiros 2,048 caracteres, que a linha de embedding mantém: um novo embedding parte do texto a partir do qual o vetor foi construído. Linhas gravadas por versões anteriores mantêm 240 caracteres, e um novo embedding trabalha a partir delas. Turnos system e tool ficam na transcrição sem indexação, exceto o resumo de uma compactação.
  • O embedding falha de forma aberta. Um embedding com falha ainda armazena o turno, com o erro registrado na sua linha de embedding. Nada tenta de novo: o turno fica fora da busca vetorial e só é encontrado pelo fallback de substring.
  • Um turno classificado como high não recebe embedding. Um turno cujo texto contém um formato high (uma chave de API colada, uma atribuição password=, um número de cartão, um SSN ou um PIN informado) é armazenado como escrito, mas não recebe linha de embedding, e seu texto nunca é enviado ao modelo de embedding. conversation.search nunca o retorna, nem por vetor nem pelo fallback de substring, e conversation.threads lista um último turno assim com um trecho vazio (e um título que se classifica como high fica vazio); ele verifica os 240 caracteres que seu trecho mostra e 1,024 além deles. O gerador de títulos nunca envia esse turno ao seu modelo. Uma thread cujos primeiros oito turnos de user e assistant são todos classificados como high, ou cujo título gerado é classificado como high, permanece sem título, marcada com title_refused em seus metadados para que o gerador de títulos não peça de novo; uma com menos desses turnos espera, sem marca, por um turno comum. Novos metadata vindos de conversation.update ou conversation.create substituem a marca, e o gerador de títulos então pergunta mais uma vez e marca a thread de novo. conversation.get e conversation.list ainda servem o turno em sua thread (sensibilidade).

Salvando mensagens individuais

Um cliente de chat pode permitir que um usuário salve uma mensagem para busca posterior sem gravar as transcrições do namespace. conversation.save_message (writer) é esse opt-in, e conversation.search_saved_messages (viewer) é a sua busca. Uma mensagem salva é uma linha de conversa, nunca um documento na coleção pessoal do usuário (compartilhamento).

Os clientes salvam mensagens somente quando todas as réplicas preservam o estado salvo durante a compactação. Veja as regras de rolling upgrade.

Elas diferem de conversation.append e conversation.search em seis aspectos:

  • A chave Record conversations não se aplica. O salvamento é armazenado mesmo quando a chave (ou conversation.set_logging) desativou a gravação, e salvar não ativa a gravação.
  • A mensagem é sinalizada, não rotulada de novo. A linha da transcrição e sua linha de embedding carregam is_saved e saved_at, o momento em que o usuário salvou a mensagem. Uma mensagem que a transcrição já contém é sinalizada no lugar: seu run_id e seu conteúdo permanecem como foram gravados.
  • A busca é por usuário. conversation.search_saved_messages retorna apenas mensagens sinalizadas pertencentes a user_id, no único namespace indicado. conversation.search ranqueia todos os turnos gravados e, por padrão, se estende pelos namespaces do chamador.
  • A busca é híbrida. A perna vetorial gera o embedding dos primeiros 2,048 caracteres de uma mensagem; uma perna BM25 lê o texto inteiro, de modo que um termo exato (um id de ticket, um nome de tabela) ou uma frase no fundo de uma resposta salva longa ainda é ranqueado. search_mode="hybrid" (padrão) funde as duas por rank recíproco, semantic e lexical executam uma só perna, e lexical_weight (0–1) escala a perna BM25. O trecho de um resultado BM25 é centrado nos termos encontrados. O corpus é o conjunto de mensagens salvas de um usuário, então suas estatísticas são calculadas a cada consulta.
  • Um token fixado em um usuário funciona aqui. Uma integração que atende muitos usuários por uma única credencial a emite com --read-scope own_user (e --read-user-id para um usuário). As operações de mensagens salvas então agem somente como esse usuário: um corpo que nomeia outro user_id é recusado com 403, e toda instrução carrega o usuário do token. Um token de usuário final chama essas operações com namespace: "@me" (compartilhamento). As tabelas de conversa não têm session_id, então um token own_session é recusado. Toda outra operação de conversa (append, get, list, search, threads, …) continua recusada com tal token, porque uma thread mistura usuários e não tem eixo de usuário para delimitar.
  • Propriedade, exclusão e papel são verificados a cada salvamento. Salvar uma mensagem armazenada sob outro user_id responde indexed: false, reason: "owner_mismatch". Uma mensagem com tombstone responde reason: "deleted", e um turno system ou tool armazenado, que nunca é embutido, responde reason: "unsupported_role". Uma mensagem cujo texto é classificado como high também nunca recebe embedding: ela responde reason: "high_sensitivity", e uma nova não é armazenada. Uma que uma versão anterior salvou nunca é um resultado vetorial ou por palavra-chave de conversation.search_saved_messages, e conversation.list_saved_messages a lista com um trecho vazio (ele verifica os conversation_search_excerpt_chars caracteres que mostra e 1,024 além deles, como conversation.threads faz). As verificações também se aplicam a uma mensagem que já está salva.

Salvar e remover dos salvos compartilham uma lease de thread renovável com as escritas de embedding do append, a retirada da compactação e a exclusão da thread. Append e compactação concluem o trabalho do provedor antes de obter a lease.

A linha da transcrição decide quem é o dono de uma mensagem salva. Um salvamento reivindica apenas linhas que nenhum usuário possui ou que o chamador possui, na própria mutação, de modo que, entre dois usuários salvando uma mesma mensagem sem dono, o primeiro a reivindica e o segundo recebe owner_mismatch. A linha de embedding só é sinalizada depois que a linha da transcrição é lida de volta como do chamador.

Um salvamento pode ser repetido com segurança. Dois salvamentos concorrentes de uma mensagem nova armazenam uma única linha de transcrição: seu insert carrega um token de deduplicação derivado da identidade da mensagem. Cada chamada relê a mensagem e repara o que uma escrita interrompida ou concorrente deixou para trás: grava uma linha de embedding ausente, gera o embedding de novo quando o último falhou, e sinaliza qualquer linha ainda sem sinalização. Um salvamento cujo embedding falha armazena a mensagem como salva e responde indexed: false, reason: "embed_failed"; salvá-la de novo tenta o embedding outra vez. Um append de transcrição cujo embedding chega depois de um salvamento concorrente sinaliza sua própria linha de embedding.

conversation.list_saved_messages (viewer) percorre as mensagens salvas de um usuário, sem consulta, das salvas mais recentemente para as mais antigas (limit até 200, um cursor opaco e um conversation_id opcional). Seu ts é o momento em que o usuário salvou a mensagem, independente do horário da mensagem na transcrição. Linhas gravadas sem timestamp de salvamento usam o timestamp da mensagem. É a primeira visão de um painel “Saved”; a busca a restringe quando o usuário digita. conversation.saved_status (viewer) recebe um conversation_id e até 500 message_ids e responde quais deles esse usuário salvou, de modo que um cliente desenha o estado salvo de cada mensagem ao abrir uma conversa em uma única chamada.

conversation.unsave_message (writer) retira uma mensagem salva da busca do seu proprietário. Onde o namespace grava transcrições, o turno permanece na transcrição com a sinalização removida, porque o proprietário escolheu gravá-lo. Onde não grava, o turno é removido com um delete leve, porque só existia por causa do salvamento (removed: true). O embedding mantém um tombstone para que versões mais antigas não reapareçam. Uma mensagem que o usuário do chamador nunca salvou, ou que outro usuário salvou, responde found: false; nunca diz qual dos casos. Remover dos salvos é idempotente, e salvar de novo restaura a mensagem. A exclusão por usuário remove as mensagens salvas junto com o resto das linhas de conversa desse usuário.

Leitura e busca

Operação Papel Faz
conversation.threads viewer Threads recentes de um namespace, das mais novas às mais antigas (window_days, limit, offset até 100,000; agent="*" para todos os agentes).
conversation.get viewer Metadados de uma thread; include_messages=true pagina seus turnos (order="desc" para o final).
conversation.list viewer Os turnos de uma thread, paginados por cursor, opcionalmente por run_id.
conversation.search viewer Busca vetorial sobre turnos com embedding, opcionalmente por thread, execução ou papel.
conversation.update writer Altera title, metadata ou run_id de uma thread.

conversation.search ranqueia os turnos por similaridade de cosseno, descarta os abaixo de LOOM_CONVERSATION_SEARCH_MIN_SIMILARITY (0.30) e, por padrão, se estende pelos namespaces do chamador (namespace_scope="all_mine"). Quando o modelo de embedding está indisponível, recorre a uma correspondência de substring para que a operação ainda responda. Os resultados mostram os primeiros LOOM_CONVERSATION_SEARCH_EXCERPT_CHARS caracteres de um turno (240 por padrão); leia o turno com conversation.get ou conversation.list. A operação fica oculta do MCP; os agentes recebem a seção de conversas de loom_search.

memory.recall é uma leitura diferente: ele busca os turnos que uma extração leu (mantidos em loom.memory_evidence), que existem quer o plano de conversas grave ou não. Veja busca e pergunta.

Compactação e exclusão

  • conversation.compact (writer, requer um provedor de LLM) resume os turnos mais antigos anteriores aos últimos keep_recent (padrão 10) que cabem no prompt do sumarizador, grava o resumo como um único turno system com embedding cujo metadata.compacted_from lista os msg_ids resumidos, e põe tombstone nos originais e em seus embeddings: conversation.search então encontra o resumo no lugar deles. Um turno que outro agente da thread ainda mantém ativo com o mesmo texto, como um turno que a busca indexa, mantém seu embedding (veja delete abaixo). Uma janela com menos de min_to_compact (padrão 4) turnos novos é deixada como está. Um resumo anterior não conta nem para min_to_compact nem para messages_summarized. Resumos no início da janela são incorporados ao prompt a partir de uma cota separada; um que não cabe no que resta dela permanece ativo, e um que uma execução com falha deixou (seus turnos todos ainda ativos e na janela, no ts do primeiro) é substituído sem ser lido. Um resumo mais adiante na janela consome o orçamento do prompt como qualquer turno e é substituído junto com ele. Um turno classificado como high fica fora da janela: ele permanece ativo e nunca é enviado ao sumarizador, de modo que o resumo, colocado no primeiro turno da janela, pode vir antes dele na thread. Um turno salvo com conversation.save_message também nunca é resumido nem recebe tombstone; ele permanece literal entre o resumo e os turnos recentes. Um resumo que não pode receber embedding não compacta nada (reason: "embed-failed"), e o mesmo vale para um que é classificado como high de qualquer forma (reason: "summary-high-sensitivity"), já que nunca recebe embedding. Ao contrário de embed-failed, essa recusa não vale uma nova tentativa: a janela continua a mesma enquanto seus turnos estão ativos, então uma nova tentativa paga pela mesma chamada ao sumarizador e muito provavelmente obtém o mesmo resumo. Uma janela que contém apenas turnos salvos ou turnos classificados como high responde reason: "nothing-to-compact".
  • conversation.delete (admin) põe tombstone nos turnos, na linha da thread e nos embeddings de uma thread; confirm_thread_id deve ser igual a thread_id. Um turno que outro agente também registrou na thread mantém seu embedding enquanto esse agente tiver uma cópia ativa com o mesmo texto que a busca indexa (um turno de user ou assistant, ou um resumo), já que as duas cópias compartilham uma linha de embedding; a linha assume o agente, o papel, a execução e o usuário dessa cópia, de modo que a busca do próprio agente que excluiu a descarta (a compactação faz o mesmo). Uma linha de exatamente 240 caracteres (um corte de uma versão anterior, ou um turno desse tamanho) é mantida apenas para uma cópia cujos primeiros 2,048 caracteres coincidem com o turno do seu agente, e recebe tombstone quando não resta linha de mensagem para verificar isso. Uma exclusão também conclui linhas da thread cujo próprio agente não mantém mais uma mensagem ativa para o turno: uma que ele excluiu ou compactou (versões anteriores deixaram algumas), ou uma que o TTL de retenção expirou. Para os dados de uma pessoa ou de um namespace em todos os lugares, use erasure.request.

Turnos com tombstone são filtrados de toda leitura, exceto erasure.export, que os retorna a menos que seja chamado com include_tombstoned: false. Eles só são removidos do disco se o operador definiu um TTL de tabela (LOOM_RETENTION_CONVERSATIONS_DAYS, 0 = manter para sempre). Esse TTL cobre apenas loom.conversations: a linha de embedding de um turno, que mantém até 2,048 caracteres do seu texto, não tem TTL. Depois que sua mensagem expirou, uma exclusão de thread inteira em sua thread a passa a uma cópia ativa do turno ou põe tombstone nela; uma solicitação de erasure põe tombstone nela e só a remove em um erasure namespace_list com purge. erasure.export não retorna linhas de embedding, então o trecho de um turno que o TTL expirou é apagado junto com o titular, mas não está na exportação dele.

Títulos de thread

O worker conversation_titler dá às threads sem título (criadas por appends sem conversation.create) um título curto escrito por LLM, com o qual a página Conversas do painel abre. Ele cobre namespaces que gravam conversas, threads ativas nas últimas LOOM_CONVERSATION_TITLER_WINDOW_HOURS (168) horas com pelo menos LOOM_CONVERSATION_TITLER_MIN_TURNS (4) turnos, no máximo LOOM_CONVERSATION_TITLER_MAX_THREADS_PER_PASS (10) por passagem. Vem ativado por padrão (LOOM_CONVERSATION_TITLER_ENABLED) e não faz nada com o LLM fake.

Capturando sessões a partir de clientes

Cliente Como os turnos chegam ao Loom
Plugin do Claude Code O hook Stop (hooks/loom-conversation.mjs) adiciona cada novo turno a partir da transcrição da sessão, com msg_id = o uuid da transcrição; LOOM_CAPTURE_CONVERSATIONS=false o desativa. Ele mantém em cache o veredito de gravação do namespace e ignora as adições enquanto a gravação está desativada.
Plugin do Codex A mesma captura, veja Codex.
Cursor integrations/cursor/cursor-session-hook.sh, executado pelo hook de fim de conversa do Cursor, entrega a transcrição para loom ingest-transcript.
Outros agentes integrations/generic/ingest.sh sobre a transcrição exportada.
Qualquer cliente MCP A listagem core padrão não inclui conversation.append, e nada nela leva o modelo a registrar turnos: faça a captura com um hook de transcrição, ou monte ?toolset=all, que lista loom_conversation_append.
Seu próprio código conversation.append, ou o Session do SDK Python, abaixo.

loom ingest-transcript --namespace NS --file session.md lê um arquivo Markdown com seções # user / # assistant alternadas, ou um array JSON de {role, content}, e adiciona cada turno (--dry-run os conta; --thread-id define um id estável).

Os plugins também entregam os turnos da sessão a memory.set_from_messages(defer=true) ao fim da sessão, de modo que os fatos são extraídos independentemente de a transcrição estar gravada, e registram as ações de ferramentas como observações episódicas por meio de observe.record / observe.crystallize (veja extração). A configuração hook a hook está em Claude Code.

Briefs de sessão

Um brief de sessão é o estado retomável de uma linha de trabalho: objetivo, status, decisões, becos sem saída, o que foi feito, questões em aberto, próximos passos, arquivos principais, restrições e ponteiros. Ele é lido após uma compactação, no dia seguinte, em outro cliente ou por um colega de equipe. Nunca é gerado como embedding nem retornado por memory.search. Qualquer agente que consiga ler o namespace pode retomá-lo.

Operação Papel Faz
session.brief_save writer Revisa (ou inicia) um brief a partir de events (o que aconteceu desde o último salvamento), de sections escritas pelo agente, ou de ambos.
session.brief_get viewer Carrega um brief por brief_key; senão o mais recente que uma sessão escreveu (from_session); senão o mais recente de um project.
session.brief_list viewer Os briefs do namespace, do mais recente ao mais antigo, uma linha cada (mine_only para os do chamador).
session.brief_delete writer Exclui um brief quando quem o escreveu pede que seja esquecido.

Endereçamento. Um brief_key vazio vira auto/<project>/<branch>, de modo que toda sessão na mesma linha de trabalho revisa o mesmo brief, ou session/<session_id> quando nenhum dos dois é conhecido. As chaves seguem ^[A-Za-z0-9][A-Za-z0-9_.:/@+-]{0,159}$. Um token limitado a um usuário (ou sessão) armazena seus briefs como ~<user>~<key> (ou ~<user>~<session>~<key>) e os vê como <key>; um token válido para todo o namespace os lista com esse prefixo e pode obtê-los ou excluí-los por ele. Um token limitado não pode enviar uma chave com ~.

Revisão. Um salvamento com events (tipos user, assistant, edit, command, error, read, search, tool, note, summary; até 4,000 por chamada) é condensado no servidor. Com LOOM_SESSION_BRIEF_LLM ativado (padrão), o modelo indicado por LOOM_SESSION_BRIEF_LLM_MODEL revisa o brief uma vez por janela de LOOM_SESSION_BRIEF_WINDOW_CHARS caracteres, no máximo LOOM_SESSION_BRIEF_MAX_WINDOWS janelas por salvamento; sem a chave desse modelo, o LLM do deployment o escreve, e sem nenhum LLM o construtor determinístico escreve objetivo, status, arquivos, erros e ponteiros (sem decisões nem becos sem saída). O campo author na resposta indica llm, deterministic ou model (o agente que chamou escreveu as seções). Sob uma política de extração do operador, o construtor nunca é executado e nenhum resumo do cliente é extraído dos eventos. Uma janela cuja chamada ao modelo falhou é ignorada enquanto as demais são revisadas. Um salvamento somente de eventos sem modelo para chamar (nenhum configurado, use_llm: false, ou as chamadas de modelo da organização desativadas antes de a primeira janela ser revisada) não grava nada e responde changed: false, reason: "not-revised"; uma organização desativada depois de algumas janelas terem sido revisadas mantém essas janelas e não revisa mais nenhuma. Um salvamento somente de eventos em que toda chamada ao modelo falhou, ficou retida por uma chave não lida ou não pôde ser interpretada é recusado com 503 para que o cliente envie novamente. Um salvamento que também traz as sections do agente as grava sobre o brief como estava, nos dois casos, e não aproveita nada dos eventos. As seções de estado são substituídas a cada revisão; decisões, becos sem saída e itens concluídos se acumulam. Toda revisão é mantida em loom.session_brief_revisions; revision=N em brief_get lê uma delas. Um salvamento que repete a sessão e o event_cursor do salvamento anterior é uma nova tentativa e não grava nada; if_revision faz de um salvamento um compare-and-set (409 em caso de divergência).

A restauração é escolha da pessoa. Os plugins de código salvam briefs na compactação e no fim da sessão sem gastar nenhum token de modelo no cliente, e o primer de início de sessão apenas cita os briefs salvos. O carregamento acontece quando a pessoa pede, pela skill loom-session ou pela seção de briefs da página Conversations do painel. brief_get(full=true) anexa, literalmente, o último resumo de compactação do próprio cliente abaixo do brief. Os briefs nunca são carregados sozinhos: só a pessoa sabe qual linha de trabalho está retomando.

Exemplo

A Session do SDK Python vincula estas ops a um escopo (user, session): append grava os turnos na transcrição e, a cada flush_every turnos, em memory.set_from_messages; resume é context.pack para o escopo mais o final da transcrição.

from loom import Agent

async with Agent("dev", "local", "support-bot", base_url="http://localhost:7777") as bot:
    s = bot.session("thread-42", user_id="u1")
    resumed = await s.resume(query="resume the billing migration")
    await s.append(
        {"role": "user", "content": "We moved invoices to the new ledger."},
        {"role": "assistant", "content": "Noted; I'll update the export job."},
    )
    print(s.transcript_stored)  # False when the namespace does not record
    await s.close()  # flushes the buffered turns to extraction

    await bot.briefs.save(
        project="billing",
        branch="ledger-move",
        sections={
            "goal": "Move invoices to the new ledger",
            "next_steps": ["Update the export job"],
        },
    )

A extração em close() precisa de um provedor de LLM real para encontrar fatos; com o provedor falso padrão, os turnos ainda são gravados.

Configurações

Configuração Efeito
LOOM_CONVERSATION_SEARCH_MIN_SIMILARITY O limite mínimo de cosseno de conversation.search (Conhecimento → Conversas).
LOOM_CONVERSATION_SEARCH_EXCERPT_CHARS Quanto de um turno um resultado de busca ou uma listagem de mensagens salvas exibe, em tempo real (Conhecimento → Conversas).
LOOM_CONVERSATION_TITLER_* A chave de ativação, a cadência, a janela e o limite por passagem do worker de títulos (Conhecimento → Conversas).
LOOM_RETENTION_CONVERSATIONS_DAYS, LOOM_TIERING_CONVERSATIONS_WARM_DAYS TTL opcional e movimentação para o volume warm das transcrições (Retenção, armazenamento em camadas).
LOOM_SESSION_BRIEF_LLM, …_LLM_MODEL, …_WINDOW_CHARS, …_MAX_WINDOWS Como os resumos são condensados (Contexto).
LOOM_MCP_SESSION_RUN_IDLE_SECONDS Encerra a execução implícita de uma sessão MCP após esse tempo sem nenhuma chamada (MCP).

Limites

  • “Fiz o append, mas não há nada lá.” A gravação está desativada para o namespace; o append respondeu stored: false. Ative-a com conversation.set_logging.
  • As transcrições não são mineradas. Os turnos gravados nunca se tornam memórias por conta própria.
  • conversation.search prioriza vetores. Uma redação exata que o embedding não captura pode ficar mal classificada; memory.recall faz leituras lexicais e por janela de tempo sobre os turnos que a extração leu.
  • Os briefs têm tamanho limitado. Um brief renderizado fica abaixo de cerca de 12,000 caracteres; cada seção de lista tem um limite (por exemplo, 20 decisões, 12 caminhos sem saída, 8 próximos passos), então itens antigos são descartados.
  • Um brief não é um lock. Duas sessões no mesmo branch revisam o mesmo brief; passe if_revision quando isso não puder se intercalar.

Relacionados

Esta página foi útil?