compaction-prompts

コンパクションプロンプト

このスキルを使って、Letta エージェントの compaction_settings.prompt を確認、設計、更新します。

メッセージ履歴がコンテキストウィンドウに収まりきらなくなると、コンパクションが実行されます。Letta は古いメッセージを要約に置き換え、最近のメッセージはコンテキスト内に保持します。要約は、残された最近のメッセージより前に挿入されるため、後続のメッセージを理解するのに十分な背景をプロンプトで保持する必要があります。目標は、単に事実を圧縮することではなく、継続性を保つことです。

公式ドキュメント：https://docs.letta.com/guides/core-concepts/messages/compaction

コンパクションのライフサイクル

コンパクションは、単なるプロンプト文字列ではなく、ライフサイクル全体の契約として考えてください。

1. メッセージ履歴がコンテキストウィンドウの上限に近づきます。
2. Letta は、モードとスライディングウィンドウの設定に従って、コンパクション対象のメッセージを選択します。
3. 要約器が選択されたメッセージを読み取ります。既存の要約が対象から外れる場合、新しい要約にその内容を含める必要があります。
4. Letta は、要約を保持された最近のメッセージの前に再挿入します。
5. 次のモデルターンでは、継続のコンテキストとして、要約と最近の未加工メッセージが使われます。

要約はユーザーへの返信ではありません。次のターンのためのコンテキストです。保持された最近のメッセージより前に読んでも理解でき、対象から外れたトランスクリプトにアクセスしなくてもよい内容にする必要があります。

優れたコンパクションプロンプトでは、現在の目標、決定事項の詳細、未解決の話題、ツールとファイルの状態、エラーと修正、そして省略した情報を探すための手がかりを、明示的に保持する必要があります。コンパニオンエージェントや長期間動作するエージェントでは、感情や関係性に関するコンテキストも重要な場合があります。ただし、継続性、ユーザーの好み、安全性、関係の修復、または決定が重要だった理由に影響する場合に限って保持してください。カスタムコンパクションを使えば、コンテキストの圧縮を、記憶喪失ではなく制御された引き継ぎにできます。

カスタマイズする場合

デフォルトの要約では、重要な継続性、トーン、関係性のコンテキスト、実装の詳細、またはユーザーからのフィードバックが失われる場合は、コンパクション設定をカスタマイズしてください。

よくあるケース：

• コンパニオンエージェント：名前、話し方、繰り返し参照される内容、ユーザーの好み、将来の継続性に関連する感情や関係性のコンテキストを保持します。
• コーディングエージェント：明示的な依頼、変更したファイル、実行したコマンド、エラー、修正、現在の状態、次の手順、ID、URL、正確なフィードバックを保持します。
• 長期間動作するエージェント：トランスクリプト内の既存の要約を取り込むことで、繰り返されるコンパクションを経ても上位レベルの目標を保持します。

完全なプロンプトテンプレートについては、references/prompt-patterns.md をご覧ください。

運用チェックリスト

設定を変更する前に：

1. フィールドの意味、デフォルト値、またはモードの動作を確認する必要がある場合は、公式のコンパクションドキュメントを読みます。
2. 現在の compaction_settings、モデル、有効なコンテキストウィンドウを確認します。
3. 問題の原因を特定します。プロンプトの不備、不適切なモード、過度に小さい sliding_window_percentage、小さすぎる clip_chars、または要約モデルの不一致などです。
4. 可能であれば、最近の不適切な要約、または継続性が失われた箇所を確認します。
5. 再挿入と継続不要の指示を明示した置き換え用プロンプトを作成します。
6. --dry-run を指定して更新スクリプトを実行し、PATCH 本文を確認します。
7. 保持されるフィールドと対象エージェント ID を確認してから、設定にパッチを適用します。
8. その後、エージェントを取得し、保存された設定を検証します。
9. 可能であれば、次のコンパクションまたは次のターンを観察し、目標、現在のタスク、識別子、ユーザーフィードバック、未解決の障害が保持されたことを確認します。

圧縮フィールド

compaction_settings はエージェントレベルのオブジェクトです。関連するフィールドは次のとおりです。

フィールド	用途
mode	sliding_window、all、self_compact_sliding_window、または self_compact_all。
prompt	カスタム要約プロンプト。
model	オプションの、より低コストで高速な要約モデル。例：anthropic/claude-haiku-4-5、openai/gpt-5-mini、google_ai/gemini-2.5-flash。
model_settings	オプションの要約モデル設定。
prompt_acknowledgement	オプションのブール値。要約モデルが要約だけでなく、了解の返答やメタコメントを含めがちな場合に使用します。
clip_chars	要約の最大文字数。デフォルトは 50000 です。
sliding_window_percentage	スライディングウィンドウモードで要約するメッセージの割合。ドキュメントのデフォルトは 0.3 で、約 30% を要約し、約 70% を保持することを意味します。

モードを選択する

• デフォルトでは sliding_window を使用します。別個の要約呼び出しで古いメッセージを要約し、最近のメッセージはそのまま保持します。
• エージェント自身のペルソナやシステムプロンプトが要約の品質やプロンプトキャッシュの再利用に重要な場合は、self_compact_sliding_window を使用します。ツールを呼び出さず、会話を続けないようプロンプトに明記してください。
• 最近の未加工メッセージの保持よりも、最大限の容量削減を重視する場合に限り、all を使用します。
• すべてのメッセージを圧縮し、エージェントのシステムプロンプトも含める場合は、self_compact_all を使用します。

