コンテンツにスキップ

未翻訳のページは英語で開き、英語と表示されます。

このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 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 がない場合は 400 IDENTITY_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 します。一致する書き込みは 422 BLACKLISTED で拒否されます。

ユーザーの発言(「デプロイは火曜日に行う」)が書き込みのきっかけです。先に検索しないでください。重複と競合はサーバーが処理します。

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. タスクごとにコンテキストを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
    
  2. 質問ごとに検索を1回だけ行う。 MCP では、loom_search が1回の呼び出しでメモリ、プロファイル、ナレッジ、会話を対象に検索します。SDK では agent.memory.search(query) を使います。出典付きの回答が必要な場合は agent.memory.ask(question) を使います。回答にさらに多くの行(一覧や件数)が必要な場合にのみ、next_page でページを送ります。

  3. abstain は回答として扱う。 abstain: true は、類似度のゲートをどの候補も通過しなかったことを意味します。最も近い弱いヒットを返さず、「メモリにありません」と返答してください。abstain_code はどのゲートかを示します(abstain コード)。pending_extraction が 0 より大きい間は、遅延された抽出が実行されていないため、空の回答が存在しない証拠にはなりません。
  4. 出所を尊重する。 ヒットの 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 上で動作するコーディングエージェントは、エージェント向け指示ブロックを使います。このブロックの最後のメモリ行は、このレビューを短くしたものです。完全なレビューを実行するには、以下の質問をそのブロックの下に貼り付けてください。それ以外のエージェントは、質問を自分の指示にコピーします。完了を報告する前に、「はい」と答えられるものだけを書き込みます。

  1. 今後のセッションに必要な決定、制約、担当者を、作成した、または把握したか。
  2. 既存のメモリが誤っていた、または古くなっていたか。その場合は、同じキーで更新する。
  3. ユーザーから訂正を受けたか。その場合は事実を更新する。却下された場合は memory.delete で削除し、再発しそうなら blacklist.add でそのパターンを登録する。
  4. 今後の作業で把握しておくべき成果物(ファイル、PR、ダッシュボード)を作成したか。
  5. 手間をかけて見つけた、自明ではない事柄があるか。
  6. 書き込んだ推論が確認されたか。その場合は 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 を使い(リダイレクトが残ります)、すべての読み取り側が移行するまで何も削除しないでください。

関連ドキュメント