Memória
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.
Uma memória é uma afirmação que um agente deve conseguir encontrar de novo: “os deploys acontecem às terças-feiras”, “a equipe de pagamentos é responsável pelo serviço de faturamento”. O Loom armazena cada afirmação como uma linha em loom.memory, sob uma chave legível, com informações sobre quem a escreveu, quando ela era verdadeira, de onde veio e se alguém a validou. Esta página explica a linha, como uma escrita é avaliada em relação ao que já está armazenado e como as linhas mudam ao longo do tempo.
Recuperação e ranqueamento explica como as linhas são encontradas.
Linhas no ClickHouse
Memórias, chunks de documentos, turnos de conversa, arestas de entidades, símbolos de código, execuções, entradas de auditoria e solicitações de apagamento são todos linhas no ClickHouse, criadas por migrações numeradas que o servidor aplica na inicialização. Sob a
autoridade de memória no Postgres,
o Postgres guarda o estado ativo de memória e conhecimento, e o ClickHouse mantém os vetores, a busca e o histórico. Os originais dos documentos enviados também são linhas do ClickHouse
(loom.document_blobs), a menos que a implantação mantenha seus bytes em um bucket compatível com S3. Fora do ClickHouse, do Postgres e desse bucket, o Loom mantém os espelhos git do índice de código, um cache dos remotos que o ClickHouse registra, e os buckets de limite de taxa em um volume compartilhado.
- A tupla de identidade lidera as chaves de ordenação.
loom.memoryé ordenada por(org, namespace, agent, user_id, session_id, memory_key), então restringir uma leitura a um namespace é um intervalo da chave primária; um usuário só a restringe totalmente sob um agente nomeado, e uma sessão só sob um agente e um usuário nomeados. Identidades e namespaces descreve a tupla. - Um único mecanismo. Sob a autoridade padrão do ClickHouse, a busca vetorial, a busca lexical, a travessia do grafo, os filtros, a auditoria e o apagamento são SQL sobre as mesmas linhas, sem um segundo armazenamento para manter sincronizado. O custo é que toda leitura é uma consulta, e não um acesso chave-valor. Sob a autoridade do Postgres, leituras pontuais (por chave ou id, fora de um replay com
as_of) são respondidas pelo Postgres. - Uma escrita é uma nova versão. As tabelas de memória são
ReplacingMergeTree(version)lidas comFINAL. Uma revisão, tombstone, fixação ou restauração insere uma nova linha de versão.
O ciclo de escrita, derivação e leitura
- Escrita.
memory.setexecuta suas verificações (abaixo), gera o embedding do valor de forma inline e insere a linha da memória, a linha do embedding, chunks literais para valores longos e uma linha de auditoria apenas com hash. Se o embedding inline falhar, a chamada falha e nada é gravado.memory.set_from_messagesfaz o LLM escolher os fatos duráveis de uma transcrição e grava pelo mesmo caminho em lote. - Derivação. Os workers adicionam o que é lento demais para o caminho de escrita: tags de entidade (
entity_extractor), extração adiada (extraction_queue), fatos consolidados, recalibração do gate e o uso incorporado aos sinais de ranqueamento (usage_fold). As linhas derivadas carregamsource_class=derived. - Leitura.
memory.searchexecuta várias etapas (vetorial, lexical, grafo de entidades, chunks literais, resumos de sessão), as combina, ranqueia e retorna resultados ou se abstém.memory.askescreve uma resposta fundamentada;context.packmonta um bloco de prompt com orçamento definido. - Retroalimentação. Uma execução que indica as memórias em que se baseou (
run.completememories_used, oumemory.outcome) credita essas memórias; um resultado ruim registra dano. Isso se torna um termo de ranqueamento limitado e com decaimento. Ele nunca exclui uma linha nem a coloca abaixo da sua relevância.
O ciclo tem consistência eventual. Uma leitura logo após uma escrita encontra o fato por meio do embedding inline; entidades e fatos extraídos chegam após a próxima passada do worker.
A linha loom.memory
Uma linha é uma versão de uma memória.
| Grupo | Colunas | Decide |
|---|---|---|
| Identidade | org, namespace, agent, user_id, session_id, run_id |
Quem pode lê-la e quem a escreveu |
| Endereço | memory_key, memory_id |
Como um chamador a nomeia (key) e como o Loom nomeia uma linha (id) |
| Conteúdo | value, memory_type, tags, entities, files, confidence |
O que ela diz e como é classificada |
| Ciclo de vida | status, pinned, conflict_with, duplicate_of, superseded_by, version |
Se ela é servida e o que a substituiu |
| Tempo | created_at, updated_at, valid_at, valid_to, invalid_at, expires_at |
Quando foi escrita, quando era verdadeira, quando saiu de serviço |
| Proveniência | actor, source_class, content_sha256, verified_by, verified_sha256 |
Quem a escreveu, como o Loom a aprendeu, se alguém a atestou |
| Proteções | lock_mode, lock_until, sensitivity, on_expire |
Quais escritas ela recusa e como é lida |
A lista completa de colunas está na referência do schema. Uma
memória pesquisável também tem uma linha em loom.memory_embeddings: vetores para o valor e para a chave,
cópias do trecho em minúsculas, com stemming e lematizadas para correspondência lexical, e as
flags source_class e verified que o ranker lê.
Chaves
Uma chave nomeia um atributo de um sujeito, como um caminho legível <scope>/<kind>/<id>:
sre/case/1234/evidence/dns-sidecar
project/loom/deploy-window
user/preferences/editor
- Um fato por chave. As verificações de conflito, a substituição e o histórico funcionam por chave. Uma chave que guarda uma lista de fatos não relacionados não pode ser revisada em parte.
- Uma revisão reescreve a mesma chave. O Loom mantém todas as versões, então uma cópia numerada (
…-v2) ou uma chave criada a partir de um hash do valor apenas esconde a revisão. Chaves criadas por hash são o achadohash_keysdenamespace.audit. - Facetas vão em
tagseentities, não na chave.
A identidade de armazenamento é (org, namespace, agent, user_id, session_id, memory_key): a mesma chave gravada por dois agentes ou em duas sessões resulta em duas linhas. Sob a política de namespace newest_wins, a gravação mais recente de uma chave aposenta toda linha ativa mais antiga com essa chave no namespace, não importa quem a gravou. A extração gera as chaves a partir do sujeito e do atributo, nunca do valor, de modo que uma sessão posterior que declare o mesmo atributo cai na mesma chave. Sob auto_reinforce e manual_review, o resolvedor de conflitos julga as linhas de uma mesma chave que duas sessões do mesmo usuário gravaram (não o usuário anônimo - nem um user_id enviado vazio, cujas sessões são tarefas separadas), seja por gravação pontual ou em lote, como julga qualquer par próximo: ele aposenta a linha mais antiga de uma atualização da qual tem certeza (exceto sob manual_review), sinaliza uma contradição para revisão e deixa ativos dois fatos diferentes sob uma chave reutilizada. Sob append_only, nada é julgado.
Tipos de memória
memory_type é uma string livre, com padrão semantic. Alguns valores mudam a forma como a linha é
armazenada e encontrada (server/memory/domain/memory_types.py):
| Tipo | Embedding | Na busca sem filtro | Use para |
|---|---|---|---|
semantic (padrão) |
sim | sim | Fatos duradouros. |
preference |
sim | sim | Preferências que devem ter destaque na recuperação. |
procedural |
sim | sim | Procedimentos (procedure.*). |
reflection |
sim | não | Lições aprendidas em execuções; leia com memory_type="reflection". |
episodic |
não | não | Eventos de sessão reproduzidos por recência. |
profile |
não | não | Contexto sempre carregado, obtido por label (profile.*). |
qualquer outro (decision) |
sim | sim | Tipos de domínio podem ser pesquisados por padrão. |
- Reflexões ficam ocultas da busca sem filtro e de
memory.ask: uma lição sobre um processo não é uma afirmação sobre o mundo. - Uma escrita
proceduralcujo valor não seja um corpo de procedimento (umsituationnão vazio e pelo menos doissteps) é armazenada comosemantic, com a tagretyped_from:procedural, e a resposta informa isso emretyped_from. - Sensibilidade. Uma linha com
sensitivity="high"nunca recebe embedding, portanto nenhuma etapa de busca a encontra. Ela só pode ser lida pela chave, e essa leitura é auditada. Comsensitivitynão definido, o servidor detecta formatos de credenciais, números de cartão, números de Social Security dos EUA e PINs informados (high), além de formatos de email, telefone e IBAN (medium) (LOOM_MEMORY_SENSITIVITY_AUTODETECT).
Situação
| Situação | Significado | Servido por padrão |
|---|---|---|
active |
A crença vigente. | sim |
conflicted |
Próxima de uma linha par, mas dizendo algo diferente; ligada por conflict_with. |
sim |
duplicate |
Quase idêntica a uma linha canônica (duplicate_of), que responde por ela. |
não (include_duplicates) |
superseded |
Uma linha posterior a substituiu (superseded_by, encerrada em invalid_at). |
não (include_superseded) |
proposed |
Um fato em teste, decidido com memory.proposal_decide. |
não (include_proposed) |
rejected |
Marcada como incorreta (memory.reject, ou uma proposta rejeitada). |
não |
tombstoned |
Excluída por quem a escreveu (memory.delete). |
não |
O conjunto servido é definido em um único lugar, em server/memory/domain/temporal_sql.py (SERVED_STATUSES). Uma
linha em conflito continua sendo servida: ocultar um dos lados de uma contradição faria o armazenamento
responder com confiança usando um fato sobre o qual ele tem motivos para duvidar.
Como uma escrita é julgada
Cinco operações cobrem o ciclo de vida da memória:
| Lente | Operação | Efeito |
|---|---|---|
| Expandir | memory.set |
Aprende um fato sob uma chave. |
| Revisar | memory.update_by_id |
Corrige uma linha por id (memory.update faz o mesmo por chave). |
| Contrair | memory.delete |
Marca uma chave com tombstone. memory.restore a revive até 14 dias após a exclusão. |
| Reforçar | memory.pin |
Armazena e fixa: nenhuma escrita posterior que não fixe a si mesma a substitui. |
| Recusar | blacklist.add |
Recusa toda escrita futura que corresponda a uma substring ou regex. |
Um memory.set pesquisável executa estas verificações, em ordem:
- Proteções de lock e pin na linha sob a chave.
memory.lock(read_onlyouno_delete) responde 423LOCKED. Um valor alterado sob uma chave fixada é 409PINNED_CONFLICT. Uma repetição idêntica byte a byte passa por todas as proteções. - Blacklist. Um valor que corresponda a um padrão registrado é 422
BLACKLISTED; em uma escrita em lote, a entrada é ignorada. As réplicas mantêm os padrões em cache e consultam uma tabela de versão de uma linha (loom.blacklist_version), então um novo padrão chega a todas as réplicas em segundos. - Pré-condição.
if_match_sha256faz a escrita ser aplicada somente se o hash da linha ativa ainda corresponder; caso contrário, 409PRECONDITION_FAILED. O hash atual vem em toda resposta dememory.get,memory.get_by_idememory.set(content_sha256). - Repetição. Um valor idêntico byte a byte ao da linha ativa grava uma nova versão que
carrega o
reinforcement_count + 1da linha ativa. O caminho em lote (memory.bulk_set, usado porset_from_messages) trata qualquer linha ativa com o mesmo hash em(org, namespace, agent, user_id)como o fato (LOOM_MEMORY_BULK_DEDUP_SCOPE=identity). - Busca de pares e veredito. Linhas ativas do mesmo
memory_typecujo embedding está próximo do novo valor são pares, comparados do mais próximo ao mais distante; uma escrita que informa seuuser_idtoma os pares somente das linhas desse usuário (como uma escrita é julgada):- mesma forma canônica (minúsculas, pontuação removida, espaços colapsados) →
merge: nada é gravado, o par é reforçado,merged_into_keyo nomeia; - um par fixado próximo →
rejected, 409PINNED_CONFLICT(sob um token de todo o namespace, uma escrita que informa seu usuário e repete o valor fixado de outro usuário ou compartilhado é gravada); - sob
newest_wins, um par que declara o mesmo sujeito e predicado com um objeto diferente →refines: o par é retirado, a menos que seuvalid_atseja posterior ao da nova linha, o que respondeconflict; - cosseno igual ou acima do limiar de duplicata, com as mesmas palavras de conteúdo e sem
valor divergente (número, hora, quantia ou unidade; “27:10” / “26:30”) →
duplicate; - cosseno igual ou acima do limiar de conflito, mas diferente →
conflict, ambas as linhasconflicted; - nenhum par próximo →
clear.
- mesma forma canônica (minúsculas, pontuação removida, espaços colapsados) →
- Inserção em
loom.memoryeloom.memory_embeddings, substituição (supersession), projeção de entidades e uma linha apenas com hash emloom.audit_log.
Um tipo não pesquisável ou uma linha de sensibilidade high pula a busca de pares: não tem
embedding para comparar. dry_run=true executa todas as verificações e não grava nada, o que
responde “fato novo, repetição ou contradição?” antes de você se comprometer com uma chave. A
resposta traz conflict_verdict, até cinco peers e uma dica next.
- Limiares. Com
LOOM_ADAPTIVE_THRESHOLDSativado e um embedder real, os limiares de conflito e de duplicata vêm da distribuição de similaridade do próprio embedder na inicialização (server/memory/app/embedder_calibration.py). Os escalaresLOOM_CONFLICT_THRESHOLD(0.85) eLOOM_DUPLICATE_THRESHOLD(0.97) são o fallback. Um namespace ou tipo de memória pode fixar o seu;calibration.getinforma qual está em vigor. - O resolvedor de conflitos. O cosseno diz que duas afirmações tratam da mesma coisa, não
se elas concordam. Um worker exclusivo do líder julga, depois que a escrita é gravada, cada
escrita que tem um par próximo, com uma chamada de LLM por linha: ele retira a linha mais
antiga de uma atualização da qual tem certeza sob o padrão
auto_reinforcee sobnewest_wins(o valor antigo continua legível cominclude_supersededeas_of), sinaliza uma contradição e limpa um sinal falso (conflitos). Nenhum veredito sobre a própria escrita chama um LLM. - Escopo de execução. Uma escrita sob um
run_idcuja correspondência canônica pertence a outra execução é armazenada comoduplicate, não mesclada, de modo que uma leitura com escopo de execução ainda a encontre. - Política do namespace.
default_conflict_policydecide o que uma contradição faz (auto_reinforce,manual_review,newest_wins,append_only).
memory.update, memory.update_by_id e memory.bulk_set executam a mesma verificação. Os
detalhes dos vereditos, as políticas, a fila de revisão e conflicts.resolve estão em
conflitos e recusa.
Pins protegem o que o usuário disse. Uma linha fixada nunca é substituída por uma escrita
que não fixe a si mesma, seja por chave, seja por um valor próximo sob outra chave. Para
alterá-la, use memory.update (mantém o pin) ou memory.pin (fixa de novo).
memory.for_file lista as linhas fixadas primeiro; nenhuma outra leitura ordena pelo pin.
A consolidação preserva a linhagem. memory.consolidate (e o worker de consolidação,
quando um namespace opta por ele) mescla fragmentos sobre um mesmo assunto em linhas
canônicas com source_class='derived' e grava uma linha em loom.memory_belief_sources por
fonte (support_type='derived_from'). Excluir uma fonte retira uma linha consolidada quando
nenhuma de suas fontes sobrevive e a rebaixa para conflicted quando alguma sobrevive
(dependents_tombstoned, dependents_downgraded na resposta de memory.delete).
O ciclo de vida de uma memória
Toda seta é uma nova versão; a antiga permanece em loom.memory_versions.
Tags, entidades e arquivos
tagssão rótulos livres (case:1234,kind:evidence). Uma busca filtra por elas (tags), dá peso a elas (tags_soft) ou as rebaixa (demote_tags). Otag_registryde um namespace pode associar a uma tag uma política de retenção, de deduplicação e de conflito. As tags mantêm a caixa em que foram escritas:memory.listeknowledge.listas comparam sem diferenciar maiúsculas de minúsculas, e todos os outros filtros de tag, incluindomemory.searchememory.apply, as comparam exatamente.entitiessão as coisas nomeadas que o valor menciona, armazenadas na forma canônica em que a busca as lê (em minúsculas; artigos, possessivos e pontuação removidos; o substantivo principal no singular), de modo queBilling Servicesebilling servicesão uma só entidade. Quem escreve pode passá-las; caso contrário, o workerentity_extractoras preenche. Elas alimentam o peso por entidade e o grafo de entidades.filessão caminhos do repositório sobre os quais a memória trata;memory.for_fileos serve antes de uma edição desses arquivos.
memory.for_file renderiza uma linha por memória. Uma decisão ou uma restrição é impressa inteira,
até o limite abaixo, e não conta contra o token_budget da requisição (300
tokens por padrão); as demais linhas ficam sujeitas a ele, cortadas em uma linha de 220 caracteres. Uma
linha que não cabe é deixada de fora por inteiro, enquanto as linhas seguintes ainda têm a sua vez,
e uma linha final - … <n> more, que também conta contra o orçamento, informa quantas
foram deixadas de fora e como listá-las. O cabeçalho e o rodapé de remoção são sempre
impressos, e a linha … more sempre que uma linha é deixada de fora; por isso um orçamento menor que esses itens pode ser excedido.
Decisões e restrições compartilham um único limite, memory_for_file_whole_tokens (1,500
tokens, cerca de 6,000 caracteres), de modo que um arquivo regido por dezenas delas não consiga inundar o
prompt. Elas são impressas na ordem do bloco; uma que ultrapassaria o limite é deixada de fora,
e as seguintes que ainda couberem são impressas. Uma linha final conta as que ficaram de fora e
nomeia as cinco primeiras chaves, cada uma lida com memory.get (no namespace que ela nomeia, para uma
linha de equipe) ou encontrada com loom_search. Uma linha deixada de fora junto com a linha mais nova que a substitui
é contada na linha … more, nunca nomeada como uma linha a ser lida. O padrão
mantém o bloco inteiro abaixo dos 10,000 caracteres que um host de agente de código passa de um hook
ao modelo como estão.
Cada linha:
- Uma memória de um namespace extra (o namespace de código do repositório) recebe o cabeçalho
Team rule (by <author>, <age>), ouDecision (by <author>, <age>)para uma decisão (memory_typedecisionou a tagdecision). - Uma linha lista seus tipos
constraint,gotchaedecisionem um único colchete ([constraint, decision]; uma linha com o cabeçalhoDecisionomitedecision). (pinned)marca uma linha fixada. A fixação é um sinalizador da própria linha: um membro de um namespace de código pode defini-lo em uma linha que escreva ali, de modo que(pinned)em uma linha de equipe diz que alguém a congelou, não que um mantenedor o fez.- Uma decisão que ninguém fixou, como uma escrita por
loom decisions extract, não traz marca de fixação: ela é servida como está. (outcome: failed)marca qualquer decisão cujo resultado registrado foi falha, fixada ou não.- Uma decisão com a tag
source-changed(seu documento de origem não a diz mais; veja extração de decisões) aparece como(source changed), fixada ou não. - Uma nota informa quando o código vinculado mudou ou foi removido.
- Um valor de string é impresso como texto, não como o JSON em que está armazenado, e uma linha que não seja
decisão ou restrição termina em
…quando a leitura ou a linha a cortou; um objeto ou lista cortado é impresso como está armazenado. - Uma decisão com origem traz
— source: <source_resource_id>após o valor, inteiro, de modo que uma citaçãoknowledge:mantém seu#sectione é resolvida porknowledge.get. - Uma linha mais nova que a verificação de conflito vinculou a uma mais antiga do seu tipo é colocada acima dela,
e uma linha de equipe diz qual ela substitui (
supersedes decisionquando a mais antiga tem a tagdecision). Duas decisões tipadas que a verificação vinculou mantêm cada uma seu lugar no bloco, sem essa nota, pois cada chave de decisão é uma decisão própria. Quando o orçamento ou o limite deixa de fora qualquer linha que substitui outras, em qualquer namespace, toda linha que ela substitui é deixada de fora junto, para que uma linha mais antiga nunca seja lida como atual.
Memórias vinculadas ao código
O que isso oferece a um agente de código e por onde começar: memória vinculada ao código.
Uma memória sobre código é vinculada às definições e aos arquivos que ela nomeia, e os vínculos
acompanham o código. O worker memory_code_links vincula cada memória marcada com repo:<id>
(os plugins de código marcam suas sessões) ou escrita no namespace de código de um repositório
ao trunk desse repositório:
- cada nome entre crases,
A::be chamadaa.b()que resolve para exatamente uma definição; osfilesda memória desempatam entre homônimos, e um nome definido mais de uma vez não é vinculado; - uma palavra solta em camelCase ou snake_case da prosa, apenas a uma definição nos
filesda memória; - cada arquivo que a memória nomeia e que não contém nenhuma dessas definições.
Um nome qualificado que o trunk ainda não define espera memory_code_links_pending_days
(14), de modo que uma memória sobre código não integrado é vinculada quando ele for integrado.
Um vínculo registra a impressão digital (fingerprint) da definição: todas as suas sobrecargas e as condições que
as selecionam, como tokens. Assim, espaços em branco, comentários (exceto uma diretiva //go: do Go ou um
comentário # type: do Python) e a maior parte do que os formatadores alteram (vírgulas finais e outros
separadores opcionais, um ; em JavaScript, o estilo de aspas e os escapes que ele exige, a caixa de um
literal numérico, a indentação de uma docstring em Python, parênteses em Python, JavaScript e
TypeScript) não alteram a impressão digital. Juntar literais de string adjacentes, ou qualquer outra edição, altera.
O que um arquivo define é lido do arquivo no head indexado do repositório em seu
espelho git bare. A cada commit indexado, o worker acompanha as renomeações e edições do commit:
| Estado do vínculo | Quando |
|---|---|
fresh |
A definição está onde estava, com o texto contra o qual a memória foi escrita. |
moved |
Seu arquivo foi movido, ou ela foi renomeada sem nenhuma outra alteração, ou foi movida para outro arquivo. |
changed |
Seu texto mudou depois que a memória foi escrita (changed_since nomeia o commit), renomeada ou não. |
unresolved |
Seu nome sumiu e uma nova definição em seu lugar pode ser ela, mas nenhuma é com certeza. Servida, com um sinal de revisão. |
missing |
O código sumiu: nada novo tomou seu lugar. O vínculo mantém seu lugar, de modo que um revert o encontra de novo. |

