ClickHouse Loom

ClickHouse Loom

Shared memory, document search and code intelligence for AI agents.

For Claude Code, Codex, Cursor and your own agents.

English · 简体中文 · 日本語 · 한국어 · Português (Brasil) · Español · Русский

What Loom is for · Benchmarks · Get started · Capabilities · Integrations · Documentation

Loom is an open-source, self-hosted MCP server that gives your agents long-term, shared memory: what one agent learns in a session, the next agent or tool can find.

Agents connect through MCP, HTTP, Python or TypeScript. Self-host with Docker or on Kubernetes with the Helm chart; agent context and index data live in ClickHouse, and a deployment can choose Postgres at first boot for live memory and knowledge state. The dashboard brings memories, repositories, tasks and runs into one place.

What Loom is for

• Long-term memory shared across your coding agents, with plugins that load context at session start and capture the session as it runs. Agent memory · Connect a coding agent
• Memory for an agent application, per user, from the Python or TypeScript SDK. Your first agent
• A multi-user MCP memory server with namespaces, roles and tokens. Multi-user mode · Namespaces and sharing
• A code index of your repositories that coding agents query for definitions, callers and change impact. Code index
• Lower model cost for coding agents, as measured below. Coding-agent cost
• Document search with citations (RAG), including PDF, .docx and .pptx files the extractor service converts. Document search
• Shared context for multi-agent workflows: shared memory, task inboxes and decisions. Multi-agent
• Memory, recall, audit and erasure for autonomous agents. Autonomous agents
• A record of agent work, with searchable conversations (when recording is on), session briefs to resume from, runs with their goals, outcomes and model costs when supplied, and PR and tracker history. Runs and PR history

Every use case, and when another tool fits better: use cases.

Loom is not an in-process library for one agent's short-lived memory, nor an agent framework. When Loom does not fit

Measured results

Both coding setups use Claude Code (claude-sonnet-5) on the ClickHouse codebase; cost is the whole session's model bill, excluding Loom's server-side model calls, hosting and indexing. Answer quality measures coverage of a verified answer's key points, with a contradiction penalty. File localization counts whether the right file is among the up to three files the agent is asked to name at the end of its answer.

The memory row compares retrieved memories with full conversation history using the same gpt-5 reader. Token savings exclude memory construction; the 94% vs 90% accuracy difference is descriptive, not statistically established.

Separately, Loom's `memory.ask` configuration scored 96.6% answer accuracy on all 500 LongMemEval-S questions. This is a product evaluation with its own configured answer models, not the fixed-reader comparison above.

Results are specific to the tested workloads.

Protocols and reproducible artifacts · detailed results · evaluate on your workload

Get started

1. Choose your Docker setup

• Personal use—the default: no login, localhost-only access and a dev/local namespace. One person can connect multiple agents.
• Team use: authenticated accounts and namespace access controls. Start in multi-user mode from the first boot.

Both modes support the same Loom features, including configured LLMs and embeddings. Single-user is not a reduced-feature edition. You can also switch an existing installation without deleting its data; grant new accounts access to the existing namespaces.

To try it with nothing installed, open it in a codespace:

(what it runs and who can reach it)

For the default personal installation, with Docker installed (on Windows, in a WSL 2 terminal where docker works: Docker Desktop with its WSL integration on, or Docker Engine installed in the distribution):

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

Run it from your home directory, or another directory only you can write to. The installer starts Loom and ClickHouse, applies migrations and prints the dashboard URL: http://localhost:7777/; on a new install it then checks that a memory saves and reads back. On a terminal it also offers to connect the coding agents it finds (Claude Code, Codex, VS Code) and, on a new install, opens the dashboard. The image includes the server, workers, dashboard and Python, TypeScript and Go compiler indexers, plus the C++ one on amd64; TypeScript dependencies are prepared automatically. Quickstart and pinned releases

The installation lives in ~/.loom (LOOM_INSTALL_DIR chooses another directory): the Compose file and the startup settings in ~/.loom/.env. Running the install command again upgrades in place and keeps your .env settings.

Keep single-user mode localhost-only. For shared access, follow the team deployment guide, including TLS.

2. Configure models and API keys

The stock installation boots without keys or network. Storage, the dashboard, structural code indexing and semantic search work, on a small local embedding model the image carries; the fake LLM gives no AI-generated answers.

Open Settings → Models & keys, choose both providers and models, enter their keys, then click Test & apply. No Docker restart is needed; changing the embedding space rebuilds the existing index. The dashboard's embedding choices are hosted providers: to keep local and add an LLM, set the LLM lines in ~/.loom/.env instead (Models and keys).

One OpenAI API key can serve both roles. Claude needs a separate embedding provider. OpenAI, Gemini and OpenAI-compatible embedding endpoints are supported. Your agent's CLI login or subscription does not supply Loom's provider keys.

Prefer environment configuration? Edit ~/.loom/.env, then recreate the server:

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

A key alone does not change the pinned models (the local embedder and the fake LLM); set the provider and model too. Saved dashboard settings take precedence over .env. Follow models and API keys for provider recipes and health checks.

Everything else is in one file. loom.example.yaml lists every setting with its default and what it does, by area: the ClickHouse connection, timeouts and budgets, rate limits, workers, and the *_enabled switches that turn features on and off. Set any of them as LOOM_ in ~/.loom/.env and recreate the server; a deployment that mounts a config file can set them in a copy of this file instead (how settings are read). One marked live also changes while Loom runs: loom settings set , or Admin → Deployment settings. loom settings list --changed shows what differs from the defaults and where each value came from (runtime settings).

3. Connect your agents

If the installer connected your agent, skip the commands below. On the machine running a personal installation, the plugins need no token:

# Claude Code

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

Codex

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

Start a new session; the first one connects to http://localhost:7777. In Codex, run codex interactively once and approve the plugin's hooks; until then only the tools work. Tell the agent something worth keeping, then ask about it in the next session.

For Cursor on the machine running a personal installation, the button below adds the local MCP entry, which needs no token:

[![Add Loom to Cursor