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
- FA score
- 68/100 · Some gaps
At a glance
- Works with
- Universal · cross-platformCodex · Claude Code
- You'll need
- 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.
- Developers using Claude Code or Codex who want decisions and findings from one session available in the next.
- Teams coordinating several agents that need work assigned through task inboxes with preserved handoffs.
- Developers building per-user long-term memory into their own agent application via the Python or TypeScript SDK.
- Engineering teams that need cross-repository lookups of definitions, callers, and change impact to judge edit risk.
- Teams standing up an internal cited document Q&A (RAG) system over PDF, Word, and PowerPoint files.
- 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/.envloom.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.shThe 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 loomConnect 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@loomStart 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?
- 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.
- 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-1yields 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?
Why each dimension lost points
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.
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.
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.
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.
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.
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.
- 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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
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 ↗ -
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 ↗
FAQ
Can I use it without any model API keys?
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?
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?
Is this an agent framework or a memory library?
How does multi-agent coordination actually work?
Which port does ClickHouse Loom use?
Is ClickHouse Loom open source?
Is ClickHouse Loom safe to use?
Is ClickHouse Loom still maintained?
Who makes ClickHouse Loom?
What is ClickHouse Loom's official website?
Thanks — we use this to improve the page.