O detalhe de uma memória no painel lista esses vínculos com seu estado (clipe).
Um vínculo acompanha sua definição por movimentações de arquivo, renomeações (com uma edição, quando o novo
nome está relacionado ao antigo) e pela renomeação de sua classe dentro do arquivo. Um homônimo em
outra classe ou namespace nunca herda um vínculo, e um vínculo missing só volta
quando seu próprio nome volta. Um nome que sumiu de seu arquivo é procurado nos arquivos alterados
desde sua última verificação, como o espelho os mantém, ao lado do índice, de modo que uma definição movida por
um commit que o índice não absorveu por inteiro (acima de code_ingest_max_files_per_commit) é
acompanhada quando o vínculo é reverificado. Quando memory_code_links_mirror_naming_files ou mais
desses arquivos o nomeiam, ou mais de memory_code_links_mirror_changed_files arquivos mudaram
sob os prefixos da entrada, ou o diff não pode ser lido, ou os caminhos são mais do que o git
aceita em um comando ou pesquisa dentro do seu tempo, o espelho não acrescenta nada e o índice
decide. Quando o git não consegue executar a busca, ou uma definição que ele encontra não pode ser
convertida em impressão digital, um vínculo ativo que os homônimos do índice não resolvem fica unresolved. Arquivos que a
ingestão não indexaria (fora dos path_prefixes da entrada, recusados por sua denylist,
acima do limite de bytes, binários) não adicionam nenhuma definição; um arquivo gerado, que a ingestão declara
sem pesquisar seu texto, adiciona. Um arquivo em que o parser falha mantém seus vínculos como estavam
até que seja interpretado. Quando as regras de impressão digital mudam, todo vínculo é recalculado a partir dos
commits em que seus hashes foram obtidos. Quando seu texto antigo some do git, um vínculo que coincidia com
ele assume o texto que a próxima verificação encontrar, e um já alterado continua changed; um cujo texto antigo
não é mais interpretado mantém seu último estado, e o worker o reporta.
O Loom nunca escreve na memória. O code_change_policy do namespace
(namespace.register) decide o que as leituras fazem com uma mudança:
| Política | Código removido | Código alterado |
|---|---|---|
retire_removed (padrão) |
Quando todos os vínculos de uma memória são missing (um vínculo pendente ou unresolved conta como não), a busca (e memory.ask, context.pack) a deixa de fora antes de escolher seus resultados; memory.get ainda a mostra. Ela volta quando o código volta. |
Sinalizado. |
flag |
Sinalizado. | Sinalizado. |
revise |
Como retire_removed. |
A afirmação é reverificada pelo LLM contra o código antigo e o novo: uma que se sustenta é reancorada, uma contradita recebe uma afirmação corrigida como suggestion do vínculo. |
Em qualquer política, uma memória que uma busca ainda serve fica em posição inferior quando seu pior vínculo
é changed, unresolved ou missing: ela desce abaixo das próximas
memory_search_code_changed_places (3) linhas ranqueadas por score (uma linha que também desce,
ou já desceu, não é contada), nunca saindo dos resultados nem ficando abaixo de uma linha servida apenas
como preenchimento (abaixo do piso de similaridade, ou sinalizada abaixo do limiar de abstenção), depois que as
verificações de confiança e de abstenção as leram em ordem de relevância;
score_components.code_changed_places diz quantas posições ela desce entre as linhas da própria busca
(loom_search posiciona suas decisões de repositório mescladas por similaridade entre as linhas que sua
busca não rebaixou). Nunca são rebaixadas:
- uma memória que uma pessoa mantém;
- uma memória cujos únicos vínculos desse tipo são para código que o chamador não pode ler, ou são vínculos
que nada mantém atualizados (
memory_code_links_enableddesligado); - uma linha posicionada por uma correspondência de identificador ou por uma camada
anchor_firstourecent_first, cuja movimentação também não conta como posição; - toda linha que uma busca serve para uma consulta cuja resposta é uma ordem de datas
(as decisões de repositório mescladas de
loom_search, posicionadas por similaridade, ainda descem); - as linhas de uma página posterior (
page=<handle>), servidas em sua ordem estacionada; - um hit de chunk, registro ou resumo, que não carrega
code_state.
Um bloco de leitor (render="reader", o bloco de loom_search) cuja pergunta traz uma palavra de tempo
(when, after, since, latest, …) lista suas linhas por data, então a
movimentação não aparece nele; results mantém a movimentação.
memory.ask reordena as linhas da busca por similaridade e recência enquanto
memory_ask_recency_weight for maior que 0 (0.2 por padrão), e suas consultas
por identificador posicionam suas próprias linhas; uma leitura de inicialização de context.pack sem consulta não
faz busca. Uma movimentação não aparece em nenhum desses casos.
revise julga um vínculo alterado uma vez por edição, dentro de um orçamento por passagem
(memory_code_links_revise_per_pass). Uma memória rotulada com sensibilidade high nunca é enviada
ao modelo. Uma memória que uma pessoa fixou, bloqueou (até o bloqueio expirar) ou verificou, e
uma que nomeia mais código do que o limite de vínculos, é apenas sinalizada. Vínculos feitos para um valor anterior
de uma memória (seu texto, arquivos, repositório ou usuário) são ignorados por toda leitura até que ela seja revinculada.
Os vínculos são mantidos contra o trunk. Em outro branch, uma lição compara a definição do próprio branch,
sob qualquer um dos últimos 16 nomes do vínculo, com o texto contra o qual a memória foi escrita:
um branch de release que ainda tem o texto antigo fica fresh depois que o trunk o alterou,
e um que tem código que o trunk removeu ainda recebe sua lição. Onde os arquivos do branch
não podem ser lidos (um host com LOOM_GIT_HISTORY=none não tem espelho git), uma lição carrega
o último estado do trunk.
Os vínculos são lidos onde o código está:
code.symbolanexa as memórias vinculadas comolessons, cada uma com seucode_state. Elas vêm do namespace da equipe do repositório e doslesson_namespacesque a chamada nomeia (via MCP, o memory home do chamador quando ela não nomeia nenhum), nunca de todos os namespaces que o chamador pode ler.code.search,code.callers,code.callees,code.impact,code.outlinee ocode.context_packde uma tarefa anexamlessonspara os principais arquivos da resposta (code_result_lessons_paths): dos mesmos namespaces, menos o namespace de código de qualquer outro repositório, as memórias vinculadas a código em cada arquivo ou que o nomeiam por seu caminho ou por um final dele (um nome de arquivo simples,search/handler.py; um caminho absoluto é considerado como nomeando um arquivo abaixo da raiz em que termina), cada uma com seucode_state, dentro decode_result_lessons_tokens. Cada linha carregapath,memory_key,namespace,excerpt,code_state,changed_since(o commit que colocou seu código em um estado changed, unresolved ou missing) quando conhecido, esupersedes_keyquando substitui uma linha mais antiga; uma linha que outra linha lida para a resposta substitui não é servida.lessons_left_outconta as linhas que o limite, um corte ou essa regra deixou de fora. Uma decisão ou restrição é servida inteira ou deixada de fora. A leitura roda depois da resposta, nunca entra no memo da busca, e é ignorada cominclude_lessons: false, comcode_result_lessonsdesligado, ou para um token restrito ao seu próprio usuário ou sessão.memory.for_fileserve memórias vinculadas a código no arquivo, ao lado daquelas cujosfileso nomeiam. Uma linha cujo código mudou, não foi encontrado de novo ou sumiu diz isso e nomeia o primeiro commit indexado em que isso apareceu; as linhas de decisão decontext.packcarregam a mesma nota, e suas linhas de memória um rótulocode_state=<state>@<commit>.memory.getretorna os vínculos comocode(com qualquersuggestion); os hits dememory.searchlidos da própria linha de uma memória carregam seu pior vínculo comocode_state(um hit de chunk, registro ou resumo não carrega nenhum e nunca é deixado de fora);memory.askanota as memórias cujo código foi movido, alterado ou sumiu.namespace.validatelista memórias cujo código mudou, não foi encontrado de novo ou sumiu, nos repositórios que o chamador pode ler.
Tempo
| Coluna | Eixo | Significado |
|---|---|---|
valid_at |
mundo | Quando o fato passou a ser verdadeiro, conforme declarado por quem escreveu. NULL = desconhecido. |
valid_to |
mundo | Quando o fato deixou de ser verdadeiro. Uma leitura descarta uma linha após o seu valid_to. |
temporal_anchor |
mundo | A data sobre a qual o fato trata (a data de um evento), definida pela extração. |
created_at |
registro | Quando o Loom gravou a linha. |
invalid_at |
registro | Quando o Loom aposentou a linha (substituição). |
tombstoned_at |
registro | Quando quem escreveu a excluiu. |
expires_at |
registro | Quando a linha sai do conjunto servido, caso quem a escreveu ou o dono do namespace tenha definido uma expiração. |
Uma leitura as_of reproduz um eixo. as_of_basis="valid_time" (o padrão) pergunta o que
era verdadeiro em T: linhas cuja melhor data do mundo (valid_at, senão temporal_anchor,
senão created_at) é igual ou anterior a T. as_of_basis="knowledge_time" pergunta o que o
Loom havia aprendido até T: linhas gravadas até T e não aposentadas, excluídas ou
invalidadas até T.
Sob newest_wins, uma substituição por template aposenta o par somente se o valid_at do
par não for posterior ao da nova linha, de modo que um backfill de fatos antigos não
aposenta os atuais. Isto é tempo de validade mais um carimbo de aposentadoria, não um
modelo bitemporal: é a substituição, e não a exclusão por data, que decide qual de duas
linhas é a atual. Um modelo de intervalos completo exigiria que todo agente que escreve
informasse quando cada fato terminou, o que os agentes raramente sabem.
Versões e histórico
Toda alteração (edição de valor, tombstone, restauração, bloqueio, mudança de status) é uma nova linha com um version em nanossegundos mais alto e todas as outras colunas copiadas da versão anterior. Os merges descartam as versões antigas, então loom.memory representa o estado atual, não um histórico.
O histórico fica em loom.memory_versions, um espelho somente de acréscimo (append-only) preenchido por uma materialized view a cada inserção. memory.history lê todas as versões de uma chave; namespace.rollback devolve todos os heads de um namespace à sua versão em um determinado momento; memory.redact apaga um valor histórico e mantém o registro de auditoria correspondente. O content_sha256 de cada versão é o que if_match_sha256 compara e ao que uma attestation se vincula.
Proveniência
O servidor registra duas colunas em cada escrita e nunca as aceita vindas do corpo da requisição:
actor:human:<subject>ouprocess:<subject>(uma conta de serviço), obtido do token.source_class: como o Loom passou a ter o conteúdo, a partir da operação e do token.
source_class |
Significado |
|---|---|
asserted |
Um chamador declarou o conteúdo diretamente (memory.set). |
extracted |
O pipeline de extração inferiu o conteúdo a partir de uma transcrição. |
observed |
O Loom registrou o conteúdo a partir de uma atividade que ele viu. |
derived |
Calculado a partir de outras memórias (saída de consolidação, resumos de sessão). |
imported |
Carregado de outro sistema por um importador. |
external |
Declarado pelo escritor como conteúdo externo: o resultado de uma ferramenta, uma página, um documento. |
Uma requisição só pode declarar um rebaixamento (derived, external ou imported); qualquer
outro valor resulta em 422. O texto que um agente copia do ambiente é o que um atacante controla,
então memory.ask mantém as linhas external sem atestação fora da sua síntese
(LOOM_MEMORY_ASK_EXCLUDE_UNVERIFIED_EXTERNAL, ativado por padrão), e
LOOM_MEMORY_SEARCH_TRUST_WEIGHT pode elevar no ranking as linhas afirmadas e as atestadas.
- Linhagem. A consolidação grava linhas em
loom.memory_belief_sources; um resumo de sessão lista as chaves que ele resumiu emsession_summaries.derived_from.memory.provenanceinforma de onde veio uma linha,memory.evidenceretorna os turnos da conversa dos quais um fato extraído foi obtido, ememory.lineagepercorre como uma memória compartilhada foi promovida. - Atestação.
memory.verifyregistra quem avalizou o conteúdo, vinculado ao seu hash. As leituras informamverification:humanouprocessenquanto o conteúdo não muda,staledepois que ele muda,nonese nunca foi atestado. Uma edição mantém a atestação e aparece comostale; ela nunca transfere confiança para o novo conteúdo.
O que vai onde
| É… | Plano | Por que não é memória |
|---|---|---|
| Um fato que continuará verdadeiro na semana que vem e que outra sessão precisa | Memória durável, memory.set |
É memória. |
| Uma transcrição que o usuário quer que seja lembrada | memory.set_from_messages (extração) |
Uma linha grande só pode ser encontrada como um todo; a extração grava um fato curto por chave. |
| O plano atual, um lease, um cursor, “onde eu estava” | Memória de trabalho, working_memory.* |
O estado de coordenação muda a cada passo; ranqueá-lo polui a recuperação. |
| Um resultado grande de ferramenta que você pode reler | context.offload / context.fetch |
É um blob a ser buscado por chave, não uma afirmação a ser ranqueada. |
| O estado retomável de uma linha de trabalho | Resumos de sessão, session.brief_* |
Um resumo é restaurado por escolha, nunca ranqueado na resposta de outra tarefa. |
| Um documento, especificação ou runbook; qualquer coisa com mais de alguns kilobytes | Conhecimento, knowledge.add / knowledge.upsert |
Os documentos são divididos em chunks por título; uma memória é gerada por embedding a partir de um trecho de no máximo 1,200 caracteres. |
| Um log de turnos de chat | Conversas, conversation.* |
Turnos são evidência, não crenças; memory.recall lê os turnos usados por uma extração. |
| Dados com identidade e campos exatos (um PR, um ticket) | Registros, memory.record.* |
Os registros são combinados campo a campo e filtrados com exatidão. |
| Persona ou preferências sempre carregadas | Perfil, profile.* |
Buscado por rótulo todas as vezes; ranqueá-lo contra perguntas desperdiça o espaço. |
Para documentos: armazene o documento em conhecimento e escreva uma memória curta, com uma
chave legível que diga o que ela é e aponte para ele. context.pack carrega a memória de
trabalho antes das seções duráveis, de modo que um agente veja primeiro o seu próprio estado.
Retenção
O Loom exclui apenas o que seu autor pediu. Nenhuma tabela de memória tem TTL padrão e nenhuma varredura remove linhas por idade. Uma linha sai do conjunto servido quando seu autor a exclui ou a substitui, quando seu autor definiu uma expiração (ttl_seconds, valid_to), ou quando o proprietário do namespace ou o operador configurou uma janela de retenção. memory.restore reativa uma tombstone em até 14 dias.
Retenção e eliminação abrange as configurações e a saga de eliminação.
Um fato ao longo do tempo
Em março, um usuário diz “Moro em Délhi”; em junho, “Me mudei para Berlim.”
- Escrita de junho. A extração gera a chave a partir do sujeito e do atributo, então as duas
afirmações caem na mesma chave. A linha de junho não sobrescreve a de março: a versão de Délhi
permanece em
loom.memory_versions, e pode ser lida commemory.history. - Um fato arquivado no lugar errado. Se Berlim cair sob outra chave, a busca por pares encontra
a linha de Délhi próxima, porém diferente, e marca ambas como
conflicted, ligadas porconflict_with. A política do namespace decide o que acontece depois (veja como uma escrita é avaliada). - “Onde a pessoa morava em abril?” Uma leitura com
as_ofresponde, tanto pelo momento em que o fato era verdadeiro quanto pelo que o Loom sabia naquela data (tempo). - “Quem disse isso?”
actoresource_classregistram quem escreveu e como o fato chegou;memory.evidenceretorna os turnos dos quais um fato extraído veio. - Uma importação ruim.
namespace.rollbackdevolve todos os heads do namespace à sua versão em um ponto no tempo, e roda como simulação (dry run), a menos que se indique o contrário.
Exemplo
Escreva um fato, teste uma alteração antes de gravá-la e depois atualize usando o hash que você leu:
import asyncio
import os
from datetime import datetime, timezone
from loom import Datapack
async def main() -> None:
dp = Datapack(
org="acme",
namespace="eng-tooling",
base_url=os.environ["LOOM_BASE_URL"],
api_key=os.environ["LOOM_API_KEY"],
)
agent = dp.agent("release-bot")
key = "project/billing/deploy-window"
out = await agent.memory.set(
memory_key=key,
value="Billing deploys only on Tuesdays and Thursdays, never on Fridays.",
tags=["kind:constraint", "service:billing"],
entities=["billing"],
valid_at=datetime.now(timezone.utc),
)
print(out["conflict_verdict"], out["content_sha256"])
probe = await agent.memory.set(
memory_key="project/billing/deploy-days",
value="Billing deploys only on Thursdays.",
dry_run=True,
)
if probe["conflict_verdict"] == "conflict":
peer = probe["peers"][0] # closest peer, with its key
current = await agent.memory.get(memory_key=peer["memory_key"])
await agent.memory.update(
memory_key=peer["memory_key"],
value="Billing deploys only on Thursdays.",
if_match_sha256=current["content_sha256"],
)
asyncio.run(main())
Um 409 PRECONDITION_FAILED na atualização significa que outro escritor alterou a linha depois da leitura: leia novamente e decida de novo. Via HTTP, a escrita é POST /v1/memory.set; via MCP, é a ferramenta loom_memory_set.