Sessions: Conversation History Management
Sessions are the core unit of conversation in PocketPaw. Each session tracks a complete conversation thread with history and metadata.
Session Lifecycle
- Creation — A new session is created when a user starts a new conversation
- Active — Messages are added as the conversation progresses
- Suspended — The user switches to another session or closes the dashboard
- Resumed — The user returns to a previous session
- Deleted — The user explicitly deletes the session
Session Keys
Each channel generates unique session keys:
| Channel | Key Format | Example |
|---|---|---|
| Web | Auto-generated UUID | session_a1b2c3d4 |
| Telegram | {chat_id} | 123456789 |
| Telegram Topics | {chat_id}:topic:{topic_id} | 123456789:topic:42 |
| Discord | {channel_id} or dm:{user_id} | dm:987654321 |
| Slack | {channel_id}:{thread_ts} | C01ABC:1705123456.789 |
{phone_number} | +1234567890 | |
| Signal | {phone_number} | +1234567890 |
| Matrix | {room_id} | !abc:matrix.org |
| Teams | {conversation_id} | 19:[email protected] |
| Google Chat | {space_name} | spaces/abc123 |
Dashboard Session Management
The web dashboard provides full session management:
Session List
The sidebar shows all sessions grouped by time:
- Today — Sessions from today
- Yesterday — Sessions from yesterday
- This Week — Sessions from this week
- Older — Older sessions
Session Operations
- New session — Create a blank conversation
- Switch session — Click a session in the sidebar
- Rename session — Edit the session title
- Delete session — Remove a session
- Search sessions — Full-text search across all sessions
REST API
| Endpoint | Method | Description |
|---|---|---|
/api/sessions | GET | List all sessions |
/api/sessions/{id} | DELETE | Delete a session |
/api/sessions/{id}/title | PUT | Rename a session |
/api/sessions/search | GET | Search sessions |
/api/sessions/recent | GET | Get recent sessions |
WebSocket Actions
| Action | Description |
|---|---|
switch_session | Switch to a session by ID |
new_session | Create and switch to a new session |
resume_session | Resume a session (query param) |
State Management
The frontend uses a StateManager that:
- Caches session data in localStorage for fast switching
- Uses an LRU cache to limit memory usage
- Syncs state between the sidebar and chat area
- Persists the active session ID for page reloads
Related
File Store
How sessions are stored as JSON files on disk.
Context Building
How session history is assembled into the agent’s context window.
Memory Isolation
Per-user session scoping for multi-channel deployments.
Was this page helpful?