context-folding

Context Folding

Create isolated branches for complex sub-tasks. Each branch has its own token budget and cleans up on return, preventing context bloat.

Prerequisites: contextd Integration

Context folding uses contextd MCP tools:

• branch_create - Create isolated context branch
• branch_return - Return summary and cleanup branch
• branch_status - Monitor budget and hierarchy

If contextd unavailable: Context folding degrades to inline execution (no isolation).

---

When to Use

Use context folding when:

• Investigating a problem requiring many file reads
• Running exploratory work that would bloat context
• Multi-step sub-tasks with verbose intermediate steps
• Parallel agent coordination is needed
• Task complexity is STANDARD or COMPLEX tier

Don't use when:

• Task is SIMPLE tier (< 3 steps)
• Results need to stay in main context
• You're at end of session anyway

---

Tools

branch_create

{
  "session_id": "my-session",
  "description": "Brief description of the sub-task",
  "prompt": "Detailed instructions for the branch",
  "budget": 4096,
  "timeout_seconds": 300,
  "parent_branch_id": "br_parent123"
}

Parameter	Required	Default	Description
session_id	Yes	-	Session identifier
description	Yes	-	Brief description (shown in status)
prompt	No	-	Detailed instructions
budget	No	8192	Token budget
timeout_seconds	No	300	Auto-return timeout
parent_branch_id	No	-	Parent branch for nesting

branch_return

{
  "branch_id": "br_abc123",
  "message": "Summary of findings",
  "return_value": { "key": "structured data" }
}

Parameter	Required	Description
branch_id	Yes	Branch to return from
message	Yes	Summary (scrubbed for secrets)
return_value	No	Structured data for parent

branch_status

{ "branch_id": "br_abc123" }

Or check active branch:

{ "session_id": "my-session" }

Returns:

{
  "status": "active",
  "budget_total": 8192,
  "budget_used": 3421,
  "budget_remaining": 4771,
  "budget_percent": 42,
  "depth": 2,
  "parent_id": "br_parent123",
  "children": ["br_child456", "br_child789"],
  "timeout_remaining_seconds": 180
}

---

Complexity-Based Budget Allocation

Integrate with complexity-assessment skill to determine appropriate budgets:

Tier	Budget	Timeout	Rationale
SIMPLE	4096	120s	Quick investigation, minimal context
STANDARD	8192	300s	Multi-file analysis, moderate exploration
COMPLEX	16384	600s	Deep investigation, cross-system analysis

Adaptive allocation pattern:

1. Run complexity-assessment on sub-task
2. Map tier to budget:
   - SIMPLE (5-8): budget=4096
   - STANDARD (9-12): budget=8192
   - COMPLEX (13-15): budget=16384
3. Create branch with calculated budget

---

Observability

Real-Time Budget Monitoring

Check budget proactively during branch execution:

# Check at natural breakpoints
branch_status(branch_id) -> {
  budget_percent: 72,
  budget_remaining: 2294,
  warning_level: "caution"
}

Warning Levels:

Percent Used	Level	Action
0-70%	normal	Continue execution
70-85%	caution	Consider wrapping up
85-95%	warning	Begin summarization
95-100%	critical	Force return

Branch Hierarchy Visualization

For nested branches, use branch_status with session to see full tree:

branch_status(session_id: "main") -> {
  hierarchy: {
    "br_root": {
      status: "active",
      budget_percent: 45,
      children: {
        "br_analysis": { status: "active", budget_percent: 72 },
        "br_testing": { status: "completed", budget_percent: 89 }
      }
    }
  }
}

Token Usage Breakdown

Monitor what consumes budget:

branch_status(branch_id, detailed: true) -> {
  usage_breakdown: {
    file_reads: 1200,
    searches: 800,
    tool_calls: 400,
    reasoning: 1021
  }
}

---

Adaptive Budget Management

Dynamic Warnings

Implement threshold-based warnings:

# After each significant operation
status = branch_status(branch_id)

if status.budget_percent >= 95:
  # CRITICAL: Force immediate return
  branch_return(branch_id, message: "Budget exhausted: {partial_findings}")

elif status.budget_percent >= 85:
  # WARNING: Begin summarization
  # Summarize findings, stop new exploration

elif status.budget_percent >= 70:
  # CAUTION: Plan exit strategy
  # Complete current task, avoid new threads

Graceful Degradation

When approaching limits, auto-summarize:

# At 85% budget
1. Stop exploratory work
2. Consolidate findings so far
3. Create summary of discovered patterns
4. Return with partial results + "investigation incomplete" flag

branch_return(
  branch_id,
  message: "Partial analysis (budget: 87%): Found 3 of estimated 5 patterns...",
  return_value: {
    complete: false,
    findings: [...partial...],
    unexplored: ["area1", "area2"]
  }
)

---

Dependency DAG

Branch Dependencies

Track dependencies between parallel branches:

# Create independent branches
br_auth = branch_create(description: "Analyze auth module")
br_db = branch_create(description: "Analyze DB schema")

