Pular para conteúdo

As páginas sem tradução abrem em inglês e são identificadas como inglês.

O original em inglês mudou desde esta tradução automática. Consulte a página em inglês para ver as instruções atuais.

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.

Início rápido

Esta página inicia o Loom em um laptop e salva uma primeira memória via HTTP, Python e MCP. Não exige chave de API nem conta. Uma instalação nova da stack publicada gera embeddings com um pequeno modelo local que a imagem já traz, então a busca retorna resultados relevantes sem rede (uma instalação atualizada mantém o embedder indicado no seu .env); o LLM dela é falso, então a extração e as respostas de memory.ask não produzem nada. O .env de um checkout usa provedores falsos para ambos.

A instalação padrão do Docker é de usuário único: sem login, com acesso apenas via localhost e um namespace padrão dev/local. Uma pessoa pode conectar vários agentes sem ativar o modo multiusuário. Implantações para equipes também são suportadas no OSS, com contas autenticadas e controles de acesso por namespace; comece no modo multiusuário ou siga Implantação → Modos de identidade. Ambos os modos oferecem os mesmos recursos do Loom; LLMs e embeddings reais exigem configuração de provedor em qualquer um dos modos.

Pré-requisitos

Necessário Para
Docker com o plugin compose A stack: ClickHouse e o servidor Loom.
Python 3.12 ou mais recente CLI loom, apenas para contribuidores. O SDK é compatível com 3.11+.
Node.js 20 ou mais recente O SDK TypeScript (opcional).
Porta livre 7777 Loom. O desenvolvimento a partir do checkout também expõe o ClickHouse em 8123 e 9000.
jq Ler a saída do curl no passo 4 (opcional).

1. Inicie a stack

Caminho rápido: imagem publicada, sem clonar

Pré-requisito: Docker Desktop ou Docker Engine com Compose 2.20 ou posterior. No Windows, execute o comando em um terminal WSL 2 onde docker funcione: Docker Desktop com a integração com WSL ativada para essa distribuição, ou Docker Engine instalado nela. O instalador é um 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

O comando salva o instalador no diretório atual e depois executa esse arquivo; por isso, execute-o a partir do seu diretório home, ou de outro diretório em que só você possa escrever: em um diretório compartilhado, outra pessoa pode substituir loom-install.sh, ou apontá-lo para outro arquivo, antes de ele ser executado. Um download com falha é interrompido com o erro do curl e um código de saída diferente de zero; depois de uma instalação com falha, corrija o que ela informar e execute o comando inteiro novamente. O instalador baixa loom-stack.tar.gz do GitHub Release mais recente, verifica seu SHA-256, instala a configuração do Compose e do ClickHouse em ~/.loom, baixa as imagens correspondentes ghcr.io/clickhouse/loom:X.Y.Z e ghcr.io/clickhouse/loom-extractor:X.Y.Z (o serviço extrator de documentos) e aguarda http://localhost:7777/v1/health. A imagem do servidor contém a API, os workers, as migrações e o painel React compilado na raiz do servidor; não é necessário instalar Python nem Node. Os indexadores da camada do compilador para Python, TypeScript e Go estão incluídos e ativados, assim como o de C++ (scip-clang) em amd64. Um repositório indexado com o indexador de TypeScript tem suas dependências instaladas automaticamente. As duas imagens oferecem suporte a Linux amd64 e arm64, incluindo Docker Desktop em Apple Silicon.

