OpenAgentsControl/.opencode/context/core/context-management.md

Context Management Strategy

Session-Based Isolation

Purpose

Prevent concurrent agent instances from interfering with each other by using isolated session folders.

Session Structure

.tmp/sessions/{session-id}/{task-category}/{task-name}-context.md

Session ID Format

{timestamp}-{random-4-chars}

Example: 20250118-143022-a4f2

Session Manifest

Each session has a manifest file tracking all context files:

Location: .tmp/sessions/{session-id}/.manifest.json

Structure:

{
  "session_id": "20250118-143022-a4f2",
  "created_at": "2025-01-18T14:30:22Z",
  "last_activity": "2025-01-18T14:35:10Z",
  "context_files": {
    "features/user-auth-context.md": {
      "created": "2025-01-18T14:30:22Z",
      "for": "@subagents/core/task-manager",
      "keywords": ["user-auth", "authentication", "features"]
    },
    "tasks/user-auth-tasks.md": {
      "created": "2025-01-18T14:32:15Z",
      "for": "@subagents/core/task-manager",
      "keywords": ["user-auth", "tasks", "breakdown"]
    },
    "documentation/api-docs-context.md": {
      "created": "2025-01-18T14:35:10Z",
      "for": "@subagents/core/documentation",
      "keywords": ["api", "documentation"]
    }
  },
  "context_index": {
    "user-auth": [
      "features/user-auth-context.md",
      "tasks/user-auth-tasks.md"
    ],
    "api": [
      "documentation/api-docs-context.md"
    ]
  }
}

Temporary Context Files

When to Create

Only create context files when ALL of these apply:

• Delegating to a subagent
• Context description is verbose (>2 sentences) OR
• Risk of misinterpretation without detailed context

File Structure

.tmp/sessions/{session-id}/{task-category}/{task-name}-context.md

Categories

• features/ - Feature development context
• documentation/ - Documentation tasks
• code/ - Code-related tasks
• refactoring/ - Refactoring tasks
• testing/ - Testing tasks
• tasks/ - Task breakdowns created by task-manager
• general/ - General tasks that don't fit other categories

Examples

.tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
.tmp/sessions/20250118-143022-a4f2/documentation/api-docs-context.md
.tmp/sessions/20250118-150000-b7k9/code/database-refactor-context.md
.tmp/sessions/20250118-151500-c3x8/testing/integration-tests-context.md

File Contents

# Context: {Task Name}
Session: {session-id}

## Request Summary
[Brief description of what needs to be done]

## Background
[Relevant context and information]

## Expected Output
[What the subagent should produce]

## Constraints
[Any limitations or requirements]

Cleanup Strategy

During Session

1. Remove individual context files after task completion
2. Update manifest to remove file entry
3. Update last_activity timestamp

End of Session

1. Remove entire session folder: .tmp/sessions/{session-id}/
2. Only delete files tracked in current session's manifest

Stale Session Cleanup

• Automatically clean sessions older than 24 hours with no activity
• Check last_activity timestamp in manifest
• Safe to run periodically without affecting active sessions

Manual Cleanup

Users can safely delete:

• Entire .tmp/ folder anytime
• Individual session folders
• Stale sessions (check last_activity timestamp)

Concurrent Safety

Isolation Guarantees

✅ Each agent instance has unique session ID ✅ Context files are isolated per session ✅ Manifest tracks only files created by this session ✅ Cleanup only affects current session's files ✅ No risk of deleting another instance's context

Best Practices

1. Generate session ID early - At first context file creation
2. Track all files - Add every context file to manifest
3. Update activity - Touch last_activity on each operation
4. Clean up promptly - Remove files after task completion
5. Only clean own files - Never delete files outside current session

Dynamic Context Loading

Purpose

Allow subagents to discover and load relevant context files created earlier in the session.

How It Works

1. Context File Creation When creating a context file, add metadata to manifest:

"context_files": {
  "features/user-auth-context.md": {
    "created": "2025-01-18T14:30:22Z",
    "for": "@subagents/core/task-manager",
    "keywords": ["user-auth", "authentication", "features"]
  }
}

2. Context Indexing Manifest maintains keyword index for fast lookup:

"context_index": {
  "user-auth": [
    "features/user-auth-context.md",
    "tasks/user-auth-tasks.md"
  ]
}

3. Context Discovery When delegating to subagent:

1. Search manifest for related context files (by keyword/category)
2. Pass relevant context file paths to subagent
3. Subagent reads context files as needed

4. Delegation Pattern

Delegating to @subagents/code/coder-agent:
"Implement user authentication login component.

Related context available at:
- .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
- .tmp/sessions/20250118-143022-a4f2/tasks/user-auth-tasks.md

Read these files for full context on requirements and task breakdown."

Example Workflow

1. User: "Build user authentication system"
   → OpenAgent creates: features/user-auth-context.md
   → Delegates to @task-manager
   
2. Task-manager creates: tasks/user-auth-tasks.md
   → Both files tracked in manifest with keyword "user-auth"
   
3. User: "Implement the login component"
   → OpenAgent searches manifest for "user-auth" context
   → Finds both context files
   → Delegates to @coder-agent with references to both files
   → Coder-agent reads files to understand full context

Benefits

• No context loss: Information persists across subagent calls
• Automatic discovery: Related context found by keywords
• Flexible: Subagents read only what they need
• Traceable: Manifest shows all context relationships

---

Why This Approach?

Session Isolation

• Concurrent safety: Multiple agents can run simultaneously
• No conflicts: Each session has its own namespace
• Easy cleanup: Delete entire session folder when done
• Traceable: Manifest shows what belongs to each session

Dynamic Context

• Discoverable: Context files indexed by keywords
• Reusable: Later subagents can access earlier context
• Flexible: Load only relevant context
• Persistent: Context survives across subagent calls

Why .tmp/sessions/?

• Standard .tmp/ convention (commonly ignored)
• sessions/ subfolder makes purpose clear
• Session ID provides unique namespace
• Easy to identify and clean up stale sessions
• Hidden folder (starts with .)

Example Workflow

# Agent Instance 1 starts
Session ID: 20250118-143022-a4f2
Creates: .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md

# Agent Instance 2 starts (concurrent)
Session ID: 20250118-143030-b7k9
Creates: .tmp/sessions/20250118-143030-b7k9/features/payment-context.md

# Both agents work independently without conflicts

# Agent Instance 1 completes
Deletes: .tmp/sessions/20250118-143022-a4f2/ (entire folder)

# Agent Instance 2 continues unaffected
Still has: .tmp/sessions/20250118-143030-b7k9/