Las páginas sin traducir se abren en inglés y se indican como inglés.
El original en inglés ha cambiado desde esta traducción automática. Consulta la página en inglés para ver las instrucciones actuales.
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.
Inicio rápido
Esta página pone en marcha Loom en un portátil y guarda una primera memoria por HTTP, Python y MCP. No
necesita ninguna API key ni cuenta. Una instalación nueva del stack publicado genera embeddings con un pequeño
modelo local que incluye la imagen, de modo que la búsqueda devuelve resultados relevantes sin red (una
instalación actualizada conserva el embedder que indica su .env); su LLM es falso, así que la extracción y
las respuestas de memory.ask no producen nada. El .env de un checkout usa proveedores falsos para ambos.
La instalación estándar de Docker es de un solo usuario: sin inicio de sesión, con acceso solo desde localhost y
un espacio de nombres dev/local por defecto. Una persona puede conectar varios agentes sin activar el
modo multiusuario. Los despliegues para equipos también son compatibles en OSS, con cuentas
autenticadas y controles de acceso a los espacios de nombres; empieza en modo multiusuario
o sigue Despliegue → Modos de identidad.
Ambos modos admiten las mismas funciones de Loom; los LLM y embeddings reales requieren configurar proveedores
en cualquiera de los dos modos.
Requisitos previos
| Necesidad | Para |
|---|---|
| Docker con el plugin compose | El stack: ClickHouse y el servidor de Loom. |
| Python 3.12 o superior | CLI loom solo para contribuidores. El SDK admite 3.11+. |
| Node.js 20 o superior | El SDK de TypeScript (opcional). |
Puerto libre 7777 |
Loom. El desarrollo desde el checkout también expone ClickHouse en 8123 y 9000. |
jq |
Leer la salida de curl en el paso 4 (opcional). |
1. Arrancar el stack
Camino rápido: imagen publicada, sin clonar
Requisito previo: Docker Desktop o Docker Engine con Compose 2.20 o posterior. En Windows, ejecuta
el comando en una terminal de WSL 2 donde docker funcione: Docker Desktop con su integración
con WSL activada para esa distribución, o Docker Engine instalado en ella. El
instalador es un script de shell POSIX.
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh
El comando guarda el instalador en el directorio actual y después ejecuta ese archivo, así que ejecútalo
desde tu directorio personal, o desde otro directorio en el que solo tú puedas escribir: en uno compartido,
otra persona puede reemplazar loom-install.sh, o apuntarlo a otro archivo, antes de que se ejecute. Una
descarga fallida se detiene con el error de curl y un código de salida distinto de cero; tras una instalación fallida, corrige
lo que informe y vuelve a ejecutar el comando completo. El instalador descarga
loom-stack.tar.gz de la última GitHub Release, verifica su SHA-256, instala la
configuración de Compose y de ClickHouse en ~/.loom, descarga las imágenes correspondientes
ghcr.io/clickhouse/loom:X.Y.Z y ghcr.io/clickhouse/loom-extractor:X.Y.Z (el
servicio extractor de documentos) y espera a http://localhost:7777/v1/health. La imagen
del servidor contiene la API, los workers, las migraciones y el dashboard de React ya compilado en la raíz
del servidor; no hace falta instalar Python ni Node. Los indexadores del compilador para Python, TypeScript y Go
están incluidos y habilitados, y también el de C++ (scip-clang) en amd64. Un
repositorio indexado con el indexador de TypeScript recibe sus dependencias instaladas
automáticamente. Ambas imágenes son compatibles con Linux amd64 y arm64, incluido Docker Desktop
en Apple Silicon.
Una vez que Loom responde, el instalador:
- Comprueba una memoria. Una instalación nueva guarda una memoria de prueba, la lee de nuevo y la elimina, lo que demuestra que las escrituras y lecturas funcionan y no deja ninguna memoria activa (su versión eliminada aparece en Eliminadas recientemente). Una nueva ejecución después de que esa comprobación haya pasado, o una actualización, la omite.
- Averigua si el inicio de sesión está activado. Con el inicio de sesión activado, no conecta ningún agente e indica de dónde salen los tokens.
- Ofrece conectar tus agentes de programación. En una terminal pregunta, por cada uno que encuentra:
Claude Code y Codex mediante sus plugins, VS Code mediante
code --add-mcp.LOOM_CONNECTresponde en su lugar, también en una ejecución sin terminal, y solo se examinan los clientes que nombra: una lista separada por comas declaude-code,codexyvscode,all, ononesolo; cualquier otro valor detiene la instalación. Sin terminal y sinLOOM_CONNECT, no se examina ni se modifica ningún agente. Un plugin o servidor MCP configurado antes (por el plugin,claude mcp add,codex mcp addoloom install) se deja como está; para un plugin de Claude Code el instalador imprime el comando que lo apunta a esta instalación. El plugin de Claude Code ejecuta el Node.js 18 o posterior que esté en el PATH, así que si no hay uno el instalador no instala ningún plugin e imprime la líneaclaude mcp addsolo para el servidor MCP; el de Codex encuentra Node.js también mediante nvm y similares, así que se instala, con la líneacodex mcp addjunto a él. El plugin de Codex siempre usahttp://localhost:7777, así que para una instalación en otro lugar recibe un enlace a su página de configuración. VS Code no se ofrece en una sesión remota ni en WSL. Se avisa de un cliente queLOOM_CONNECTnombra y que no está en el PATH. - Abre el dashboard en un escritorio, en una instalación nueva;
LOOM_NO_OPEN=1lo omite.
Antes de iniciar Loom, a una instalación nueva en una terminal con Ollama respondiendo en
localhost:11434 también se le pregunta si ejecutar en él los trabajos de modelo de Loom (extracción, y
el asistente una vez habilitado), sin clave de API; LOOM_LOCAL_MODELS=ollama responde que sí
y off que no
(un servidor de modelos en tu máquina).
Si se ejecuta desde WSL, estos pasos actúan dentro de WSL: conecta un agente que se ejecute en Windows desde Windows con la guía de conexión, y abre la dirección del dashboard que imprime el instalador en un navegador de Windows.
Ctrl-C detiene la ejecución en cualquier paso; un clon que la CLI de un agente inició para su plugin puede terminar igualmente en segundo plano.
El stack ejecuta su propio contenedor de ClickHouse. Para usar un ClickHouse que ya tengas en marcha, un
servidor autogestionado o un servicio de ClickHouse Cloud (26.4 o posterior, con un Keeper), indica su
URL; el instalador pide la contraseña cuando la URL no la tiene, crea la base de datos loom
y un usuario lector de solo lectura, o imprime el SQL que debe ejecutar un administrador
(elegir el ClickHouse):
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh \
&& sh loom-install.sh --clickhouse https://loom@abc123.us-east-1.aws.clickhouse.cloud:8443 && rm loom-install.sh
El install.sh de cada versión instala esa versión, así que la copia que sirve latest instala la
última versión, y la URL propia de una versión, más abajo, instala esa versión siempre. Sobre una instalación
más reciente, la copia de una versión anterior se niega a instalar, en lugar de arrancar un Loom y
un ClickHouse más antiguos sobre datos más nuevos; para volver a una versión anterior a propósito, sigue
volver a una versión anterior de una instalación con instalador.
Para fijar una versión, usa su propia URL:
curl -fsSL https://github.com/ClickHouse/loom/releases/download/v1.2.3/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh
Para inspeccionar todo antes de empezar, descarga los archivos y compruébalos:
curl -fLO https://github.com/ClickHouse/loom/releases/latest/download/loom-stack.tar.gz
curl -fLO https://github.com/ClickHouse/loom/releases/latest/download/loom-stack.tar.gz.sha256
curl -fL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh
sha256sum -c loom-stack.tar.gz.sha256
tar -tzf loom-stack.tar.gz
Después, cuando lo que imprimen te parezca correcto, instala desde el paquete comprobado:
LOOM_INSTALL_BUNDLE="$PWD/loom-stack.tar.gz" \
LOOM_INSTALL_CHECKSUM="$PWD/loom-stack.tar.gz.sha256" sh loom-install.sh && rm loom-install.sh
LOOM_PORT, LOOM_BIND_HOST, LOOM_IMAGE_REPOSITORY, LOOM_EXTRACTOR_IMAGE_REPOSITORY
y LOOM_CLICKHOUSE_IMAGE que se pasen al instalador se escriben en el .env del directorio de instalación,
de modo que los comandos docker compose posteriores allí y las ejecuciones posteriores del instalador usen el mismo
puerto e imágenes. Un LOOM_BIND_HOST distinto de loopback publica Loom más allá de este host,
y el servidor se niega a arrancar así sin LOOM_PUBLIC_BASE_URL y sin inicio de sesión:
instala con LOOM_SKIP_START=1, defínelos en .env (más abajo) y vuelve a ejecutar el comando de instalación
sin LOOM_SKIP_START=1.
Cada versión ejecuta la versión de ClickHouse que era la más reciente cuando se compiló, así que volver a ejecutar el
comando de instalación para la misma versión de Loom mantiene su ClickHouse; instalar una versión más reciente de
Loom lo cambia, a menos que .env fije LOOM_CLICKHOUSE_IMAGE (borra esa línea para
volver a seguir las versiones). Volver a ejecutar el comando de instalación actualiza los archivos de
Compose y de configuración gestionados y reconcilia los contenedores. Conserva ~/.loom/.env,
añadiendo la URL del extractor y un token a uno que no los tenga, y los volúmenes con nombre de Docker. Para
detener sin borrar datos:
docker compose --project-directory "$HOME/.loom" down
Añade --volumes solo para un reinicio intencionado e irreversible.
Pruébalo en GitHub Codespaces
El dev container del repositorio ejecuta la última versión en un codespace, sin nada en
tu máquina: instala Loom con el instalador de arriba, lo inicia y conecta Claude
Code a él. El primer arranque descarga unos 3 GB de imágenes y tarda unos minutos. Abre
el dashboard en la dirección que imprimen las últimas líneas del registro de creación (Loom is running in the
codespace. Dashboard: https://<codespace name>-7777.app.github.dev, la dirección
reenviada de la pestaña Ports para el puerto 7777); el http://127.0.0.1:7777/ del instalador que aparece encima es la
dirección propia del codespace. En la terminal del codespace, ejecuta cd ~ && claude (fuera del
checkout, cuyas instrucciones son para trabajar en el propio Loom), inicia sesión y di "Remember
that I never deploy on Friday"; en una nueva sesión de claude, pregunta "When can I deploy?".
La prueba se ejecuta en modo de un solo usuario, sin inicio de sesión. En el navegador, el puerto 7777 se reenvía
de forma privada: su dirección solo responde a tu cuenta de GitHub. Mantenlo privado: hacerlo público, o
privado para una organización, abre un servidor sin inicio de sesión a todos con quienes se comparta.
Los agentes dentro del codespace, como su claude, usan http://localhost:7777; las líneas de conexión
del dashboard nombran en su lugar la dirección reenviada, que necesita un inicio de sesión de GitHub
que los agentes del codespace no tienen. Abierto en VS Code de escritorio, el codespace
también reenvía el puerto al localhost:7777 de tu portátil, donde está tan abierto como una instalación
local para todos los programas del portátil, y los agentes del portátil pueden llegar a él allí; el
reenvío necesita que ese puerto local esté libre, así que detén primero un Loom local. Usa el dashboard desde la
dirección del navegador: desde el localhost:7777 del portátil la página se abre, pero el servidor rechaza
sus peticiones, así que no muestra datos; solo la dirección reenviada es la página propia de este servidor.
La instalación vive en /workspaces/.loom, así que un codespace reconstruido conserva su .env y su
proyecto de Compose, aunque sus memorias viven en volúmenes de Docker que una reconstrucción puede no conservar; una
reconstrucción también ejecuta sobre él el instalador de la última versión, lo que lo mueve a esa versión.
Dondequiera que estos documentos nombren ~/.loom o "$HOME/.loom", un codespace usa
/workspaces/.loom. Codespaces ofrece abrir el puerto 7777 en cuanto escucha; el
dashboard responde cuando el registro de creación imprime "Loom is running in the codespace". Si el
registro termina con un error, ejecuta sh .devcontainer/start-loom.sh en la terminal
del codespace: conserva lo que configuró la primera ejecución.
Iniciar en modo multiusuario
Para una instalación nueva con imagen publicada, con cuentas e inicio de sesión desde el primer arranque, prepara los archivos del stack sin iniciar contenedores:
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh \
&& LOOM_SKIP_START=1 sh loom-install.sh && rm loom-install.sh
Edita ~/.loom/.env antes de iniciar Docker. Reemplaza las entradas existentes de identidad y autenticación,
y añade el ajuste de registro:
LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open
Conserva los COMPOSE_PROJECT_NAME y LOOM_JWT_SECRET generados. Después descarga e inicia
el stack (con tu propio ClickHouse, ejecuta antes ch-setup, como indicó el instalador):
docker compose --project-directory "$HOME/.loom" pull
docker compose --project-directory "$HOME/.loom" run --rm loom loom ch-setup # your own ClickHouse only
docker compose --project-directory "$HOME/.loom" up -d
Cuando pasen las comprobaciones de estado, abre http://localhost:7777/ y
regístrate. Los clientes del SDK y de MCP necesitan tokens; usa la organización y los espacios de nombres concedidos a tu
cuenta, no los valores predeterminados de un solo usuario dev/local de los ejemplos siguientes.
Esto habilita la autenticación multiusuario, no la red pública: el stack sigue enlazado a localhost. Antes de compartirlo con un equipo, configura el acceso de operador y TLS. Configura también los modelos reales y las claves de API; seleccionar el modo multiusuario no sustituye al LLM falso.
Para un stack de un solo usuario que ya está en marcha, sigue en cambio las instrucciones para cambiar; recrear los contenedores conserva los volúmenes de datos existentes.
Camino del colaborador: compilar un checkout
Requisito previo: Docker Compose 2.34 o posterior, que el archivo compose del checkout necesita para descargar ClickHouse a diario.
git clone https://github.com/ClickHouse/loom && cd loom
python3 -m venv .venv && . .venv/bin/activate
pip install -e .
loom up
loom up hace tres cosas:
- Crea los dos archivos que git no rastrea:
.enva partir de.env.example, ydeploy/clickhouse-config/named_collections.xmla partir de su plantilla. Nunca sobrescribe ninguno; a un.envexistente sin token del extractor le da uno. - Ejecuta el stack compose de desarrollo con
--build. - Consulta
http://localhost:7777/v1/healthhasta que el servidor esté listo, imprimiendo el número de migraciones pendientes. Se rinde tras--timeout(300 s) con el último cuerpo de health y las últimas líneas del registro.
El primer arranque de colaborador compila la imagen y aplica todas las migraciones de esquema, así que calcula
unos minutos. Después loom up imprime la URL del dashboard (http://localhost:7777/), una llamada curl
y un fragmento de Python que guardan una primera memoria, y una línea que conecta Claude Code.
Cuando la autenticación está activada, también genera un token de escritor y lo incluye en esos fragmentos.
| Flag | Qué hace |
|---|---|
--rebuild |
Recompila tras un cambio de código. |
--no-build |
Reutiliza la imagen en caché. |
--open |
Abre el dashboard. |
--port |
Usa otro puerto de Loom. |
--env-file |
Apunta a otro archivo env. |
Volver a ejecutar loom up sobre un stack en marcha solo vuelve a comprobar el estado. make dev hace lo mismo
sin la CLI y ejecuta:
docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --build
Con compose.yaml primero, Compose lee el .env de la raíz del repositorio para las sustituciones
${VAR:-default}; --env-file .env solo lo indica explícitamente. loom down
detiene el stack y conserva sus volúmenes. loom down --delete-data elimina de forma permanente
solo los volúmenes con nombre de esta instalación después de que escribas el nombre generado del proyecto de
Compose; --yes es la confirmación no interactiva. Los targets del Makefile
hacen lo mismo: make down conserva los datos y make down-all los elimina.
Qué arranca el .env por defecto
Las plantillas .env del checkout y del paquete de versión seleccionan ambas el modo de un solo usuario.
El paquete de versión define LOOM_IDENTITY_PROVIDER=single-user explícitamente; el checkout
lo deja vacío e infiere el mismo modo a partir de LOOM_AUTH_REQUIRED=false.
| Ajuste | Valor | Efecto |
|---|---|---|
LOOM_AUTH_REQUIRED=false, LOOM_IDENTITY_PROVIDER=single-user (o vacío) |
single-user |
Sin inicio de sesión. Espacio de nombres predeterminado dev/local. Las llamadas del SDK y de MCP no necesitan token. |
LOOM_LLM_PROVIDER=fake, LOOM_LLM_MODEL=fake-echo-1 |
LLM falso | La extracción, el etiquetado de entidades y la síntesis de memory.ask no producen nada. |
LOOM_EMBEDDING_MODEL=local, LOOM_EMBEDDING_DIM=384 (paquete de versión) |
bge-small | Búsqueda semántica en CPU, a partir de los archivos de modelo que lleva la imagen. |
LOOM_EMBEDDING_MODEL=fake-ngram-3072, LOOM_EMBEDDING_DIM=3072 (checkout) |
embedder falso | La búsqueda ordena por n-gramas de caracteres. Basta para comprobar el cableado, no la recuperación. |
Ambos instaladores generan un COMPOSE_PROJECT_NAME único, un secreto aleatorio de firma JWT, un
token aleatorio del extractor y LOOM_BIND_HOST=127.0.0.1. Por tanto, clones distintos no comparten
volúmenes de ClickHouse sin avisar, y Loom y ClickHouse solo son accesibles desde este
equipo.
Para usar proveedores reales, abre Settings → Models & keys, elige tus proveedores y modelos, introduce sus claves de API y haz clic en Test & apply. Una sola clave de API de OpenAI puede servir tanto al LLM como a los embeddings. No hace falta reiniciar Docker; los cambios de embeddings activan una reconstrucción verificada, con el progreso y el reintento visibles en el dashboard.
Para un despliegue basado en variables de entorno, reemplaza las líneas de proveedor en ~/.loom/.env
(stack publicado) o en .env (checkout). Definir solo OPENAI_API_KEY no cambia nada:
las líneas de proveedor por defecto nombran sus proveedores explícitamente. Pasar del embedder local o falso
vuelve a calcular los embeddings de lo almacenado.
LOOM_EMBEDDING_MODEL=text-embedding-3-large
LOOM_EMBEDDING_DIM=3072
LOOM_LLM_PROVIDER=openai
LOOM_LLM_MODEL=gpt-6-luna
OPENAI_API_KEY=sk-...
Para Claude, OpenAI, embeddings alojados, clientes solo con suscripción y despliegues con
un único proveedor de LLM, sigue Configurar modelos y claves de API.
Solo después de editar el .env del stack publicado, aplícalo con
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom;
un simple reinicio no recarga el entorno del contenedor. Los ajustes avanzados están en
Despliegue → Proveedores.
Comprobar el stack
curl -fsS http://localhost:7777/v1/health | jq '{status, fake_embedding, fake_llm, providers_degraded, problems}'
docker compose --project-directory "$HOME/.loom" exec loom loom doctor
/v1/healthdevuelvestatus: okcuando ClickHouse es accesible y ningún problema distinto decode_tier_failing(el fallo de un nivel del índice de código de un repositorio) es un error.fake_embedding,fake_llmyproviders_degradedindican en qué modo estás;problemslista cada incidencia con su solución;schema.pendinglista las migraciones sin aplicar.loom doctorimprime una línea por cada comprobación del lado del servidor.--jsonda JSON. Desde un stack de checkout de código fuente, ejecutadocker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml exec loom loom doctor.
2. Abre el dashboard
http://localhost:7777/ abre directamente el dashboard en modo single-user;
en modo multiusuario, primero regístrate o inicia sesión. En modo single-user
el dashboard y los valores predeterminados del agente usan dev/local (LOOM_DEFAULT_NAMESPACE cambia el nombre del
espacio de nombres). Este es un modo de conveniencia, no un límite de aislamiento entre usuarios: cualquiera que pueda
acceder al servidor puede acceder a sus datos y a la administración. Mantenlo solo en localhost.
Para probar el registro en su lugar (trust-network: correo electrónico y contraseña, y la primera persona que
reclame el nombre de un espacio de nombres se convierte en su administrador), reemplaza estas entradas en ~/.loom/.env
(stack publicado) o en .env (checkout):
LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open
Configurar solo LOOM_AUTH_REQUIRED=true no es suficiente cuando single-user se selecciona explícitamente:
ese modo mantiene la autenticación desactivada. Conserva el LOOM_JWT_SECRET generado por el instalador y los volúmenes existentes, y luego recrea el servidor para cargar el entorno:
# Released stack:
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
# Checkout stack (run from the repository root):
docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --force-recreate loom
Entonces el dashboard se abre en su página de inicio de sesión, que tiene una pestaña Sign up, y cada llamada del SDK
y de MCP necesita un token. Los modos de identidad se describen en Identidades y espacios de
nombres. Indicar
trust-network es también lo que permite que un LOOM_BIND_HOST que no sea loopback arranque con el registro abierto,
de modo que cualquiera que llegue al puerto podrá registrarse. Antes de hacer que el servidor sea accesible para un
equipo, sigue la guía de despliegue para
el acceso de operadores y TLS.
3. Obtener un token
En modo de un solo usuario un token es opcional. Generar uno de todos modos mantiene tus scripts funcionando
cuando se activa la autenticación, siempre que indiquen su org (o la envíen en blanco), namespace
y agent: una llamada que envía una credencial, como hace el SDK cuando encuentra alguna (SDK de Python
→ Credenciales), no recibe ninguno de ellos completado,
y una org en blanco es la propia del token.
- Dashboard: Settings → Tokens → New token. De forma predeterminada, el token lee todos los espacios de nombres y repositorios a los que perteneces (un repositorio restringido solo cuando lo añades), pero ninguna colección, y guarda en el espacio de nombres en el que estás. Only what you choose lo limita a los espacios de nombres, colecciones y repositorios que marques (ninguno al principio); los marcados se buscan en el orden indicado, y lo cambias con las flechas de una fila o, en un ordenador de escritorio, arrastrando el asa de la fila. El resultado muestra el token una sola vez, con la configuración para tu cliente MCP o un script.
-
CLI, como operador: ejecútalo dentro del contenedor del servidor, que guarda el secreto de firma:
docker compose --project-directory "$HOME/.loom" exec loom loom mint-token --subject my-bot --org dev --namespaces local --roles writerAñade
--ttl-days 30para cualquier token que salga de tu máquina.loom mint-token --helpmuestra las opciones de alcance (--namespace-role,--read-scope,--traffic-class).
- Un bot que se registra solo (solo en redes de confianza):
loom init --agent nightly-triage --server-url http://localhost:7777crea el espacio de nombresagent-nightly-triage, guarda un token de escritor en~/.loom/tokeny la URL en~/.loom/config.json, e imprime un código de reclamación. Una persona lo introduce una vez en/oauth/agent-claimcon una contraseña propia para asumir la propiedad.
Guarda el token donde lo buscan el SDK, la CLI y los plugins:
mkdir -p ~/.loom && (umask 077; printf '%s' "<token>" > ~/.loom/token)
export LOOM_API_KEY="<token>"
Los claims, roles y permisos están en Tokens y permisos.
4. Primera memoria por HTTP
Cada operación es un POST /v1/<op> con un cuerpo JSON. Una instalación nueva con el .env por defecto, ya sea desde el instalador o desde un checkout, es de un solo usuario: no hay token, y una llamada cotidiana de memoria o de búsqueda (memory.set, memory.get, memory.search y alguna más) que no indique org ni namespace se ejecuta en los propios de la instalación, la org dev y el espacio de nombres local, los mismos que usan MCP y el dashboard; un memory.set que no indique agent se registra con el agente http, y una búsqueda lee todos los agentes. Por eso las llamadas siguientes solo necesitan sus propios campos (qué ops). Si una llamada sin token responde 401 AUTH_INVALID, la autenticación está activada: añade -H "Authorization: Bearer $LOOM_API_KEY" e indica el org, el namespace y el agent de tu cuenta; un encabezado con un token vacío se rechaza.
curl -sX POST http://localhost:7777/v1/memory.set -H 'Content-Type: application/json' \
-d '{"memory_key":"deploy_window","value":"Tue and Thu only; never Friday."}'
curl -sX POST http://localhost:7777/v1/memory.get -H 'Content-Type: application/json' \
-d '{"memory_key":"deploy_window"}' | jq '{found, value}'
curl -sX POST http://localhost:7777/v1/memory.search -H 'Content-Type: application/json' \
-d '{"query":"when can we deploy?"}' | jq '.results[0].content_excerpt'
La respuesta de memory.set incluye memory_id, content_sha256 y status.
memory.get lee una clave: found indica si la clave contiene un valor vigente, y value es el valor tal como se escribió. La respuesta de la búsqueda incluye results y abstain, que indica si el mejor resultado es lo bastante sólido como para responder a partir de él. La búsqueda lee las memorias de todos los agentes del espacio de nombres, incluidas las añadidas en el dashboard; indica un agent para leer solo las de ese agente.
GET /v1/operations lista todas las operaciones, y http://localhost:7777/docs te permite probar cada una desde el navegador. Los formatos están en la referencia de la API HTTP.
5. Primera memoria desde Python
pip install clickhouse-loom # or, from a clone: pip install ./sdk/python
Una versión que aún no está en PyPI se instala desde sus assets (instalar desde un GitHub Release).
El ejemplo indica org y namespace, por lo que funciona con o sin el token del paso
3, que el SDK envía cuando encuentra uno. En un servidor de un solo usuario, una llamada sin token
puede omitirlos: Agent(agent="quickstart", base_url=...) también se ejecuta en dev/local.
import asyncio
from loom import Agent
async def main():
async with Agent(
org="dev",
namespace="local",
agent="quickstart", # names the writer in the audit log
base_url="http://localhost:7777",
) as a: # sends a credential it finds; none needed in single-user mode
await a.memory.set("standup_time", "Daily standup is at 9:30.")
row = await a.memory.get("standup_time") # None when the key is unset
print(row["value"] if row else "unset")
for hit in await a.memory.search("when is standup?"):
print(hit.content_excerpt)
asyncio.run(main())
Dónde encuentra el SDK su servidor y su credencial se explica en
SDK de Python → Credenciales.
El SDK de TypeScript se instala con npm install @clickhouse/loom
(desde un clon).
Las superficies del cliente están en las referencias del SDK de Python y del SDK de TypeScript.
6. Primera memoria desde un agente de código
Si el instalador conectó a tu agente, pasa al último párrafo de esta sección.
Para Claude Code, instala el plugin de Loom. Añade hooks (contexto al inicio de la sesión, captura al final) y skills sobre las herramientas MCP:
claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom
En un servidor de un solo usuario en esta máquina, conserva la URL del servidor predeterminada y deja el token vacío cuando Claude Code solicite la configuración del plugin.
Sin el plugin, añade la entrada MCP directamente:
claude mcp add --transport http loom "http://localhost:7777/mcp?toolset=coding" -s user
Ambos llegan a un servidor de un solo usuario en esta máquina sin un token tuyo.
Con la autenticación activada, crea un token en Settings → Tokens y elige Claude Code en Connect: el cuadro de diálogo muestra la configuración para el plugin y para una entrada claude mcp add, con el token incluido. Después:
- Sobrescribe
~/.loom/config.jsoncon el bloqueconfig.jsondel cuadro de diálogo más el espacio de nombres en el que guarda el token ("namespace": "<namespace>"): unorgonamespaceque una sesión de un solo usuario haya dejado en el archivo tiene prioridad sobre el token, y sin uno el plugin escribe en el primer espacio de nombres del token distinto de*, o encoding. Vuelve a añadir los valores decode_repooagentque hubieras definido. - Deja vacíos
LOOM_API_KEY(el paso 3 pudo haber exportado uno:unset LOOM_API_KEY) y la opcióntokendel plugin, o asígnales el nuevo token: el plugin lee ambos antes que ese archivo (configuración). - Elimina una entrada de
claude mcp addcreada sin token (claude mcp remove loom -s user) antes de ejecutar el comando del cuadro de diálogo, que rechaza un nombre que ya existe.
loom install --client <name> escribe la entrada MCP para Claude Desktop, Claude Code, Codex, Cursor, VS Code, Cline, Windsurf y Zed; sin la opción, conecta todos los clientes que encuentra. Conectar un agente de código cubre Codex y Cursor.
Inicia una sesión nueva y di "Remember that I never deploy on Friday." El agente llama a loom_memory_set. En una sesión nueva, pregunta "When can I deploy?" El agente llama a loom_search y responde a partir del dato almacenado. El modelo decide cuándo guardar y buscar a partir de las descripciones de las herramientas; no hay palabras clave que lo activen.
7. Ver en el panel
| Página | Muestra |
|---|---|
/memories |
Las memorias del espacio de nombres, con autor y hora. |
/admin/activity |
El registro de auditoría: qué agente escribió qué clave y cuándo. |
/admin/usage |
Costo por operación y agente. |
El resto está en Panel.
Opcional: indexar un repositorio en el stack publicado
En este stack, añadir un repositorio desde el dashboard se rechaza con SANDBOX_UNAVAILABLE:
requiere el sandbox de trabajos de repositorio,
que este stack deja desactivado porque el confinamiento predeterminado de Docker lo bloquea. Incluye solo
repositorios de confianza: sus pasos de compilación (instalaciones de TypeScript, descargas de módulos de Go,
CMake) se ejecutan sin el sandbox, en el contenedor loom, cuyo entorno contiene el secreto JWT
y las claves de los proveedores.
LOOM_CODE_REPOS_JSON es una sola línea que contiene todos los repositorios como un arreglo JSON
(Configurar la entrada).
En ~/.loom/.env, descomenta esa línea (añádela si falta) y edítala.
dev es la organización con la que se ejecuta un stack de un solo usuario, y la organización en la que se registran las cuentas multiusuario
(LOOM_SELF_SIGNUP_ORG); si lo cambiaste, usa aquí la organización de tu cuenta y en
--org más abajo:
LOOM_CODE_REPOS_JSON=[{"org":"dev","namespace":"code-myrepo","repo":"acme/myrepo","git_branch":"main","public":true}]
- Loom elige los indexadores del nivel del compilador a partir de los archivos de compilación del repositorio (
go.mod,package.json,pyproject.toml, unCMakeLists.txten la raíz, …);scip_producernombra uno en su lugar (Nivel del compilador). C/C++ también necesita un árbol de compilación configurado, así que sin uno un repositorio C/C++ obtiene solo el nivel del parser. - Para un repositorio privado, añade un token de GitHub (
LOOM_CODE_GITHUB_TOKENen.env, ogithub_tokenen la entrada) y elimina"public":true: ese valor es para repositorios públicos en su host, y permite que cualquier miembro de la organización se una al índice como lector de inmediato desde Repositories. Decídelo antes del primerloom code init: este establece la política de ingreso del espacio de nombres a partir depublic, y editarpublicdespués no la cambia (un maintainer la cambia concode.repo.set_access).
Luego recrea el contenedor loom y ejecuta la primera indexación:
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
docker compose --project-directory "$HOME/.loom" exec loom loom code init --namespace code-myrepo --org dev
docker compose --project-directory "$HOME/.loom" exec loom loom code backfill --namespace code-myrepo --org dev --embed
backfill --embed se ejecuta con el embedder local del stack publicado. Con un embedder falso (el .env de un checkout, o una instalación actualizada que aún nombra fake-ngram-*) se rechaza y
termina; para probar la configuración de todos modos, añade --allow-fake-embedder. Elegir un modelo más tarde en
Settings → Models & keys vuelve a generar los embeddings del índice de código; tras un cambio en .env necesita su
propia regeneración de embeddings, como describe Modelos y claves.
En modo multiusuario, un repositorio listado no tiene maintainer, así que sin "public":true la solicitud de ingreso
de un lector queda esperando sin nadie que la apruebe. Después de loom code init, da
acceso a alguien como operador con un token generado en el contenedor: admin lo convierte
en el maintainer, quien aprueba a los lectores a partir de entonces, y viewer le permite leer. El
sujeto es el espacio de nombres con el que se registró la cuenta (su identificador de inicio de sesión, el sujeto de
sus tokens); un correo de autorregistro nunca se verifica, así que una concesión a él no admite a nadie:
ADMIN_TOKEN=$(docker compose --project-directory "$HOME/.loom" exec -T loom loom mint-token --subject operator --org dev --namespaces code-myrepo --roles admin --ttl-days 1)
curl -s http://localhost:7777/v1/grants.create -H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"org":"dev","namespace":"code-myrepo","subject":"your-namespace","role":"admin"}'
Opcional: hacer una pregunta sobre un documento
loom demo
loom demo sube el AGENTS.md de este repositorio, lo ingiere con knowledge.ingest (el extractor de referencia del stack lo analiza) y hace una pregunta sobre él con knowledge.synthesize, e imprime
la respuesta y los fragmentos que citó. Con el LLM falso imprime en su lugar los mejores resultados de
knowledge.search. --file y --question lo dirigen a tu propio documento.
Problemas comunes
| Síntoma | Causa y solución |
|---|---|
set_from_messages no escribe hechos |
El LLM es el falso. Sigue Modelos y claves para configurar uno. |
| Los resultados de búsqueda parecen arbitrarios | El embedder es uno falso (fake-ngram-* en .env). Cámbialo como indica Modelos y claves, lo que vuelve a calcular los embeddings de lo almacenado. No borres tus volúmenes para cambiar de modelo. |
401 AUTH_INVALID tras activar la autenticación |
Falta el token, o está firmado con otro LOOM_JWT_SECRET. Genera uno nuevo con el comando de Compose en Obtener un token. |
| El dashboard devuelve 503 | El servidor se ejecuta desde el código fuente (make server) sin un frontend compilado. Ejecuta make frontend-build. |
| La pila publicada no pasa a estado saludable | Ejecuta docker compose --project-directory "$HOME/.loom" logs --tail 100 loom clickhouse. Consulta Solución de problemas. |
Al añadir un repositorio se responde SANDBOX_UNAVAILABLE |
La pila se ejecuta sin el sandbox de tareas de repositorio. Indexa el repositorio mediante LOOM_CODE_REPOS_JSON (Indexar un repositorio). |
El instalador dice que el puerto 7777 está en uso |
Otro programa, u otro Loom, escucha ahí. Deténlo, o vuelve a ejecutar el comando de instalación con LOOM_PORT=7778 delante de sh loom-install.sh; .env conserva el puerto. |
El instalador dice que el puerto 7777 no responde |
Un programa lo ocupa sin responder, o LOOM_BIND_HOST, LOOM_PORT o un firewall impiden que este host lo alcance. |
El instalador no pudo comprobar el puerto 7777 |
Curl falló por el motivo que indica su código de salida; revisa LOOM_BIND_HOST y LOOM_PORT. |
En Docker Desktop sobre WSL, la instalación se detiene con Ports are not available |
Windows ocupa o reserva el puerto, algo que la comprobación del instalador dentro de WSL no puede ver. netsh interface ipv4 show excludedportrange protocol=tcp muestra los rangos reservados; vuelve a ejecutar el comando de instalación con un LOOM_PORT fuera de ellos delante de sh loom-install.sh. |
El puerto 8123 o 9000 de un clon está ocupado |
Reasigna los puertos de host de ClickHouse (pila local). |
| El instalador no pudo descargar las imágenes | Docker accede por sí mismo al registro: si estás detrás de un proxy, configura el daemon de Docker con los ajustes de proxy. |
Siguientes pasos
- Evaluar Loom: convierte esta prueba de humo en una evaluación de calidad, latencia y costo específica para tu carga de trabajo.
- Conectar un agente de código: Claude Code, Codex o Cursor contra este stack.
- Tu primer agente: identidad, manejo de abstenciones, sesiones, paquetes de contexto y ejecuciones desde el SDK.
- Despliegue: cómo ejecutar Loom para un equipo.