ClickHouse Loom

Self-hosted shared long-term memory, document search and code index for AI coding agents.

Source repo
ClickHouse/loom
Stars
★ 172
Last updated
today
License
Apache-2.0
Primary language
Python

At a glance

Works with
Universal · cross-platformCodex · Claude Code
You'll need
DockerClickHousePython SDK (clickhouse-loom)TypeScript SDK (@clickhouse/loom)Shell / CLINetwork accessLocal filesystemMCP Server
Typical use
Developers using Claude Code or Codex who want decisions and findings from one session available in the next.
Main limitation
Deployment needs Docker (or Kubernetes with Helm) and a running ClickHouse; team mode adds accounts, tokens, and TLS, so operational overhead exceeds a plain library.
Website
clickhouse.github.io/loom ↗ set on GitHub
Maintenance
Commits in the last 30 dayslast commit 2026-11-20latest release v1.3.0 (2026-11-20)+22.6 ★/day over 7 days
Source review
68/100 · Some gaps

What does this agent do, and when should you use it?

Loom is an open-source, self-hostable MCP server from ClickHouse that gives coding agents and your own applications long-term memory shared across sessions. Agents connect over MCP, HTTP, or the Python and TypeScript SDKs, and official plugins load context at session start for Claude Code, Codex, Cursor, and VS Code. Memories point at the files and symbols they concern and resurface when an agent edits those locations, while the code index answers questions about definitions, callers, and change impact. Context and index data live in ClickHouse, with an option to choose Postgres at first boot for live memory and knowledge state, deployed via Docker or a Helm chart on Kubernetes. It targets teams that need shared multi-agent context, auditable memory, and cited document retrieval (RAG) rather than a single-process short-term memory library.

Loom runs as an MCP server and also exposes an HTTP interface plus Python and TypeScript SDKs. It records memories written by agents, tracking who wrote each fact, version history, conflict review, and namespace rollback, and it builds a code index over repositories to answer questions about definitions, callers, change impact, and relevant tests with revision, source location, and completeness attached to results. Document search ingests PDF, .docx, and .pptx files converted by an extractor service, cites sources in answers, and can abstain on low-confidence retrieval. It also coordinates multi-agent handoffs through durable task inboxes with leases, retries, and review rules, and, when recording is on, keeps searchable conversations, session briefs, runs with goals and model costs, plus PR and tracker history. A dashboard gathers memories, repositories, tasks, and runs in one place.

  1. Developers using Claude Code or Codex who want decisions and findings from one session available in the next.
  2. Teams coordinating several agents that need work assigned through task inboxes with preserved handoffs.
  3. Developers building per-user long-term memory into their own agent application via the Python or TypeScript SDK.
  4. Engineering teams that need cross-repository lookups of definitions, callers, and change impact to judge edit risk.
  5. Teams standing up an internal cited document Q&A (RAG) system over PDF, Word, and PowerPoint files.
  6. Organizations needing namespace access control, audit records, and verifiable erasure for agent data.

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Ports
7777
Environment variables
LOOM_INSTALL_DIR
Config files
~/.loom ~/.loom/.env loom.example.yaml
Install notes cover
Windows · WSL · Docker

How do you install or deploy this agent?

The default personal install requires Docker (on Windows, run it in a WSL 2 terminal where docker works):

curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh

The installer starts Loom and ClickHouse, applies migrations, prints the dashboard URL http://localhost:7777/, and installs into ~/.loom (LOOM_INSTALL_DIR picks another directory). Re-running it upgrades in place and keeps your .env settings. A Helm chart is available for Kubernetes, and a GitHub Codespaces path exists for trying it out. A stock install boots without keys: structural code indexing and semantic search work on the bundled local embedding model, but the LLM defaults to fake-echo-1 and produces no real summaries or answers.

How do you use this agent?

After boot, open Settings → Models & keys in the dashboard, pick embedding and LLM providers and models, enter keys, then click Test & apply—no Docker restart needed. Alternatively edit ~/.loom/.env and recreate the server:

docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom

Connect the Claude Code and Codex plugins (no token needed on the machine running a personal install):

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