# Create dependent branch
br_integration = branch_create(
  description: "Analyze auth-DB integration",
  depends_on: [br_auth, br_db]  # Waits for these to complete
)

Parallel Branch Coordination

For orchestration patterns:

# Phase 1: Independent branches (parallel)
branches = [
  branch_create(description: "Task A"),
  branch_create(description: "Task B"),
  branch_create(description: "Task C")
]

# Monitor all branches
for br in branches:
  status = branch_status(br)
  # Track completion

# Phase 2: Collect results
results = [branch_return(br) for br in branches]

# Phase 3: Dependent work using results
branch_create(
  description: "Synthesize findings",
  prompt: "Combine results: {results}"
)

Return Value Propagation

Pass structured data between branches:

# Child branch returns structured data
branch_return(
  branch_id: "br_analysis",
  message: "Found 3 security issues",
  return_value: {
    issues: [
      { severity: "high", file: "auth.go", line: 42 },
      { severity: "medium", file: "db.go", line: 108 },
      { severity: "low", file: "utils.go", line: 15 }
    ],
    recommendations: ["Add input validation", "Use parameterized queries"]
  }
)

# Parent receives return_value for further processing

---

Error Handling

Branch Timeout Handling

Branches auto-return on timeout. Handle gracefully:

# Timeout returns partial results
branch_return(
  branch_id,
  message: "TIMEOUT: Partial results after 300s",
  return_value: {
    timed_out: true,
    completed_steps: ["step1", "step2"],
    incomplete_steps: ["step3", "step4"],
    partial_findings: {...}
  }
)

# Parent should:
1. Check return_value.timed_out
2. Decide: retry with larger timeout OR accept partial
3. Record in memory for future budget planning

Failed Branch Recovery

When a branch fails:

# Branch encounters error
try:
  # ... work that might fail ...
except error:
  # Record remediation for future reference
  remediation_record(
    title: "Branch failure: {description}",
    problem: error.message,
    root_cause: "...",
    solution: "..."
  )

  # Return with error flag
  branch_return(
    branch_id,
    message: "FAILED: {error.summary}",
    return_value: {
      failed: true,
      error: error.message,
      partial_work: {...},
      recovery_suggestions: [...]
    }
  )

Orphaned Branch Cleanup

Detect and clean up orphaned branches:

# Check for orphaned branches at session start
status = branch_status(session_id: "main")

for branch in status.all_branches:
  if branch.status == "orphaned" or branch.timeout_exceeded:
    # Force return with cleanup
    branch_return(
      branch_id: branch.id,
      message: "CLEANUP: Orphaned branch recovered"
    )

    # Record for awareness
    memory_record(
      title: "Orphaned branch cleanup",
      content: "Branch {branch.description} was orphaned and cleaned up"
    )

---

Checkpoint Integration

Save Branch State

Before risky operations or at natural breakpoints:

# Within a branch, save checkpoint
checkpoint_save(
  session_id: current_session,
  name: "branch-{branch_id}-checkpoint",
  summary: "Mid-branch checkpoint: completed {steps}, next {remaining}",
  context: "Branch work in progress..."
)

Resume From Branch Checkpoint

# List available checkpoints
checkpoints = checkpoint_list(session_id)

# Find branch checkpoints
branch_checkpoints = [c for c in checkpoints if "branch-" in c.name]

# Resume specific branch state
checkpoint_resume(
  checkpoint_id: branch_checkpoint.id,
  level: "context"
)

---

Memory Recording at Boundaries

On Branch Create

memory_record(
  project_id: current_project,
  title: "Branch created: {description}",
  content: "Created branch for: {prompt}. Budget: {budget}.",
  outcome: "in_progress",
  tags: ["context-folding", "branch-start"]
)

On Branch Return

memory_record(
  project_id: current_project,
  title: "Branch completed: {description}",
  content: "Findings: {summary}. Budget used: {percent}%.",
  outcome: "success",  # or "partial" or "failed"
  tags: ["context-folding", "branch-complete"]
)

Cross-Branch State Sharing

Use memory for state that needs to persist across branches:

# In branch A: Record finding
memory_record(
  title: "Discovery: Auth pattern",
  content: "Found JWT validation in auth/middleware.go",
  tags: ["auth", "discovery", "branch-a"]
)

# In branch B: Search for related
results = memory_search(
  query: "auth pattern discovery",
  tags: ["discovery"]
)
# Use findings from branch A

---

Integration Patterns

With Orchestration Skill

# Orchestration creates branches for each task group
branch_create(
  description: "Group 1: Issues #42, #43",
  budget: 8192
)

# Launch task agents within branch
Task(subagent_type: "contextd:task-agent", ...)

# Return with group results
branch_return(message: "Group complete: 2 issues resolved")

With Complexity Assessment

# Before creating branch
tier = complexity_assessment(task_description)

# Map tier to budget
budget = {
  "SIMPLE": 4096,
  "STANDARD": 8192,
  "COMPLEX": 16384
}[tier]

