Add doc 12: Context lifecycle management — condensation, threads, staleness
This commit is contained in:
165
docs/hq/12-CONTEXT-LIFECYCLE-MANAGEMENT.md
Normal file
165
docs/hq/12-CONTEXT-LIFECYCLE-MANAGEMENT.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user