> Source: https://clickhouse.github.io/loom/ja/reference/operations/session/ (Markdown: https://clickhouse.github.io/loom/ja/reference/operations/session.md)

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

<a id="session-operations"></a>

# `session` オペレーション

各 `session.*` オペレーションが受け取るフィールドと返すフィールドの詳細です。

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

すべてのオペレーションは、HTTP では `POST /v1/<op>`、MCP ツールでは `loom_<op>` として呼び出せます。ID フィールド（`org`、`namespace`、`agent`、`user_id`、`session_id`）は、トランスポートが対応している場合にトークンと MCP セッションから補完されます。シングルユーザーサーバーでトークンなしの HTTP 呼び出しを行う場合、`code.*` と `tracker.*`（それぞれのプレーンの値を保持します）を除くすべてのオペレーションでインストールの org が使われ、[一部のオペレーション](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)では名前空間とエージェントも補完されます。詳しくは [ID と名前空間](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)を参照してください。ロール、種別、MCP の `all` 一覧については、[オペレーション一覧](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)で説明しています。未知の入力フィールドは処理され、`ignored_args` に名前が示されます。

<!-- prettier-ignore-start -->

<a id="sessionbrief_delete"></a>

## `session.brief_delete`

ユーザーから忘れるよう求められた場合に、brief_key を指定してセッションブリーフを削除します。

`POST /v1/session.brief_delete` · MCP `loom_session_brief_delete` · ロール `writer` · 冪等 · 監査対象 · MCP の `all` ツールセットには含まれません

| 入力フィールド | 型 | デフォルト | 意味 |
| --- | --- | --- | --- |
| `org` | `str` | 必須 | テナント（識別タプルの最初の要素）。 |
| `namespace` | `str` | 必須 | この op が読み書きする名前空間。 |
| `agent` | `str` | 必須 | 書き込みまたは読み取りを行うエージェント。op が許可する場合、`'-'` または `'*'` は任意のエージェントを意味します。 |
| `user_id` | `str` | `'-'` | 行が属するエンドユーザー。なしの場合は `'-'`。 |
| `session_id` | `str` | `'-'` | 行が属するセッションまたは会話。なしの場合は `'-'`。 |
| `run_id` | `str` | `'-'` | 呼び出しが属するエージェントの実行（タスクスコープ）。なしの場合は `'-'`。 |
| `brief_key` | `str` | 必須 | 削除するブリーフ。session.brief_list に表示されるキーで指定します。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `deleted` | `bool` | このキーを持つ有効なブリーフがない場合（不明、または削除済み）は False。 |
| `brief_key` | `str` | 入力の `brief_key` をそのまま返したもの。 |
| `revision` | `int` | 削除時点でのブリーフのリビジョン。何も削除されなかった場合は 0。 |

<a id="sessionbrief_get"></a>

## `session.brief_get`

ブリーフを読み込みます。`brief_key` を指定した場合はそのブリーフを、指定がなければ指定したセッションが書き込んだ最新のブリーフ（`from_session`）を、それもなければ `project` の最新のブリーフを読み込みます。

`POST /v1/session.brief_get` · MCP `loom_session_brief_get` · ロール `viewer` · 読み取り · MCP の `all` ツールセットには含まれません

