---
id: reflection
title: Reflection の調整
category: admin
order: 180
keywords: [Reflection, 学習, 自動改善, memory, piece]
---

# Reflection の調整 (admin)

**Reflection (Hermes mode)** は、タスクが終わるたびに安いモデルでそのジョブを振り返り、ユーザーの memory や piece への更新を提案する仕組みです。これにより、エージェントが同じユーザーの好みや過去の失敗を学習し、徐々に賢くなっていきます。

コストと安全性のトレードオフがあるため **デフォルトでは無効** で、admin が明示的に有効化・調整します。

## 何をするのか

1. 通常ジョブが `succeeded` / `failed` / `aborted` のいずれかで終了する
2. 裏で `task_kind='reflection'` の新規ジョブが作られる
3. `roles: [reflection]` を持つ専用 worker が、cheap なモデルでそれを拾う
4. reflection ハンドラがユーザーの memory・activity log サマリ・タスクコメント・feedback を読み、`submit_reflection` で更新案を出す
5. 意味検証 (validator) を通過した変更だけが memory / piece に atomic に適用される
6. 全変更は snapshot として保存され、後から revert 可能

LLM が「学ぶことはない」と判断した場合は何も変更しません (abstain)。これが正常な多数派です。

## 有効化と調整

設定 → **Agent Runtime → Reflection** で操作します。

### 有効化

- **Reflection を有効化（自動適用）** チェックボックス — これが全体スイッチ (`reflection.enabled`)。デフォルト OFF
- 有効化しても、`roles: [reflection]` を持つ worker が LLM → Workers に無いとジョブは enqueue されず、フォーム上に警告が出ます。cheap モデル + `roles: [reflection]` の worker を 1 つ追加してください

### 主な調整項目

`config.yaml` の `reflection.*` (スネークケース) として保存されます。

| 項目 | キー | デフォルト | 意味 |
|------|------|-----------|------|
| 専用 worker を必須にする | `worker_required` | true | reflection worker が無ければスキップ |
| Max memory changes per job | `max_memory_changes_per_job` | 3 | 1 ジョブで書ける memory entry 上限 |
| Max entry body bytes | `max_entry_body_bytes` | 8192 | memory entry 本文の最大バイト |
| Piece edit cooldown (hours) | `piece_edit_cooldown_hours` | 24 | 同じ piece への連続編集の cooldown |
| Per-user daily budget (tokens) | `per_user_daily_budget_tokens` | 200000 | 1 ユーザー / 1 日の token 上限 |
| Snapshot retention (days) | `snapshot_retention_days` | 90 | snapshot の保持日数 |
| Abstain rate floor | `abstain_rate_floor` | 0.3 | abstain 率がこれを下回ると過剰学習として warn |

## built-in piece は触らない

Reflection が piece への変更を提案しても、**組み込み piece (`pieces/{name}.yaml`) は決して書き換えません**。代わりに `data/users/{userId}/pieces/{name}.yaml` への **silent fork** を作り、そちらを編集します。fork の frontmatter には `forked_from_commit` が記録され、本家との差分を追えます。

さらに cooldown による暴走防止が働きます:

- `piece_edit_cooldown_hours` (デフォルト 24h) 以内は同じ piece を再編集しない
- ウィンドウ内の編集回数にも上限がある (デフォルト 2 回 / 24h)

これにより「Reflection が毎タスク piece を書き換えて挙動が安定しない」事故を防ぎます。

## 結果の確認

学習結果は次の 2 か所で見えます。

- **設定 → 🧠 Reflection 履歴** — Reflection の適用履歴と各履歴の **revert ボタン**（memory の現在値・編集は ユーザーフォルダ → memory/）。詳細は [メモリと学習](#memory) を参照
- **タスク詳細の概要タブ** — そのタスクの Reflection が実際に変更を加えた場合だけ **🧠 Learned N things** バッジが出る (piece も編集した場合は「+ piece edit」付き)

revert は before snapshot から memory / piece を書き戻します。ユーザー自身の編集を上書きしないよう CAS (Compare-and-Swap) ベースで安全に実装されています。

## 運用の指針

- まず `enabled: false` のまま運用し、タスクが十分溜まってから有効化する。空のユーザーで回しても学ぶものがない
- cheap モデルを専用 worker に割り当ててコストを抑える
- 適用が多すぎる (abstain 率が `abstain_rate_floor` を下回る) と warn がログに出る。`max_memory_changes_per_job` を下げて様子を見る
- 緊急停止は `reflection.enabled: false`。進行中のジョブは完走するが、新規 enqueue は止まる
- 気に入らない学習は履歴の revert で気軽に戻せる。信用しきれないうちは「ダメなら戻す」運用が安全

## TIP

> Reflection は通常タスクごとに 1 回追加で LLM 呼び出しを行う。コスト倍増を避けるため必ず cheap モデルの専用 worker を使う。

> `worker_required: true` のままにしておけば、worker を止めるだけで Reflection を一時停止できる。
