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.
Integrar Loom en un agente
Esta guía cubre lo que un agente envía a Loom y cómo lee las respuestas: la superficie del cliente, la identidad, qué escribir y cómo leer. Da por supuestos los conceptos de memoria y de identidades y espacios de nombres. Un agente de programación con un plugin incluido (Claude Code, Codex) obtiene la mayor parte de esto del plugin.
Las mismas reglas, escritas para el agente en lugar de para ti, son la Agent Skill loom (skills/loom/). Un agente sin plugin la lee desde el servidor: la operación experimental mentor.guide devuelve el bucle, dónde va cada tipo de estado y cómo leer las respuestas (part: "skill"), o bien todos los planos con sus operaciones (part: "reference"). Colócala en el prompt de sistema del agente:
system_prompt = "You triage support tickets.\n\n" + await agent.guide()
Con MCP, la introducción indica la llamada; un cliente de Agent Skills la instala con npx skills add ClickHouse/loom --skill loom.
1. Elegir la superficie de cliente
| Superficie | Úsala cuando | Qué obtienes |
|---|---|---|
MCP (/mcp) |
El agente es un cliente LLM que ya habla MCP (Claude Code, Codex, Cursor, una aplicación de escritorio). | Un listado curado de herramientas por ?toolset=, descripciones de herramientas escritas para el modelo, valores de identidad por defecto tomados de la conexión. El modelo decide cuándo llamar. |
SDK de Python (clickhouse-loom, from loom import Agent) |
El agente es tu propio proceso de Python. | Clientes tipados por plano, reintentos y claves de idempotencia, agent.tools() para el bucle de herramientas de un modelo, ámbitos de ejecución, adaptadores de frameworks (LangGraph LoomStore, Strands LoomMemoryStore). |
SDK de TypeScript (@clickhouse/loom) |
El agente es un servicio de Node o del lado del navegador. | Datapack / Agent, agent.call(op, body) tipado a partir de la tabla de ops generada, AgentTools, Session. |
HTTP (POST /v1/<op>) |
Cualquier otro lenguaje, o un script puntual. | Todas las ops, con los mismos cuerpos JSON; tú gestionas los reintentos y el encabezado Idempotency-Key. |
Las cuatro sirven las mismas ops desde un único registro. Elige según quién decide llamar: MCP cuando decide el
modelo, un SDK cuando decide tu código. Muchos agentes usan ambos: el SDK para cargar contexto al
inicio y registrar la ejecución al final, y las herramientas MCP para lo que el modelo elige recordar o
consultar. Con MCP, elige el listado con ?toolset= (toolsets de MCP);
una op que el listado omite sigue siendo invocable mediante loom_op.
2. Elegir la identidad
Cada fila lleva la tupla de identidad (org, namespace, agent, user_id, session_id), además de
run_id. El token fija org y los espacios de nombres; el resto viaja en cada llamada.
| Campo | Valor recomendado | Por qué importa |
|---|---|---|
namespace |
Uno por agente (agent-<name>), o uno compartido por un equipo de agentes |
La pertenencia es el límite de lectura: quien puede leer el espacio de nombres lee todas sus filas, sin importar qué agente las escribió. |
agent |
Un nombre estable para el agente que escribe | Indica autoría, no aislamiento. Por MCP el valor predeterminado es el nombre del cliente (clientInfo.name, en formato slug). |
user_id |
El usuario final al que atiende el agente, cuando atiende a varios | Con un token creado con --read-scope own_user, el prompt de un usuario no puede extraer las memorias de otro usuario. |
session_id |
La conversación o el trabajo | Delimita la memoria de trabajo y las lecturas own_session; agrupa una transcripción. |
run_id |
Una ejecución de una tarea | Vincula las escrituras, búsquedas, checkpoints y la transcripción de una ejecución (ejecuciones). |
- Un agente, varios usuarios, un token: crea el token con
--read-scope own_user(o fija--read-user-id) y pasauser_iden cada llamada. Una lectura con alcance restringido sin eseuser_idresponde 400IDENTITY_INCOMPLETE; nunca se amplía. - Varios agentes que comparten conocimiento: un espacio de nombres compartido que todos leen, y cada uno escribe bajo
su propio
agent; o un token que lee un espacio de nombres compartido y escribe en el suyo (ns_write). Consulta acceso a espacios de nombres. - No pongas secretos ni identificadores personales en
agent: se registra en cada fila del ledger.
3. Decide qué escribir
Elige primero el plano. La memoria duradera se incrusta, se ordena por relevancia, se comprueba en busca de conflictos y se versiona. La memoria de trabajo se lee por clave y nunca se ordena. Knowledge contiene documentos divididos en fragmentos.
| El agente tiene… | Escribe con | No con |
|---|---|---|
| Un hecho que seguirá siendo cierto la próxima semana y que otra sesión necesita (una decisión, una restricción, un responsable, una preferencia) | memory.set: un hecho por llamada, una clave por hecho |
memoria de trabajo |
| Su plan actual, supuestos abiertos, una lista de comprobación para esta tarea | working_memory.set / append, cargada por context.pack |
memory.set |
| Una transcripción, un correo o un hilo que vale la pena recordar | memory.set_from_messages: el servidor extrae hechos con claves cortas |
un único memory.set gigante |
| Un documento (especificación, runbook, informe, cualquier cosa de más de unos 2 KB) | knowledge.upsert como Markdown, más un párrafo con un puntero en memory.set bajo la misma clave |
un memory.set que contenga el texto |
| Una tabla de hechos con identidad (PR por número, servicios por id) | memory_schema.register una vez, luego memory.record.write |
una fila de memoria por lote |
| Estado de coordinación (un lease, un indicador de congelación, «dónde estamos») | working_memory.set por block_key |
memory.set + memory.get en un bucle |
| Un punto de control desde el que reanudar | un bloque de memoria de trabajo, o context.offload para un blob grande |
una memoria duradera por paso |
| Una conversación para mostrar y buscar más tarde | conversation.create / conversation.append |
memoria |
| Razonamiento, saludos, salida intermedia de herramientas | nada | cualquier cosa |
Memoria de agente de investigación aplica esta tabla a un agente que trabaja casos; rastreo y reanudación cubre los puntos de control.
Da forma a cada hecho para que una sesión posterior pueda confiar en él:
- Primero la afirmación. El valor expresa el hecho en texto plano; la línea de la fuente va después. Solo el inicio de un valor se incrusta (el extracto se recorta a 1,200 caracteres).
- Claves legibles, con la forma
<scope>/<kind>/<id>:sre/case/1234/evidence/dns-sidecar, no un hash. Las facetas van entags(case:1234,kind:evidence) y enentities. - Una revisión reescribe la misma clave. Loom conserva las versiones (
memory.history) y sirve la actual; nunca creesdeploy_window_v2, nunca mantengas una fila de índice que nombre la clave actual. - Indica de dónde viene:
source_resource_idpara el archivo, la URL o el documento del que se leyó el hecho. - Nunca disfraces una inferencia como un hecho. Escribe «Inferred from A and B: C» con
confidencepor debajo de 1.0. - Resuelve las fechas («on
», no «ayer») y establece valid_atcon el momento en que se hizo la observación. - Sin secretos. Para una clase de cosa que el usuario nunca quiere que se recuerde, usa
blacklist.addcon el patrón: las escrituras que coincidan se rechazan con 422BLACKLISTED.
Una afirmación del usuario («desplegamos los martes») es el desencadenante para escribir. No busques primero; el servidor se encarga de los duplicados y los conflictos.
4. Lee la respuesta de la escritura
Una respuesta de memory.set es un recibo. Léela:
| Campo | Significado |
|---|---|
memory_id, version, content_sha256 |
La escritura se guardó. Sin ellos no se guardó; nunca le digas al usuario que algo se guardó si no fue así. |
conflict_verdict: conflict, peers |
La escritura choca con un hecho existente (ambas filas quedan marcadas como conflicted). Muestra ambos valores y pregunta cuál es el vigente; no sobrescribas en silencio. |
409 PINNED_CONFLICT |
Una persona fijó el hecho existente. Infórmalo; no reintentes con una clave nueva. |
duplicate_of, merged_into_key, noop |
El hecho ya era conocido; no se guardó nada nuevo. |
advisories |
Una advertencia sobre la forma del valor: base64, JSON con doble codificación, un valor que supera LOOM_MEMORY_VALUE_ADVISORY_CHARS. |
Pasa if_match_sha256 (obtenido de un memory.get) cuando dos escritores puedan competir por una misma clave; un hash obsoleto se rechaza en lugar de sobrescribir.
5. Leer con una llamada por pregunta
-
Carga el contexto una vez por tarea.
context.packdevuelve un paquete con presupuesto de tokens: secciones del perfil, memoria de trabajo, las memorias relevantes paraquery, procedimientos y, opcionalmente, conocimiento, conversaciones y ejecuciones recientes (include_knowledge,include_conversations,include_runs). Los plugins lo llaman al inicio de la sesión.pack = await agent.context.pack("fix the flaky ingest test", token_budget=2000) system_prompt = base_prompt + "\n\n" + pack.rendered -
Busca una vez por pregunta. Por MCP,
loom_searchcubre memoria, perfil, conocimiento y conversaciones en una sola llamada. En el SDK, usaagent.memory.search(query), oagent.memory.ask(question)para obtener una respuesta con citas. Pagina connext_pagesolo cuando la respuesta necesite más filas (una lista, un conteo). - Trata una abstención como una respuesta.
abstain: truesignifica que nada superó los umbrales de similitud; responde "no está en la memoria", no con el resultado débil más cercano.abstain_codeindica el umbral (códigos de abstención). Mientraspending_extractionsea mayor que 0, la extracción diferida no se ha ejecutado, por lo que una respuesta vacía no es evidencia de ausencia. - Respeta la procedencia. El
source_classde un resultado indica cómo entró el contenido en la memoria yverifiedindica si lo cubre una atestación vigente.memory.getdevuelveverification(human,process,stalecuando el contenido cambió después de la atestación, onone).memory.askdeja fuera de su síntesis, por defecto, las filas declaradasexternaly sin atestación.
hits = await agent.memory.search("refund window for EU customers", top_k=5)
if hits.abstain:
reply = "I don't have that in memory."
else:
reply = hits[0].content_excerpt
6. Registrar ejecuciones
Una ejecución (run) es una pasada de una tarea: su objetivo, lo que recuperó y en lo que se apoyó, lo que escribió y su resultado. Las ejecuciones registradas permiten que el ranking aprenda qué memorias ayudan (ejecuciones).
async with agent.run_scope(goal="Fix the flaky CI job") as run:
answer = await agent.memory.ask("what broke CI last week?")
run.used("ci/flaky/runner-image")
run.final_response = "Pinned the runner image."
El scope llama a run.begin al entrar y a run.complete al salir, con el estado completed o failed y, como memories_used, las claves que citaron sus respuestas de memory.ask más las que se pasaron a used(). Las escrituras dentro del bloque llevan su run_id. Sin el SDK, llama tú mismo a run.begin y a run.complete(run_id, status=..., memories_used=[...]). memories_used es lo que el agente utilizó, no todo lo que se le mostró; las claves recuperadas se registran por separado.
Un agente que no use los plugins también debería entregar la transcripción terminada a memory.set_from_messages (o cerrar una agent.session(...)), para que el servidor extraiga lo que era duradero.
7. Sigue la revisión de la skill de memoria
Los plugins incluyen una skill loom-memory
(integrations/claude-code-plugin/skills/loom-memory/, generada en el plugin de Codex)
que codifica esta guía para un modelo. Un agente de programación que use MCP sin plugin utiliza el bloque de instrucciones para agentes, cuya última línea sobre memoria es una versión resumida de esta revisión; para ejecutar la revisión completa, pega las preguntas siguientes debajo del bloque. Cualquier otro agente copia las preguntas en sus instrucciones. Antes de informar que terminó, escribe solo lo que merezca un sí:
- ¿Tomé o aprendí una decisión, una restricción o un responsable que una sesión futura necesite?
- ¿Alguna memoria existente resultó ser incorrecta o estar desactualizada? Actualízala, con la misma clave.
- ¿El usuario me corrigió? Actualiza el dato; si lo rechazó, elimínalo con
memory.deletey añade el patrón conblacklist.addsi podría repetirse. - ¿Produje un artefacto (un archivo, un PR, un dashboard) que el trabajo futuro deba conocer?
- ¿Descubrí algo poco evidente que costó un esfuerzo real?
- ¿Una inferencia que escribí ahora está confirmada? Sube
confidencey quita el prefijo "Inferred".
Después ejecuta namespace.validate y actúa sobre los hallazgos que nombren las claves que escribiste. Di "guardado" solo cuando el recibo incluyó memory_id y version, "verificado" solo cuando una persona o un proceso lo certificó, y "no verificado aquí" cuando la comprobación no pudo ejecutarse. Otras skills incluidas cubren las preguntas sobre código (loom-code, también en skills/loom-code/ para cualquier cliente), la reorganización de un espacio de nombres (loom-optimize), la restauración de sesiones (loom-session) y el estado del cliente (loom-status).
Errores que debes evitar
namespace.audit detecta cada uno de estos; optimizar un espacio de nombres convierte
sus hallazgos en una corrección.
| Hallazgo | El error | En su lugar |
|---|---|---|
double_encoded_values |
json.dumps(json.dumps(doc)): el texto incrustado empieza con una comilla escapada. |
Envía texto, o el propio objeto, como value. |
json_prefix_excerpts |
Un objeto JSON más largo que el recorte de embedding; el vector se construye a partir de su prefijo. | Primero declara la afirmación como texto plano; los documentos a knowledge.upsert. |
hash_keys |
Un sha como identidad de la fila: ilegible, no se puede agrupar, y una revisión se convierte en una clave nueva. | <scope>/<kind>/<id>; revisa bajo la misma clave. |
exact_key_store |
Las lecturas por clave exacta superan en número a las búsquedas: el espacio de nombres es un almacén de objetos. | Recupera con memory.search; leases y punteros en la memoria de trabajo. |
coordination_as_memory |
Leases, locks y flags de congelación guardados como memorias y leídos en bucle. | working_memory.set / get: nunca se incrustan, se ordenan ni se comprueban en busca de conflictos. |
hand_rolled_index_rows |
Una fila que lista otras claves porque el agente no encuentra sus propias filas. | tags + memory.list prefix=; encadena revisiones con memory.link supersedes. |
oversized_values, unembedded_rows |
Documentos como memorias; por encima del límite del embedder un valor nunca se incrusta. | knowledge.upsert más una fila de puntero de un párrafo. |
episodic_blobs, version_churn |
Volcados de ejecución como filas episódicas, reescritos en cada paso. | context.offload para el blob; una fila episódica corta por ejecución; revisa la afirmación, no el blob. |
Dos más que ninguna auditoría detecta:
- Un blob por turno. Cinco hechos son cinco llamadas a
memory.set, cada una bajo su propia clave. - Retirar claves que un agente activo todavía lee. Sus lecturas responden
found: false, un cliente puede recurrir al estado local, y dos almacenes se contradicen. Mueve conmemory.move(deja una redirección) y no borres nada hasta que todos los lectores hayan migrado.