Otimizar um namespace a partir da sua auditoria
Otimizar um namespace a partir da sua auditoria
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.
Um escritor que usa memory.set como um object store (blobs JSON sob chaves de hash, leases como memórias, documentos como claims) deixa todas as tabelas consistentes e a recuperação inútil. Este procedimento reorganiza esse namespace no layout descrito no
guia do agente de investigação. Cada movimentação deixa um redirecionamento, de modo que um escritor em execução que ainda leia as chaves antigas continue recebendo respostas.
A skill loom-optimize nos plugins do Claude Code e do
Codex executa os mesmos passos.
As duas operações
namespace.audit (POST /v1/namespace.audit, MCP loom_namespace_audit, CLI
loom audit-namespace). Somente leitura.
| Entrada | Padrão |
|---|---|
org, namespace |
obrigatório |
window_seconds |
604800 (7 dias) |
sample_limit |
5 |
Ela retorna summary (live_rows, live_bytes, excerpt_bytes, version_rows,
version_bytes, unembedded_rows, gets, searches, sets, get_search_ratio e
inspector_calls: os gets e searches do painel e do conjunto de ferramentas do assistente, deixados
fora das contagens; uma escrita feita pelo painel é contada em sets),
findings[] (code, severity, count, share, bytes, samples[], detail,
remedy), skipped (regras que não puderam ser executadas: verificações, leituras do resumo, a leitura
de evidências; as demais ainda retornam), coverage, healthy (“nenhum achado crítico”) e as
contagens criticals / warnings / infos. As amostras trazem chaves, ids de linhas, colunas de identidade
e contagens, nunca um valor. Cada achado também traz os campos de
evidência; um plano lê
kind (uma heurística de uso não é prova de uso indevido), samples_complete e evidence[],
a version e o content_sha256 atuais de cada linha amostrada.
memory.move (POST /v1/memory.move, MCP loom_memory_move).
| Entrada | Padrão |
|---|---|
org, namespace, agent, from_key, to_key |
obrigatório |
value, memory_type, tags, entities, valid_at, source_resource_id |
herdado da linha de origem |
keep_redirect |
true |
if_match_sha256 |
nenhum |
dry_run |
false |
Ela retorna {from_key, to_key, redirected, memory_id, version, content_sha256, advisories, dry_run}; um dry run adiciona memory_type e value_preview. Depois de um move:
memory.get(from_key)ainda responde com o valor antigo maiscanonical_key;memory.get(from_key, follow=true)serve a nova linha;memory.searchememory.listmostram apenas a nova linha.
1. Auditoria
loom audit-namespace --org <org> --namespace <ns> --window-days 7 --samples 5
A CLI é executada no servidor (ela lê o ClickHouse diretamente). Ela imprime uma tabela (code, severity,
kind, count, share, primeira amostra), ou o modelo de saída com --json, e termina com código 1 quando o
namespace não está saudável. De qualquer outro lugar, chame namespace.audit por HTTP ou MCP.
Leia summary primeiro:
- um
get_search_rationa casa das centenas significa que o namespace está sendo usado como um armazenamento chave-valor (leituras de procedimentos, que são lidas de volta por chave de propósito, ficam de fora); unembedded_rowsacima de zero significa linhas que a busca nunca consegue encontrar.
Depois leia os achados. Pare quando healthy for true e nada estiver em warning ou
critical: um achado info é uma observação para quem escreve, não um retrabalho. Um achado
system_state (um backlog de indexação, telemetria ausente) diz respeito à
implantação, nunca a quem escreve; enquanto telemetry_unavailable for um warning,
exact_key_store e intentional_exact_key_reads ficam em skipped, e não como limpos, e
coordination_as_memory executa apenas o ramo de segmento de chave (samples_complete: false).
O painel de auditoria de namespace do painel mostra a mesma auditoria. context.pack traz um
bloco namespace_health quando o namespace não está saudável (um achado crítico, ou dois
warnings entre exact_key_store, double_encoded_values, unembedded_rows e
coordination_as_memory), de modo que um agente o vê no início da sessão.
2. Plano
Escreva uma seção por achado. Só os códigos que a auditoria retornou ganham uma seção.
| Achado | O que muda | Como |
|---|---|---|
double_encoded_values, json_prefix_excerpts, hash_keys |
a linha passa para uma chave legível, com um valor que começa pela afirmação | decodifique uma vez; frase da afirmação, linha da fonte, o resto em linhas curtas; memory.move com value, tags, entities, valid_at, if_match_sha256 |
oversized_values, episodic_blobs |
o corpo vira um documento ou um blob; uma linha de um parágrafo mantém a chave | knowledge.upsert (Markdown, source_uri=loom://<org>/<ns>/<key>) ou context.offload, depois memory.move da chave antiga com o parágrafo como value |
unembedded_rows |
o valor é dividido ou encurtado para que seja gerado o embedding | como em oversized_values; namespace.validate as lista entre suas linhas unembedded |
coordination_as_memory |
o bloco vai para a memória de trabalho; a chave antiga continua respondendo | working_memory.set, depois memory.move com keep_redirect=true |
hand_rolled_index_rows |
as linhas continuam legíveis e ganham tags; o escritor deixa de produzi-las |
apenas tags (memory.update_by_id); sem move |
exact_key_store, version_churn |
o escritor muda | liste as chaves para o responsável |
telemetry_unavailable, index_backlog, intentional_exact_key_reads |
nada: é o estado do deployment ou um fluxo de trabalho | sem retrabalho; para telemetry_unavailable, execute de novo quando o ledger cobrir a janela; para um index_backlog parado, verifique o worker de embedding |
O mentor (mentor.brief) nomeia mais três formatos que são mudanças de dados. Eles são
retrabalhados sob as mesmas regras, com a evidence da dica como contagem:
| Dica do mentor | O que muda | Como |
|---|---|---|
documents_as_memories |
como em oversized_values |
knowledge.upsert, depois memory.move com o parágrafo como value |
checkpoints_as_memory |
um dump de execução vira um blob de context.offload; uma linha episódica curta, chaveada pelo id da execução, o substitui |
context.offload, depois memory.move com um value de uma linha de ledger, memory_type=episodic |
records_for_identities |
linhas com chave <prefix>-<id> e campos escalares viram um schema e um registro por linha |
memory_schema.register uma vez, memory.record.write por linha, depois memory.move para uma linha de ponteiro |
Cada seção informa: a contagem e os bytes, três chaves de exemplo antes → depois (a partir dos
samples do achado), as chamadas exatas com seus argumentos e o que ela não fará:
- nenhum
memory.delete; - nenhuma alteração de valor no local: um valor reescrito só é gravado sob uma chave nova;
- nenhuma linha gravada na última hora: o escritor pode estar no meio da operação.
Armazene o plano como um documento de conhecimento em loom://<org>/<ns>/_optimize/plan-<YYYYMMDD>
(knowledge.upsert com esse source_uri), para que a aprovação do responsável e os números
de antes/depois fiquem em um só lugar.
3. Obter aprovação
O proprietário do namespace aprova por escrito. Um plano apresentado não é um plano aprovado. Uma aprovação parcial se aplica apenas às seções nomeadas. Se o writer do proprietário estiver em execução (o sets da auditoria na janela indica isso), avise-o; a última hora de linhas está fora do escopo de qualquer forma.
4. Aplicar
Faça um backup antes, se o namespace for importante: memory.list … fields=["value"] para um arquivo JSONL, namespace.snapshot (HTTP ou SDK; não é servido via MCP) ou, no servidor, CREATE TABLE … AS loom.memory mais INSERT SELECT
(backup e recuperação).
- Execute as três primeiras movimentações de cada seção com
dry_run=true; leia de voltato_key,redirectedeadvisories. - Depois mova em lotes de no máximo 50, em ordem de
created_at, para que as revisões entrem como versões da nova chave. - Passe
if_match_sha256a partir da amostra da auditoria ou de ummemory.getrecente. Um 409 significa que a linha mudou enquanto você trabalhava: pause a seção, leia novamente e pergunte. - Uma resposta sem
memory_id,versionecontent_sha256é uma movimentação que não aconteceu. Não a conte.
curl -s "$LOOM_BASE_URL/v1/memory.move" -H "Authorization: Bearer $LOOM_API_KEY" \
-H 'Content-Type: application/json' -d '{
"org": "acme", "namespace": "agent-sre", "agent": "sre-bot",
"from_key": "3f9a0c1e5b7d2a4c6e8f0a1b3c5d7e9f",
"to_key": "sre/case/c-42/evidence/e-7",
"value": "Disk on ingest-3 filled at 02:10 UTC.\nSource: alert A-981.",
"tags": ["case:c-42", "kind:evidence"],
"dry_run": true}'
5. Medir
Execute a auditoria novamente sobre a mesma janela e acrescente uma tabela de antes/depois ao documento do plano (knowledge.upsert no mesmo source_uri). Entregue ao responsável as regras do writer.
6. Não aposente nada
As chaves antigas continuam legíveis por meio do redirecionamento pelo tempo que o proprietário quiser. Depois que o escritor passar a usar as novas chaves, o proprietário pode marcar as antigas com tombstone usando memory.delete (exclusão lógica: memory.history as preserva). Este procedimento nunca faz isso.
Aviso: aposentar chaves que um escritor ativo ainda lê divide a visão dele: o
memory.getrespondefound: false, um cliente pode recorrer ao estado local, e os dois armazenamentos passam a divergir. O redirecionamento existe para evitar isso.
Relacionados
- Memória de agente de investigação: o layout de destino
- Integração de agentes
- Histórico e proveniência