Pular para o conteúdo
ClickHouse Loom
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Visão geral

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.

Loom é um servidor que armazena memória, documentos, conversas, um grafo de entidades e um índice de código para agentes de IA, como linhas no ClickHouse, com Postgres como opção para o estado da memória e do conhecimento em tempo real. Agentes e pessoas o acessam por MCP, HTTP, pelos SDKs de Python e TypeScript e pelo painel. Ele é Apache-2.0. Esta página ajuda você a decidir se ele atende às suas necessidades.

O que ele faz

  • Memória que dura. Os fatos que um agente salva continuam disponíveis em sessões posteriores e em outras ferramentas, uma afirmação por chave, com histórico, proveniência e validade. Pode ser a memória de uma pessoa ou compartilhada por vários agentes e pessoas.
  • Verificações no momento da escrita. Um quase-duplicado é mesclado, uma contradição é sinalizada, uma escrita contra um fato fixado é recusada.
  • Busca que se abstém. memory.search retorna abstain=true com um código de motivo quando nada passa por um limiar calibrado para o seu embedder.
  • Auditoria e apagamento. Toda escrita que altera a memória deixa uma linha de auditoria com hash de conteúdo. erasure.request termina com um censo de resíduos em todas as tabelas que os caminhos de leitura acessam.
  • Um índice de código com o seu histórico. Busca, símbolos, chamadores, impacto, histórico de PRs com comentários de revisão e candidatos a bisect para os seus repositórios, com cada resposta indicando o commit e a camada do índice por trás dela. Com uma fonte de tracker conectada, o issue tracker também: verificações de duplicatas, vínculos issue↔PR e testes instáveis.

A memória e o índice de código são planos separados em um mesmo servidor. Use um deles isoladamente ou ambos. A memória precisa de um servidor e de um token de escrita. O índice de código também precisa de um repositório adicionado (LOOM_CODE_REPOS_JSON, ou Repositories → Add repository no painel, onde o sandbox de jobs de repositório está em execução) e LOOM_CODE_INGEST_ENABLED=true. Os plugins do Claude Code e do Codex usam ambos.

Onde os namespaces se encaixam

  • Uma org é o tenant.
  • Um namespace é a unidade de compartilhamento e de acesso dentro dela. Uma implantação geralmente tem um por equipe ou projeto, um por bot que precisa permanecer isolado, um personal-<slug> por pessoa (criado no primeiro uso e usado como padrão para os clientes MCP dessa pessoa) e um code-<repo>[-<branch>] por branch indexada.
  • Todo membro de um namespace lê todas as linhas dele.
  • agent registra quem escreveu uma linha; não é uma fronteira.
  • user_id / read_scope=own_user separa os usuários finais dentro do namespace de um bot.
  • O acesso é um papel (viewer/writer/admin) em um namespace, carregado por um token ou adicionado por uma concessão.

Identidades e namespaces traz o modelo completo.

Quando o Loom é indicado

  • Você usa várias ferramentas de IA e quer que elas compartilhem o que você contou a qualquer uma delas, em um namespace pessoal.
  • Várias ferramentas e pessoas (Claude Code, Codex, Cursor, um bot de suporte, uma pessoa no painel) precisam da mesma memória.
  • Você quer usar SQL sobre o que seus agentes sabem: fatos, traces, custos e linhas de auditoria são tabelas do ClickHouse.
  • Você já executa o ClickHouse, ou pode executar. Ele é o único armazenamento obrigatório do Loom; o Postgres é uma opção para a memória em tempo real e o estado do conhecimento.
  • Uma abstenção ou um conflito sinalizado é melhor do que uma resposta errada dada com confiança.
  • Você precisa de histórico, proveniência, auditoria ou exclusão verificável.
  • Agentes de código precisam de um índice dos seus repositórios.

Quando não se encaixa

Situação Por que não Considere em vez disso
Um agente, um processo, memória de curta duração Um servidor e um banco de dados são sobrecarga quando nada é compartilhado Uma biblioteca de memória em processo
Consultas de chave abaixo de um milissegundo em um caminho crítico Toda leitura é uma consulta ao banco de dados Um cache na frente do seu próprio armazenamento
Análises do grafo inteiro ou caminhos longos A travessia é uma consulta limitada por salto, com no máximo quatro saltos Um armazenamento de grafos, alimentado por loom entity-export
Você precisa de um framework de agentes O Loom não executa o loop do agente, os prompts nem o modelo Um framework de agentes, com o Loom como sua memória
Uma garantia de conformidade pronta para uso Apagamento e auditoria são primitivas de engenharia Seu processo de conformidade, usando essas primitivas
Produção em ClickHouse OSS de nó único sem plano de backup Sem replicação nem recuperação para um ponto no tempo ClickHouse Cloud
APIs congeladas Operações e campos mudam entre versões Fixe uma versão; consulte ops.capabilities

