Sessions

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

See Protocol for the full wire format.

What's next

• REPL — the terminal interface for sessions
• Agents — agents that own sessions
• Memory — cross-session recall