Session History & Resume

How Sessions Work

Every az chat session gets a unique ID. When you exit, the full conversation history is saved to .agentzero/sessions/<id>.json (or .json.enc if encrypted).

Listing Past Sessions

az history

Past sessions:

  f7a2c3e1-...  model=llama3.2  messages=24  mode=local-only
  a1b9d4f0-...  model=codellama  messages=8  mode=local-only
  e3c8a2b7-...  model=llama3.2  messages=42  mode=local-only

3 session(s) found.

Resuming a Session

az chat --resume f7a2c3e1-...

Resumed session f7a2c3e1-... (24 messages)

you> (continue where you left off)

The full message history is loaded, including system prompt, user messages, assistant responses, and tool call results. The model has full context from the previous conversation.

Session File Format

Sessions are stored as JSON:

{
  "session_id": "f7a2c3e1-...",
  "model": "llama3.2",
  "mode": "local-only",
  "message_count": 24,
  "messages": [
    {"role": "system", "content": "You are AgentZero..."},
    {"role": "user", "content": "what does this project do?"},
    {"role": "assistant", "content": "This is a Rust workspace..."}
  ]
}

Encrypted Sessions

Sessions are encrypted by default and saved as .json.enc:

az chat
# Session saved (encrypted) to .agentzero/sessions/f7a2c3e1-....json.enc

To disable encryption, pass --no-encrypt.

Encrypted sessions cannot currently be resumed (the resume feature reads plaintext JSON). This is a known limitation.

Exporting Sessions

Export a session to markdown, HTML, or JSON:

# Markdown (default)
az export f7a2c3e1-... --format md

# Self-contained HTML with role-colored messages
az export f7a2c3e1-... --format html --output /tmp/session.html

# Raw JSON
az export f7a2c3e1-... --format json

Loads from either the session JSON or checkpoint format. Outputs to stdout by default, or to a file with --output.

Context Compaction

Long conversations are automatically compacted before each model call when they exceed 50 messages or 32KB of text. Choose a strategy with --compaction:

Simple (default)

The original strategy. Preserves the system prompt and 10 most recent messages, summarizes everything in between with fixed-size previews (80 chars for user, 100 for assistant).

Code-Aware

Preserves fenced code blocks verbatim while summarizing surrounding prose. Best for coding sessions where code snippets are high-value context.

az chat --compaction code-aware

Role-Budget

Allocates per-role character budgets. Tool output (often verbose filesystem listings) gets the smallest budget, user messages get medium, and assistant reasoning gets the largest. Keeps the most recent content within each role’s budget.

az chat --compaction role-budget

All strategies tag their summaries with [COMPACTION SUMMARY] to prevent recursive re-summarization. You’ll see a notice when compaction occurs:

  [context compacted: 61 → 8 messages]

Hibernation & Checkpoints

Auto-Hibernate on Idle

Use --hibernate-after to automatically save a full checkpoint after a period of inactivity:

az chat --hibernate-after 10

When the idle timeout fires, AgentZero saves a checkpoint and prints the resume command:

Hibernated: session saved to .agentzero/sessions/f7a2c3e1-....checkpoint.json
Resume with: az chat --resume f7a2c3e1-...

Checkpoint Format

Checkpoints save more state than regular session files:

Field	Regular Session	Checkpoint
Messages	Yes	Yes
Session approvals	No	Yes
Loop config	No	Yes
Dynamic tools	No	Yes
Wake triggers	No	Yes

When resuming from a checkpoint, previously approved tool calls carry over — you don’t have to re-approve them.

Checkpoint Files

Checkpoints are stored as .checkpoint.json in the sessions directory:

.agentzero/sessions/
  f7a2c3e1-....json              # regular session (messages only)
  f7a2c3e1-....checkpoint.json   # full checkpoint (messages + approvals + config)

The --resume flag tries the checkpoint file first, then falls back to the legacy session format.

Session Tree & Branching

Every chat session tracks a conversation tree. Each send() creates a node, and you can branch from any prior node to explore alternatives without losing earlier work.

Viewing the Tree

you> /tree

n0 (3 msgs)
├── n1 (5 msgs)
│   └── n2 [refactor approach] (8 msgs)
└── n3 (6 msgs)

Branching

Branch from any prior node to explore a different direction:

you> /branch n1
Branched from n1 (5 messages)

you> try a completely different approach...

Messages are truncated to the branch point. The original branch is preserved in the tree.

Labeling Nodes

Label nodes for easier navigation:

you> /label initial database design
Labeled current node.

Labels appear in the /tree display.

Branching on Resume

Branch from a specific node when resuming a session:

az chat --resume f7a2c3e1-... --branch n1

This loads the session checkpoint, restores the full tree history, and truncates to the branch point.

Tree Storage

Trees are saved as .tree.json alongside the session:

.agentzero/sessions/
  f7a2c3e1-....json
  f7a2c3e1-....checkpoint.json
  f7a2c3e1-....tree.json          # conversation tree