A validade considera apenas o tempo de validade (valid_at, valid_to); o que o Loom registrou e quando fica no histórico de versões, não em um segundo eixo de tempo. Algumas partes exigem que um operador as ative: o índice de código, as fontes de trackers, OAuth, a exportação de telemetria e o apagamento no Langfuse e no ClickStack.

O que cada propriedade custa

Propriedade Mecanismo Custo
Um único motor (autoridade ClickHouse) Vetor, busca lexical, grafo, filtros, auditoria e exclusão são SQL sobre as mesmas linhas Toda leitura é uma consulta. Os leitores pagam FINAL em linhas versionadas. As linhas derivadas (entidades, resumos) chegam depois, por meio de workers.
Abster-se em vez de uma correspondência fraca Limites derivados na inicialização a partir da própria distribuição de distância de cosseno do embedder (LOOM_ADAPTIVE_THRESHOLDS) Algumas correspondências fracas, porém corretas, são recusadas; defina min_similarity ou floor_mode por requisição.
Fatos que mudam Veredictos de merge, duplicate, conflict e pinned a cada escrita; loom.memory_versions somente para acréscimo Cada escrita é comparada com os vizinhos. Uma paráfrase pode esperar na fila de revisão até que alguém a resolva.
Ranqueamento explicável memory.search com explain=true detalha a pontuação de cada resultado; os resultados trazem source_class e verified Acima de top_k 15, onde explain vem desativado por padrão, explain=true torna cada resultado maior.
Compartilhamento com controle de acesso A tupla de identidade em toda linha; tokens e concessões carregam papéis de namespace Você emite e rotaciona tokens e concede papéis. Uma suíte de vazamento entre principals protege toda op de leitura no CI.
Exclusão verificável Uma saga retomável que termina em um censo de resíduos; backends externos falham de forma fechada Uma exclusão é um job de várias etapas. Um backend que não consegue confirmar a exclusão deixa a saga em failed para escalonamento manual.
Respostas de código com atualidade Camadas do parser e do compilador (SCIP); as respostas trazem as_of.commit e um sinalizador de obsolescência Um repositório grande leva horas para ser indexado. A camada do compilador exige a toolchain.

Medir as alegações de qualidade fica a seu cargo. O repositório inclui os harnesses de benchmark e os resultados brutos por trás dos números publicados (resultados). Execute os gates no seu deployment com provedores reais antes de confiar em um padrão (execução).

Checklist de decisão

Duas ou mais respostas na coluna da direita indicam que o Loom provavelmente não é a ferramenta certa.

Pergunta Indica o Loom Indica outra opção
Duas ou mais ferramentas ou agentes precisam compartilhar memória? Sim Não, um único processo
Você consegue executar o ClickHouse e operar um serviço? Sim Não, você quer algo gerenciado
Os dados precisam permanecer na sua própria infraestrutura? Sim Sem preferência
É melhor uma abstenção ou um conflito sinalizado do que uma resposta errada e confiante? Sim Sempre retornar algo
Você precisa de histórico, proveniência, auditoria ou exclusão verificável? Sim Não
Seu caminho crítico é uma busca por chave abaixo de um milissegundo? Não Sim
Você precisa de análises do grafo inteiro, e não de alguns saltos? Não Sim
Você consegue absorver mudanças de API entre versões, ou fixar uma versão? Sim Não
Você pagará por um embedder e um LLM reais e fará benchmarks com os seus dados? Sim Não

Pré-requisitos

Você precisa de Para
ClickHouse (OSS para avaliar, Cloud em produção) Tudo. Veja requisitos do ClickHouse.
Postgres 16+ (opcional) Estado ativo de memória e conhecimento sob a autoridade de memória do Postgres, escolhida no primeiro boot de uma implantação; exige um standby síncrono, a menos que LOOM_PG_DURABILITY=local (requisitos).
Docker com Compose 2.20 ou posterior A stack local publicada (instalador de uma linha; no Windows, a partir do WSL 2) e a imagem do servidor.
Python 3.12+ loom up exclusivo para contribuidores, desenvolvimento do servidor e trabalho com a CLI de operador.
Um provedor de embeddings Recuperação real: OpenAI, Gemini ou o embedder local em CPU que a stack publicada usa.
Um provedor de LLM Extração, síntese de memory.ask, code.ask: OpenAI ou Anthropic.
Tokens e namespaces Acesso. Veja tokens e concessões.
Para o índice de código Acesso Git aos repositórios, LOOM_CODE_GITHUB_TOKEN para o histórico de PRs e tempo para a primeira indexação.

Próximos passos

Avaliar o Loom separa um teste de fumaça do produto de uma avaliação real de qualidade. O Guia de início rápido executa a stack local. A implantação o executa para uma equipe. O mapa da documentação lista todas as páginas em ordem de leitura.

Esta página foi útil?