Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Importar memoria de ClickGap
loom import-clickgap carga un único formato de exportación SQLite, un almacén lessons de ClickGap, en un espacio de nombres de Loom; omite esta página a menos que tengas una exportación de este tipo. Una lección es una memoria de revisión breve y deduplicada, con entidades tipadas, categorías, un tipo (kind), un TTL por fila y un recall_count.
Dos comandos hacen el trabajo:
loom import-clickgap: el importador (server/cli/import_clickgap.py), que se ejecuta donde la CLIloomalcanza ClickHouse (el contenedor del servidor o un clon con el.envdel servidor).python -m bench.clickgap_migration_validate: el validador (bench/clickgap_migration_validate.py).
Qué conserva el importador
| ClickGap | Loom | Nota |
|---|---|---|
lessons.text |
loom.memory.value + content_excerpt con embedding |
se genera el embedding de la aserción; el razonamiento no |
lessons.reasoning |
value_json.reasoning (con .text = aserción) |
get devuelve value_json, así que la aserción viaja junto con el razonamiento, sin concatenarse nunca con él |
lessons.kind |
memory_type (casi siempre 1:1) + etiqueta kind:<kind> |
summary → episodic (no se puede buscar): los resúmenes siguen accesibles mediante memory.get / memory.list y la etiqueta kind:summary, pero no puntúan en memory.search. La etiqueta kind:<kind> conserva la taxonomía original. Consulta _clickgap_memory_type / _CLICKGAP_TYPE_REMAP. |
lessons.source |
source_trace='clickgap://<class>/<source>' + etiqueta source:<class> |
clases: pipeline / session / human / reviewer / eval |
lessons.created_at |
created_at, valid_at, temporal_anchor |
la hora de registro original, no la hora de importación |
lessons.expires_at |
expires_at literal, por fila |
nunca se recalcula a partir de un TTL global |
lessons.recall_count |
recall_count y memory_embeddings.reinforcement_count |
consulta la señal de recuperación |
lessons.last_recalled_at |
last_recalled_at y last_reinforced_at |
el eje de recencia de recuperación |
lessons.evidence_count |
evidence_count |
|
lesson_entities |
entities (simple) + etiquetas entity:<kind>:<text> + loom.entity_vectors |
el array entities simple pierde el tipo; la etiqueta lo conserva |
lesson_categories + items |
loom.categories + loom.memory_categories |
nombres normalizados a minúsculas antes de calcular el category_id determinista |
lecciones false_positive |
etiqueta polarity:negative |
memorias de supresión («NO volver a reportar») |
| fuentes atribuidas a personas | etiqueta pii:human-attributed |
candidatas para borrado por etiqueta |
La importación es idempotente. memory_key='lesson_<id>' y un memory_id UUIDv5 (a partir de
clickgap://<org>/<namespace>/lesson/<id>) son deterministas, y cada ejecución asigna una única
version nueva. Una reimportación sustituye las filas bajo ReplacingMergeTree(version) y el número de filas se mantiene
igual.
1. Ejecución de prueba
No se escribe nada. La ejecución de prueba comprueba que cada marca de tiempo se pueda interpretar, imprime la tabla cruzada de kind → type y TTL junto con el recuento de categorías, y sondea el embedder para que ninguna fila quede sin embedding.
loom import-clickgap \
--sqlite ~/Downloads/clickgap-memory-YYYYMMDD/memory.db \
--org <org> --namespace clickgap --dry-run
Confirma que la tabla cruzada coincide con el origen y que el embedder es accesible.
2. Importar
Usa un espacio de nombres dedicado (clickgap) para que el rollback sea un único namespace.delete. La exportación no incluye vectores, así que cada fila se genera como embedding al importar con el LOOM_EMBEDDING_MODEL activo.
loom import-clickgap \
--sqlite .../memory.db --org <org> --namespace clickgap --agent clickgap
--agent tiene como valor predeterminado clickgap; --batch-size define las filas por inserción en ClickHouse (valor predeterminado 1000). El bloque de verificación del final imprime los siguientes datos y hace fallar la ejecución (exit 1) en estos casos:
- filas de memoria activas frente al número de lecciones de la fuente;
- filas de embedding con un modelo incorrecto (deben ser 0);
- el número de filas permanentes (sin TTL);
- el valor más alto de
recall_count, leído de nuevo.
lesson_recalls (el registro de eventos por cada recuperación) no se importa de forma predeterminada: las columnas desnormalizadas recall_count ya aportan la señal de ranking. Pasa --seed-recall-events solo si necesitas el registro por evento en loom.memory_usage_events para análisis.
Advertencia:
--seed-recall-eventses aditivo y no idempotente: ejecútalo una sola vez, en un espacio de nombres nuevo. Descartapr_number, porque los eventos de uso de Loom no tienen una columna de PR.
Señal de recuperación
El importador replica recall_count en memory_embeddings.reinforcement_count y last_recalled_at en last_reinforced_at. En memory.search, ese contador alimenta el término de ranking de refuerzo con decaimiento: LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT define su peso (0 lo desactiva), LOOM_MEMORY_SEARCH_REINFORCEMENT_HALF_LIFE_DAYS establece su decaimiento, y una solicitud puede sobrescribir ambos con reinforcement_weight / reinforcement_half_life_days
(configuración).
El término está limitado por debajo de la relevancia, por lo que Loom no reproduce el orden recall_count DESC de ClickGap: ordena principalmente por similitud, con términos de entidad, antigüedad y refuerzo (recuperación y ranking). Si tu carga de trabajo depende del orden por frecuencia de recuperación, valida que el orden resultante sea aceptable (el validador informa el τ del orden de recuperación) antes del cambio definitivo.
3. Validar antes del cambio definitivo
El validador genera su propio token de administrador con server.auth.jwt.mint_token, por lo que necesita LOOM_JWT_SECRET y un LOOM_BASE_URL explícito: no hay un destino por defecto. Sus sondeos son lecturas de evaluación (auto_touch: false, los campos de medición de bench/_gate.py), de modo que una ejecución no registra uso de recuperación en las lecciones importadas y las ejecuciones repetidas no alimentan la señal de refuerzo que mide la compuerta τ.
Advertencia: apúntalo a un endpoint de confianza. Las consultas de los sondeos son las aserciones de las lecciones; los datos de importación no deben salir de tu infraestructura a través de un embedder de terceros.
--show-queriesimprime el texto truncado de los sondeos y está desactivado por defecto por la misma razón.
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 compuerta hace fallar la ejecución con un código de salida distinto de cero cuando se fija por encima de 0 (0 = solo informar):
| Compuerta | Qué mide |
|---|---|
--min-recall |
Recall@k de elemento conocido: ¿está la propia lección del sondeo entre los k primeros de Loom? Los desgloses por tipo y por tipo de entidad detectan el colapso de un solo segmento (por ejemplo, una reasignación de tipo incorrecta). |
--min-recallw |
Recall@k ponderado por recuperación: cada sondeo se pondera por su recall_count, de modo que pasar por alto una lección muy consultada cuesta más. |
--min-tau |
τ del orden de recuperación: concordancia de Kendall entre el orden de Loom y recall_count. Es un diagnóstico: Loom no ordena por recall_count, así que no esperes un τ alto. |
Una búsqueda fallida se informa y se excluye de las razones, nunca se puntúa como un fallo, y cualquier búsqueda fallida hace que la ejecución termine con un código distinto de cero, haya compuertas o no. Una ejecución sin τ calculable imprime n/a y falla --min-tau.
Los resúmenes (summary → episodic) se excluyen de los sondeos, ya que no son buscables por diseño. --seed (por defecto 42) hace reproducible la muestra de sondeos; --concurrency (por defecto 8) limita las búsquedas concurrentes.
Usar memorias de supresión
Las lecciones false_positive ("parece un bug, NO volver a reportarlo") son la capa de supresión. Se pueden buscar y llevan la etiqueta polarity:negative. Un detector que decide si reporta un hallazgo candidato ejecuta una búsqueda filtrada por etiquetas sobre el texto del hallazgo:
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
El filtro tags se aplica a cada vía de recuperación (vectorial, léxica y el relleno por recencia/confianza), de modo que el resultado contiene solo supresiones
(test_lexical_fallback_applies_caller_filters en tests/unit/test_memory_search_service.py).
Un positivo filtrado por error ocultaría un hallazgo real.
Cualquier otro tipo se filtra de la misma manera mediante su etiqueta kind:<kind>: tags=["kind:principle"], o tags=["kind:false_positive", "kind:maintainer_preference"] para una lista de exclusión de varios tipos (tags es un filtro OR). El parámetro memory_type de memory.search acepta solo los tipos generales (semantic, procedural, preference, reflection, decision), por lo que la taxonomía completa de tipos reside en las etiquetas.
Revertir
- Reversión completa:
namespace.deletesobreclickgap(admin; por MCP, llámalo a través deloom_op). La importación apunta a un espacio de nombres dedicado, por lo que no se elimina nada más. - Borrado o limpieza de una cohorte:
erasure.requestcon un alcance de espacio de nombres (con puntos de control y reanudado por el worker de recuperación), o borra solo las filaspii:human-attributedcuando un mantenedor solicite su eliminación (retención y borrado). - Corrección del mapeo: vuelve a ejecutar el importer. Las claves deterministas y un
versionmás alto reemplazan las filas incorrectas en su lugar.
Consolidar (opcional, después de la validación)
Si compactas casi duplicados de conjuntos de entidades, ejecuta memory.consolidate después de la validación.
Las protecciones de server/memory/app/consolidate.py excluyen las filas fijadas (pinned) y nunca fusionan
entre distintos memory_type ni entre distintas polaridades, de modo que una supresión false_positive no puede
ser absorbida por una observación positiva, y un principio no puede absorber una observación.
Mantén consolidation_enabled=false en el espacio de nombres (namespace.register) para que el
worker de consolidación en segundo plano no consolide por segunda vez las lecciones summary de ClickGap que ya
fueron agrupadas.