ClickHouse Loom: Giving AI Agents Shared Long-Term Memory and Cutting Token SpendArticle · digest for November 19
ClickHouse Loom: Giving AI Agents Shared Long-Term Memory and Cutting Token Spend
Article4 sections≈ 8 min

ClickHouse Loom: Giving AI Agents Shared Long-Term Memory and Cutting Token Spend

On ClickHouse's massive repository, Claude Code with shared memory attached misses the right files less often and spends noticeably less on model calls. That only works when context stops living in disposable sessions and attaches directly to the code. That's why the ClickHouse team open-sourced ClickHouse Loom (v1.2.0, Apache-2.0 license), a long-term memory, document search, and code intelligence server for coding agents.

Why Coding Agents Have Amnesia and How Loom Anchors Memory to Code

You know the drill. Yesterday you spent two hours explaining to Claude Code, Codex, or Cursor why the old cache in the auth module can't be touched and where retry logic lives. Today you open a new session and get a blank slate. The agent scans dozens of files again, burns tokens, and cheerfully suggests breaking that exact cache. Rule files like CLAUDE.md help right up until the first major refactor, and on a team they quickly turn into a pile of contradictions.

ClickHouse took an infrastructure approach and moved memory into a self-hosted service (running on your machine or company server so history never leaks to a third-party cloud) over MCP (Model Context Protocol), the open standard for connecting tools and knowledge bases to AI agents. Everything is stored in ClickHouse: vector and full-text search, relationship graphs, and audit logs. If you want, operational memory state can run in Postgres on first boot via LOOM_STORAGE_AUTHORITY=postgres.

The core feature is code-anchored memory. Notes and decisions attach to specific files and symbols. If a method moves during a refactor, the note moves with it. If linked lines change, the fact gets flagged for review. When an agent opens that area tomorrow, the relevant context surfaces automatically. Every entry tracks its author, version history, and conflict resolution, and any namespace (an isolated memory space, dev/local by default) can be rolled back to any point in time.

Alongside memory runs a compiler-grade code index—not plain text search, but a structural map of definitions, callers, edit impact, and relevant tests tied to commits, PRs, and issues. The image ships with indexers for Python, TypeScript, and Go, plus C++ on amd64. It also includes cited RAG (searching notes, chats, and PDF, .docx, and .pptx documents via an extractor service, returning source links and abstaining on low confidence) and task inboxes with leases and retries for handing work between agents.

Benchmarks Without Illusions: Where Savings Come From and What's Excluded

ClickHouse published reproducible benchmarks on its own codebase using Claude Code (claude-sonnet-5):

Task / benchmarkWith LoomWithout LoomResource impactEvaluation scope
Coding agent answer quality0.840.78-20% model bill24 questions × 3 paired runs
File localization (top-3)96.4%91.4%-21% model bill36 questions × 10 paired runs
Memory vs full history (LongMemEval-S, gpt-5 reader)94%90%-91% prompt tokens100 paired questions
SWE-bench Verified (file in top-10)82%57% (BM25)76.5% in top-5200 tasks (file retrieval only)

The numbers look great, but the authors honestly list every caveat in the documentation, and you should know them upfront.

First, the savings in the first two rows count only the coding agent's own model bill. Excluded are Loom's server-side LLM calls, embeddings (numeric vectors for semantic search), repository indexing, and ClickHouse hosting. In practice, you shift part of the cost from the agent's expensive context window into a background service.

Second, the LongMemEval-S prompt compression figure excludes memory write and retrieval costs, and the authors describe the small accuracy lead as descriptive rather than statistically proven. Third, SWE-bench here only measures file retrieval, not solving the full task.

The math is straightforward. On a giant monorepo where agents spend ages hunting for the right module, Loom pays for itself quickly. On a small service, the overhead and database maintenance will easily eat the savings.

Spinning Up Loom in Docker and Connecting Claude Code or Codex

According to the Quickstart, local setup requires Docker with Compose 2.20+ (on Windows, WSL 2 with Docker Desktop or Docker Engine inside WSL) and free port 7777. Personal mode runs on localhost with no login, creates dev/local, and includes the full feature set. As your team grows, you can switch to multi-user mode without losing data.