Start a new session and the plugin connects to http://localhost:7777. Cursor and VS Code can add the local MCP entry http://localhost:7777/mcp via the documented install links. For a team server, pass --config server_url=… --config token=… to the plugin, creating tokens in Settings → Tokens. Every setting is listed in loom.example.yaml and can be set as LOOM_<NAME> in ~/.loom/.env.

What are this agent's strengths and limitations?

Pros
  • Memory is tied to code locations: each memory points at the files and symbols it concerns and resurfaces when an agent edits them.
  • The README publishes a structured benchmark ledger—e.g. 96.4% vs 91.4% file localization and 21% lower model cost—with protocols and reproducible artifacts.
  • Genuinely self-hosted: server, dashboard, and index data live in your own ClickHouse, with Postgres optionally hosting live memory state, plus namespace access control, audit, and verified erasure.
  • Broad integration surface: MCP, HTTP, Python/TypeScript SDKs, and official plugins plus one-click links for Claude Code, Codex, Cursor, and VS Code.
  • Beyond memory and code indexing, it ships cited document search (PDF/docx/pptx), multi-agent task inboxes, and session/run records.
Limitations
  • Deployment needs Docker (or Kubernetes with Helm) and a running ClickHouse; team mode adds accounts, tokens, and TLS, so operational overhead exceeds a plain library.
  • Meaningful extraction, summaries, and answers require configuring embedding and LLM providers with API keys; the default fake-echo-1 yields no real answers, and Claude needs a separate embedding provider.
  • The bundled local embedder is bge-small on CPU, which the README says is weaker than hosted models, and changing the embedding space rebuilds the index.
  • Benchmarks are author-run on specific workloads, and the README itself notes some comparisons (e.g. 94% vs 90%) are descriptive without statistical significance.
  • The README states it is not an in-process library for one agent's short-lived memory and not an agent framework.

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
ClickHouse Loom This agent 68 · Some gaps — ★ 172 today Python Codex · Claude Code
RepoBrain – Repo Intelligence Engine 54 · Major gaps Agent plugin / skillFree + model costs ★ 1.4k 9d ago Python Codex · Claude Code
OpenMemory Cognitive Memory Engine 65 · Some gaps Library / SDKFree + model costs ★ 4.6k 11d ago TypeScript Claude Code · OpenAI API
LLMSlim Context and Memory 70 · Some gaps MCP serverFree + model costs ★ 27 1d ago Python Codex · Claude Code

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Some gaps
68/ 100 5-point scale 3.4 / 5
This review covers the source as of Nov 13, 2026. The project has shipped 1 stable release(s) since, which have not been re-reviewed. The score and verdict describe the reviewed version only. Recent releases ↓
Trust 17/29
Reliability 8/14
Adaptability 15/18
Convention 14/18
Effectiveness 9/13
Verifiability 5/8
Why each dimension lost points
Trust17 / 29 · 2.9/5

least_privilege: the security doc describes per-org/namespace row isolation, role-gated ops, rate limits and read_scope ceilings, which is adequate design; but the default single-user mode disables auth and binds localhost, and the MCP tool surface is broad, so deducted to 2. user_confirmation: the installer asks before connecting Claude Code/Codex/VS Code, the bench skill requires consent before paid runs, and irreversible actions (delete, deploy) require asking first; but some hooks capture sessions automatically, so not full marks. data_flow_transparency: README and configuration docs state data lives in ClickHouse, optional Postgres, model/key configuration, and Langfuse/ClickStack as optional integrations; but they do not enumerate what MCP tools send to external models, deducted 1. sensitive_data_handling: sensitivity detection, high rows never embedded, prompt fencing, audit hash chain and erasure saga are documented with evidence; but it relies on correct operator key configuration and a dev secret default exists, deducted 1. dependency_security: only PyPI/npm badges and image pulls are visible; no lockfiles, SBOM or dependency audit evidence, deducted to 1. external_effects: the installer pulls images, starts containers and may modify agent configs, which are external effects; confirmation and rollback are described but evidence is limited, deducted to 1. rollback: in-place upgrade, namespace rollback to any point, down without deleting data, and older installers refusing downgrade are documented; but not all destructive operations are covered, deducted 1. source_attribution: memories record actor, source_class, verification, and retrieval results carry as_of and citations, with good evidence; but some claims are asserted, deducted 1.

