Pular para conteúdo

As páginas sem tradução abrem em inglês e são identificadas como inglês.

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.

Histórico e proveniência

Toda escrita na memória cria uma nova versão; nada é editado no local. As versões são mantidas em um espelho somente de acréscimo (append-only), de modo que o histórico de um fato sobrevive às mesclagens em segundo plano. Cada linha registra quem a escreveu e como ela entrou na memória, as linhas derivadas registram suas fontes, e uma pessoa pode atestar que uma linha é verdadeira. O funcionamento do espelho de versões está descrito em arquitetura de memória.

Proveniência e histórico de versões de uma memória no painel

Operações

Operação Papel Responde
memory.history viewer Todas as versões de uma chave, da mais recente para a mais antiga, incluindo versões com tombstone e versões com conteúdo sensível removido (redact).
memory.provenance viewer De onde veio a linha ativa: trace de origem, escritor, classe da origem e a conversa da qual foi extraída.
memory.evidence viewer Os turnos de origem dos quais um fato foi extraído, com o trecho que o sustenta e como cada vínculo foi criado.
memory.backlinks viewer O que aponta para uma linha: versões, digests, links tipados de entrada e saída, contagem de evidências, entidades vizinhas.
memory.lineage viewer O histórico de promoção de uma memória compartilhada: quem a promoveu, a partir de quais linhas e por qual revisão.
memory.verify writer Atesta que uma linha é verdadeira em nome da pessoa ou da conta de serviço autenticada, ou revoga a atestação.
memory.redact admin Remove (oculta) o valor sensível de uma versão histórica, mantendo a linha e sua entrada de auditoria.
namespace.rollback admin Retorna todos os heads de memória de um namespace à versão que tinham em um ponto no tempo.
namespace.snapshot admin Exporta o estado curado de um namespace como um payload JSON.
namespace.restore viewer Importa um snapshot para um namespace novo, ou para um existente que o chamador administra; nunca para uma collection.

namespace.snapshot e namespace.restore não são ferramentas MCP. As listas de campos estão na referência de operações, em memória e namespace.

Versões: memory.history

loom.memory guarda o estado atual e é lida com FINAL, de modo que um merge mantém apenas a versão mais recente de cada linha. loom.memory_versions é um espelho somente de acréscimo (append-only), preenchido por uma materialized view a cada insert; é o histórico que memory.history, memory.redact e namespace.rollback leem.

Uma linha de histórico traz version (a época em nanossegundos da escrita), written_at, value, confidence, pinned, expires_at, tombstoned_at, redacted_at, redaction_reason, content_sha256, agent, actor e source_class. created_at é a primeira escrita da linha e se repete em cada versão. agent="*" abrange todos os escritores da chave.

from loom import Agent

async with Agent(org="acme", namespace="support", agent="auditor") as agent:
    for v in await agent.memory.history("customer/4812/plan", agent_id="*"):
        print(v["written_at"], v["actor"], v["source_class"], v["value"])

Um tombstone também é uma versão, então uma exclusão aparece no histórico e memory.restore pode reviver a chave em até 14 dias. Para leituras do estado atual em um ponto no tempo, use as_of em memory.get, memory.search e memory.ask (tempo de validade).

Quem escreveu: actor e source class

O servidor grava actor (human:<subject> ou process:<subject>) e source_class em cada linha, a partir do token e da operação. Os valores de source_class estão em conceitos de memória. Uma requisição só pode rebaixar sua classe para external, imported ou derived.

memory.provenance retorna os dois, além de:

  • source_trace e um source_kind derivado dele (conversation, extracted, observed, consolidated, app, manual, other);
  • o source_resource_id citado pelo autor da escrita;
  • o thread_id da conversa e thread_exists (falso quando o namespace não registra transcrições, ou a transcrição não existe mais);
  • os vínculos criados manualmente (memory.link) que tocam a linha.

Os resultados de busca trazem source_class e verified, que o termo opcional de confiança (LOOM_MEMORY_SEARCH_TRUST_WEIGHT) lê.

Evidência: de quais turnos um fato veio

A extração vincula cada fato aos seus turnos em loom.memory_belief_sources. memory.evidence(memory_key) retorna esses vínculos com o texto do turno (até 600 caracteres), o papel, o horário, o trecho de apoio (span) e a forma como o vínculo foi criado:

scope support_type Significado
cited extracted_from O extrator indicou o turno de apoio.
lexical lexical_support O servidor associou o fato ao turno que melhor correspondia.
window window Nada correspondeu; a janela de extração inteira é vinculada.
derived derived_from Linhagem da consolidação: o item é o texto da memória de origem.