Quando o Loom responde, o instalador:

  1. Verifica uma memória. Uma instalação nova salva uma memória de teste, a lê de volta e a exclui, o que mostra que escritas e leituras funcionam e não deixa nenhuma memória ativa (a versão excluída aparece em Excluídas recentemente). Uma nova execução depois que essa verificação passou, ou uma atualização, a ignora.
  2. Descobre se o login está ativado. Com o login ativado, ele não conecta nenhum agente e diz de onde vêm os tokens.
  3. Oferece conectar seus agentes de código. Em um terminal, ele pergunta, para cada um que encontra: Claude Code e Codex por meio de seus plugins, VS Code por meio de code --add-mcp. LOOM_CONNECT responde no lugar, inclusive em uma execução sem terminal, e só os clientes que ele nomeia são examinados: uma lista separada por vírgulas de claude-code, codex e vscode, all, ou none sozinho; qualquer outro valor interrompe a instalação. Sem terminal e sem LOOM_CONNECT, nenhum agente é examinado nem alterado. Um plugin ou servidor MCP configurado antes (pelo plugin, claude mcp add, codex mcp add ou loom install) é deixado como está; para um plugin do Claude Code, o instalador imprime o comando que o aponta para esta instalação. O plugin do Claude Code executa o Node.js 18 ou posterior que estiver no PATH; sem ele, o instalador não instala nenhum plugin e imprime a linha claude mcp add apenas para o servidor MCP; o do Codex encontra o Node.js também por nvm e similares, então é instalado, com a linha codex mcp add ao lado. O plugin do Codex sempre usa http://localhost:7777, então para uma instalação em outro lugar ele recebe um link para sua página de configuração. O VS Code não é oferecido em uma sessão remota ou no WSL. Um cliente que LOOM_CONNECT nomeia e que não está no PATH é mencionado.
  4. Abre o painel em um desktop, para uma instalação nova; LOOM_NO_OPEN=1 ignora isso.

Executados a partir do WSL, esses passos atuam dentro do WSL: conecte um agente que roda no Windows a partir do Windows com o guia de conexão e abra o endereço do painel que o instalador imprime em um navegador do Windows.

Ctrl-C interrompe a execução em qualquer passo; um clone que a CLI de um agente iniciou para seu plugin pode ainda terminar em segundo plano.

