Atomizer/docs/hq/12-CONTEXT-LIFECYCLE-MANAGEMENT.md

# 12 — Context Lifecycle Management

> **Status:** PLAN
> **Author:** Mario Lavoie
> **Date:** 2026-02-16
> **Problem:** Discord channel context grows unbounded; agents see only a sliding window; important decisions fall off; stale context can mislead

---

## The Problem

Agents see ~20-30 recent messages in a Discord channel. Everything older is invisible to them. This creates two failure modes:

1. **Lost decisions** — Important conclusions from discussions fall off the window
2. **Stale context** — If an agent's memory references an old problem that's since been fixed, it may re-raise solved issues

## Context Layers (Current Architecture)

| Layer | Persistence | Scope | Who Manages |
|-------|------------|-------|-------------|
| Discord messages | Ephemeral (sliding window) | Channel | Automatic |
| Discord pins | Semi-permanent (50/channel) | Channel | Manager |
| Discord threads | Per-topic (own window) | Thread | Any agent |
| Handoff JSON | Permanent until archived | Task | Orchestration engine |
| Agent memory files | Permanent until edited | Agent | Each agent |
| Knowledge base | Permanent | Company | Knowledge Base agent |

## Solution: Three Mechanisms

### 1. Condensation Protocol (Secretary's Job)

When a Discord channel discussion reaches a conclusion, Secretary produces a **condensation** — a structured summary that captures the decision without the noise.

**Trigger:** Manager or any agent says "📝 condense this discussion" or Secretary detects a natural conclusion point.

**Output format:**
```markdown
## 📝 Condensation: [Topic]
**Date:** [date]
**Channel:** #[channel]
**Participants:** [agents involved]
**Context:** [what was being discussed, 1-2 sentences]
**Decision:** [what was decided]
**Rationale:** [why, key arguments]
**Action items:** [what follows from this]
**Supersedes:** [previous decisions this replaces, if any]
```

**Where it goes:**
1. Pinned in the channel (quick reference)
2. Written to `/home/papa/atomizer/hq/condensations/YYYY-MM-DD-topic.md`
3. Key decisions also go to relevant agent memory files

### 2. Thread-Based Topic Isolation

Use Discord threads for focused problem-solving:

**When to create a thread:**
- Deep technical discussion branching from a channel message
- Bug investigation or debugging session
- Review/challenge cycles (auditor challenges → agent responds)
- Any back-and-forth that would clutter the main channel

**Thread lifecycle:**
1. **Active** — ongoing discussion, agents see full thread context
2. **Resolved** — conclusion reached → Secretary condenses → thread archived
3. **Archived** — Discord auto-archives after inactivity, condensation persists

**Manager creates threads** for delegated work:
```
#proj-starspec-wfe (main channel)
├── Thread: "Material selection: Zerodur vs CCZ HS" → resolved, condensed
├── Thread: "Mesh convergence study" → active
└── Thread: "Mirror mount interface design" → active
```

### 3. Context Refresh Protocol (Per-Channel)

Each project channel gets a **living context document** that agents reference:

**File:** `/home/papa/atomizer/hq/projects/<project>/CONTEXT.md`

**Updated by Secretary** after each condensation or major event:

```markdown
# Project Context: StarSpec WFE Optimization

## Current State
- Phase: Detailed design, post-CDR
- Active: Mesh convergence study on M2 mirror
- Blocked: Nothing

## Key Decisions (most recent first)
1. [2026-02-15] Material: Clearceram-Z HS selected (CTE matches Zerodur Class 0, cheaper)
2. [2026-02-10] Approach: Assembly FEM with superposed models (Model A fixed + Model B variable)
3. [2026-02-08] Optimizer: Optuna TPE, 15 parameters, 500 trial budget

## Active Constraints
- WFE < λ/20 at 633nm under thermal load
- Mass < 12 kg
- First mode > 150 Hz

## Superseded Decisions
- ~~[2026-02-05] Material: Zerodur Class 0~~ → Replaced by CCZ HS (2026-02-15)
- ~~[2026-02-03] Approach: Single monolithic FEM~~ → Replaced by Assembly FEM (2026-02-10)
```

**When an agent starts work on a project channel**, it reads this CONTEXT.md first. This gives it the current ground truth without needing to scroll through weeks of chat history.

### 4. Staleness Detection (Auditor's Periodic Check)

During challenge mode or periodic reviews, auditor checks:
- Are any agents referencing superseded decisions?
- Are CONTEXT.md files up to date?
- Are there un-condensed resolved threads?

## How It All Flows

```
Discussion happens in Discord channel/thread
        │
        ▼ (conclusion reached)
Secretary condenses → pinned + saved to condensations/
        │
        ▼
Secretary updates project CONTEXT.md
        │
        ▼ (superseded decisions marked)
Old context naturally falls off Discord window
        │
        ▼
Agents reference CONTEXT.md for current ground truth
Handoff files preserve structured task results
Agent memory files preserve individual learnings
```

## What Changes for Each Agent

| Agent | New Responsibility |
|-------|-------------------|
| 📋 Secretary | Produce condensations, maintain CONTEXT.md per project |
| 🎯 Manager | Create threads for focused work, request condensations |
| 🔍 Auditor | Check for stale context during reviews |
| All agents | Read project CONTEXT.md before starting work on a project |

## Implementation

| Step | Work | Effort |
|------|------|--------|
| 1 | Add condensation protocol to Secretary SOUL | 1h |
| 2 | Create CONTEXT.md template + initial project contexts | 1h |
| 3 | Add thread creation to Manager's delegation workflow | 1h |
| 4 | Add staleness check to Auditor's challenge mode | 1h |
| 5 | Add condensation file browser to dashboard | 3h |
| **Total** | | **~7h** |

---

## Key Insight

The system IS more intelligent than "everything stays forever" — the sliding window naturally forgets. The challenge is making sure the RIGHT things persist before they fall off. That's what condensation + CONTEXT.md solve: **intentional memory** vs. accidental forgetting.

---

*Prepared by Mario — 2026-02-16*