Histórico e proveniência
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.
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.

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_tracee umsource_kindderivado dele (conversation,extracted,observed,consolidated,app,manual,other);- o
source_resource_idcitado pelo autor da escrita; - o
thread_idda conversa ethread_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.consolidatee os resumos periódicos gravam um linkderived_frompor fonte emloom.memory_belief_sources;memory.evidenceos retorna como itensderived.- O resumo de uma sessão lista as chaves que ele comprimiu (
derived_fromem um resultadosummary). 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_confidenceexactouinferred), e os eventos de auditoria.mechanisméreview,import,autoouunknown.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
staleaté que alguém verifique novamente. revoke=truea 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. Oactordo 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.askecode.aske 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=falsee não oculta nada, nem mesmo versões de perfil. - Ele executa um
ALTER TABLE … UPDATEsíncrono nas duas tabelas de memória (e emloom.sharedquando uma cópia ainda contém o texto) e umDELETEleve 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,removeesample;dry_run=falsea aplica. memory_keys(até 500) restringe o alcance;max_keys(padrão 5,000) limita uma chamada etruncatedindica que é preciso chamar novamente.- O
embedding_workergera novamente os embeddings das versões principais reinstaladas. - Um
as_ofmais 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.memorydeve ser adicionada aloom.memory_versionse à sua view na mesma migration. - A validade considera apenas o valid-time.
knowledge_timereproduzcreated_atem 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=falsenão é um erro.- Um rollback não restaura chaves excluídas definitivamente (
skipped_no_head).