Sessions

Every interactive conversation with an agent is a session. Sessions persist the full message history to disk, manage the LLM's context window, and support resumption, export, and search.

How Sessions Work

When you start a chat with supyagent chat myagent, a new session is created with a unique ID (e.g., a1b2c3d4). Every message -- user input, assistant responses, and tool call results -- is appended to a JSONL file on disk.

.supyagent/
  sessions/
    myagent/
      a1b2c3d4.jsonl           # Full message history
      a1b2c3d4_summary.json    # Context summary (if generated)
      a1b2c3d4_media/          # Images and media files

JSONL Format

Each line in the session file is a JSON object representing one message:

{"type": "user", "content": "List all Python files", "timestamp": "2025-01-15T10:30:00Z"}
{"type": "assistant", "content": "I'll search for Python files.", "tool_calls": [...]}
{"type": "tool_result", "tool_call_id": "call_abc", "name": "find__find_files", "content": "{\"ok\": true, \"data\": [...]}"}
{"type": "assistant", "content": "I found 12 Python files..."}

Session Commands

List Sessions

# From the CLI
supyagent sessions myagent

# Inside a chat
/sessions

This shows all sessions for the agent with their ID, creation date, message count, and title (if set).

Resume a Session

# Resume a specific session
supyagent chat myagent --session a1b2c3d4

# Inside a chat, switch to another session
/session a1b2c3d4

When resuming, the full message history is reconstructed from the JSONL file, including any context summary that was generated.

Start a New Session

# Force a new session (don't resume the last one)
supyagent chat myagent --new

# Inside a chat
/new

Delete a Session

# Delete the current session
/delete

# Delete a specific session
/delete a1b2c3d4

Rename a Session

# Set a display title for the current session
/rename My refactoring project

Titles are shown in the session list for easier identification.

Export a Session

# Export to markdown
/export conversation.md

# From the CLI
supyagent sessions myagent --export a1b2c3d4

This renders the conversation as readable Markdown with user messages, assistant responses, and tool call summaries.

View History

# Show last 10 messages (default)
/history

# Show last 5 messages
/history 5

Context Management

Full conversation history always persists to disk. But the LLM has a finite context window. The ContextManager handles this by sending only a subset of messages to the LLM on each turn:

[System Prompt]
[Context Summary]  (if available)
[Recent Messages]  (as many as fit in the budget)

How Context Trimming Works

1. The total context budget is calculated: model_context_limit - response_reserve - tool_definitions.
2. The system prompt is always included first.
3. If a context summary exists, it is included (up to 30% of the remaining budget).
4. Recent messages are added from newest to oldest until the budget is exhausted.
5. At minimum, min_recent_messages are always included, even if they exceed the budget.

This ensures the agent always has the system prompt, a summary of earlier context, and the most recent conversation turns.

Configuration

context:
  auto_summarize: true
  max_messages_before_summary: 30
  max_tokens_before_summary: 128000
  min_recent_messages: 6
  response_reserve: 4096

Summarization Triggers

Summarization is triggered by whichever condition is met first:

1. Message count: More than max_messages_before_summary messages since the last summary.
2. Token count: Total tokens exceed max_tokens_before_summary.

Both checks happen after each user turn completes.

What Summaries Contain

When summarization triggers, the ContextManager generates a structured state snapshot using the LLM:

• Files Modified -- Each file path and what was changed
• Key Decisions -- Decisions made and their rationale
• Important Values -- Exact file paths, URLs, IDs, error messages, configuration values
• Current State -- What task is in progress, last action, expected next step
• Pending Tasks -- Remaining work items

The summary is kept under 600 words and preserves all concrete values (paths, IDs, URLs) exactly. This means the agent retains awareness of earlier work even after older messages are trimmed from context.

Monitoring Context Usage

# Inside a chat
/context

This shows:

• Messages since last summary and the threshold
• Total tokens and the token threshold
• Whether summarization will trigger on the next turn
• Percentage progress toward each trigger

# Force summarization manually
/summarize

Token Display

# Toggle token usage display
/tokens

When enabled, each response shows the token count for the request and response.

Emergency Truncation

If messages still exceed the context window after normal trimming (rare but possible with very large tool results), the ContextManager applies emergency truncation:

1. Strip images from multimodal messages (convert to text descriptions)
2. Truncate tool results longer than 2000 characters
3. Drop the oldest non-protected messages one by one

Protected messages include the system prompt, the summary message, and the last min_recent_messages messages.

Memory System

Supyagent also has a long-term memory system that works across sessions. When memory.enabled: true, the agent tracks entities and facts in an entity-graph that persists between conversations.

memory:
  enabled: true
  extraction_threshold: 5     # Extract every 5 signal-flagged exchanges
  retrieval_limit: 10          # Inject up to 10 memories per turn
  auto_extract: true           # Automatically extract from conversation

Memory is separate from context summarization. Summaries are per-session and handle context window limits. Memory is cross-session and handles long-term knowledge persistence.

The agent also has access to memory tools for explicit control:

• memory_search -- Search for memories by query
• memory_write -- Store a specific fact
• memory_recall -- Recall everything known about an entity

Pre-Compaction Memory Flush

Before summarization runs, the memory system flushes any pending memory extractions. This ensures important facts are saved to long-term memory before they are summarized away from the conversation context.

Session Storage

Sessions are stored under .supyagent/sessions/{agent_name}/:

.supyagent/
  sessions/
    myagent/
      a1b2c3d4.jsonl            # Message history
      a1b2c3d4_summary.json     # Context summary
      a1b2c3d4_media/           # Images referenced in messages
    coder/
      e5f6g7h8.jsonl

Cleanup

Over time, sessions accumulate. Clean up old sessions:

supyagent cleanup

This removes completed agent registry entries and optionally cleans stale sessions.

Related

• Configuration -- Context settings reference
• Chat Commands -- All interactive commands
• Core Concepts -- Overview of sessions and context