| 入力フィールド | 型 | デフォルト | 意味 |
| --- | --- | --- | --- |
| `org` | `str` | 必須 | テナント（identity タプルの最初の要素）。 |
| `namespace` | `str` | 必須 | この op が読み書きする名前空間。 |
| `agent` | `str` | 必須 | 書き込みまたは読み取りを行うエージェント。op が許す場合、`'-'` または `'*'` は任意のエージェントを意味します。 |
| `user_id` | `str` | `'-'` | 行が属するエンドユーザー。なしの場合は `'-'`。 |
| `session_id` | `str` | `'-'` | 行が属するセッションまたは会話。なしの場合は `'-'`。 |
| `run_id` | `str` | `'-'` | 呼び出しが属するエージェントの実行（タスクスコープ）。なしの場合は `'-'`。 |
| `brief_key` | `str` | `''` | 読み込むブリーフ。`from_session` と `project` より優先されます。 |
| `from_session` | `str` | `''` | このセッション ID が寄与した最新のブリーフを読み込みます。 |
| `project` | `str` | `''` | このプロジェクトの最新のブリーフを読み込みます（`brief_key` と `from_session` が空の場合に使用）。 |
| `revision` | `int` | `0` | 0 = 現在のリビジョン。N = 履歴にあるそのリビジョン。 |
| `include_sections` | `bool` | `False` | 構造化された `sections` も返します。False の場合は `rendered` のみを返します。 |
| `full` | `bool` | `False` | クライアント自身の最後のコンパクション時の要約を、ブリーフの下にそのまま追加します（最大で約 15k 文字追加）。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `found` | `bool` | 一致するブリーフがない、ブリーフが削除されている、またはリビジョンが履歴にない場合は False。 |
| `brief_key` | `str` | 一致したブリーフのキー。 |
| `revision` | `int` | 返されたリビジョン（`revision` を指定しない限り現在のもの）。 |
| `rendered` | `str` | テキストとしてのブリーフ。`full` の場合は、クライアントのコンパクション要約が末尾に追加されます。 |
| `sections` | `BriefSections \| None` | 構造化されたブリーフ。`include_sections` を設定しない限り None。 |
| `project` | `str` | ブリーフに保存されているプロジェクト。 |
| `branch` | `str` | ブリーフに保存されているブランチ。 |
| `head_sha` | `str` | このリビジョンが保存されたときにチェックアウトされていたコミット。 |
| `author` | `str` | リビジョンの書き手：`llm`、`deterministic`、または `model`（呼び出したエージェント）。 |
| `trigger` | `str` | リビジョンの保存のきっかけ（`precompact`、`session_end`、`stop`、`manual`、`model`）。 |
| `actor` | `str` | リビジョンを保存したプリンシパル（`human:<subject>` / `process:<subject>`）。名前空間全体の書き込み権限を持つ書き手は、ユーザー自身の `~<user>~` ブリーフに保存できます。 |
| `source_sessions` | `list[str]` | ブリーフに寄与したセッション ID（古い順、最新の 20 件）。 |
| `updated_at` | `datetime \| None` | 返されたリビジョンが保存された日時。 |
| `age_seconds` | `int` | `updated_at` からの経過秒数。 |
| `revisions` | `int` | ブリーフの履歴に含まれるリビジョン数。 |
| `events_total` | `int` | ブリーフの全期間でブリーフに要約されたイベント数。 |
| `source_chars` | `int` | ブリーフの全期間でブリーフに要約されたイベントテキストの文字数。 |
| `brief_chars` | `int` | 保存されている `rendered` の長さ（文字数）。 |
| `deleted` | `bool` | ブリーフが書き手によって削除された場合は True。この場合、ほかには何も返されません。 |

<a id="sessionbrief_list"></a>

## `session.brief_list`

この名前空間のセッションブリーフを新しい順に一覧表示します。キー、リビジョン、経過時間、エージェント、ゴールを1ブリーフにつき1行で返します。

`POST /v1/session.brief_list` · MCP `loom_session_brief_list` · ロール `viewer` · 読み取り · MCP の `all` ツールセットには含まれません

| 入力フィールド | 型 | デフォルト | 意味 |
| --- | --- | --- | --- |
| `org` | `str` | 必須 | テナント（識別タプルの最初の要素）。 |
| `namespace` | `str` | 必須 | op が読み書きする名前空間。 |
| `agent` | `str` | 必須 | 書き込みまたは読み取りを行うエージェント。op が許可する場合、`'-'` または `'*'` は任意のエージェントを意味します。 |
| `user_id` | `str` | `'-'` | 行が属するエンドユーザー。なしの場合は `'-'`。 |
| `session_id` | `str` | `'-'` | 行が属するセッションまたは会話。なしの場合は `'-'`。 |
| `run_id` | `str` | `'-'` | 呼び出しが属するエージェントの実行（タスクスコープ）。なしの場合は `'-'`。 |
| `project` | `str` | `''` | このプロジェクトのブリーフのみ。空の場合はすべてのプロジェクト。 |
| `mine_only` | `bool` | `False` | True の場合は呼び出し元エージェントのブリーフのみ。デフォルトではすべてのエージェントのブリーフ。 |
| `from_session` | `str` | `''` | このセッション ID が寄与したブリーフのみ。空の場合はセッションによる絞り込みなし。 |
| `limit` | `int` | `10` | 返すブリーフの最大数（1-50）。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `briefs` | `list[SessionBriefSummary]` | 有効なブリーフ。最後に保存されたものが先頭。名前空間にブリーフがない場合は空。 |
| `rendered` | `str` | ブリーフ1件につき1行。そのまま表示できる形式。 |

