compaction-prompts

压缩提示词

使用此技能检查、设计和更新 Letta Agent 的 compaction_settings.prompt。

当消息历史增长到接近上下文窗口上限时，就会进行压缩。Letta 会用摘要替换较早的消息，同时将最近的消息保留在上下文中。摘要会出现在保留的近期消息之前，因此提示词应保留足够的背景信息，让后续消息易于理解。目标是保持连续性，而不只是压缩事实。

官方文档：https://docs.letta.com/guides/core-concepts/messages/compaction

压缩生命周期

应将压缩视为一份生命周期契约，而不只是一段提示词：

1. 消息历史接近上下文窗口上限。
2. Letta 根据模式和滑动窗口设置选择要压缩的消息。
3. 摘要器读取所选消息。如果已有摘要也将被清除，新摘要必须将其纳入。
4. Letta 会在保留的近期消息之前重新插入摘要。
5. 下一轮模型调用会依赖摘要和近期原始消息作为后续上下文。

摘要不是对用户的回复，而是下一轮的上下文。它应能在保留的近期消息之前阅读理解，且不应依赖已清除的对话记录。

优秀的压缩提示词应明确保留当前目标、确切决策、未解决的事项、工具和文件状态、错误及更正，以及被省略内容的查找提示。对于伴侣型或长期运行的 Agent，情感或关系背景也可能很重要，但只有在其影响连续性、用户偏好、安全、修复过程或决策缘由时才应保留。自定义压缩应将上下文压缩从失忆式丢弃转变为可控交接。

何时自定义

当默认摘要丢失了重要的连续性、语气、关系背景、实现细节或用户反馈时，应自定义压缩设置。

常见情形：

• 伴侣型 Agent：保留姓名、表达风格、反复提及的内容、用户偏好，以及与未来连续性相关的情感或关系背景。
• 编码 Agent：保留明确请求、涉及的文件、运行过的命令、错误、修复、当前状态、后续步骤、ID、URL 和确切反馈。
• 长期运行的 Agent：通过纳入对话记录中的已有摘要，在反复压缩时保留更高层次的目标。

如需完整的提示词模板，请阅读 references/prompt-patterns.md。

操作检查清单

更改设置前：

1. 如需了解字段语义、默认值或模式行为，请阅读官方压缩文档。
2. 检查当前的 compaction_settings、模型和实际生效的上下文窗口。
3. 确定失效原因：提示词效果不佳、模式错误、sliding_window_percentage 过于激进、clip_chars 过小，或摘要模型不匹配。
4. 如有可能，查看最近生成的不理想摘要，或找出连续性丢失的位置。
5. 起草替换提示词，明确要求重新插入摘要，并禁止续写。
6. 使用 --dry-run 运行更新脚本，并检查 PATCH 请求体。
7. 确认要保留的字段和目标 Agent ID 后，再修改设置。
8. 随后获取该 Agent，并核实已保存的设置。
9. 如有可能，观察下一次压缩或下一轮对话，检查目标、当前任务、标识符、用户反馈和未解决的阻碍是否得以保留。

压缩字段

compaction_settings 是一个 Agent 级对象。相关字段：

字段	用途
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。它会通过单独的摘要调用来总结较早的消息，并保留最近的消息原样。
• 当 Agent 自身的角色设定／系统提示词对摘要质量或提示词缓存复用很重要时，使用 self_compact_sliding_window。提示词应明确说明不要调用工具，也不要继续对话。
• 只有在最大限度减少空间比保留最近的原始消息更重要时，才使用 all。
• 使用 self_compact_all，将 Agent 系统提示词纳入对所有消息的压缩。

配套 Agent 通常适合使用 self_compact_sliding_window，或使用提示词明确的 sliding_window。编码 Agent 通常适合使用 sliding_window，并设置目标、操作、详情、错误／修正、当前状态和查找提示等章节。

提示词要求

每个自定义提示词都应：

• 说明被移出的消息是否来自上下文窗口的开头。
• 说明摘要将显示在剩余的近期消息之前。
• 说明不要继续对话、不要回答对话记录中的问题，也不要调用工具。
• 要求纳入任何即将被移出的现有摘要。
• 包含当前状态／延续内容章节，涵盖正在进行的目标、后续操作、未解决的事项，以及 Agent 应继续执行的内容。
• 在重要时保留用户的确切请求、名称、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 字段。

使用 --dry-run 可预览 PATCH 请求正文，不做任何更改。

手动 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}'

防护措施

• 除非用户明确要求，否则更改持久化的压缩设置前应先询问。
• 对于自压缩提示词，始终禁止使用工具和继续对话。
• 提示词应具体明确。过于含糊的提示词会生成破坏连贯性的摘要。
• 不要将用户的私密信息写入共享技能。可复用的结构放入技能；具体用户信息放入 Agent 的实际提示词或记忆中。