Reliability8 / 14 · 2.9/5

self_consistency: README, quickstart, AGENTS.md and skill files agree on single/multi-user modes, default fake LLM and local embeddings; but the loom/SKILL.md sample is truncated, so not all claims could be checked, deducted 1. dependency_availability: depends on Docker, ClickHouse, optional Postgres, Node 18+, Python 3.12+, and prerequisites are listed; but no version pinning or offline-availability evidence, deducted to 1. failure_messages: docs describe health checks, rerun-after-failure, and abstain/not_covered/stale failure semantics with good evidence; but no concrete error-code list is shown, deducted 1.

Adaptability15 / 18 · 4.2/5

audience_and_scenarios: covers personal, team, multi-agent, SDK, document search and code index scenarios, and explicitly states when Loom does not fit, with strong evidence. capability_boundaries: explicitly not an in-process library nor an agent framework, and skills distinguish code.* from memory.* uses, so boundaries are clear. trigger_precision: skill frontmatter has WHEN triggers and LOOM_BASE_URL/.loom markers, but triggering depends on env vars and index state, risking false or missed triggers, deducted 1. environment_fit: supports Docker, K8s Helm, Codespaces, WSL and multi-arch images; but requires Docker and port 7777, so environment fit is not universal, deducted 1.

Convention14 / 18 · 3.9/5

information_architecture: README is well structured, docs are layered (getting-started/operations/architecture/benchmarks), and AGENTS.md gives a repository map, with strong evidence. install_notes: installation steps are detailed, including checksum verification, pinned releases, upgrade and downgrade notes, with strong evidence. naming_stability: plugin and skill versions are consistently 1.2.0, but two plugins (loom and loom-code-skill) and a same-named skill create confusion, deducted 1. examples_and_faq: quickstart examples and an FAQ link exist, but the FAQ body and further examples are not in the sample, deducted 1. known_limitations: README and benchmark docs acknowledge small samples, non-significance and index staleness, with good evidence; but limitations are scattered, deducted 1. license: Apache-2.0 with LICENSE and NOTICE referenced, with strong evidence. versioning_changelog: version numbers and a settings-default change table exist, but no full CHANGELOG, deducted 1. maintenance_responsibility: publisher is ClickHouse but unverified, and SECURITY.md and CONTRIBUTING.md exist, so responsibility is partly clear, deducted 1.

Effectiveness9 / 13 · 3.5/5

output_usability: MCP tools return structured results with citations, as_of and abstain, and skills guide route-then-read, so usability is good; but it depends on correct model and index configuration, deducted 1. marginal_value: benchmarks show lower cost and better localization, but on specific workloads with limited samples, so marginal-value evidence is moderate, deducted 1. cost_benefit: requires self-hosted ClickHouse and optional model API costs, and README admits server-side model calls and hosting are excluded, so cost-benefit evidence is incomplete, deducted 1.

Verifiability5 / 8 · 3.1/5

claim_traceability: benchmark claims point to docs/benchmarks/results.md and protocols, and settings point to catalog.py, so traceability is good; but some README numbers lack raw data in the sample, deducted 1. cross_source_corroboration: README, quickstart, security docs and skill files corroborate each other, but the sample lacks tests and the results ledger body, deducted 1. fact_inference_separation: README distinguishes descriptive non-significant results from measured ones, and the bench skill requires proving the treatment ran before reading scores, so separation is good; but some performance claims remain product self-evaluation, deducted 1.

Risks and how to mitigate them
  • The default single-user mode disables auth and binds localhost; binding externally requires configuring TLS and auth or risks exposure.
  • The installer downloads and executes a remote script; despite SHA-256 verification, run it in a writable trusted directory and inspect it first.
  • Depends on Docker, ClickHouse and optional model APIs; without real model configuration the LLM is fake and extraction/Q&A produce nothing.
  • Benchmark results are workload-specific with limited samples, and some differences are described by the authors as not statistically established; do not extrapolate.
  • Publisher identity is unverified; independently confirm provenance and supply chain before production adoption.
  • The loom and loom-code-skill plugins/skills share a name and can be confused; avoid installing both.
