Before you begin
-
Docker with Compose 2.20 or later, on Linux
amd64orarm64(Docker Desktop on Apple Silicon works), and port 7777 free. -
A ClickHouse for Loom. The Loom stack can run its own ClickHouse container. To use a ClickHouse Cloud service or a self-managed server instead:
- version 26.4 or later (on Cloud, the service’s oldest replica counts);
- a Keeper: Cloud has one, and a self-managed server adds Loom’s
keeper.xmlto itsconfig.d/, or a<zookeeper>section naming your Keeper; - a user with everything on
loom.*andloom_telemetry.*(GRANT ALL, orGRANT CURRENT GRANTSon Cloud),SELECTon the system tables Loom reads, andREAD ON REMOTE.
How it works
- The installer downloads the release’s Compose bundle, verifies its checksum, and starts the Loom server and its document extractor from the published images.
- The bundled ClickHouse container starts with the
loomdatabase. On your own ClickHouse, the installer creates it, or prints the SQL an admin runs. Loom creates its tables on first boot. Memories, documents, and the code index are ordinary tables there. - Agents read and write through MCP or the HTTP API. The Python SDK, the TypeScript SDK, and the Claude Code and Codex plugins use the same API.
Install Loom
1
Run the installer
Run it from your home directory, or another directory only you can write to: it saves The installer waits until
loom-install.sh there before running it.- Bundled ClickHouse
- ClickHouse Cloud
- Self-managed ClickHouse
The stack runs its own ClickHouse container:
http://localhost:7777/v1/health reports status ok. The installation is single-user: no login, reachable from localhost only, and a default dev/local namespace, so MCP and SDK calls need no token. A team deployment turns on sign-in and gives each agent a token with namespace grants; see Identity modes.2
Save and recall a memory
memory.get response has found: true and the value as written.3
Connect a coding agent
- Claude Code
- Codex
- Cursor
Verify
Best practices
Give each team its own namespace
Memories, documents, and grants are scoped by namespace. Agents that should share what they learn write to the same namespace; tokens limit each agent to the namespaces it may read and write. See Tokens and grants.Configure an LLM provider for extraction and answers
The released stack embeds with a local CPU model and uses a stand-in LLM, so extraction, summaries, andmemory.ask give no meaningful results until a model provider is set in the dashboard’s Settings → Models & keys. One OpenAI key covers both the model and embeddings; Anthropic needs a separate embedding provider. See Models and keys.
Troubleshooting
The installer stops at the ClickHouse check
The installer stops at the ClickHouse check
Loom needs ClickHouse 26.4 or later, a Keeper, and the grants listed in Before you begin. On a self-managed server without a Keeper, add one, or run the installer with
--bundled to use the stack’s own ClickHouse. docker compose --project-directory "$HOME/.loom" run --rm loom loom ch-setup --print-sql prints the SQL for an admin without connecting.Loom doesn't become healthy
Loom doesn't become healthy
Read the logs with
docker compose --project-directory "$HOME/.loom" logs --tail 100 loom clickhouse. Troubleshooting gives each problem’s symptom, the check that confirms it, and the fix.Frequently asked questions
Does Loom run agents?
Does Loom run agents?
No. Loom stores, ranks, and retrieves context for agents; it isn’t an agent framework.
Can live memory be kept in Postgres?
Can live memory be kept in Postgres?
Yes. A new deployment can choose Postgres at its first boot as the authority for live memory and knowledge document heads, while vectors, search, and history stay in ClickHouse. See Postgres.