> Source: https://clickhouse.github.io/loom/ja/getting-started/overview/ (Markdown: https://clickhouse.github.io/loom/ja/getting-started/overview.md)

<!-- i18n: source=docs/getting-started/overview.md blob=6fbe75840c341cccfe02d72afa8d5bbb4dfb7809 model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://clickhouse.github.io/loom/getting-started/overview/)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/getting-started/overview/), which is authoritative.

<a id="overview"></a>

# 概要

Loom は、AI エージェント向けのメモリ、ドキュメント、会話、エンティティグラフ、コードインデックスを ClickHouse の行として保存するサーバーです。ライブメモリとナレッジ状態には、オプションとして [Postgres](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md) も利用できます。エージェントや人は、MCP、HTTP、Python および TypeScript の SDK、ダッシュボードから Loom にアクセスできます。ライセンスは Apache-2.0 です。このページは、Loom が用途に合うかどうかを判断する助けになります。

<a id="what-it-does"></a>

## できること

- **持続するメモリ。** エージェントが保存した事実は、後のセッションや他のツールでも利用できます。1 つのキーにつき 1 つの主張を持ち、履歴、出所、有効性を伴います。1 人のメモリにも、複数のエージェントや人で共有するメモリにもできます。
- **書き込み時のチェック。** ほぼ重複する内容は統合され、矛盾はフラグが付けられ、固定された事実に対する書き込みは拒否されます。
- **棄権する検索。** 使用している embedder 向けに調整されたゲートを通過するものがない場合、`memory.search` は理由コードとともに `abstain=true` を返します。
- **監査と消去。** メモリを変更するすべての書き込みは、コンテンツハッシュ付きの監査行を残します。`erasure.request` は、読み取りパスが参照するすべてのテーブルに対する残留調査で終了します。
- **履歴を持つコードインデックス。** リポジトリに対する検索、シンボル、呼び出し元、影響範囲、レビューコメント付きの PR 履歴、bisect 候補を提供し、各回答にはその根拠となるコミットとインデックスのティアが示されます。トラッカーソースを接続すると、課題トラッカーについても重複チェック、課題と PR のリンク、不安定なテストを扱えます。

