未翻訳のページは英語で開き、英語と表示されます。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
エージェントへの Loom の組み込み
このガイドでは、エージェントが Loom に何を送り、返答をどのように読むかを説明します。対象は、クライアントの範囲、アイデンティティ、何を書き込むか、どのように読み取るかです。前提となるのは、メモリとアイデンティティと名前空間の知識です。プラグインが提供されているコーディングエージェント(Claude Code、Codex)では、その大部分をプラグインが担います。
同じルールをあなた向けではなくエージェント向けに書いたものが、loom Agent Skill(skills/loom/)です。プラグインを使わないエージェントは、サーバーからこれを読み取ります。実験的な mentor.guide は、ループ、状態の種類ごとの書き込み先、返答の読み方(part: "skill")、またはすべてのプレーンとその op(part: "reference")を返します。これをエージェントのシステムプロンプトに含めてください。
system_prompt = "You triage support tickets.\n\n" + await agent.guide()
MCP では、プライマーがこの呼び出しを示します。Agent Skills クライアントでは、npx skills add ClickHouse/loom --skill loom でインストールします。
1. クライアントサーフェスを選ぶ
| サーフェス | 使う場面 | 得られるもの |
|---|---|---|
MCP (/mcp) |
エージェントがすでに MCP を扱える LLM クライアントである場合(Claude Code、Codex、Cursor、デスクトップアプリ)。 | ?toolset= ごとに厳選されたツール一覧、モデル向けに書かれたツールの説明、接続から得られる ID のデフォルト値。呼び出すタイミングはモデルが決めます。 |
Python SDK (clickhouse-loom, from loom import Agent) |
エージェントが自前の Python プロセスである場合。 | プレーンごとの型付きクライアント、リトライと冪等性キー、モデルのツールループ向けの agent.tools()、実行スコープ、フレームワークアダプター(LangGraph LoomStore、Strands LoomMemoryStore)。 |
TypeScript SDK (@clickhouse/loom) |
エージェントが Node またはブラウザ側のサービスである場合。 | Datapack / Agent、生成された op テーブルから型付けされる agent.call(op, body)、AgentTools、Session。 |
HTTP (POST /v1/<op>) |
その他の言語、または単発のスクリプト。 | すべての op を同じ JSON ボディで利用できます。リトライと Idempotency-Key ヘッダーは自分で処理します。 |
4 つとも、1 つのレジストリから同じ op を提供します。選ぶ基準は、呼び出しを誰が決めるかです。モデルが決めるなら MCP、コードが決めるなら SDK を使います。多くのエージェントは両方を使います。開始時のコンテキストの読み込みと終了時の実行記録には SDK を、モデルが覚えるか調べるかを選ぶ場面には MCP ツールを使います。MCP では ?toolset= で一覧を選びます(MCP ツールセット)。一覧に含まれない op も loom_op から呼び出せます。
2. アイデンティティを選ぶ
すべての行は、アイデンティティのタプル (org, namespace, agent, user_id, session_id) と run_id を持ちます。トークンが org と名前空間を固定し、残りは呼び出しごとに渡されます。
| フィールド | 設定する値 | 重要な理由 |
|---|---|---|
namespace |
エージェントごとに 1 つ(agent-<name>)、またはエージェントのチームで共有する 1 つ |
メンバーシップが読み取りの境界です:名前空間の読み取り権限を持つ者は、どのエージェントが書き込んだかにかかわらず、その中のすべての行を読み取れます。 |
agent |
書き込むエージェントの安定した名前 | 分離ではなく、書き込み元を示します。MCP 経由では、クライアント名(clientInfo.name、スラッグ化したもの)がデフォルトになります。 |
user_id |
エージェントが多数のユーザーに対応する場合の、対応中のエンドユーザー | --read-scope own_user で発行したトークンでは、あるユーザーのプロンプトが別のユーザーのメモリを取得することはできません。 |
session_id |
会話またはジョブ | ワーキングメモリと own_session の読み取りをスコープし、トランスクリプトをまとめます。 |
run_id |
タスクの 1 回の実行 | 1 回の実行の書き込み、検索、チェックポイント、トランスクリプトを結び付けます(実行)。 |
- 1 つのエージェント、多数のユーザー、1 つのトークン:
--read-scope own_userでトークンを発行し(または--read-user-idで固定し)、すべての呼び出しでuser_idを渡します。スコープ付きの読み取りでuser_idがない場合は 400IDENTITY_INCOMPLETEを返し、範囲が広げられることはありません。 - 複数のエージェントで知識を共有する: 全員が読み取る共有名前空間を 1 つ用意し、各エージェントが自身の
agentで書き込みます。または、共有名前空間を読み取り、自身の名前空間に書き込むトークンを使います(ns_write)。名前空間アクセスを参照してください。 agentにシークレットや個人を特定できる識別子を入れないでください: この値はすべての台帳の行に記録されます。
3. 何を書き込むかを決める
まずプレーンを選びます。永続メモリは埋め込み、ランク付け、競合チェック、バージョン管理の対象です。ワーキングメモリはキーで読み取り、ランク付けは行いません。ナレッジはチャンク化したドキュメントを保持します。
| エージェントが持っているもの | 書き込みに使うもの | 使わないもの |
|---|---|---|
| 来週も真であり、別のセッションが必要とする事実(決定事項、制約、担当者、設定の好み) | memory.set:1 回の呼び出しにつき 1 つの事実、1 つの事実にキーを 1 つ |
ワーキングメモリ |
| 現在の計画、未確定の前提、このタスクのチェックリスト | working_memory.set / append。context.pack が読み込む |
memory.set |
| 記憶しておく価値のあるトランスクリプト、メール、スレッド | memory.set_from_messages:サーバーが短いキーの事実を抽出する |
巨大な 1 つの memory.set |
| ドキュメント(仕様書、ランブック、レポート、約 2 KB を超えるもの) | Markdown として knowledge.upsert、さらに同じキーで memory.set に案内用の段落を 1 つ書く |
テキスト全体を保持する 1 つの memory.set |
| 識別子を持つ事実の表(番号付きの PR、id 付きのサービス) | 最初に 1 回 memory_schema.register、その後 memory.record.write |
バッチごとに 1 つのメモリ行 |
| 協調状態(リース、フリーズフラグ、「現在どこまで進んだか」) | block_key を指定した working_memory.set |
ループ内の memory.set + memory.get |
| 再開用のチェックポイント | ワーキングメモリのブロック、または大きな blob には context.offload |
ステップごとの永続メモリ |
| 後で表示・検索したい会話 | conversation.create / conversation.append |
メモリ |
| 推論、あいさつ、途中のツール出力 | 何も書かない | すべて |
調査エージェントのメモリでは、この表をケースを扱うエージェントに適用しています。チェックポイントについてはトレースと再開を参照してください。
後のセッションが信頼できるように、各事実を整える:
- 主張を先に書く。 value には事実を平易なテキストで書き、出典の行をその後に続けます。埋め込まれるのは value の先頭部分だけです(抜粋は 1,200 文字で切り詰められます)。
- 読みやすいキー。 形式は
<scope>/<kind>/<id>で、ハッシュではなくsre/case/1234/evidence/dns-sidecarのようにします。ファセットはtags(case:1234、kind:evidence)とentitiesに入れます。 - 改訂は同じキーを書き換える。 Loom はバージョンを保持し(
memory.history)、現在のバージョンを返します。deploy_window_v2のようなキーを新しく作らず、現在のキーを指すインデックス行も持たないでください。 - 出典を明記する。 事実の読み取り元のファイル、URL、ドキュメントには
source_resource_idを使います。 - 推論を事実として書かない。 「A と B からの推論:C」と書き、
confidenceは 1.0 未満にします。 - 日付は解決しておく。「昨日」ではなく「
に」と書き、 valid_atには観測した時点を設定します。 - シークレットは書かない。 ユーザーが記憶してほしくない種類のものには、パターンを
blacklist.addします。一致する書き込みは 422BLACKLISTEDで拒否されます。
ユーザーの発言(「デプロイは火曜日に行う」)が書き込みのきっかけです。先に検索しないでください。重複と競合はサーバーが処理します。
4. 書き込みの応答を読む
memory.set の応答は受領確認です。次の内容を読み取ります。
| フィールド | 意味 |
|---|---|
memory_id, version, content_sha256 |
書き込みが永続化されたことを示します。これらがない場合は永続化されていません。保存されていないのに、保存したとユーザーに伝えてはいけません。 |
conflict_verdict: conflict, peers |
書き込みが既存のファクトと衝突しています(両方の行が conflicted とマークされます)。両方の値を示し、どちらが現在の値かを尋ねてください。黙って上書きしないでください。 |
409 PINNED_CONFLICT |
既存のファクトがユーザーによってピン留めされています。その旨を報告してください。新しいキーで再試行しないでください。 |
duplicate_of, merged_into_key, noop |
そのファクトはすでに登録済みで、新たに保存されたものはありません。 |
advisories |
形式に関する警告です。base64、二重エンコードされた JSON、LOOM_MEMORY_VALUE_ADVISORY_CHARS を超える値などが対象です。 |
複数の書き込み側が 1 つのキーで競合する可能性がある場合は、memory.get で取得した if_match_sha256 を渡してください。ハッシュが古いと、上書きされずに拒否されます。
5. 質問ごとに1回の呼び出しで読み取る
-
タスクごとにコンテキストを1回だけ読み込む。
context.packは、トークン予算に収まるバンドルを返します。内容は、プロファイルのセクション、作業メモリ、queryに関連するメモリ、手順で、必要に応じてナレッジ、会話、最近の実行(include_knowledge、include_conversations、include_runs)も含められます。プラグインはセッション開始時にこれを呼び出します。pack = await agent.context.pack("fix the flaky ingest test", token_budget=2000) system_prompt = base_prompt + "\n\n" + pack.rendered -
質問ごとに検索を1回だけ行う。 MCP では、
loom_searchが1回の呼び出しでメモリ、プロファイル、ナレッジ、会話を対象に検索します。SDK ではagent.memory.search(query)を使います。出典付きの回答が必要な場合はagent.memory.ask(question)を使います。回答にさらに多くの行(一覧や件数)が必要な場合にのみ、next_pageでページを送ります。 - abstain は回答として扱う。
abstain: trueは、類似度のゲートをどの候補も通過しなかったことを意味します。最も近い弱いヒットを返さず、「メモリにありません」と返答してください。abstain_codeはどのゲートかを示します(abstain コード)。pending_extractionが 0 より大きい間は、遅延された抽出が実行されていないため、空の回答が存在しない証拠にはなりません。 - 出所を尊重する。 ヒットの
source_classは、そのコンテンツがどのようにメモリに入ったかを示し、verifiedは有効な証明(attestation)が対象にかかっているかどうかを示します。memory.getはverificationを返します(human、process、証明後にコンテンツが変更された場合のstale、またはnone)。memory.askは、デフォルトではexternalと宣言され、証明されていない行を合成から除外します。
hits = await agent.memory.search("refund window for EU customers", top_k=5)
if hits.abstain:
reply = "I don't have that in memory."
else:
reply = hits[0].content_excerpt
6. 実行を記録する
実行(run)とは、タスクを 1 回実行したものです。目標、想起して依拠したメモリ、書き込んだ内容、結果を含みます。実行を記録しておくと、ランキングがどのメモリが役に立つかを学習できます(実行)。
async with agent.run_scope(goal="Fix the flaky CI job") as run:
answer = await agent.memory.ask("what broke CI last week?")
run.used("ci/flaky/runner-image")
run.final_response = "Pinned the runner image."
スコープは、開始時に run.begin を、終了時に run.complete を呼び出します。ステータスは completed または failed で、memories_used には、memory.ask の回答が引用したキーと used() に渡したキーが入ります。ブロック内の書き込みには、その run_id が付与されます。SDK を使わない場合は、run.begin と run.complete(run_id, status=..., memories_used=[...]) を自分で呼び出してください。memories_used はエージェントが依拠したメモリであり、提示されたすべてのメモリではありません。想起されたキーは別に追跡されます。
プラグインを使わないエージェントも、完了したトランスクリプトを memory.set_from_messages に渡す(または agent.session(...) を閉じる)ようにしてください。これにより、サーバーが永続的な内容を抽出します。
7. メモリスキルのレビューに従う
プラグインには loom-memory スキル(integrations/claude-code-plugin/skills/loom-memory/、Codex プラグインには生成されて含まれます)が同梱されており、このガイドの内容をモデル向けにまとめています。素の MCP 上で動作するコーディングエージェントは、エージェント向け指示ブロックを使います。このブロックの最後のメモリ行は、このレビューを短くしたものです。完全なレビューを実行するには、以下の質問をそのブロックの下に貼り付けてください。それ以外のエージェントは、質問を自分の指示にコピーします。完了を報告する前に、「はい」と答えられるものだけを書き込みます。
- 今後のセッションに必要な決定、制約、担当者を、作成した、または把握したか。
- 既存のメモリが誤っていた、または古くなっていたか。その場合は、同じキーで更新する。
- ユーザーから訂正を受けたか。その場合は事実を更新する。却下された場合は
memory.deleteで削除し、再発しそうならblacklist.addでそのパターンを登録する。 - 今後の作業で把握しておくべき成果物(ファイル、PR、ダッシュボード)を作成したか。
- 手間をかけて見つけた、自明ではない事柄があるか。
- 書き込んだ推論が確認されたか。その場合は
confidenceを上げ、「Inferred」の接頭辞を外す。
その後、namespace.validate を実行し、書き込んだキーに言及している指摘に対応します。「保存した」と言えるのは、レシートに memory_id と version が含まれていた場合のみです。「検証済み」と言えるのは、人またはプロセスが確認を証明した場合のみです。チェックを実行できなかった場合は「ここでは未検証」と書きます。ほかに同梱されているスキルは、コードに関する質問(loom-code。どのクライアントでも使えるよう skills/loom-code/ にもあります)、名前空間の再構成(loom-optimize)、セッションの復元(loom-session)、クライアントの状態確認(loom-status)を扱います。
避けるべき間違い
namespace.audit はこれらをそれぞれ検出します。名前空間の最適化は、その検出結果を修正に変えます。
| 検出項目 | 間違い | 代わりに |
|---|---|---|
double_encoded_values |
json.dumps(json.dumps(doc)):埋め込まれるテキストがエスケープされた引用符で始まります。 |
テキスト、またはオブジェクトそのものを value として送信します。 |
json_prefix_excerpts |
埋め込みの切り詰め長を超える JSON オブジェクト。ベクトルはその先頭部分から作られます。 | まずプレーンテキストとして登録し、ドキュメントは knowledge.upsert に送ります。 |
hash_keys |
行の識別子に sha を使うこと:読めず、グループ化できず、改訂が新しいキーになります。 | <scope>/<kind>/<id>。改訂は同じキーのまま行います。 |
exact_key_store |
完全一致のキーによる読み取りが検索を大きく上回る:その名前空間はオブジェクトストアです。 | memory.search で想起し、リースやポインタはワーキングメモリに置きます。 |
coordination_as_memory |
リース、ロック、凍結フラグをメモリとして保存し、ループで読み取ること。 | working_memory.set / get:埋め込み、ランク付け、競合チェックは行われません。 |
hand_rolled_index_rows |
エージェントが自分の行を見つけられないために、他のキーを列挙する行を作ること。 | tags と memory.list prefix=。改訂は memory.link supersedes でつなぎます。 |
oversized_values, unembedded_rows |
ドキュメントをメモリとして保存すること。埋め込みモデルの上限を超えた値は埋め込まれません。 | knowledge.upsert と、1 段落のポインタ行を使います。 |
episodic_blobs, version_churn |
実行ダンプをエピソード行として保存し、ステップごとに書き換えること。 | blob には context.offload を使い、実行ごとに短いエピソード行を 1 つ置きます。blob ではなく主張(claim)を改訂します。 |
監査では検出されないものがさらに 2 つあります。
- ターンごとに 1 つの blob にまとめる。 5 つの事実は、それぞれ別のキーで 5 回の
memory.set呼び出しにします。 - 稼働中のエージェントがまだ読んでいるキーを廃止する。 読み取りは
found: falseを返し、クライアントがローカル状態にフォールバックして、2 つのストアが食い違うことがあります。移動にはmemory.moveを使い(リダイレクトが残ります)、すべての読み取り側が移行するまで何も削除しないでください。