A resposta contabiliza os vínculos por escopo, de modo que uma verificação consiga distinguir um fato citado de um vinculado de forma frouxa. Para a redação exata de uma conversa, memory.recall pesquisa os turnos armazenados (extração).

Linhagem

  • memory.consolidate e os resumos periódicos gravam um link derived_from por fonte em loom.memory_belief_sources; memory.evidence os retorna como itens derived.
  • O resumo de uma sessão lista as chaves que ele comprimiu (derived_from em um resultado summary).
  • memory.lineage (scope="shared") percorre a promoção de uma memória compartilhada: o evento, quem a promoveu, as linhas de apoio, o candidato a aprendizado de onde ela veio, quando há correspondência (match_confidence exact ou inferred), e os eventos de auditoria. mechanism é review, import, auto ou unknown.
  • memory.backlinks é o inverso: o que aponta para uma linha.

memory.delete aposenta um resumo consolidado cujas fontes foram todas removidas e rebaixa para conflicted um resumo que ainda tem fontes remanescentes.

Atestação: memory.verify

pinned e confidence não dizem quem verificou um fato. memory.verify registra isso: o ator do token do chamador e o hash de conteúdo que ele atestou. Enderece a linha por memory_id, ou por namespace e memory_key com a identidade do writer. Exige permissão de writer no namespace da linha.

memory.get e memory.get_by_id retornam verification, derivado do hash armazenado e do hash atual da linha:

verification Significado
human Uma pessoa atestou e o conteúdo não mudou desde então.
process Uma conta de serviço atestou e o conteúdo não mudou desde então.
stale Alguém atestou, e o conteúdo mudou desde então.
none Nunca foi atestado, ou foi revogado.
  • Uma edição não limpa uma atestação; ela a torna stale até que alguém verifique novamente.
  • revoke=true a limpa. Verificar novamente uma linha inalterada pelo mesmo ator não faz nada (changed=false).
  • O prefixo human: vem do token, então um agente não pode marcar sua própria escrita como human. O actor do corpo só é lido no modo dev sem autenticação.
  • Snapshots e restaurações carregam as colunas de atestação; uma restauração nunca remove verified_by.

Apagando o histórico: memory.redact

memory.redact(memory_id, version) oculta o texto de uma versão histórica em todos os lugares onde ele foi copiado, e também todas as versões de perfil que um modelo construiu a partir da memória. Ele grava redacted_at e redaction_reason, e mantém as linhas e suas entradas de auditoria. Use-o para um segredo ou um dado pessoal que vazou para uma versão anterior. Aqui, redigir significa remover ou ocultar conteúdo sensível por motivo de privacidade, não escrever nem compor texto.

Onde O que acontece
loom.memory, loom.memory_versions value passa a ser "[REDACTED]"; value_json, evidence, entities e concepts são limpos.
loom.memory_embeddings, loom.memory_chunks As linhas cujo trecho ou hash de chunk não é o da versão atual (head) são excluídas; as linhas da versão atual permanecem.
As versões de perfil do usuário construídas a partir da memória Toda versão cujo trace cita a memória tem o conteúdo ocultado do mesmo modo, inclusive a versão atual, junto com as linhas derivadas da sua chave.
loom.shared, uma cópia promovida a partir da chave Toda versão cujo value é o texto ocultado pela redação passa a ser "[REDACTED]", e suas linhas de busca são excluídas. Uma cópia ativa continua promovida até que um administrador a rebaixe.

Fora do escopo: tags, arquivos, content_sha256, loom.memory_evidence (pertence ao apagamento definitivo), as tabelas de linhagem (apenas ids e hashes) e o grafo de entidades. Uma cópia compartilhada é deixada como está enquanto a versão atual também contém o texto ocultado (uma edição revertida byte a byte).

  • Ele recusa a versão atual da memória (refused_head=true): exclua ou reescreva a chave antes. Um perfil ativo com conteúdo ocultado fica fora de renderizações, packs e buscas de perfil até que o worker o reconstrua.
  • Os dois modos de lock o recusam, tanto na chave da própria memória quanto em qualquer chave de perfil que ele alcance.
  • Ele exclui as respostas em cache de memory.ask e code.ask e os precedentes que citaram a chave ou a chave de uma cópia compartilhada (cache_rows_deleted, precedent_rows_deleted). Para uma chave de perfil que ele alcance, a exclusão vale para toda a organização: o perfil de cada usuário tem a mesma chave, então ele limpa toda resposta em cache e todo precedente da organização cuja janela continha essa chave, em todos os namespaces.
  • O namespace é verificado depois da busca; uma recusa responde redacted=false, não 403.
  • Uma versão que não existe responde redacted=false e não oculta nada, nem mesmo versões de perfil.
  • Ele executa um ALTER TABLE … UPDATE síncrono nas duas tabelas de memória (e em loom.shared quando uma cópia ainda contém o texto) e um DELETE leve nas linhas derivadas: uma chamada administrativa.