メモリとコードインデックスは、1 つのサーバー上の別々のプレーンです。どちらか一方だけでも、両方でも使用できます。メモリにはサーバーと書き込み用トークンが必要です。コードインデックスにはさらにリポジトリの追加が必要です（`LOOM_CODE_REPOS_JSON`、または[リポジトリジョブサンドボックス](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#repository-job-sandbox)が動作している環境ではダッシュボードの **Repositories → Add repository**）。また、`LOOM_CODE_INGEST_ENABLED=true` も必要です。[Claude Code と Codex のプラグイン](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/connect-a-coding-agent.md)は両方を使用します。

<a id="where-namespaces-fit"></a>

## 名前空間の位置づけ

- **org** はテナントです。
- **名前空間**は、org の内側での共有とアクセスの単位です。通常、1 つのデプロイには、チームまたはプロジェクトごとに 1 つ、分離しておく必要がある bot ごとに 1 つ、個人ごとに 1 つの `personal-<slug>`（初回利用時に作成され、その人の MCP クライアントのデフォルトになります）、インデックス化したブランチごとに 1 つの `code-<repo>[-<branch>]` があります。
- 名前空間のすべてのメンバーは、その中のすべての行を読み取れます。
- `agent` は行を書き込んだ主体を記録するものであり、境界ではありません。
- `user_id` / `read_scope=own_user` は、1 つの bot の名前空間内でエンドユーザーを分離します。
- アクセスは名前空間に対するロール（viewer/writer/admin）で、トークンに含まれるか、グラントによって追加されます。

[IDと名前空間](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)に完全なモデルが記載されています。

<a id="when-loom-fits"></a>

## Loom が適しているケース

- 複数の AI ツールを使っていて、いずれかに伝えた内容を、個人用の名前空間で全ツールに共有させたい。
- 複数のツールや人（Claude Code、Codex、Cursor、サポートボット、ダッシュボードを使う担当者）が同じメモリを必要としている。
- エージェントが把握している内容に対して SQL を使いたい。ファクト、トレース、コスト、監査行は ClickHouse のテーブルとして保存されます。
- すでに ClickHouse を運用している、または運用できる。ClickHouse は Loom に必須の唯一のストアです。ライブメモリとナレッジの状態には、オプションとして [Postgres](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md) も使えます。
- 自信を持って誤答するよりも、回答を保留（abstain）したり、競合をフラグ付きで示したりするほうがよい。
- 履歴、来歴、監査、検証可能な消去が必要である。
- コーディングエージェントにリポジトリのインデックスが必要である。

<a id="when-it-does-not-fit"></a>

## 適合しない場合

| 状況                                                         | 適さない理由                                                | 代わりに検討するもの                            |
| ------------------------------------------------------------ | ----------------------------------------------------------- | ----------------------------------------------- |
| エージェントが1つ、プロセスが1つで、短命なメモリのみ         | 何も共有しない場合、サーバーとデータベースはオーバーヘッドになる | インプロセスのメモリライブラリ                  |
| ホットパスでのミリ秒未満のキー検索                           | すべての読み取りがデータベースクエリになる                  | 自前のストアの前段に置くキャッシュ              |
| グラフ全体の分析や長いパス                                   | 走査は1ホップにつき1回の制限付きクエリで、最大4ホップまで   | `loom entity-export` で投入するグラフストア     |
| エージェントフレームワークが必要                             | Loom はエージェントループ、プロンプト、モデルを実行しない   | Loom をメモリとして使うエージェントフレームワーク |
| コンプライアンス保証をそのまま得たい                         | 消去と監査はエンジニアリング上のプリミティブである          | それらのプリミティブを使う自社のコンプライアンス手続き |
| バックアップ計画のない単一ノードの ClickHouse OSS での本番運用 | レプリケーションもポイントインタイムリカバリもない          | ClickHouse Cloud                                |
| 固定されたAPI                                                | オペレーションとフィールドはリリース間で変わる              | リリースを固定し、`ops.capabilities` を確認する |

有効性は有効時間（`valid_at`、`valid_to`）のみです。Loom がいつ何を記録したかは、第2の時間軸ではなくバージョン履歴に残ります。一部の機能は、オペレーターが有効にする必要があります。コードインデックス、トラッカーソース、OAuth、テレメトリのエクスポート、Langfuse と ClickStack での消去です。

<a id="what-each-property-costs"></a>

## 各特性のコスト

| 特性                              | 仕組み                                                                                                  | コスト                                                                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 単一のエンジン（ClickHouse が正）  | ベクトル、字句、グラフ、フィルタ、監査、消去はすべて同じ行に対する SQL です                              | すべての読み取りがクエリになります。リーダーはバージョン付き行で `FINAL` のコストを負担します。派生行（エンティティ、サマリー）はワーカー経由で後から反映されます。 |
| 弱い一致の代わりに回答を控える    | エンベッダー自身のコサイン距離の分布から起動時に導出されるゲート（`LOOM_ADAPTIVE_THRESHOLDS`）          | 弱いが正しい一致の一部が除外されます。リクエストごとに `min_similarity` または `floor_mode` を設定してください。              |
| 変化する事実                      | 書き込みごとのマージ、重複、競合、固定の判定。追記専用の `loom.memory_versions`                          | 書き込みのたびに近傍と比較します。言い換えは、誰かが解決するまでレビューキューで待機することがあります。                      |
| 説明可能なランキング              | `explain=true` を指定した `memory.search` が各ヒットのスコアを項目別に示します。ヒットには `source_class` と `verified` が付きます | `top_k` が 15 を超える場合、`explain` はデフォルトでオフです。`explain=true` にすると各ヒットが大きくなります。               |
| アクセス制御付きの共有            | すべての行にアイデンティティタプルを持ちます。トークンとグラントは名前空間のロールを持ちます            | トークンの発行とローテーション、およびロールの付与は利用者が行います。プリンシパル間の漏えいテストスイートが、CI ですべての読み取り op をゲートします。 |
| 確認できる消去                    | 残留調査で終わる、再開可能なサーガ。外部バックエンドはフェイルクローズです                               | 消去は複数ステップのジョブです。削除を確認できないバックエンドがあると、サーガは `failed` のままとなり、手動でのエスカレーションが必要です。 |
| 鮮度付きのコード回答              | パーサーとコンパイラ（SCIP）のティア。回答には `as_of.commit` と古さのフラグが付きます                  | 大規模なリポジトリのインデックス作成には数時間かかります。コンパイラティアにはツールチェーンが必要です。                      |

品質に関する主張は、利用者自身で測定してください。リポジトリには、公開している数値の根拠となるベンチマークハーネスと生の結果が含まれています（[結果](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md)）。デフォルト値に依存する前に、実際のプロバイダーを使ってご自身のデプロイでゲートを実行してください（[実行方法](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)）。

<a id="decision-checklist"></a>

## 判断チェックリスト

右側の列に該当する回答が 2 つ以上ある場合、Loom は適したツールではない可能性が高いです。

| 質問                                                                      | Loom に向く | Loom に向かない            |
| ------------------------------------------------------------------------- | ----------- | -------------------------- |
| 2 つ以上のツールやエージェントでメモリを共有する必要がありますか。        | はい        | いいえ、単一のプロセス     |
| ClickHouse を実行し、サービスを運用できますか。                           | はい        | いいえ、マネージドが必要   |
| データを自社のインフラ内に留める必要がありますか。                        | はい        | 特にこだわりなし           |
| 自信のある誤答よりも、回答の保留や矛盾の指摘のほうが望ましいですか。      | はい        | 常に何か返す必要がある     |
| 履歴、来歴、監査、検証可能な消去が必要ですか。                            | はい        | いいえ                     |
| ホットパスは 1 ミリ秒未満のキー検索ですか。                               | いいえ      | はい                       |
| 数ホップではなく、グラフ全体の分析が必要ですか。                          | いいえ      | はい                       |
| リリース間の API 変更を吸収できますか。またはバージョンを固定できますか。 | はい        | いいえ                     |
| 実際の埋め込みモデルと LLM に費用をかけ、自分のデータでベンチマークできますか。 | はい        | いいえ                     |

<a id="prerequisites"></a>

## 前提条件

| 必要なもの                                        | 用途                                                                                                                                                                                                                                                           |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ClickHouse（評価には OSS、本番では Cloud）        | すべての機能。[ClickHouse の要件](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#clickhouse-requirements)を参照してください。                                                                                                                                                                |
| Postgres 16+（任意）                              | [Postgres メモリオーソリティ](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md)のもとでのライブメモリとナレッジの状態。デプロイの初回起動時に選択します。`LOOM_PG_DURABILITY=local` でない限り、同期スタンバイが必要です（[要件](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md#requirements)）。 |
| Compose 2.20 以降を含む Docker                    | リリース済みのローカルスタック（ワンラインインストーラ。Windows では [WSL 2 から](https://clickhouse.github.io/loom/ja/getting-started/quickstart/#fast-path-released-image-no-clone)）とサーバーイメージ。                                                                                                                   |
| Python 3.12+                                      | コントリビューター専用の `loom up`、サーバー開発、オペレーター CLI の作業。                                                                                                                                                                                          |
| 埋め込みプロバイダー                              | 実際の検索：OpenAI、Gemini、またはリリース済みスタックが使用するローカル CPU 埋め込みモデル。                                                                                                                                                                             |
| LLM プロバイダー                                  | 抽出、`memory.ask` の合成、`code.ask`：OpenAI または Anthropic。                                                                                                                                                                                           |
| トークンと名前空間                                | アクセス。[トークンとグラント](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md)を参照してください。                                                                                                                                                                                               |
| コードインデックス用                              | リポジトリへの Git アクセス、PR 履歴用の `LOOM_CODE_GITHUB_TOKEN`、および初回インデックス作成のための時間。                                                                                                                                                         |

<a id="next"></a>

## 次のステップ

[Loom の評価](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/evaluate.md)では、製品のスモークテストと実際の品質評価を区別して説明しています。[クイックスタート](https://clickhouse.github.io/loom/ja/getting-started/quickstart/)では、ローカルスタックを実行します。[デプロイ](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md)では、チーム向けに Loom を運用する方法を説明します。[ドキュメントマップ](https://github.com/ClickHouse/loom/blob/main/docs/index.md)には、すべてのページが読む順序で並んでいます。
