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.
Importar a memória do ClickGap
loom import-clickgap carrega um formato específico de exportação SQLite, um armazenamento lessons do ClickGap, em um namespace do Loom; pule esta página, a menos que você tenha uma exportação desse tipo. Uma lição é uma memória de revisão curta e deduplicada, com entidades tipadas, categorias, um tipo (kind), um TTL por linha e um recall_count.
Dois comandos fazem o trabalho:
loom import-clickgap: o importador (server/cli/import_clickgap.py), executado onde a CLIloomalcança o ClickHouse (o contêiner do servidor ou um clone com o.envdo servidor).python -m bench.clickgap_migration_validate: o validador (bench/clickgap_migration_validate.py).
O que o importador preserva
| ClickGap | Loom | Observação |
|---|---|---|
lessons.text |
loom.memory.value + content_excerpt embutido |
a afirmação é embutida; o raciocínio não |
lessons.reasoning |
value_json.reasoning (com .text = afirmação) |
get retorna value_json, então a afirmação viaja junto com o raciocínio, nunca concatenada a ele |
lessons.kind |
memory_type (na maioria 1:1) + tag kind:<kind> |
summary → episodic (não pesquisável): os resumos continuam acessíveis por memory.get / memory.list e pela tag kind:summary, mas não são ranqueados em memory.search. A tag kind:<kind> preserva a taxonomia original. Veja _clickgap_memory_type / _CLICKGAP_TYPE_REMAP. |
lessons.source |
source_trace='clickgap://<class>/<source>' + tag source:<class> |
classes: pipeline / sessão / humano / revisor / avaliação |
lessons.created_at |
created_at, valid_at, temporal_anchor |
o momento original do registro, não o momento da importação |
lessons.expires_at |
expires_at literal, por linha |
nunca recalculado a partir de um TTL global |
lessons.recall_count |
recall_count e memory_embeddings.reinforcement_count |
veja sinal de recall |
lessons.last_recalled_at |
last_recalled_at e last_reinforced_at |
o eixo de recência do recall |
lessons.evidence_count |
evidence_count |
|
lesson_entities |
entities (simples) + tags entity:<kind>:<text> + loom.entity_vectors |
o array entities simples descarta o tipo; a tag o mantém |
lesson_categories + items |
loom.categories + loom.memory_categories |
nomes normalizados para minúsculas antes do category_id determinístico |
lessons false_positive |
tag polarity:negative |
memórias de supressão ("do NOT re-raise", ou seja, não levantar novamente) |
| fontes atribuídas a humanos | tag pii:human-attributed |
candidatas a apagamento por tag |
A importação é idempotente. memory_key='lesson_<id>' e um memory_id UUIDv5 (a partir de
clickgap://<org>/<namespace>/lesson/<id>) são determinísticos, e cada execução carimba uma
version nova. Uma nova importação substitui os registros sob ReplacingMergeTree(version) e a contagem de linhas
permanece a mesma.
1. Execução de teste
Nenhuma escrita é feita. A execução de teste verifica se todos os timestamps são interpretados corretamente, exibe a tabela cruzada de kind → type e TTL e a contagem de categorias, e testa o embedder para que nenhuma linha seja gravada sem embedding.
loom import-clickgap \
--sqlite ~/Downloads/clickgap-memory-YYYYMMDD/memory.db \
--org <org> --namespace clickgap --dry-run
Confirme que a tabela cruzada corresponde à origem e que o embedder está acessível.
2. Importação
Use um namespace dedicado (clickgap) para que o rollback seja um único namespace.delete. A exportação não traz vetores, então cada linha recebe embedding na importação com o LOOM_EMBEDDING_MODEL em uso.
loom import-clickgap \
--sqlite .../memory.db --org <org> --namespace clickgap --agent clickgap
--agent tem como padrão clickgap; --batch-size define as linhas por insert no ClickHouse (padrão 1000). O bloco de verificação no final imprime os resultados e faz a execução falhar (exit 1) em caso de divergência em:
- linhas de memória ativas em comparação com a contagem de lições da origem;
- linhas de embedding com o modelo errado (deve ser 0);
- a contagem de linhas permanentes (sem TTL);
- o maior
recall_count, lido de volta.
lesson_recalls (o log de eventos por recall) não é importado por padrão: as colunas desnormalizadas recall_count já carregam o sinal de ranking. Passe --seed-recall-events somente se você precisar do log por evento em loom.memory_usage_events para análises.
Aviso:
--seed-recall-eventsé aditivo e não é idempotente: execute-o uma única vez, em um namespace novo. Ele descartapr_number, porque os eventos de uso do Loom não têm coluna de PR.
Sinal de recall
O importador espelha recall_count em memory_embeddings.reinforcement_count e
last_recalled_at em last_reinforced_at. Em memory.search, essa contagem alimenta o
termo de ranking de reforço com decaimento: LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT define o seu peso
(0 o desativa), LOOM_MEMORY_SEARCH_REINFORCEMENT_HALF_LIFE_DAYS define o seu decaimento, e uma
requisição pode sobrescrever ambos com reinforcement_weight / reinforcement_half_life_days
(configuração).
O termo tem um limite abaixo da relevância, então o Loom não reproduz a ordenação
recall_count DESC do ClickGap: ele ordena principalmente por similaridade, com termos de entidade, recência e
reforço (recuperação e ranking). Se a sua
carga de trabalho depende da ordenação por frequência de recall, valide se a ordem resultante é
aceitável (o validador relata o τ da ordem de recall) antes da virada.
3. Validar antes da migração final
O validador gera seu próprio token de administrador com server.auth.jwt.mint_token, portanto precisa de
LOOM_JWT_SECRET e de um LOOM_BASE_URL explícito: não há destino padrão. Suas sondagens
são leituras de avaliação (auto_touch: false, os campos de medição de bench/_gate.py), então uma
execução não registra uso de recall nas lessons importadas, e execuções repetidas não alimentam o sinal de
reforço que o gate τ mede.
Aviso: aponte para um endpoint confiável. As consultas das sondagens são as asserções das lessons; os dados da importação não devem sair da sua infraestrutura por meio de um embedder de terceiros.
--show-queriesimprime o texto truncado das sondagens e vem desativado por padrão pelo mesmo motivo.
LOOM_BASE_URL=http://localhost:7777 LOOM_JWT_SECRET=... \
python -m bench.clickgap_migration_validate \
--sqlite .../memory.db --org <org> --namespace clickgap --agent clickgap \
--probes 200 --top-k 10 \
--min-recall 0.90 --min-recallw 0.90 --min-tau 0.2
Cada gate faz a execução falhar com saída diferente de zero quando definido acima de 0 (0 = apenas relatório):
| Gate | O que mede |
|---|---|
--min-recall |
Recall@k de item conhecido: a própria lesson da sondagem está entre os k primeiros do Loom? Os detalhamentos por tipo e por tipo de entidade detectam o colapso de uma única fatia (um remapeamento de tipo errado, por exemplo). |
--min-recallw |
Recall@k ponderado por recall: cada sondagem pesa conforme seu recall_count, então deixar de encontrar uma lesson muito acessada custa mais. |
--min-tau |
τ da ordem de recall: concordância de Kendall entre a ordem do Loom e recall_count. Um diagnóstico: o Loom não ordena por recall_count, então não espere um τ alto. |
Uma busca que falha é reportada e excluída das razões, nunca contada como erro, e qualquer
busca com falha faz a execução sair com código diferente de zero, com ou sem gates. Uma execução sem τ calculável imprime n/a e
falha em --min-tau.
Os resumos (summary → episodic) são excluídos das sondagens, pois não são pesquisáveis por
design. --seed (padrão 42) torna a amostra de sondagens reproduzível; --concurrency
(padrão 8) limita as buscas concorrentes.
Usar memórias de supressão
As lições false_positive ("parece um bug, NÃO levantar de novo") formam a camada de
supressão. Elas são pesquisáveis e carregam a tag polarity:negative. Um detector que
decide se deve levantar um achado candidato executa uma busca filtrada por tag sobre o
texto do achado:
hits = await agent.memory.search(finding_text, tags=["polarity:negative"], top_k=5)
if hits and hits[0].similarity >= SUPPRESS_THRESHOLD: # calibrate per embedder
skip_or_downweight(finding) # a known false positive
O filtro tags se aplica a todas as etapas de recuperação (vetorial, lexical e o
preenchimento por recência/confiança), de modo que o resultado contém apenas supressões
(test_lexical_fallback_applies_caller_filters em tests/unit/test_memory_search_service.py).
Um positivo que vazasse para o resultado esconderia um achado real.
Filtre qualquer tipo da mesma forma, pela tag kind:<kind>: tags=["kind:principle"], ou
tags=["kind:false_positive", "kind:maintainer_preference"] para uma lista de bloqueio com
vários tipos (tags é um filtro OR). O parâmetro memory_type de memory.search aceita
apenas os tipos gerais (semantic, procedural, preference, reflection, decision),
então a taxonomia completa de tipos fica nas tags.
Reverter
- Reversão completa:
namespace.deleteemclickgap(admin; via MCP, chame-o por meio deloom_op). A importação usa um namespace dedicado, então nada mais é removido. - Apagamento ou limpeza de coorte:
erasure.requestcom escopo de namespace (com checkpoint e retomado pelo worker de recuperação), ou apague apenas as linhaspii:human-attributedpara atender a um pedido de remoção de um mantenedor (retenção e apagamento). - Correção de mapeamento: execute o importador novamente. Chaves determinísticas e um
versionmaior substituem as linhas incorretas no lugar.
Consolidar (opcional, após a validação)
Se você compactar quase-duplicatas de conjuntos de entidades, execute memory.consolidate depois da validação.
As proteções em server/memory/app/consolidate.py excluem linhas fixadas (pinned) e nunca mesclam
entre memory_type diferentes nem entre polaridades diferentes, de modo que uma supressão false_positive não pode ser
absorvida por uma observação positiva, e um princípio não pode absorver uma observação.
Mantenha consolidation_enabled=false no namespace (namespace.register) para que o
worker de consolidação em segundo plano não consolide uma segunda vez as lições summary do ClickGap
que já foram agrupadas.