Skip to main content
This guide installs ClickHouse Loom, an open-source (Apache-2.0) MCP server and HTTP API that gives AI agents shared long-term memory, document search with citations, and a code index of your repositories. By the end, Loom runs against ClickHouse, holds a first memory, and serves a connected coding agent.

Before you begin

  • Docker with Compose 2.20 or later, on Linux amd64 or arm64 (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.xml to its config.d/, or a <zookeeper> section naming your Keeper;
    • a user with everything on loom.* and loom_telemetry.* (GRANT ALL, or GRANT CURRENT GRANTS on Cloud), SELECT on the system tables Loom reads, and READ ON REMOTE.
    See ClickHouse requirements.

How it works

  1. The installer downloads the release’s Compose bundle, verifies its checksum, and starts the Loom server and its document extractor from the published images.
  2. The bundled ClickHouse container starts with the loom database. 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.
  3. 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 loom-install.sh there before running it.
The stack runs its own ClickHouse container:
The installer waits until 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

The memory.get response has found: true and the value as written.
3

Connect a coding agent

When Claude Code asks for the plugin’s settings, keep the default server URL and leave the token empty.

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, and memory.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

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.
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

No. Loom stores, ranks, and retrieves context for agents; it isn’t an agent framework.
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.

Next steps