---
title: ClickHouse Loom documentation
---

Loom is a memory, document and code-index server for AI agents, stored in ClickHouse,
with [Postgres](/docs/architecture/storage-authority#why-two-stores) as an option for live
memory and knowledge state. Agents and people reach it over MCP, HTTP, the Python and
TypeScript SDKs, and the dashboard. This page lists every page in reading order.

![The dashboard's Library: a search for a refund rule answered by cited passages](/docs/blume-assets/content/.blume-content/assets/screenshots/document-search.webp)

<video src="/docs/blume-assets/content/.blume-content/assets/screenshots/clip-assistant-answer.webm" controls autoplay loop muted playsinline width="100%" aria-label="Ask AI answering a question about refunds, with its numbered sources checked against Loom"><a href="/docs/blume-assets/content/.blume-content/assets/screenshots/clip-assistant-answer.webm">Ask AI answering with checked sources (clip)</a></video>

## Start here

| Step                     | Read                                                                                                                                                                                      |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Decide                | [Overview](/docs/getting-started/overview) → [Evaluate Loom](/docs/getting-started/evaluate)                                                                                                    |
| 2. Install               | [Quickstart](/docs/getting-started/quickstart) → [Deployment](/docs/operations/deployment)                                                                                                      |
| 3. Connect agents        | [Connect a coding agent](/docs/getting-started/connect-a-coding-agent) → [Integrations](/docs/features/integrations)                                                                      |
| 4. SDK and API           | [Your first agent](/docs/getting-started/first-agent) → [Python SDK](/docs/reference/python-sdk) / [HTTP API](/docs/reference/http-api)                                                            |
| 5. Namespaces and access | [Identities and namespaces](/docs/concepts/identities-and-namespaces) → [Tokens and grants](/docs/guides/tokens-and-grants)                                                                     |
| 6. Code index            | [Code index](/docs/features/code-index/overview) → [Repositories](/docs/features/code-index/repositories) → [Code-index operations](/docs/operations/code-index-operations)                        |
| 7. Operate               | [Monitoring](/docs/operations/monitoring) · [Troubleshooting](/docs/operations/troubleshooting) · [Upgrades](/docs/operations/upgrades) · [Backup and recovery](/docs/operations/backup-and-recovery) |

## Use cases

One page per need, each saying what Loom does for it and where to start:
[agent memory](/docs/use-cases/agent-memory) ·
[document search and RAG](/docs/use-cases/document-search) ·
[code index for coding agents](/docs/use-cases/code-intelligence) ·
[code index by language](/docs/use-cases/code-intelligence-by-language) ·
[memory linked to code](/docs/use-cases/memory-linked-to-code) ·
[coding-agent model cost](/docs/use-cases/coding-agent-cost) ·
[multi-agent shared context](/docs/use-cases/multi-agent) ·
[autonomous agents: recall, audit, erasure](/docs/use-cases/autonomous-agents) ·
[runs, traces and PR history](/docs/use-cases/runs-and-pr-history) ·
[self-hosted on ClickHouse](/docs/use-cases/self-hosted-clickhouse) ·
[all use cases](/docs/use-cases).

## 1. Getting started

- [Overview](/docs/getting-started/overview): what Loom is, when it fits, prerequisites.
- [What's included](/docs/getting-started/whats-included): Loom's main capabilities, each with its page.
- [Quickstart](/docs/getting-started/quickstart): the local stack end to end.
- [Configure models and API keys](/docs/getting-started/models-and-keys): agent subscriptions,
  server LLMs, embeddings and single-provider setups.
- [Evaluate Loom](/docs/getting-started/evaluate): smoke test, workload evaluation and
  reproducible public benchmarks.
- [Connect a coding agent](/docs/getting-started/connect-a-coding-agent): plugin or MCP entry.
- [Set up Loom with your coding agent](/docs/getting-started/agent-setup): for an agent that
  installs a pinned release and proves it works, with a fixed report.
- [Your first agent](/docs/getting-started/first-agent): an SDK tutorial.

## 2. Install and run the server

- [Deployment](/docs/operations/deployment): shapes, environment, providers, identity modes,
  proxy, images, production checklist.
- [Single sign-on](/docs/operations/sso): an OIDC identity provider for the dashboard,
  `loom login` and MCP clients.
- [Use Loom without the dashboard](/docs/guides/without-the-dashboard): `loom login`, `loom call`
  and the SDK call for every dashboard view.
- [Upgrades](/docs/operations/upgrades) · [Supported versions](/docs/operations/supported-versions) ·
  [Backup and recovery](/docs/operations/backup-and-recovery) ·
  [Monitoring](/docs/operations/monitoring) · [Maintenance](/docs/operations/maintenance) ·
  [Runtime settings](/docs/operations/runtime-settings) ·
  [Troubleshooting](/docs/operations/troubleshooting) ·
  [Code-index operations](/docs/operations/code-index-operations) ·
  [Running N replicas](/docs/operations/replicas): identical Looms behind one URL ·
  [Postgres](/docs/operations/postgres): the Postgres memory authority ·
  [Kubernetes](/docs/operations/kubernetes): the Helm chart, with EKS and kind overlays ·
  [ClickHouse Cloud and Managed Postgres](/docs/operations/clickhouse-cloud): the chart over
  both managed services ·
  [Copying a namespace to another Loom](/docs/operations/okf-sync) ·
  [Exporting usage to a data warehouse](/docs/operations/analytics-export)

## 3. Connect agents

[Integrations](/docs/features/integrations) ·
[MCP clients](/docs/features/integrations/mcp-clients) ·
[Agent instructions](/docs/features/integrations/agent-instructions) ·
[Claude Code](/docs/features/integrations/claude-code) ·
[Codex](/docs/features/integrations/codex) · [Cursor](/docs/features/integrations/cursor) ·
[VS Code](/docs/features/integrations/vscode) ·
[Frameworks](/docs/features/integrations/frameworks) ·
[Grep shim](/docs/features/integrations/grep-shim) ·
[Langfuse](/docs/features/integrations/langfuse) ·
[ClickStack](/docs/features/integrations/clickstack) ·
[OKF](/docs/features/integrations/okf)

## 4. SDK and API

[Reference index](/docs/reference) · [HTTP API](/docs/reference/http-api) ·
[MCP](/docs/reference/mcp) · [Python SDK](/docs/reference/python-sdk) ·
[TypeScript SDK](/docs/reference/typescript-sdk) · [Environment](/docs/reference/environment) ·
[Operations](/docs/reference/operations) · [Configuration](/docs/reference/configuration) ·
[Workers](/docs/reference/workers) · [CLI](/docs/reference/cli) · [Errors](/docs/reference/errors) ·
[Status](/docs/reference/status) · [Schema](/docs/reference/schema) ·
[Extractor contract](/docs/reference/extractor-contract). Operations and fields change between releases;
[unknown and removed fields](/docs/reference/http-api#unknown-and-removed-fields) says how a
client sees one the server no longer reads.

## 5. Namespaces, access and the memory model

- [Identities and namespaces](/docs/concepts/identities-and-namespaces): the tuple, roles,
  grants and read scope.
- [Memory](/docs/concepts/memory): the row, how a write is judged, time, history,
  provenance.
- [Retrieval and ranking](/docs/concepts/retrieval-and-ranking): legs, fusion, abstain,
  calibration.

## Guides

[Agent integration](/docs/guides/agent-integration) ·
[Offer Loom in an agent platform or factory](/docs/guides/agent-platforms) ·
[Headless bots](/docs/guides/headless-bots) ·
[Tokens and grants](/docs/guides/tokens-and-grants) ·
[Trace and resume long runs](/docs/guides/trace-and-resume) ·
[Optimize a namespace](/docs/guides/optimize-namespace) ·
[Investigation-agent memory](/docs/guides/investigation-agent-memory) ·
[Extraction pipelines](/docs/guides/extraction-pipeline) ·
[Performance tuning](/docs/guides/performance-tuning) · [Debugging](/docs/guides/debugging) ·
[Query Loom from Postgres](/docs/guides/query-from-postgres) ·
[Teaching with Loom](/docs/guides/teaching)

## Features

- Planes: [namespaces and sharing](/docs/features/namespaces-and-sharing) ·
  [unified search](/docs/features/unified-search) · [knowledge](/docs/features/knowledge) ·
  [entity graph](/docs/features/entity-graph) ·
  [conversations and sessions](/docs/features/conversations-and-sessions) ·
  [runs](/docs/features/runs) · [tasks and decisions](/docs/features/tasks-and-decisions) ·
  [dashboard](/docs/features/dashboard)
- Memory: [writing](/docs/features/memory/writing) ·
  [search and ask](/docs/features/memory/search-and-ask) ·
  [conflicts and refusal](/docs/features/memory/conflicts-and-refusal) ·
  [extraction](/docs/features/memory/extraction) ·
  [history and provenance](/docs/features/memory/history-and-provenance) ·
  [retention and erasure](/docs/features/memory/retention-and-erasure) ·
  [procedures and learnings](/docs/features/memory/procedures-and-learnings) ·
  [working memory and profiles](/docs/features/memory/working-memory-and-profiles)
- Observability: [audit](/docs/features/observability/audit) ·
  [cost and usage](/docs/features/observability/cost-and-usage) ·
  [telemetry](/docs/features/observability/telemetry)
- Tracker: [overview](/docs/features/tracker/overview) ·
  [record contract](/docs/features/tracker/record-contract)

## 6. Code index

[Overview](/docs/features/code-index/overview) ·
[Repositories](/docs/features/code-index/repositories) ·
[Repository Q&A for agents and chatbots](/docs/guides/repository-questions) ·
[Freshness](/docs/features/code-index/freshness) ·
[History and PRs](/docs/features/code-index/history-and-prs) ·
[Operations](/docs/features/code-index/operations) ·
[Code-index operations runbook](/docs/operations/code-index-operations)

## Architecture

[System overview](/docs/architecture/system-overview) ·
[Server layout](/docs/architecture/server-layout) ·
[ClickHouse](/docs/architecture/clickhouse) ·
[Memory architecture](/docs/architecture/memory-architecture) ·
[Storage authority](/docs/architecture/storage-authority) ·
[Cells](/docs/architecture/cells) ·
[Storage layout](/docs/architecture/storage-layout) ·
[Code-index architecture](/docs/architecture/code-index-architecture) ·
[Document extraction](/docs/architecture/document-extraction) ·
[Document sources](/docs/architecture/document-sources) ·
[LLM and embeddings](/docs/architecture/llm-architecture) ·
[Security](/docs/architecture/security) ·
[Assistant design](/docs/architecture/assistant) ·
[Failure and recovery](/docs/architecture/failure-and-recovery) ·
[Rolling upgrades](/docs/architecture/rolling-upgrades)

## Benchmarks

[Overview](/docs/benchmarks/overview) · [Coverage](/docs/benchmarks/coverage) ·
[Methodology](/docs/benchmarks/methodology) ·
[Running](/docs/benchmarks/running) · [Results](/docs/benchmarks/results) ·
[Adding a case](/docs/benchmarks/adding-a-case) · [Skill eval](/docs/benchmarks/skill-eval)

## Development

For contributors: [repository guide](/docs/development/repository-guide) ·
[local development](/docs/development/local-development) ·
[testing](/docs/development/testing) · [code generation](/docs/development/code-generation) ·
[migrations](/docs/development/migrations) ·
[release process](/docs/development/release-process) ·
[documentation style](/docs/development/documentation-style) ·
[curation loop design](/docs/development/curation-loop-design) ·
[extending Loom](/docs/development/extending-loom) ·
[add an operation](/docs/development/adding-an-operation) ·
[add a worker](/docs/development/adding-a-worker) ·
[add a table](/docs/development/adding-a-table) ·
[add language support](/docs/development/adding-language-support) ·
[dashboard design](/docs/development/dashboard-design).
[CONTRIBUTING.md](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md) covers the pull-request workflow.

## Also

[Glossary](/docs/glossary): Loom's terms, defined once. [FAQ](/docs/faq): the first questions, one
paragraph each. [`llms.txt`](https://github.com/ClickHouse/loom/blob/main/llms.txt): a generated index of the docs for agents;
[`llms-full.txt`](https://clickhouse.github.io/loom/llms-full.txt) holds, in one file, the
pages that say what Loom is and how to start.
