A Context Bundle is a JSONL recording of one session's tool calls — captured by a hook, written to disk. A future agent reads it to skip the rediscovery phase.

Primitive

Context Bundle

Why it exists

Cross-session continuity without conversation history.

cold start

🤖 Session 2 — no bundle

1.Grep for entry points~800 tok

2.Read 6 candidate files~4,200 tok

3.Trace call graph~1,800 tok

4.Infer conventions~600 tok

5.Start actual work—

~7,400 tokens spent before the first real edit. Every session re-derives what the previous session already knew.

warm start

🤖 Session 2 — with bundle

1.Load prior bundle~400 tok

2.Grep for entry pointsskipped

3.Read 6 candidate filesskipped

4.Trace call graphskipped

5.Start actual work—

~400 tokens to warm-start. File-read set is pre-populated. Rediscovery is delegated to the bundle.

Thousands of tokens of re-orientation collapse to hundreds.

The bundle is delegated context — captured once, reused by any future agent.

How bundles are written

A PostToolUse hook. No agent cooperation required.

The agent doesn't decide what goes in the bundle. The hook captures everything at tool-call granularity.

🤖

Agent

calls a tool

Read · Edit · Bash · Grep

→

PostToolUse

🪝

context-bundle-capture.sh

observes, doesn't block

appends one JSONL line

→

append

📄

session-abc.jsonl

current hour bucket

JSONL, append-only

Transparent capture. Same enforcement model as every Hook — the agent cannot forget, cannot opt out, cannot shape the bundle. Cooperation isn't required.

What a bundle looks like

One JSONL line per tool call.

.claude/context_bundles/2026-04-16/10/session-abc123.jsonl

JSONL

10:00:00{tool: Read, path: "src/auth/middleware.py"}

10:00:05{tool: Grep, pattern: "validate_session_token", matches: 3}

10:00:12{tool: Edit, path: "src/auth/middleware.py", op: "add-function"}

10:00:30{tool: Bash, cmd: "just test auth", exit_code: 0}

Structured format — parseable by any future agent. No unstructured free-text; downstream tools key on field names.

How they're organized

Day · hour · session. Retention becomes mechanical.

.claude/context_bundles/

├──2026-04-16/# day bucket

│   ├──10/# hour bucket

│   │   ├──session-abc123.jsonl

│   │   └──session-def456.jsonl

│   └──14/

│       └──session-ghi789.jsonl

└──2026-04-17/

└──09/

└──session-jkl012.jsonl

The bucket hierarchy isn't cosmetic. It's what makes time-based retention a simple file-system operation — delete a day, compact an hour, tail a session.

The retention policy

Bundles are a recovery resource. They age out.

Without retention, bundles accumulate unbounded until directory listing is the bottleneck.

🔥 Hot0–24h

☀ Warm1–7d

❄ Cold7–90d

✕ Purge90d+

now24h7d90d

Hot Kept in full. Most common warm-start source.

Warm Kept in full. Recent enough that full detail still matters.

Cold Compacted to file-read summaries. Diffs dropped.

Purge Deleted. No long-term archive.

Exact thresholds are system-dependent. The point: bundles are a recovery resource, not an archive.

Don't confuse it with

Context Bundle vs Conversation Log.

Audience

Future agent in a new session

Current agents in this session

Purpose

Cross-session warm-start

In-session coherence

Captures

Tool calls — reads, writes, greps, bash

Messages between agents in a team

Lifetime

Tiered retention (hot → purge)

Bounded to the session's lifetime

Both are append-only JSONL. They answer different questions — "what did the last agent do?" vs "what did my teammate just say?"

The discipline

Rediscovery is the tax agents pay for being stateless.

The bundle pays that tax once, at the hook boundary, without asking the agent to remember anything. The next session reads what the last one did and picks up where it left off — no conversation history, no trust in agent cooperation, no context bloat.