Context Profiles

Context profiles control how much and what type of context is loaded during session_start. Each profile tunes the retrieval limits for different agent scenarios.

Profile Definitions#

default#

The balanced profile suitable for general-purpose conversations.

Use when: General conversations, code review, everyday tasks. This is the default when no mode is specified.

planning#

Optimized for planning sessions where tasks and facts matter more than session history.

Use when: Sprint planning, architecture discussions, roadmap reviews. Loads more facts and tasks but fewer episodic summaries since historical context is less critical.

incident#

Optimized for debugging and incident response where recent session history is critical.

Use when: Debugging sessions, incident response, troubleshooting. Loads more episodic memories to understand what happened recently, and more facts for technical context.

handoff#

Optimized for handing off work to another agent with maximum context transfer.

Use when: Agent-to-agent handoffs, shift changes, bringing a new agent up to speed. Loads full session history and task context to ensure nothing is lost.

deep#

Maximum context retrieval for comprehensive research or analysis.

Use when: Deep research, comprehensive code analysis, system architecture review. Loads the maximum number of facts for thorough context.

minimal#

Reduced retrieval for quick, focused tasks that do not need extensive context.

Use when: Simple questions, quick lookups, or when the agent knows exactly what it needs. Saves tokens by loading less context.

none#

No context retrieval. The session starts with an empty context.

Use when: The agent will manually fetch what it needs, testing scenarios, or when context is provided through other means.

Parameter Overrides#

Individual limits can be overridden regardless of the selected mode. Explicit parameters always take precedence over profile defaults:

{
  "mode": "default",
  "maxFacts": 15,
  "maxTasks": 0
}

This uses the default profile but overrides facts to 15 and disables task retrieval.

Constraints Are Always High#

Note that maxConstraints is set to 10 across all profiles. Constraints are always loaded at their full limit because violating a constraint is considered an error -- the agent should always have access to all active constraints.

Profile Selection Strategy#

Token Impact#

Each additional memory returned in session_start costs tokens. In summaryOnly: true mode (default), each memory is clipped to 120 characters. Approximate token costs per profile:

These are rough estimates. Actual token usage depends on memory content length and the number of vaults, agents, and documents.

Resolution Logic#

The context limits are resolved using this logic:

1. Start with the selected profile's defaults
2. Apply explicit parameter overrides (maxEpisodic, maxFacts, etc.)
3. Unknown modes fall back to "default"

For example, mode: "unknown_mode" is treated as mode: "default".

Related Pages#

• Session Protocol -- Full session lifecycle
• Agent Routes -- session-start API details
• Tool Reference -- Compact tool listing
• Limits and Quotas -- System limits