letta-ai/self-configuration

Letta self-configuration

Use the Letta API when an agent needs to change its own persistent defaults or the current conversation's temporary runtime settings.

Safety rule

Ask before changing persistent agent defaults unless the user explicitly requested the change. Persistent changes include agent model, system prompt, context window, model settings, and compaction settings. Prefer conversation-scoped changes for experiments.

Decision tree

• Need a temporary model/context experiment? Patch the current conversation.
• Need persistent model, system prompt, or compaction behavior? Patch the agent.
• Need better summaries after context eviction? Use the Compaction settings section and prompt patterns.
• Need provider keys, BYOK setup, or server deployment env vars? Use the broader Letta configuration/API skills instead.
• Need to design a new agent from scratch? Use the agent-development skill.

Environment

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

Use AGENT_ID for yourself. Use CONVERSATION_ID for the current thread when it is available.

Inspect first

curl -sS "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" | \
  jq '{id, model, context_window_limit, llm_config, model_settings, compaction_settings, system_chars: (.system | length)}'

Choose the API target

| Target | Endpoint | Persistence | Use for | | --- | --- | --- | --- | | Agent | PATCH /v1/agents/$AGENT_ID | Persistent across conversations | model defaults, context window, system prompt, compaction settings | | Conversation | PATCH /v1/conversations/$CONVERSATION_ID | Current conversation only | temporary model/context/reasoning experiments |

Quick patches

Context window only

context_window_limit is top-level. Do not put it inside model_settings.

curl -sS -X PATCH "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context_window_limit": 64000}'

Conversation-scoped:

: "${CONVERSATION_ID:?Set CONVERSATION_ID}"

curl -sS -X PATCH "$BASE_URL/v1/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context_window_limit": 64000}'

Agent-level model update

model_settings is usually treated as a replacement object, not a deep merge. Read the current agent first and include any existing settings you want to keep. Provider-specific examples live in references/model-settings.md.

curl -sS -X PATCH "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "context_window_limit": 272000,
    "model_settings": {
      "provider_type": "openai",
      "parallel_tool_calls": true,
      "reasoning": { "reasoning_effort": "medium" },
      "max_output_tokens": 128000
    }
  }'

Conversation-scoped model update

: "${CONVERSATION_ID:?Set CONVERSATION_ID}"

curl -sS -X PATCH "$BASE_URL/v1/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "context_window_limit": 64000,
    "model_settings": {
      "provider_type": "openai",
      "parallel_tool_calls": true,
      "reasoning": { "reasoning_effort": "low" }
    }
  }'

Safe conversation-scoped model test

A successful PATCH means the API accepted the configuration shape. It does not always prove the selected model handle can generate at runtime for the current server, provider, account, or routing configuration. The first actual model call may still fail with a resolver/provider error.

For model experiments, prefer this bounded recipe:

1. Save or inspect the current agent/conversation configuration.
2. Patch the current conversation, not persistent agent defaults.
3. Verify the response or re-fetch the conversation to confirm the config changed.
4. Run a tiny low-risk runtime test in the same conversation.
5. If the runtime test fails, revert the conversation to the saved known-good model/settings.

This keeps failed model-handle experiments from damaging the agent's persistent continuity or requiring the user to repair global defaults.

System prompt replacement

Only use system when the user explicitly asks to change the persistent system prompt. It is a full replacement, not an append.

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

Then send the complete replacement prompt:

curl -sS -X PATCH "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"system": "<FULL replacement system prompt. Preserve important existing instructions.>"}'

Safer bundled updater

Use scripts/update-agent-settings.ts when you want a dry-runable patch that can optionally merge existing model_settings or compaction_settings before updating.

npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
  --target agent \
  --context-window-limit 64000 \
  --dry-run

Examples and all flags are in references/api-patch-examples.md.

Compaction settings

Compaction runs when message history grows too large for the context window. Letta replaces older messages with a summary while keeping recent messages in context. The summary appears before the remaining recent messages, so a custom compaction prompt should preserve enough background for the later messages to make sense.

Customize compaction when the default summary loses important continuity, tone, relationship context, implementation details, or user feedback.

Compaction fields

| Field | Use | | --- | --- | | mode | sliding_window, all, self_compact_sliding_window, or self_compact_all. | | prompt | Custom summarization prompt. | | model | Optional cheaper/faster summarizer model. | | model_settings | Optional summarizer model settings. | | prompt_acknowledgement | Optional boolean for summarizers that add acknowledgements/meta-commentary. | | clip_chars | Max summary length in characters. Default is 50000. | | sliding_window_percentage | Fraction of messages to summarize in sliding-window modes. Docs default: 0.3. |

Choose a compaction mode

• Use sliding_window by default. It summarizes older messages with a separate summarizer call and keeps recent messages intact.
• Use self_compact_sliding_window when the agent's own persona/system prompt is important for summary quality or prompt-cache reuse.
• Use all only when maximum space reduction matters more than preserving recent raw messages.
• Use self_compact_all for all-message compaction with the agent system prompt included.

Prompt requirements

Every custom compaction prompt should:

• State whether evicted messages come from the beginning of the context window.
• Say the summary will appear before remaining recent messages.
• Say not to continue the conversation, answer transcript questions, or call tools.
• Require incorporation of any existing summary being evicted.
• Preserve exact user requests, names, IDs, URLs, file paths, dates, and quoted phrases when they matter.
• Include lookup hints for detailed content that cannot fit.
• End with "Only output the summary."

For complete prompt templates, read references/compaction-prompt-patterns.md.

Update compaction with the bundled script

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

The script preserves existing compaction_settings fields unless flags override them. It uses LETTA_API_KEY, AGENT_ID, and LETTA_BASE_URL unless corresponding flags are provided.

SDK examples

TypeScript and Python examples live in references/api-patch-examples.md.

Verify

curl -sS "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" | \
  jq '{id, model, context_window_limit, llm_config_context_window: .llm_config.context_window, model_settings, compaction_settings, system_chars: (.system | length)}'

Guardrails

• Ask before changing persistent agent defaults unless explicitly requested.
• Prefer conversation-scoped updates for experiments.
• Keep context windows only as large as needed. Bigger windows increase latency and cost.
• Preserve existing model_settings and compaction_settings fields unless intentionally changing them.
• For self-compaction prompts, always forbid tool use and conversation continuation.
• If an update returns 400, first check model handle validity, provider type, and whether settings are in the expected shape.