Capsules: Context Snapshots for AI Session Handoffs

Full examples: [examples.md](examples.md) | Reference: [reference.md](reference.md)

Capsules are distilled context snapshots for preserving working state across sessions, tools, or agents. Not a chat log—a structured summary of what matters.

When NOT to Use Capsules

• Ephemeral debugging — Use scratch files or logs, not capsules
• Real-time state — Capsules are for handoffs, not live sync between agents
• Large data — 12K char limit; store references to files, not file contents
• Chat transcripts — Distill first; capsules are summaries, not logs
• Temporary single-session notes — Just keep them in context; no need to persist

Quick Reference

Before Storing: Distill First

Before calling capsule_store, distill your context:

"Distill into a capsule under 12,000 chars. State not story. Must include: Objective, Current status, Decisions/Constraints, Next actions, Key locations, Open questions/Risks. Max 1-3 tiny code snippets only if critical. If too long, compress—do not omit decisions or next actions."

capsule_store saves the result. It doesn't summarize for you.

Capsule Format

6 required sections (validated unless allow_thin: true):

## Objective
What you're trying to accomplish (1-2 sentences)

## Status
What's done, in progress, or blocked

## Decisions
Key choices made and rationale

## Next actions
- Concrete next steps (bulleted)

## Key locations
- `src/auth/login.ts:45` - auth entry point

## Open questions
- Unresolved issues or uncertainties

See [reference.md](reference.md) for accepted section names and format variations.

Addressing Modes

Pick ONE (mutually exclusive):

# WRONG - causes AMBIGUOUS_ADDRESSING error
capsule_fetch(id: "01HX...", workspace: "default", name: "auth")

# CORRECT
capsule_fetch(id: "01HX...")
capsule_fetch(workspace: "default", name: "auth")

Output Bloat Rules

Pattern: Use capsulelist/capsuleinventory to browse, then capsule_fetch to load specific capsules.

Appending to Sections

Use capsule_append to add content to a specific section without rewriting the full capsule:

capsule_append(workspace: "default", name: "auth", section: "Decisions", content: "Round 2: Approved")

• Section matching: Exact header name, case-insensitive (use header as written, e.g., ## Status → "Status")
• Placeholder handling: Replaces (pending), TBD, etc. if section only contains placeholder
• Append behavior: Otherwise adds after existing content with blank line separator
• Error messages: Lists available sections if target not found

Use case: Accumulating history (design reviews, verification rounds, decisions) without risk of losing previous content.

When to Skip Validation

Use allow_thin: true only for:

• Quick scratch notes
• Temporary debugging context
• Notes you'll expand later

Avoid for anything persisted or shared between agents.

Multi-Agent Orchestration

Use run_id, phase, role to coordinate:

capsule_store(name: "design", run_id: "task-1", phase: "design", role: "architect", ...)
capsule_latest(run_id: "task-1", phase: "review")
capsule_list(workspace: "default", run_id: "task-1")

See [examples.md](examples.md) for orchestration patterns.

Error Quick Reference

Note on mode: "replace": Only overwrites active capsules. If a capsule was soft-deleted, replace creates a new one (doesn't revive the deleted). To recover deleted capsules, use capsuleexport(includedeleted: true) then capsule_import.

See [reference.md](reference.md) for full error details.

Additional Resources

• [reference.md](reference.md) — Section synonyms, name normalization, backup/restore, limits, tips
• [examples.md](examples.md) — Store, fetch, update, orchestration examples