A stack executa seu próprio contêiner ClickHouse. Para usar um ClickHouse que você já executa, um servidor autogerenciado ou um serviço ClickHouse Cloud (26.4 ou posterior, com um Keeper), passe a URL dele; o instalador pede a senha quando a URL não tem uma, cria o banco de dados loom e um usuário leitor somente leitura, ou imprime o SQL que um administrador precisa executar (escolhendo o 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

O install.sh de cada release instala essa release; assim, a cópia que latest serve instala a release mais recente, e a URL própria de uma release, abaixo, instala essa release sempre. Sobre uma instalação mais nova, a cópia de uma release mais antiga se recusa a instalar, em vez de iniciar um Loom e um ClickHouse mais antigos sobre dados mais novos; para fazer downgrade de propósito, siga fazendo downgrade de uma instalação pelo instalador. Para fixar uma release, use a URL própria dela:

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 inspecionar tudo antes de começar, baixe os arquivos e verifique-os:

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

Depois, quando o que eles imprimirem parecer correto, instale a partir do pacote verificado:

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 e LOOM_CLICKHOUSE_IMAGE passados ao instalador são gravados no .env do diretório de instalação, de modo que comandos docker compose posteriores ali e execuções posteriores do instalador usem a mesma porta e as mesmas imagens. Um LOOM_BIND_HOST diferente de loopback publica o Loom além deste host, e o servidor se recusa a iniciar assim sem LOOM_PUBLIC_BASE_URL e login: instale com LOOM_SKIP_START=1, defina-os no .env (abaixo) e execute o comando de instalação novamente sem LOOM_SKIP_START=1.

Cada release executa a release do ClickHouse que era a mais recente quando foi compilada; assim, executar o comando de instalação novamente para a mesma versão do Loom mantém o ClickHouse dela; instalar uma versão mais nova do Loom o atualiza, a menos que o .env fixe LOOM_CLICKHOUSE_IMAGE (apague essa linha para voltar a seguir as releases). Executar o comando de instalação novamente atualiza os arquivos gerenciados de Compose/configuração e reconcilia os contêineres. Ele preserva ~/.loom/.env, acrescentando a URL do extrator e um token a um que não os tenha, e os volumes Docker nomeados. Para parar sem apagar dados:

docker compose --project-directory "$HOME/.loom" down

Adicione --volumes apenas para uma redefinição intencional e irreversível.

Experimente no GitHub Codespaces

Abrir no GitHub Codespaces

O dev container do repositório executa a release mais recente em um codespace, sem nada na sua máquina: ele instala o Loom com o instalador acima, o inicia e conecta o Claude Code a ele. A primeira inicialização baixa cerca de 3 GB de imagens e leva alguns minutos. Abra o painel no endereço que as últimas linhas do log de criação imprimem (Loom is running in the codespace. Dashboard: https://<codespace name>-7777.app.github.dev, o endereço encaminhado da aba Ports para a porta 7777); o http://127.0.0.1:7777/ do instalador acima dele é o endereço do próprio codespace. No terminal do codespace, execute cd ~ && claude (fora do checkout, cujas instruções são para trabalhar no próprio Loom), faça login e diga "Remember that I never deploy on Friday"; em uma nova sessão do claude, pergunte "When can I deploy?".

O teste roda em modo de usuário único, sem login. No navegador, a porta 7777 é encaminhada de forma privada: o endereço dela responde apenas à sua conta do GitHub. Mantenha-a privada: pública, ou privada para uma organização, abre um servidor sem login para todos com quem ela for compartilhada. Agentes dentro do codespace, como o claude dele, usam http://localhost:7777; as linhas de conexão do painel nomeiam o endereço encaminhado, que exige um login no GitHub que os agentes no codespace não têm. Aberto no VS Code desktop, o codespace também encaminha a porta para o localhost:7777 do seu laptop, onde ela é tão aberta quanto uma instalação local para todo programa no laptop, e agentes no laptop podem alcançá-la ali; o encaminhamento precisa que essa porta local esteja livre, então pare um Loom local primeiro. Use o painel a partir do endereço do navegador: a partir do localhost:7777 do laptop a página abre, mas o servidor recusa as requisições dela, então não mostra dados; apenas o endereço encaminhado é a página do próprio servidor.

A instalação fica em /workspaces/.loom, de modo que um codespace reconstruído mantém seu .env e o projeto Compose, embora suas memórias fiquem em volumes Docker que uma reconstrução pode não manter; uma reconstrução também executa o instalador da release mais recente sobre ela, o que a move para essa release. Onde quer que estes documentos citem ~/.loom ou "$HOME/.loom", um codespace usa /workspaces/.loom. O Codespaces oferece abrir a porta 7777 assim que ela começa a escutar; o painel responde quando o log de criação imprime "Loom is running in the codespace". Se o log terminar com um erro, execute sh .devcontainer/start-loom.sh no terminal do codespace: ele mantém o que a primeira execução configurou.

Inicie no modo multiusuário

Para uma instalação nova com imagem publicada, com contas e login desde a primeira inicialização, prepare os arquivos da stack sem iniciar contêineres:

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

Edite ~/.loom/.env antes de iniciar o Docker. Substitua as entradas existentes de identidade e autenticação e adicione a configuração de cadastro:

LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open

Mantenha o COMPOSE_PROJECT_NAME e o LOOM_JWT_SECRET gerados. Depois, baixe as imagens e inicie a stack (com seu próprio ClickHouse, execute ch-setup primeiro, como o instalador disse):

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

Depois que as verificações de saúde passarem, abra http://localhost:7777/ e cadastre-se. Clientes SDK e MCP precisam de tokens; use a organização e os namespaces concedidos à sua conta, não os padrões de usuário único dev/local dos exemplos abaixo.

Isso ativa a autenticação multiusuário, não a rede pública: a stack ainda escuta apenas em localhost. Antes de compartilhá-la com uma equipe, configure o acesso de operador e o TLS. Configure também modelos reais e chaves de API; selecionar o modo multiusuário não substitui o LLM falso.

Para uma stack de usuário único já em execução, siga as instruções de troca ; a recriação do contêiner preserva os volumes de dados existentes.

Caminho do contribuidor: compile um checkout

Pré-requisito: Docker Compose 2.34 ou posterior, de que o arquivo compose do checkout precisa para baixar o ClickHouse diariamente.

git clone https://github.com/ClickHouse/loom && cd loom
python3 -m venv .venv && . .venv/bin/activate
pip install -e .
loom up

loom up faz três coisas:

  1. Cria os dois arquivos que o git não rastreia: .env a partir de .env.example e deploy/clickhouse-config/named_collections.xml a partir do seu modelo. Ele nunca sobrescreve nenhum dos dois; a um .env existente sem token do extrator ele dá um.
  2. Executa a stack compose de desenvolvimento com --build.
  3. Consulta http://localhost:7777/v1/health até o servidor estar pronto, imprimindo a contagem de migrações pendentes. Ele desiste após --timeout (300 s) com o último corpo de saúde e as últimas linhas de log.

A primeira inicialização do contribuidor compila a imagem e aplica todas as migrações de esquema, então reserve alguns minutos. Em seguida, loom up imprime a URL do painel (http://localhost:7777/), uma chamada curl e um trecho de Python que salvam uma primeira memória, e uma linha que conecta o Claude Code. Quando a autenticação está ativada, ele também gera um token de escrita e o coloca nesses trechos.

Flag Faz
--rebuild Recompila após uma mudança de código.
--no-build Reutiliza a imagem em cache.
--open Abre o painel.
--port Usa outra porta do Loom.
--env-file Aponta para outro arquivo env.

Executar loom up novamente em uma stack em execução apenas reverifica a saúde. make dev faz o mesmo sem a CLI e executa:

docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --build

Com compose.yaml primeiro, o Compose lê o .env da raiz do repositório para as substituições ${VAR:-default}; --env-file .env apenas diz isso explicitamente. loom down para a stack e preserva seus volumes. loom down --delete-data exclui permanentemente apenas os volumes nomeados desta instalação, depois que você digita o nome gerado do projeto Compose; --yes é a confirmação não interativa. Os alvos do Makefile fazem o mesmo: make down preserva os dados e make down-all os exclui.

O que o .env padrão inicia

Os modelos de .env do checkout e do pacote de release selecionam ambos o modo de usuário único. O pacote de release define LOOM_IDENTITY_PROVIDER=single-user explicitamente; o checkout o deixa vazio e infere o mesmo modo a partir de LOOM_AUTH_REQUIRED=false.

Configuração Valor Efeito
LOOM_AUTH_REQUIRED=false, LOOM_IDENTITY_PROVIDER=single-user (ou vazio) single-user Sem login. Namespace padrão dev/local. Chamadas SDK e MCP não precisam de token.
LOOM_LLM_PROVIDER=fake, LOOM_LLM_MODEL=fake-echo-1 LLM falso Extração, marcação de entidades e síntese de memory.ask não produzem nada.
LOOM_EMBEDDING_MODEL=local, LOOM_EMBEDDING_DIM=384 (pacote de release) bge-small Busca semântica em CPU, a partir dos arquivos de modelo que a imagem carrega.
LOOM_EMBEDDING_MODEL=fake-ngram-3072, LOOM_EMBEDDING_DIM=3072 (checkout) embedder falso A busca ordena por n-gramas de caracteres. Suficiente para verificar a ligação, não a revocação.

Os dois instaladores geram um COMPOSE_PROJECT_NAME único, um segredo aleatório de assinatura JWT, um token aleatório do extrator e LOOM_BIND_HOST=127.0.0.1. Clones separados, portanto, não compartilham volumes do ClickHouse silenciosamente, e o Loom e o ClickHouse ficam acessíveis apenas a partir deste computador.

Para provedores reais, abra Settings → Models & keys, escolha seus provedores e modelos, informe as chaves de API deles e clique em Test & apply. Uma única chave de API da OpenAI pode servir tanto ao LLM quanto aos embeddings. Não é necessário reiniciar o Docker; mudanças de embedding disparam uma reconstrução verificada, com progresso e nova tentativa exibidos no painel.

Para uma implantação baseada em variáveis de ambiente, substitua as linhas de provedor em ~/.loom/.env (stack publicada) ou .env (checkout). Definir apenas OPENAI_API_KEY não muda nada: as linhas de provedor padrão nomeiam seus provedores explicitamente. Sair do embedder local ou falso reincorpora o que está armazenado.

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 hospedados, clientes apenas com assinatura e implantações com um único provedor de LLM, siga Configure modelos e chaves de API. Somente depois de editar o .env da stack publicada, aplique-o com docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom; uma reinicialização simples não recarrega o ambiente do contêiner. As configurações avançadas estão em Implantação → Provedores.

Verifique a 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/health diz status: ok quando o ClickHouse está acessível e nenhum problema além de code_tier_failing (uma camada de índice de código de um repositório com falha) é um erro. fake_embedding, fake_llm e providers_degraded dizem em que modo você está; problems lista cada problema com sua correção; schema.pending lista as migrações não aplicadas.
  • loom doctor imprime uma linha por verificação do lado do servidor. --json gera JSON. A partir de uma stack de checkout do código-fonte, execute docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml exec loom loom doctor.

2. Abra o painel

http://localhost:7777/ abre diretamente o painel no modo single-user; no modo multiusuário, faça o cadastro ou entre primeiro. No modo single-user, o painel e os padrões do agente usam dev/local (LOOM_DEFAULT_NAMESPACE renomeia o namespace). Este é um modo de conveniência, não um limite de isolamento entre usuários: qualquer pessoa que consiga acessar o servidor pode acessar seus dados e a administração. Mantenha-o somente em localhost.

Para testar o cadastro (trust-network: e-mail e senha, e a primeira pessoa a reivindicar o nome de um namespace se torna seu administrador), substitua estas entradas em ~/.loom/.env (stack de release) ou em .env (checkout):

LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open

Definir apenas LOOM_AUTH_REQUIRED=true é insuficiente quando single-user é selecionado explicitamente: esse modo mantém a autenticação desativada. Mantenha o LOOM_JWT_SECRET gerado pelo instalador e os volumes existentes, depois recrie o servidor para carregar o ambiente:

# 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

O painel passa então a abrir na página de login, que tem uma aba Sign up, e toda chamada de SDK e MCP precisa de um token. Os modos de identidade estão em Identidades e namespaces. Declarar trust-network também é o que permite que um LOOM_BIND_HOST fora do loopback inicie com o cadastro aberto, de modo que qualquer pessoa que alcance a porta pode se cadastrar. Antes de tornar o servidor acessível por uma equipe, siga o guia de implantação para acesso de operador e TLS.

3. Obtenha um token

No modo de usuário único, o token é opcional. Mesmo assim, gerar um mantém seus scripts funcionando quando a autenticação for ativada, desde que eles informem org (ou a enviem em branco), namespace e agent: uma chamada que envia uma credencial, como faz o SDK quando encontra alguma (SDK Python → Credenciais), não tem nenhum deles preenchido automaticamente, e um org em branco é o do próprio token.

  • Painel: Settings → Tokens → New token. Por padrão, o token lê todos os namespaces e repositórios aos quais você pertence (um repositório restrito somente quando você o adiciona), mas nenhuma coleção, e grava no namespace em que você está. Only what you choose o limita aos namespaces, coleções e repositórios que você marcar (nenhum no início); os marcados são pesquisados na ordem listada, e você a altera com as setas de uma linha ou, em um desktop, arrastando a alça da linha. O resultado mostra o token uma única vez, com a configuração para o seu cliente MCP ou para um script.
  • CLI, como operador: execute dentro do contêiner do servidor, que guarda o segredo de assinatura:

    docker compose --project-directory "$HOME/.loom" exec loom loom mint-token --subject my-bot --org dev --namespaces local --roles writer
    

    Adicione --ttl-days 30 para qualquer token que saia da sua máquina. loom mint-token --help lista as opções de escopo (--namespace-role, --read-scope, --traffic-class).

  • Um bot que se cadastra sozinho (somente em trust-network): loom init --agent nightly-triage --server-url http://localhost:7777 cria o namespace agent-nightly-triage, salva um token de writer em ~/.loom/token e a URL em ~/.loom/config.json, e imprime um código de reivindicação. Uma pessoa o informa uma vez em /oauth/agent-claim, com uma senha própria, para assumir a propriedade.

Salve o token onde o SDK, a CLI e os plugins o procuram:

mkdir -p ~/.loom && (umask 077; printf '%s' "<token>" > ~/.loom/token)
export LOOM_API_KEY="<token>"

Claims, funções e concessões estão em Tokens e concessões.

4. Primeira memória via HTTP

Toda operação é um POST /v1/<op> com um corpo JSON. Uma instalação nova com o .env padrão, feita pelo instalador ou a partir de um checkout, é de usuário único: não há token, e uma chamada comum de memória ou de busca (memory.set, memory.get, memory.search e mais algumas) que não informa org nem namespace roda no próprio contexto da instalação, org dev e namespace local, os mesmos que o MCP e o painel usam; um memory.set que não informa agent é registrado como agente http, e uma busca lê todos os agentes. Portanto, as chamadas abaixo precisam apenas dos seus próprios campos (quais ops). Se uma chamada sem token responder 401 AUTH_INVALID, a autenticação está ativada: adicione -H "Authorization: Bearer $LOOM_API_KEY" e informe org, namespace e agent da sua conta; um cabeçalho com token vazio é recusado.

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'

A resposta de memory.set traz memory_id, content_sha256 e status. memory.get lê de volta uma chave: found indica se a chave contém um valor ativo, e value é o valor como foi escrito. A resposta da busca traz results e abstain, que indica se o melhor resultado é forte o bastante para responder a partir dele. A busca lê as memórias de todos os agentes no namespace, inclusive as adicionadas no painel; informe um agent para ler apenas as memórias desse agente. GET /v1/operations lista todas as operações, e http://localhost:7777/docs permite testar cada uma pelo navegador. Os formatos estão na referência da API HTTP.

5. Primeira memória com Python

pip install clickhouse-loom    # or, from a clone: pip install ./sdk/python

Uma versão que ainda não está no PyPI é instalada a partir dos seus assets (instalando a partir de um GitHub Release).

O exemplo define org e namespace, então funciona com ou sem o token do passo 3, que o SDK envia quando encontra um. Em um servidor de usuário único, uma chamada sem token pode omiti-los: Agent(agent="quickstart", base_url=...) também roda em 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())

Onde o SDK encontra o servidor e a credencial está descrito em SDK Python → Credenciais. O SDK TypeScript é instalado com npm install @clickhouse/loom (a partir de um clone).

As interfaces de cliente estão nas referências do SDK Python e do SDK TypeScript.

6. Primeira memória a partir de um agente de código

Se o instalador conectou seu agente, pule para o último parágrafo desta seção.

Para o Claude Code, instale o plugin do Loom. Ele adiciona hooks (contexto no início da sessão, captura no final) e skills sobre as ferramentas MCP:

claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom

Em um servidor de usuário único nesta máquina, mantenha a URL padrão do servidor e deixe o token vazio quando o Claude Code pedir as configurações do plugin.

Sem o plugin, adicione a entrada MCP diretamente:

claude mcp add --transport http loom "http://localhost:7777/mcp?toolset=coding" -s user

Ambos acessam um servidor de usuário único nesta máquina sem um token seu.

Com autenticação ativada, crie um token em Settings → Tokens e escolha Claude Code em Connect: a caixa de diálogo mostra a configuração para o plugin e para uma entrada claude mcp add, com o token incluído. Depois:

  1. Sobrescreva ~/.loom/config.json com o bloco config.json da caixa de diálogo mais o namespace em que o token salva ("namespace": "<namespace>"): um org ou namespace deixado no arquivo por uma sessão de usuário único tem precedência sobre o token, e sem um deles o plugin grava no primeiro namespace do token diferente de *, ou em coding. Adicione de volta qualquer code_repo ou agent que você tinha definido.
  2. Deixe LOOM_API_KEY (o passo 3 pode ter exportado uma: unset LOOM_API_KEY) e a opção token do plugin vazias, ou defina ambas com o novo token: o plugin lê as duas antes desse arquivo (configuração).
  3. Remova uma entrada claude mcp add criada sem token (claude mcp remove loom -s user) antes de executar o comando da caixa de diálogo, que recusa um nome já existente.

loom install --client <name> grava a entrada MCP para Claude Desktop, Claude Code, Codex, Cursor, VS Code, Cline, Windsurf e Zed; sem a flag, ele configura todos os clientes que encontrar. Conectar um agente de código cobre Codex e Cursor.

Inicie uma nova sessão e diga "Lembre que eu nunca faço deploy na sexta-feira." O agente chama loom_memory_set. Em uma sessão nova, pergunte "Quando posso fazer deploy?" O agente chama loom_search e responde a partir do fato armazenado. O modelo decide quando salvar e pesquisar com base nas descrições das ferramentas; não há palavras de gatilho.

7. Veja no painel

Página Mostra
/memories As memórias do namespace, com autor da escrita e horário.
/admin/activity O log de auditoria: qual agente escreveu qual chave e quando.
/admin/usage Custo por operação e por agente.

O restante está em Painel.

Opcional: indexar um repositório na stack lançada

Adicionar um repositório pelo painel é recusado nesta stack com SANDBOX_UNAVAILABLE: isso exige o sandbox de jobs de repositório, que esta stack deixa desativado porque o confinamento padrão do Docker o bloqueia. Liste apenas repositórios em que você confia: as etapas de build deles (instalações de TypeScript, downloads de módulos Go, CMake) rodam sem o sandbox, no contêiner loom, cujo ambiente contém o segredo JWT e as chaves dos provedores.

LOOM_CODE_REPOS_JSON é uma única linha com todos os repositórios como um array JSON (Configurar a entrada). Em ~/.loom/.env, descomente essa linha (adicione-a se ela não existir) e edite-a. dev é a org sob a qual uma stack de usuário único roda, e a org em que as contas multiusuário se cadastram (LOOM_SELF_SIGNUP_ORG); se você alterou isso, use a org da sua conta aqui e em --org abaixo:

LOOM_CODE_REPOS_JSON=[{"org":"dev","namespace":"code-myrepo","repo":"acme/myrepo","git_branch":"main","public":true}]
  • O Loom escolhe os indexadores da camada do compilador a partir dos arquivos de build do repositório (go.mod, package.json, pyproject.toml, um CMakeLists.txt na raiz, …); scip_producer indica um explicitamente (Camada do compilador). C/C++ também precisa de uma árvore de build configurada; sem ela, um repositório C/C++ recebe apenas a camada do parser.
  • Para um repositório privado, adicione um token do GitHub (LOOM_CODE_GITHUB_TOKEN no .env, ou github_token na entrada) e remova "public":true: essa opção é para repositórios públicos no host deles, e permite que qualquer pessoa da org entre no índice como leitora imediatamente a partir de Repositories. Decida antes do primeiro loom code init: ele define a política de entrada do namespace a partir de public, e editar public depois não a altera (um mantenedor a altera com code.repo.set_access).

Em seguida, recrie o contêiner loom e execute a primeira indexação:

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 roda no embedder local da stack lançada. Com um embedder fake (o .env de um checkout, ou uma instalação atualizada que ainda nomeia fake-ngram-*) ele se recusa e encerra; para testar a configuração mesmo assim, adicione --allow-fake-embedder. Escolher um modelo depois em Settings → Models & keys reindexa os embeddings do índice de código; após uma mudança no .env, ele precisa de uma reindexação própria, como descreve Modelos e chaves.

No modo multiusuário, um repositório listado não tem mantenedor, então sem "public":true o pedido de entrada de um leitor fica esperando sem ninguém para aprová-lo. Depois do loom code init, dê acesso a alguém como operador, com um token gerado no contêiner: admin o torna mantenedor, que a partir daí aprova leitores, e viewer permite leitura. O subject é o namespace com o qual a conta se cadastrou (seu identificador de login, o subject dos seus tokens); o email de um autocadastro nunca é verificado, então uma concessão a ele não admite ninguém:

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: faça uma pergunta sobre um documento

loom demo

loom demo envia o AGENTS.md deste repositório, o ingere com knowledge.ingest (o extrator de referência da stack faz o parsing) e faz uma pergunta sobre ele com knowledge.synthesize, exibindo a resposta e os trechos que ela citou. Com o LLM falso, ele exibe os principais resultados de knowledge.search. --file e --question apontam para o seu próprio documento.

Problemas comuns

Sintoma Causa e correção
set_from_messages não grava nenhum fato O LLM é o falso. Siga Modelos e chaves para configurar um.
Os resultados de busca parecem arbitrários O embedder é um falso (fake-ngram-* no .env). Troque-o como diz Modelos e chaves, o que gera novamente os embeddings do que está armazenado. Não apague seus volumes para trocar de modelo.
401 AUTH_INVALID após ativar a autenticação Nenhum token, ou um assinado com outro LOOM_JWT_SECRET. Gere um novo com o comando do Compose em Obtenha um token.
O painel retorna 503 O servidor roda a partir do código-fonte (make server) sem um frontend compilado. Execute make frontend-build.
A stack publicada não fica saudável Execute docker compose --project-directory "$HOME/.loom" logs --tail 100 loom clickhouse. Veja Solução de problemas.
Adicionar um repositório responde SANDBOX_UNAVAILABLE A stack roda sem o sandbox de jobs de repositório. Indexe o repositório por meio de LOOM_CODE_REPOS_JSON (Indexar um repositório).
O instalador diz que a porta 7777 está em uso Outro programa, ou outro Loom, escuta nela. Pare-o, ou execute o comando de instalação novamente com LOOM_PORT=7778 antes de sh loom-install.sh; o .env guarda a porta.
O instalador diz que a porta 7777 não responde Um programa a mantém ocupada sem responder, ou LOOM_BIND_HOST, LOOM_PORT ou um firewall impede este host de alcançá-la.
O instalador não conseguiu verificar a porta 7777 O curl falhou pelo motivo indicado pelo seu código de saída; verifique LOOM_BIND_HOST e LOOM_PORT.
No Docker Desktop com WSL, a instalação para com Ports are not available O Windows mantém ou reserva a porta, e a verificação do instalador dentro do WSL não consegue ver isso. netsh interface ipv4 show excludedportrange protocol=tcp lista as faixas reservadas; execute o comando de instalação novamente com um LOOM_PORT fora delas antes de sh loom-install.sh.
A porta 8123 ou 9000 de um clone está ocupada Remapeie as portas do host do ClickHouse (stack local).
O instalador não conseguiu baixar as imagens O próprio Docker acessa o registry: atrás de um proxy, forneça ao daemon do Docker as configurações de proxy.

Próximos passos

  • Avalie o Loom: transforme este teste de fumaça em uma avaliação de qualidade, latência e custo específica para a sua carga de trabalho.
  • Conecte um agente de código: Claude Code, Codex ou Cursor com esta stack.
  • Seu primeiro agente: identidade, tratamento de abstenção, sessões, context packs e execuções a partir do SDK.
  • Implantação: executando o Loom para uma equipe.