by ClickHouse
Provides shared long‑term memory, document search, and code intelligence for AI coding agents, backed by ClickHouse.
ClickHouse Loom delivers a self‑hosted MCP server that stores and indexes memories, documents, and source‑code symbols. Memories are linked to the exact files and symbols they reference, surfacing automatically when an agent edits or reads the related code. The system also exposes a searchable code index and RAG‑style document retrieval, enabling multiple agents to share context, hand off tasks, and audit their work.
http://localhost:7777.~/.loom/.env to specify embedding and LLM providers (e.g., OpenAI, Claude). A local embedding model works out‑of‑the‑box.memory.ask, code.search, or document.search via the HTTP API, Python SDK, TypeScript SDK, or the MCP protocol.Q: Do I need an external database? A: Loom stores embeddings, memories, and code indexes in ClickHouse by default. An optional Postgres instance can be used for live memory state at first boot.
Q: Can I run Loom without internet access? A: Yes. The default installation includes a local embedding model and a fake LLM, allowing full indexing and search offline. Real LLM calls require API keys.
Q: Is Loom a library for a single agent? A: No. Loom is a centralized server offering shared memory and code intelligence; it is not an in‑process short‑term memory library.
Q: Which programming languages are supported for the code index? A: The built‑in indexer handles C++, Go, Python, TypeScript, and other common languages. Language support details are in the documentation.
Q: How do I secure a multi‑user deployment? A: Enable multi‑user mode at first boot, configure TLS, and issue scoped tokens per namespace. Permissions are managed via role‑based access controls in the dashboard.
Q: Can I integrate with observability tools? A: Optional integrations exist for Langfuse (trace and cost) and ClickStack/HyperDX (OpenTelemetry metrics, logs, and traces).
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. In an authenticated team deployment, each agent uses a token scoped to namespaces and read or write roles. Check shared memory and denied access.
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.
.docx and .pptx files the
extractor service converts. Document searchMemory for a software factory. Loom gives implementation and review agents shared lessons, issue context and source provenance across sessions. Scope each principal's access with tokens, await required writes and task handoffs in your application, and recheck code-linked lessons against the current source before review. The same service supports multi-agent workflows and autonomous bots; your orchestration runs the agents, tests and approvals. Offering a tool does not guarantee the model uses it. Multi-agent workflow · Autonomous-agent memory
Every use case, and when another tool fits better: use cases.
Read Choosing memory for a software factory for memory architecture choices, data ownership and operating responsibilities.
Loom is not an in-process library for one agent's short-lived memory, nor an agent framework. When Loom does not fit
| Evaluation | With Loom | Without Loom | Efficiency gain | Scope |
|---|---|---|---|---|
| Coding-agent answer quality | 0.84 | 0.78 | 20% lower model cost | 24 questions × 3 paired runs |
| Coding-agent file localization | 96.4% | 91.4% | 21% lower model cost | 36 questions × 10 paired runs |
| Memory vs full-history answers | 94% | 90% | 91% fewer reader prompt tokens | 100 paired LongMemEval-S questions |
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
dev/local
namespace. One person can connect multiple agents.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.
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.
| Component | Configure for real use | Without configuration |
|---|---|---|
| Embeddings | Provider, embedding model, dimensions and API key. | local (bge-small on CPU): semantic retrieval, weaker than a hosted model. |
| LLM | Provider, model and API key. | fake-echo-1: no meaningful extraction, summaries or 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_<NAME> 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 <name> <value>, or Admin → Deployment
settings. loom settings list --changed shows what differs from the defaults and
where each value came from (runtime settings).
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 a Teams or Enterprise plan, a team admin can import this repository as a team marketplace; its Cursor plugin, untested in Cursor, installs the MCP entry and Loom's skills. On the machine running a personal installation, the button below adds the local MCP entry, which needs no token:
For VS Code agent mode on the machine running a personal installation, the buttons below add the local MCP entry, which needs no token:
For a team server, pass --config server_url=… --config token=… to Claude Code, or
point Codex at it as described in
connect a coding agent. Create
tokens in Settings → Tokens. Cursor and other MCP clients, and
the SDK, are covered there too.
| Integration | What it connects |
|---|---|
| Claude Code, Codex, Cursor and other MCP clients (all integrations) | Memory and code intelligence in your existing agent workflow. |
| Python, TypeScript, Rust, Go, .NET and HTTP | Your own agents and applications. |
| Langfuse | Request traces, model costs, retrieval scores and prompt-version attribution. |
| ClickStack / HyperDX | OpenTelemetry traces, logs and metrics in ClickHouse. |
Langfuse and ClickStack are optional integrations, not bundled services in the Docker stack.
| Evaluation | Result |
|---|---|
| LongMemEval-S evidence retrieval (500 questions) | 98.6% of questions with at least one supporting session in the first 30 memories. |
LongMemEval-S fixed gpt-5 reader (500 questions) |
92.0% answer accuracy from the top 200 memories. |
| LoCoMo (all 10 conversations) | 89.6% answer accuracy; 90.8% correct abstentions on adversarial questions. |
| MemoryAgentBench fact-question sample (500 questions) | 99.0% SubEM; 95.7% token-overlap F1 on generated answers. |
| Conceptual code search (36 questions) | Gold-file recall 91.2% at 5 / 97.2% at 10; MRR 0.91. |
| SWE-bench Verified file localization (200 issues) | Issues with a changed file in the first 10: 82% vs 57% for BM25; 76.5% in the first 5. |
| Tracker duplicate detection (104 pairs) | Recorded older duplicate ranked first 87.5% of the time. |
These measure different tasks, not one aggregate score. SWE-bench measures file localization, not issue resolution. The results ledger includes scoring definitions, small-sample evaluations, weaker and negative findings, and the full protocols, models and artifacts.
Methodology · coverage and known gaps · run the benchmarks
For shared agent context, code intelligence and permissioned retrieval, start with the documentation. For deployment requirements, see the prerequisites.
Deployment · FAQ ·
Contributing · Security reporting ·
llms.txt ·
llms-full.txt
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
by topoteretes
Provides dynamic memory for AI agents through modular ECL (Extract, Cognify, Load) pipelines, enabling seamless integration with graph and vector stores using minimal code.
by basicmachines-co
Enables persistent, local‑first knowledge management by allowing LLMs to read and write Markdown files during natural conversations, building a traversable knowledge graph that stays under the user’s control.
by agentset-ai
Provides an open‑source platform to build, evaluate, and ship production‑ready retrieval‑augmented generation (RAG) and agentic applications, offering end‑to‑end tooling from ingestion to hosting.
by smithery-ai
Provides read and search capabilities for Markdown notes in an Obsidian vault for Claude Desktop and other MCP clients.
by chatmcp
Summarize chat messages by querying a local chat database and returning concise overviews.
by dmayboroda
Provides on‑premises conversational retrieval‑augmented generation (RAG) with configurable Docker containers, supporting fully local execution, ChatGPT‑based custom GPTs, and Anthropic Claude integration.
by qdrant
Provides a Model Context Protocol server that stores and retrieves semantic memories using Qdrant vector search, acting as a semantic memory layer.
by doobidoo
Provides a universal memory service with semantic search, intelligent memory triggers, OAuth‑enabled team collaboration, and multi‑client support for Claude Desktop, Claude Code, VS Code, Cursor and over a dozen AI applications.