<!-- source: https://deepwiki.com/qhkm/zeptoclaw/9.4-session-management -->

# Session Management

- src/bus/message.rs
- src/bus/mod.rs
- src/safety/leak_detector.rs
- src/session/history.rs
- src/session/mod.rs
- src/session/types.rs

This page documents ZeptoClaw's session management system, which maintains conversation state across multiple messages and channels. Session management handles persistent storage of conversation history, session isolation per chat, and coordination of concurrent message processing.

For configuration of session repair behavior, see [Configuration](/qhkm/zeptoclaw/5-configuration). For the agent loop that consumes sessions, see [Agent Loop](/qhkm/zeptoclaw/3.2-agent-loop). For message bus routing that determines session keys, see [Message Bus and Routing](/qhkm/zeptoclaw/3.3-message-bus-and-routing).

## Overview

The session management system provides:

- Persistent conversation history — Messages are stored and retrieved across agent restarts src/session/mod.rs 46-51
- Per-chat isolation — Each channel + chat ID combination gets its own session src/bus/message.rs 22-23
- Pluggable storage backends — File-based persistence or in-memory for testing src/session/mod.rs 62-67
- Concurrent access control — Per-session locks prevent race conditions (implemented via RwLock ) src/session/mod.rs 42-43
- Session discovery and cleanup — List, search, and prune old sessions src/session/history.rs 32-37
- Automatic repair — Detects and fixes malformed conversation histories src/session/repair.rs 1-10
- Multi-modal Support — Storage of structured content including text and images src/session/types.rs 125-133
- Secret Leak Prevention — Integration with LeakDetector to prevent sensitive data from entering persistent logs src/safety/leak_detector.rs 55-57

**Sources:** [src/session/mod.rs1-7](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L1-L7) [src/bus/message.rs9-26](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/message.rs#L9-L26) [src/session/history.rs1-7](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/history.rs#L1-L7) [src/safety/leak_detector.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/leak_detector.rs#L1-L5)

## Core Concepts

### Session

A `Session` represents a single conversation thread, containing:

- Session key — Unique identifier in format channel:chat_id src/session/types.rs 15-16
- Messages — Ordered list of user, assistant, system, and tool messages src/session/types.rs 17-18
- Metadata — Creation time, last update time src/session/types.rs 21-24
- Summary — Optional condensed context for long histories src/session/types.rs 19-20

### Session Key Format

Session keys follow the pattern `{channel}:{chat_id}` [src/bus/message.rs97](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/message.rs#L97-L97):

```

```

This ensures conversations from different channels or chat IDs never collide.

### Message Types

Sessions contain messages defined by `Role` and `ContentPart` [src/session/types.rs151-166](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/types.rs#L151-L166) Content is structured to support multi-modal inputs like images [src/session/types.rs125-133](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/types.rs#L125-L133)

**Sources:** [src/session/types.rs9-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/types.rs#L9-L25) [src/session/types.rs151-260](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/types.rs#L151-L260)

## SessionManager Architecture

The `SessionManager` is the central authority for session lifecycle. It maintains an in-memory cache for performance while optionally syncing to a filesystem backend.

```

```

**Key Components:**

1. File Persistence — Created via new() ; persists to ~/.zeptoclaw/sessions/ src/session/mod.rs 85-92
2. In-Memory — Created via new_memory() ; useful for testing or ephemeral agents src/session/mod.rs 105-110
3. Concurrency — Uses Arc<RwLock> to allow multiple readers or a single writer to access the session cache safely src/session/mod.rs 42-43

**Sources:** [src/session/mod.rs62-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L62-L67) [src/session/history.rs37-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/history.rs#L37-L39)

## Session Lifecycle

### Creating or Loading a Session

Sessions are retrieved via `get_or_create`. If persistence is enabled, the manager attempts to load from disk before creating a new instance [src/session/mod.rs160-189](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L160-L189) During loading, the system may trigger `maybe_repair_loaded_session` to fix inconsistencies [src/session/mod.rs175](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L175-L175)

### Persisting a Session

Sessions are saved explicitly. In the file backend, keys are sanitized (URL-encoded) via `sanitize_key` to ensure filesystem compatibility [src/session/mod.rs245-265](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L245-L265)

```

```

**Sources:** [src/session/mod.rs160-265](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L160-L265) [src/session/types.rs27-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/types.rs#L27-L49)

## Session Keys and Isolation

### Session Key Derivation

The session key is automatically generated during `InboundMessage` construction as `"{channel}:{chat_id}"` [src/bus/message.rs97](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/message.rs#L97-L97)

### Isolation Guarantees

Each session key maps to a distinct file or `HashMap` entry. This ensures:

- No cross-talk between different users or channels.
- Independent Context for each chat thread.

**Sources:** [src/bus/message.rs85-99](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/message.rs#L85-L99) [src/session/mod.rs62-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L62-L67)

## History Management

The `ConversationHistory` struct provides high-level management for CLI-originated sessions [src/session/history.rs37-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/history.rs#L37-L39)

### Listing and Searching

- list_conversations() : Scans for files starting with cli%3A and extracts metadata like title (first user message) and message_count src/session/history.rs 77-126
- find_conversation(query) : Performs case-insensitive substring matches on titles or exact key matches src/session/history.rs 146-159
- generate_session_key() : Generates a timestamp-based key for new CLI sessions src/session/history.rs 164-170

### Cleanup

- cleanup_old_conversations(keep_count) : Prunes the oldest CLI sessions to manage disk space src/session/history.rs 197-210

**Sources:** [src/session/history.rs17-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/history.rs#L17-L30) [src/session/history.rs177-195](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/history.rs#L177-L195)

## Session Repair and Safety

### Repair Logic

The `repair_messages` function fixes structural issues in conversation history [src/session/repair.rs25-40](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/repair.rs#L25-L40)

1. Orphan Tool Results : Removes Role::Tool messages that don't follow a ToolCall src/session/repair.rs 60-70
2. Missing Tool Results : Detects if an assistant made a call but no result was provided.
3. Empty Content : Strips messages with no text or media.

### Leak Detection

The `LeakDetector` scans content for secrets (API keys, tokens) before they are potentially persisted or transmitted [src/safety/leak_detector.rs55-57](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/leak_detector.rs#L55-L57) It supports actions such as `Block`, `Redact`, or `Warn` [src/safety/leak_detector.rs24-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/leak_detector.rs#L24-L31)

**Sources:** [src/session/mod.rs175-176](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L175-L176) [src/session/repair.rs1-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/repair.rs#L1-L20) [src/safety/leak_detector.rs66-145](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/leak_detector.rs#L66-L145)

## Summary of Key Types

**Sources:** [src/session/types.rs1-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/types.rs#L1-L10) [src/session/mod.rs1-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L1-L10) [src/safety/leak_detector.rs1-18](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/leak_detector.rs#L1-L18)