Escritas que concorrem com a redação de uma cópia compartilhada (a limpeza de privacidade do histórico):

  • uma linha de busca que o worker de embeddings grava depois da limpeza, a partir de um stub que ele leu antes, permanece até a próxima redação dessa chave; uma escrita comum não é o gatilho de limpeza;
  • uma promoção da chave perde sua linha de busca até ser promovida novamente;
  • um rebaixamento que leu a cópia antes da limpeza grava seu tombstone com o texto, que permanece até que essa versão específica seja redigida novamente; uma escrita comum não é o gatilho de limpeza.

Uma cópia que uma promoção posterior da sua chave substituiu, e que o loom.shared já mesclou e descartou, não é mais encontrada: sua linha de busca, que o FINAL não serve mais, permanece até uma limpeza posterior da chave, e as respostas em cache sob uma chave diferente da ocultada permanecem até expirarem. Esse é o limite de uma redação feita em regime de melhor esforço.

Uma cópia cujo valor é "[REDACTED]" conta como uma que uma redação anterior já ocultou, então uma memória que contém esse texto por si mesma e foi promovida perde suas linhas de busca na próxima redação da sua chave.

O alcance sobre perfis e seus limites estão em segurança. Para remover os dados de uma pessoa em todos os lugares, use apagamento definitivo.

Revertendo um namespace: namespace.rollback

namespace.rollback(as_of) reinsere, para cada chave, a versão mais alta igual ou anterior a as_of como a nova versão principal (head), e marca com tombstone as chaves criadas depois dela. A reversão em si gera novas versões, então pode ser desfeita da mesma forma.

  • Por padrão é uma simulação (dry run), que informa reinstate, remove e sample; dry_run=false a aplica.
  • memory_keys (até 500) restringe o alcance; max_keys (padrão 5,000) limita uma chamada e truncated indica que é preciso chamar novamente.
  • O embedding_worker gera novamente os embeddings das versões principais reinstaladas.
  • Um as_of mais antigo que o histórico do namespace, ou no futuro, é recusado.
curl -sX POST http://localhost:7777/v1/namespace.rollback \
  -H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"org":"dev","namespace":"local","as_of":"<YYYY-MM-DD>T09:00:00Z"}' \
  | jq '{reinstate, remove, truncated, sample}'

Snapshots: namespace.snapshot e namespace.restore

namespace.snapshot exporta o estado curado de um namespace como JSON: cada linha de memória com version, content_sha256, actor, source_class, colunas de validade e de atestação, a configuração por tipo, as concessões (grants) e até include_audit_tail_n linhas recentes de auditoria (padrão 1,000). include_embeddings é false por padrão, portanto o destino gera novamente os embeddings com o próprio modelo.

namespace.restore(target_namespace, payload) grava o payload de volta como linhas de versão. É idempotente em snapshot_id (uma nova execução responde restored=false). Ele restaura em um namespace novo (o chamador passa a ser admin; é recusado para um nome sem linha que já contenha dados ou concessões, a menos que o chamador já o administre) ou em um namespace que o chamador administra; rebind_agent reatribui o escritor de cada linha. As linhas restauradas são imported.

Um snapshot não é um backup de implantação; consulte backup e recuperação.

O log de auditoria

Toda escrita que cria ou altera a memória deixa uma linha apenas com hash em loom.audit_log (chave, id, hash do conteúdo, ator, classe da fonte, veredito; nunca o valor). Checkpoints a cada hora encadeiam o log. Veja auditoria.

Limites

  • A remoção de conteúdo sensível (redact) de uma versão que foi mesclada é feita em regime de melhor esforço em loom.memory; o espelho é limpo de qualquer forma.
  • O histórico só é tão completo quanto o espelho. Uma coluna adicionada a loom.memory deve ser adicionada a loom.memory_versions e à sua view na mesma migration.
  • A validade considera apenas o valid-time. knowledge_time reproduz created_at em relação aos carimbos de desativação (invalid_at) e de exclusão (tombstoned_at); não existe uma tabela separada de transaction-time.
  • thread_exists=false não é um erro.
  • Um rollback não restaura chaves excluídas definitivamente (skipped_no_head).

Relacionados