OpenAgentsControl/.opencode/context/core/context-system/operations/harvest.md

Context Harvest Operation

Purpose: Extract knowledge from AI summaries → permanent context, then clean workspace

Last Updated: 2026-01-06

---

Core Problem

AI agents create summary files (OVERVIEW.md, SESSION-*.md, SUMMARY.md) that contain valuable knowledge but clutter the workspace. These files "plague" the codebase.

Solution: Harvest the knowledge → permanent context, then delete the summaries.

---

Auto-Detection Patterns

Harvest automatically detects these patterns:

Filename patterns:

• *OVERVIEW.md
• *SUMMARY.md
• SESSION-*.md
• CONTEXT-*.md
• *NOTES.md
  

Location patterns:

• Files in .tmp/ directory
• Files with "Summary", "Overview", "Session" in title
• Files >2KB in root directory (likely summaries)

---

6-Stage Workflow

Stage 1: Scan

Action: Find all summary files in workspace

Process:

1. Search for auto-detection patterns
2. Check .tmp/ directory
3. List files with sizes
4. Sort by modification date (newest first)

Output: List of candidate files

Example:

Found 3 summary documents:
1. CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB, modified 1 hour ago)
2. SESSION-auth-work.md (1.8 KB, modified today)
3. .tmp/IMPLEMENTATION-NOTES.md (800 bytes, modified today)

---

Stage 2: Analyze

Action: Categorize content by function

Mapping Rules: | Content Type | Target Folder | How to Identify | |--------------|---------------|-----------------| | Design decisions | concepts/ | "We decided to...", "Architecture", "Pattern" | | Solutions/patterns | examples/ | Code snippets, "Here's how we..." | | Workflows | guides/ | Numbered steps, "How to...", "Setup" | | Errors encountered | errors/ | Error messages, "Fixed issue", "Gotcha" | | Reference data | lookup/ | Tables, lists, paths, commands |

Process:

1. Read each file
2. Identify valuable sections (skip planning/conversation)
3. Categorize by function
4. Determine target file path
5. Generate preview (first 60 chars)

Output: Categorized items with letter IDs

---

Stage 3: Approve (CRITICAL)

Action: Present approval UI with letter-based selection

ALWAYS show approval UI before extracting/deleting. NEVER auto-harvest without user confirmation.

Format:

### CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB)

✓ [A] Design: Function-based context organization
    → Would add to: core/concepts/context-organization.md
    Preview: "Organize by function (concepts/, examples/...)..."

✓ [B] Pattern: Minimal Viable Information
    → Would add to: core/concepts/mvi-principle.md
    Preview: "Extract core only (1-3 sentences), 3-5 key points..."

✓ [C] Workflow: Harvesting summary documents
    → Would create: core/guides/harvesting.md
    Preview: "Scan for summaries → Extract → Approve → Delete"

✗ [D] Skip: Planning discussion notes (temporary knowledge)

---

### SESSION-auth-work.md (1.8 KB)

✓ [E] Error: JWT token expiration not handled
    → Would add to: development/errors/auth-errors.md
    Preview: "Symptom: 401 after 1 hour. Cause: No refresh flow..."

✓ [F] Example: JWT refresh token implementation
    → Would create: development/examples/jwt-refresh.md
    Preview: "Store refresh token → Check expiry → Request new..."

---

### .tmp/IMPLEMENTATION-NOTES.md (800 bytes)

✗ [G] Skip: Duplicate info (already in development/concepts/api-design.md)

---

**Quick options**:
- Type 'A B C E F' - Approve specific items
- Type 'all' - Approve all ✓ items (A B C E F)
- Type 'none' - Skip harvesting, delete files anyway
- Type 'cancel' - Keep files, don't harvest

Validation:

• MUST wait for user input
• MUST not proceed without approval
• If user types 'cancel', stop immediately

Output: List of approved items

---

Stage 4: Extract

Action: Extract and minimize approved items

Apply MVI to all extracted content:

• Core concept: 1-3 sentences
• Key points: 3-5 bullets
• Minimal example: <10 lines
• Reference link: to original source
• Files: <200 lines each

Process:

1. For each approved item:
   • Extract core content
   • Apply MVI minimization (see compact.md)
   • Add to target file (create if needed)
   • Add cross-references
   • Update related files
2. Update navigation.md navigation maps
3. Validate file sizes (<200 lines)

Output: List of created/updated files

---

Stage 5: Cleanup

Action: Archive or delete source summary files

Default Strategy: Archive (safe)

• Move to .tmp/archive/harvested/{date}/
• Preserves originals in case of mistakes
• Can be safely deleted later

Alternative: Delete (if user specified)

• Permanently remove files
• Only delete items user approved for harvest

ONLY cleanup files that had content successfully harvested. If extraction failed, keep the original file.

Output: Cleanup report

---

Stage 6: Report

Action: Show comprehensive results summary

Format:

✅ Harvested 5 items into permanent context:
   - Added to core/concepts/context-organization.md
   - Added to core/concepts/mvi-principle.md
   - Created core/guides/harvesting.md
   - Added to development/errors/auth-errors.md
   - Created development/examples/jwt-refresh.md

🗑️ Cleaned up workspace:
   - Archived: CONTEXT-SYSTEM-OVERVIEW.md → .tmp/archive/harvested/2026-01-06/
   - Archived: SESSION-auth-work.md → .tmp/archive/harvested/2026-01-06/
   - Deleted: .tmp/IMPLEMENTATION-NOTES.md (no valuable content)

📊 Updated navigation maps:
   - .opencode/context/core/navigation.md
   - .opencode/context/development/navigation.md

💾 Disk space freed: 6.8 KB

---

Usage Examples

Scan entire workspace

/context harvest

Scan specific directory

/context harvest .tmp/
/context harvest docs/sessions/

Harvest specific file

/context harvest OVERVIEW.md
/context harvest SESSION-2026-01-06.md

---

Smart Content Detection

✅ Extract (Valuable Knowledge)

• Design decisions ("We chose X because...")
• Patterns that worked ("This pattern solved...")
• Errors encountered + solutions
• API changes ("Updated from v1 to v2...")
• Performance findings ("Optimization reduced...")
• Core concepts explained

❌ Skip (Temporary/Noise)

• Planning discussion ("Should we...?", "Maybe try...")
• Conversational notes ("I think...", "We talked about...")
• Duplicate info (already in context)
• TODO lists (move to task system instead)
• Timestamps and session metadata

---

Safety Features

1. Approval gate - Never auto-delete without confirmation
2. Archive by default - Move to .tmp/archive/, not permanent delete
3. Validation - Check file sizes, structure before committing
4. Rollback - Can restore from archive if needed
5. Dry run - Show what would happen before doing it

---

Success Criteria

After harvest operation:

• Valuable knowledge extracted to permanent context?
• All extracted files <200 lines?
• Files in correct function folders?
• navigation.md navigation updated?
• Summary files archived/deleted?
• Workspace cleaner than before?
• No knowledge lost?

---

Related

• compact.md - How to minimize extracted content
• mvi-principle.md - What to extract
• structure.md - Where files go
• creation.md - File creation rules