# Sessions

Persistent conversations — append-only JSONL, auto-compaction, crash-safe.

Every conversation is a session. Sessions persist as append-only JSONL files — they survive crashes, restarts, and daemon reloads. The daemon manages persistence so clients don't store history.

## How sessions work

A session is bound to an `(agent, sender)` pair. When you send a message, the daemon finds the latest session for that pair or creates a new one:

```
~/.crabtalk/sessions/crab_user_1.jsonl
~/.crabtalk/sessions/crab_tg-12345_2.jsonl
~/.crabtalk/sessions/researcher_user_hello-world.jsonl
```

The file format is one JSON object per line — metadata on line 1, messages after:

```
{"agent":"crab","created_by":"user","created_at":"...","title":"","uptime_secs":42}
{"role":"user","content":"hello"}
{"role":"assistant","content":"hi there"}
```

## Auto-compaction

When a conversation exceeds the token threshold (default: 100,000 tokens), the agent automatically compacts the history. Earlier messages are summarized into a dense prose summary that preserves:

- Agent identity and user profile
- Key decisions and active tasks
- Important facts and context

A compact marker is appended to the file:

```
{"compact":"Summary of the conversation so far..."}
```

On the next load, only content after the last compact marker is read into context. History before the marker stays in the file — archived, not deleted.

Configure the threshold per agent:

```
[system.crab]
compact_threshold = 100000
```

## Auto-injected messages

Some context is injected fresh before every turn — not persisted to the session file:

- Memory recall results
- Environment blocks
- Agent descriptions (for delegation)
- Working directory announcements

These are marked `auto_injected: true`, stripped before each run, and re-injected via the daemon's hook system. This prevents context accumulation while keeping each turn informed.

## Session titles

After the first exchange, the daemon auto-generates a short title (3-6 words) and renames the session file to include it. Titles appear in the session browser and `/resume` picker.

## Crash safety

The JSONL format is append-only — a crash during a write can truncate the last line but never corrupts earlier messages. On the next load, the daemon reads up to the last complete line.

The one exception: uptime tracking rewrites the metadata line. A crash during this operation can lose the metadata but preserves the full conversation history.

## Protocol

| Operation                   | Message                  | Response                    |
|-----------------------------|-------------------------|-----------------------------|
| List sessions               | `Sessions`              | `SessionList`              |
| Kill session                | `KillMsg`               | —                           |
| Compact                     | `CompactMsg`            | `CompactResponse { summary }` |
| List conversations           | `ListConversationsMsg`   | `ConversationList`         |

See [Protocol](/content/docs/crabtalk/protocol/index.html) for the full wire format.

## What's next

- [REPL](/content/docs/crabtalk/repl/index.html) — the terminal interface for sessions
- [Agents](/content/docs/crabtalk/agents/index.html) — agents that own sessions
- [Memory](/content/docs/crabtalk/memory/index.html) — cross-session recall

### On this page

- [How sessions work](/content/docs/crabtalk/sessions#how-sessions-work/index.html) 
- [Auto-compaction](/content/docs/crabtalk/sessions#auto-compaction/index.html) 
- [Auto-injected messages](/content/docs/crabtalk/sessions#auto-injected-messages/index.html) 
- [Session titles](/content/docs/crabtalk/sessions#session-titles/index.html) 
- [Crash safety](/content/docs/crabtalk/sessions#crash-safety/index.html) 
- [Protocol](/content/docs/crabtalk/sessions#protocol/index.html) 
- [What's next](/content/docs/crabtalk/sessions#whats-next/index.html)