<a id="sessionbrief_save"></a>

## `session.brief_save`

ブリーフを1件更新（または新規作成）します。

`POST /v1/session.brief_save` · MCP `loom_session_brief_save` · ロール `writer` · 冪等 · 監査対象 · MCP の `all` ツールセットには含まれません

| 入力フィールド | 型 | デフォルト | 意味 |
| --- | --- | --- | --- |
| `org` | `str` | 必須 | テナント（アイデンティティタプルの最初の要素）。 |
| `namespace` | `str` | 必須 | op が読み書きする名前空間。 |
| `agent` | `str` | 必須 | 書き込みまたは読み取りを行うエージェント。op が許可する場合、`'-'` または `'*'` は任意のエージェントを意味します。 |
| `user_id` | `str` | `'-'` | 行が属するエンドユーザー。なしの場合は `'-'`。 |
| `session_id` | `str` | `'-'` | 行が属するセッションまたは会話。なしの場合は `'-'`。 |
| `run_id` | `str` | `'-'` | 呼び出しが属するエージェントの実行（タスクスコープ）。なしの場合は `'-'`。 |
| `brief_key` | `str` | `''` | 名前空間内でのブリーフのアドレス。 |
| `project` | `str` | `''` | 作業が属するプロジェクト。`branch` と合わせて自動キーを構成します。 |
| `repo` | `str` | `''` | 作業対象のリポジトリ。ブリーフに保存されます。空の場合は保存済みの値を保持します。 |
| `branch` | `str` | `''` | 作業中のブランチ。`project` と合わせて自動キーを構成します。 |
| `head_sha` | `str` | `''` | 保存時にチェックアウトされていたコミット。空の場合は保存済みの値を保持します。 |
| `trigger` | `Literal['precompact', 'session_end', 'stop', 'manual', 'model']` | `'manual'` | 保存のきっかけ。`manual` と `model` は常に保存します。自動の `precompact`、`session_end`、`stop` は、名前空間の記録がオフの間は何も保存しません。 |
| `events` | `list[BriefEvent]` | *（算出）* | 前回の保存以降に起きたこと（最大4000件のイベント）。リビジョンにまとめられます。 |
| `sections` | `BriefSections \| None` | `None` | 呼び出し元のエージェントが自身のコンテキストから書いたブリーフ。入力されたセクションが保存済みのものを置き換えます（決定事項と行き止まりは追記されます）。 |
| `event_cursor` | `str` | `''` | イベントが終わるクライアント側の位置を示す不透明な値（トランスクリプトの行インデックス）。 |
| `if_revision` | `int \| None` | `None` | Compare-and-set：保存済みのリビジョンがこの値でない限り拒否します（409）。 |
| `use_llm` | `bool \| None` | `None` | 決定論的ビルダーを強制する（False）か、モデルを強制する（True）か。None の場合はデプロイメントの設定に従います。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `brief_key` | `str` | ブリーフが保存されたキー（キー未指定の場合は解決された自動キー）。 |
| `revision` | `int` | この呼び出し後のブリーフのリビジョン（変更がない場合は保存済みのもの。有効なものがない場合は 0）。 |
| `changed` | `bool` | 新しいリビジョンが書き込まれた場合は True。書き込まれなかった場合は False で、理由は `reason` に示されます。 |
| `author` | `str` | "llm"（モデルが更新）、"deterministic"（モデルが未設定、または失敗した場合。オペレーターの抽出ポリシー下では発生しません）、"model"（呼び出し元のエージェントがセクションを書いた）。 |
| `reason` | `str` | 何も書き込まれなかった理由：`nothing-to-save`、`recording_off`、`already-saved`、`not-revised`（オペレーターの抽出ポリシーが有効で、ブリーフを更新するモデルがない）。`changed` の場合は空。 |
| `rendered` | `str` | そのまま表示できるテキスト形式のブリーフ。変更がない場合は保存済みのもの。 |
| `stats` | `SessionBriefStats` | この保存の集計：イベント、ウィンドウ、サイズ、トークン、使用したモデル。 |

<!-- prettier-ignore-end -->