# Create appropriately sized branch
branch_create(
  description: task_description,
  budget: budget
)

With Consensus Review

# Create branch for review work
branch_create(
  description: "Security review: {files}",
  budget: 4096
)

# Run review agents
# ... review work ...

# Return findings
branch_return(
  message: "Review complete: 2 findings",
  return_value: {
    verdict: "APPROVED_WITH_FINDINGS",
    findings: [...]
  }
)

---

Workflow

1. branch_create(session_id, description, budget) -> branch_id
2. memory_record(title: "Branch started: {description}")
3. Do work in the branch (read files, search, analyze)
4. branch_status(branch_id) - monitor budget at intervals
5. If budget >= 70%: plan exit strategy
6. If budget >= 85%: begin summarization
7. branch_return(branch_id, message, return_value)
8. memory_record(title: "Branch completed: {description}")

---

Example: Basic Usage

# Create branch for code analysis
branch_create(
  session_id: "main",
  description: "Analyze auth module structure",
  budget: 4096
) -> branch_id: "br_abc123"

# Record branch start
memory_record(title: "Branch: auth analysis started")

# Do analysis...
semantic_search("authentication handlers")
Read files, analyze patterns...

# Check budget mid-way
branch_status("br_abc123") -> budget_percent: 45

# Continue work...

# Return with summary
branch_return(
  branch_id: "br_abc123",
  message: "Auth module has 3 handlers: login, logout, refresh. Uses JWT with 15min expiry.",
  return_value: {
    handlers: ["login", "logout", "refresh"],
    token_type: "JWT",
    expiry: "15min"
  }
)

# Record completion
memory_record(title: "Branch: auth analysis complete", outcome: "success")

---

Example: Adaptive Budget with Warnings

# Create branch
br = branch_create(description: "Deep code analysis", budget: 8192)

# Work loop with monitoring
while work_remaining:
  status = branch_status(br)

  if status.budget_percent >= 85:
    # WARNING: Begin wrap-up
    summary = summarize_findings_so_far()
    branch_return(br, message: summary, return_value: {complete: false})
    break

  if status.budget_percent >= 70:
    # CAUTION: Prioritize remaining work
    work_remaining = prioritize(work_remaining)

  # Continue most important work
  do_next_task(work_remaining.pop())

# Normal completion
branch_return(br, message: final_summary, return_value: {complete: true})

---

Example: Parallel Branches with Dependencies

# Phase 1: Create parallel branches
br_frontend = branch_create(description: "Analyze frontend auth")
br_backend = branch_create(description: "Analyze backend auth")
br_database = branch_create(description: "Analyze auth tables")

# Phase 2: Execute in parallel (via Task tool)
Task(prompt: "Analyze frontend auth components", branch_id: br_frontend)
Task(prompt: "Analyze backend auth handlers", branch_id: br_backend)
Task(prompt: "Analyze user/session tables", branch_id: br_database)

# Phase 3: Collect results
results = {
  frontend: branch_return(br_frontend).return_value,
  backend: branch_return(br_backend).return_value,
  database: branch_return(br_database).return_value
}

# Phase 4: Synthesize (new branch)
br_synthesis = branch_create(description: "Synthesize auth analysis")
# Use results from all three branches...
branch_return(br_synthesis, message: "Full auth architecture documented")

---

Best Practices

Practice	Why
Keep summaries concise	Only essential info returns to parent
Use complexity-based budgets	Match budget to task tier
Monitor at 70/85/95% thresholds	Graceful degradation
Record memories at boundaries	Cross-session learning
Use return_value for structured data	Enable dependent processing
Checkpoint before risky operations	Recovery capability
Clean up orphaned branches	Prevent resource leaks

---

Common Mistakes

Mistake	Fix
Not returning from branch	Always call branch_return
Huge return messages	Summarize, don't dump
Nesting too deep	Max depth is 3
Ignoring timeout	Branch auto-returns on timeout
Skipping budget monitoring	Check at 70%, 85%, 95%
Not recording memories	Record at branch start/end
Fixed budgets for all tasks	Use complexity-based allocation
No error handling	Handle timeouts and failures gracefully
Orphaned branches	Clean up at session start

---

Anti-Patterns

Pattern	Problem	Solution
Budget guessing	Under/over allocation	Use complexity assessment
Ignore budget warnings	Context overflow	Monitor thresholds
No return_value	Lost structured data	Always return structured findings
Skip memory recording	Lost cross-session context	Record at boundaries
Monolithic branches	Hard to recover	Break into smaller branches
No checkpoint integration	Can't resume	Checkpoint before risky ops

---

Quick Reference

Scenario	Action
Starting sub-task	branch_create + memory_record
Mid-task check	branch_status -> check budget_percent
Budget at 70%	Plan exit strategy
Budget at 85%	Begin summarization
Budget at 95%	Force return
Task complete	branch_return + memory_record
Before risky op	checkpoint_save
Session start	Check for orphaned branches
Error in branch	Record remediation + return with error flag