# Sessions

ZeroClaw implements a robust session management system designed for multi-user environments and crash resilience. Unlike simple stateless request-response loops, ZeroClaw treats every interaction as part of a persistent, per-sender conversation that survives process restarts and handles context growth through automated compaction.

***

## Per-Sender Storage

Each conversation is isolated and keyed by a combination of the sender ID and the communication channel. This ensures that users on different platforms (e.g., Discord vs. Slack) or multiple users within the same platform maintain independent histories.

- **Session Keying**: Sessions are typically indexed by `(channel_id, sender_id)`.
- **Isolation**: Memory and history from one sender never bleed into another's session unless explicitly shared via global memory.
- **Persistence**: Sessions are serialized and stored as JSON files, allowing the agent to resume exactly where it left off after a restart.

***

## Compaction Logic

To prevent context window overflow and maintain performance over long conversations, ZeroClaw uses an automated compaction mechanism defined in `agent/loop_.rs`. When the history grows beyond a specific threshold, old messages are summarized and replaced by a concise context block.

- **Threshold**: Compaction triggers when the non-system message count exceeds `DEFAULT_MAX_HISTORY_MESSAGES = 50`.
- **Retention**: ZeroClaw keeps the `COMPACTION_KEEP_RECENT_MESSAGES = 20` most recent messages in their original form.
- **Source Cap**: The transcript passed to the summarizer is limited to `COMPACTION_MAX_SOURCE_CHARS = 12_000` to avoid overwhelming the summarization model.
- **Summary Cap**: The resulting summary is truncated to `COMPACTION_MAX_SUMMARY_CHARS = 2_000`.

The summarization process is handled by a recursive call to the provider, instructing it to preserve key facts, user preferences, and unresolved tasks while omitting filler and verbose tool logs.

***

## Autosave Thresholds

ZeroClaw prioritizes data integrity through aggressive autosaving. Sessions are not just saved on graceful shutdown; they are updated after every significant interaction.

- **Trigger**: `AUTOSAVE_MIN_MESSAGE_CHARS = 20`.
- **Behavior**: If a user message exceeds this length, it is considered "meaningful" enough to trigger an immediate save of the session state.
- **Crash Resilience**: This granular saving ensures that even in the event of a sudden crash or hardware failure, the agent loses at most the very last exchange.

***

## Per-Sender Overrides

Each session can carry its own configuration, allowing for dynamic behavior based on the specific user or channel requirements.

- **Model Overrides**: A specific conversation can be configured to use a different provider or model than the global default.
- **Config Storage**: These overrides are stored alongside the session JSON, ensuring consistency across restarts.

***

## Session Lifecycle

1. **Creation**: A new session is initialized when a message is received from a previously unknown `(channel, sender)` pair.
2. **Loading**: Upon receiving a message, ZeroClaw checks the local storage for an existing session file matching the sender's key.
3. **Processing**: Messages are appended to the history, and compaction is checked before sending the request to the LLM.
4. **Saving**: The session is written to disk after the LLM responds or when the autosave threshold is met.
5. **Cleanup**: Older sessions can be archived or deleted based on global retention policies, though ZeroClaw typically favors long-term persistence.

***

## Relevance to Luna

Luna's SessionManager currently implements basic compaction via the LibrarianAgent, but lacks several of ZeroClaw's more robust features. Integrating these would significantly improve reliability and flexibility:

- **Autosave**: Implementing the `AUTOSAVE_MIN_MESSAGE_CHARS` logic to move away from shutdown-only saves. This is critical for [[Core]] stability.
- **Per-Sender Overrides**: Enabling users to select specific models for their sessions, a feature currently missing from Luna's [[Configuration]].
- **Configurable Thresholds**: Exposing compaction constants (like 50/20 messages) as configurable parameters rather than hardcoded values.