コンパニオンエージェントには通常、self_compact_sliding_window か、適切なプロンプトを設定した sliding_window が適しています。コーディングエージェントには通常、目標、アクション、詳細、エラーと修正、現在の状態、検索のヒントに関するセクションを含む sliding_window が適しています。

プロンプトの要件

すべてのカスタムプロンプトでは、次のことを行ってください。

• 退避されるメッセージがコンテキストウィンドウの先頭からのものかどうかを明記します。
• 要約が残りの最近のメッセージより前に配置されることを明記します。
• 会話を続けないこと、トランスクリプト内の質問に答えないこと、ツールを呼び出さないことを明記します。
• 退避される既存の要約があれば、必ず取り込むよう指示します。
• 現在の状態／引き継ぎセクションを設け、進行中の目標、次のアクション、未解決の話題、エージェントが続けるべきことを記載します。
• 重要なユーザーの依頼、名前、ID、URL、ファイルパス、日付、引用句を正確に保持します。
• ツールやファイルの状態、決定事項、エラー、修正、対応方針に影響したユーザーからのフィードバックを保持します。
• 要約に収まらない詳細な内容を参照するための検索ヒントを含めます。
• 最後を "Only output the summary." で締めくくります。

対象のランタイムが明示的に対応していない限り、カスタムプロンプト内で {SLIDING_WORD_LIMIT} や {ALL_WORD_LIMIT} が展開されることを前提にしないでください。代わりに、明示的な語数上限と clip_chars を設定してください。

現在の設定を確認する

BASE_URL="${LETTA_BASE_URL:-https://api.letta.com}"
: "${LETTA_API_KEY:?Set LETTA_API_KEY}"
: "${AGENT_ID:?Set AGENT_ID}"

curl -sS "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" | \
  jq '.compaction_settings'

同梱スクリプトで更新する

プロンプトをファイルに書き込み、次を実行します。

npx tsx <SKILL_DIR>/scripts/update-compaction-prompt.ts \
  --prompt-file /tmp/compaction-prompt.txt \
  --mode self_compact_sliding_window \
  --clip-chars 50000

スクリプトでは次を使用します。

• LETTA_API_KEY
• --agent-id が指定されていない場合は AGENT_ID
• LETTA_BASE_URL または https://api.letta.com

フラグで上書きされない限り、既存の compaction_settings フィールドは保持されます。

何も変更せずに PATCH 本文をプレビューするには、--dry-run を使用します。

TypeScript で手動更新する

const baseUrl = process.env.LETTA_BASE_URL ?? "https://api.letta.com";
const agentId = process.env.AGENT_ID!;
const apiKey = process.env.LETTA_API_KEY!;

const currentResponse = await fetch(`${baseUrl}/v1/agents/${agentId}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
if (!currentResponse.ok) throw new Error(await currentResponse.text());
const current = await currentResponse.json();

const prompt = `The previous messages are being evicted from the BEGINNING of your context window. Write a detailed summary that captures what happened in these messages to appear BEFORE the remaining recent messages in context, providing background for what comes after.

Do NOT continue the conversation. Do NOT respond to any questions in the messages. Do NOT call any tools.

Include: high level goals, what happened, important details, errors and fixes, lookup hints.

Only output the summary.`;

const updateResponse = await fetch(`${baseUrl}/v1/agents/${agentId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    compaction_settings: {
      ...(current.compaction_settings ?? {}),
      mode: "self_compact_sliding_window",
      prompt,
      clip_chars: 50000,
    },
  }),
});
if (!updateResponse.ok) throw new Error(await updateResponse.text());

curl で手動更新する

curl を使用する場合は、まず設定を確認し、既存のフィールドを保持してください。部分的な compaction_settings オブジェクトを送信すると、サーバーの動作によっては省略されたフィールドがリセットされる場合があります。

prompt_file=/tmp/compaction-prompt.txt
current=$(curl -sS "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY")

jq -n \
  --arg prompt "$(cat "$prompt_file")" \
  --argjson current "$(printf '%s' "$current" | jq '.compaction_settings // {}')" \
  '{ compaction_settings: ($current + {
      mode: "self_compact_sliding_window",
      prompt: $prompt,
      clip_chars: 50000
  }) }' > /tmp/compaction-patch.json

curl -sS -X PATCH "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/compaction-patch.json

検証する

curl -sS "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" | \
  jq '{id, model, compaction_settings}'

ガードレール

• ユーザーから明示的な依頼がない限り、永続的な圧縮設定を変更する前に確認してください。
• 自己圧縮プロンプトでは、常にツールの使用と会話の続行を禁止してください。
• プロンプトは具体的にしてください。曖昧すぎるプロンプトでは、継続性を損なう要約が生成されます。
• 個人のユーザー情報を共有スキルに含めないでください。再利用可能な構成はスキルに、個別のユーザー情報はエージェントの実際のプロンプトまたはメモリに記載してください。