Run the installer from your home directory:

# Run from your home folder — configs and Compose go into ~/.loom
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 script saves the Compose file and .env in ~/.loom (overridable via LOOM_INSTALL_DIR), starts ClickHouse and Loom, applies migrations, tests read/write, and opens the web dashboard at http://localhost:7777/. Running it again upgrades the stack in place while keeping your settings.

The stock setup runs on stub models

Out of the box, the stack boots without keys or internet, but uses the weak local bge-small model (384 dimensions on CPU) and a fake-echo-1 LLM stub—so fact extraction, session summaries, and memory.ask stay silent. Your agent's subscription or CLI login does not pass API keys into Loom; you have to configure them separately.

You can pick providers right in the dashboard (Settings → Models & keys → Test & apply, no container restart needed) or set them in ~/.loom/.env per the Models & keys guide. One OpenAI key covers both roles:

# Enable real models instead of local bge-small and fake-echo-1
LOOM_LLM_PROVIDER=openai
LOOM_LLM_MODEL=gpt-6-luna
OPENAI_API_KEY=<your_OpenAI_key>

LOOM_EMBEDDING_PROVIDER=openai
LOOM_EMBEDDING_MODEL=text-embedding-3-large
LOOM_EMBEDDING_DIM=3072

# Prevent the server from silently falling back to stubs
LOOM_REQUIRE_REAL_PROVIDERS=true

If you use Anthropic (claude-haiku-4-5) for the LLM, you'll need a second provider for embeddings—OpenAI, Gemini (gemini-embedding-001), or an OpenAI-compatible endpoint. Note that an API key alone without LOOM_*_PROVIDER and LOOM_*_MODEL won't disable the stubs, and dashboard settings always override .env. After editing the file, recreate the container:

# Recreate the container to pick up changes from ~/.loom/.env
docker compose --project-directory "$HOME/.loom" \
  up -d --force-recreate loom

Next, connect your agents. If the installer didn't do it automatically, no token is needed on localhost—just run a couple of commands:

# Connect the plugin for Claude Code (no token needed on localhost)
claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom

# Connect the plugin for Codex
codex plugin marketplace add ClickHouse/loom
codex plugin add loom@loom

Start a new session and the agent connects to http://localhost:7777 on its own. In Codex, you must run codex interactively once after installing and approve hooks, otherwise only tools will work without automatic session capture. Local Cursor and VS Code agent mode also connect over MCP without a token (the team plugin for Cursor Teams/Enterprise is marked untested in Cursor). For custom agents, there's an HTTP API plus SDKs for Python 3.11+ and TypeScript (Node 20+), along with optional Langfuse and ClickStack / HyperDX integrations.

Who Needs Loom Now and When You're Better Off Without It

Even locally, Loom is a full client-server stack where the web server and ClickHouse share CPU and RAM. Per the Deployment guide, standalone builds cap LOOM_WEB_WORKERS at two by default (at most one per CPU core and gigabyte of RAM, max eight) to avoid starving the database, while runtime files sit in tmpfs at /run/loom.

That machinery makes sense in a large repository with multiple agents or engineers, recurring tasks, and a need to keep decision history and document search inside your perimeter. Otherwise, check the authors' own When it does not fit list—seven situations where Loom is overkill.

If you have one agent in one process needing short-term memory for a couple of hours, dragging in ClickHouse makes no sense; use an in-process library instead. Loom isn't built for sub-millisecond hot-path reads either, since every query hits SQL (with FINAL over versioned rows), so it won't replace a cache. Deep graph analytics also hits a four-hop limit—long traversals belong in a graph DB via loom entity-export.

Don't confuse roles either: Loom isn't an agent framework. It doesn't run prompts or agent loops; it only stores memory and passes tasks. Its audit trail and verified deletion (erasure saga) aren't drop-in compliance certifications. The authors also warn against running production on a single ClickHouse OSS node without backups due to missing replication and point-in-time recovery (PITR)—they recommend ClickHouse Cloud for prod. Finally, the API still evolves between releases, so pin your version and check ops.capabilities.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 8