Evidence confidence: Low Reviewed Nov 13, 2026 Reviewed revision d589bf078f9e New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/loom.svg)](https://followagents.com/en/agents/loom)
<a href="https://followagents.com/en/agents/loom"><img src="https://followagents.com/badge/loom.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v1.3.0
    Release notes excerpt
    What's Changed * The TypeScript SDK trims slashes from server URLs and the memory store's key prefix in linear time by @zlareb1 in https://github.com/ClickHouse/loom/pull/564 * The recall key's stray-link check compares the key file's name as text by @zlareb1 in https://github.com/ClickHouse/loom/pull/566 * The bundle budget builds through Vite's API, with no shell by @zlareb1 in https://github.com/ClickHouse/loom/pull/567 * Leading SQL comments are skipped in linear time by @zlareb1 in https://github.com/ClickHouse/loom/pull/565 …
    View on GitHub ↗
  2. v1.2.0
    Release notes excerpt
    New Feature - The reference extractor reads Parquet files: each file becomes a table whose rows are searchable passages cited by row, and a typed dataset. (#269) - knowledge.query calculates over the datasets ingested files become: a typed plan of filters, joins, groups and aggregates (or the rows themselves) runs over every row of the live snapshots, and the result carries a receipt naming each snapshot it read. (#278) …
    View on GitHub ↗
  3. v1.0.1

FAQ

Can I use it without any model API keys?
Yes, it boots. The image carries a small local embedding model, so storage, the dashboard, structural code indexing, and semantic search work; but the LLM defaults to fake-echo-1, so no meaningful extraction, summaries, or answers are produced until you configure a provider and key.
How do personal and team modes differ?
Personal mode has no login, is localhost-only, and uses the dev/local namespace, letting one person connect several agents. Team mode adds authenticated accounts and namespace access controls. The README states both modes share the same features—single-user is not a reduced edition—and an existing install can switch without deleting data.
Where do my memories and context live?
Agent context and index data live in ClickHouse, with an option to choose Postgres at first boot for live memory and knowledge state. Shared team access requires following the deployment guide's identity modes and TLS; single-user mode should stay reachable only from localhost.
Is this an agent framework or a memory library?
Neither in the library sense. Loom runs as a standalone MCP server that agents reach over MCP, HTTP, or the SDKs; your agents execute the workflow, and Loom preserves memory, retrieval results, and multi-agent handoffs.
How does multi-agent coordination actually work?
Work is assigned through durable task inboxes with leases, retries, review rules, and recorded outcomes; agents do the work while Loom keeps the handoffs, along with shared memories, tasks, decisions, and—when recording is on—searchable conversations and run records.
Which port does ClickHouse Loom use?
The install notes on this page use port 7777 (for example http://localhost:7777). If the project lets you change the port, its README explains how.
Is ClickHouse Loom open source?
Yes. The source code is on GitHub (ClickHouse/loom) under the Apache-2.0 licence.
Is ClickHouse Loom safe to use?
FollowAgents' FARS review (Nov 13, 2026) scored ClickHouse Loom 17/29 on trust and safety. None of the eight safety controls the review checks for was missing outright. The repository has changed since that review.
Is ClickHouse Loom still maintained?
Yes. The latest commit on GitHub is from 2026-11-20, within the last 30 days. The latest release is v1.3.0 (2026-11-20).
Who makes ClickHouse Loom?
ClickHouse Loom is published on GitHub by the account ClickHouse. FollowAgents has not verified which person or company is behind that account.
What is ClickHouse Loom's official website?
The project's GitHub repository lists https://clickhouse.github.io/loom/ as its website. That link is set by the repository owner; the source code itself is on GitHub (ClickHouse/loom).
Was this page helpful?
View on GitHub ↗ Install ↓

Host ecosystems

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts