wogiflow 1.0.21 → 1.0.22

package/.claude/docs/knowledge-base/04-memory-context/README.md

@@ -0,0 +1,189 @@
+# Memory & Context Management
+
+Preventing hallucinations, managing context windows, and preserving session history.
+
+---
+
+## The Problem
+
+AI struggles with:
+- **Context Overflow**: Losing track when context gets too large
+- **Session Amnesia**: Forgetting work between sessions
+- **Hallucinations**: Making up components that don't exist
+- **Lost History**: Not remembering past decisions
+
+---
+
+## The Solution
+
+WogiFlow manages memory through:
+- Context monitoring and compaction
+- Durable sessions for crash recovery
+- Memory blocks for key facts
+- Request log as institutional memory
+
+---
+
+## Features
+
+| Feature | Purpose |
+|---------|---------|
+| [Context Management](./context-management.md) | Monitor and compact context |
+| [Session Persistence](./session-persistence.md) | Preserve work across sessions |
+| [Memory Systems](./memory-systems.md) | Facts, decay, tiers |
+| [Team History](./team-history.md) | Shared logs, audit trails |
+| [PRD Management](./prd-management.md) | Load and query product specs |
+| [Memory Commands](./memory-commands.md) | CLI for entropy, sync, routing |
+
+---
+
+## Quick Start
+
+### Enable Context Monitoring
+
+```json
+{
+  "contextMonitor": {
+    "enabled": true,
+    "warnAt": 0.7,          // Warn at 70%
+    "criticalAt": 0.85,     // Critical at 85%
+    "contextWindow": 200000
+  }
+}
+```
+
+### Check Context Health
+
+```
+Context is monitored automatically.
+When high, you'll see:
+
+⚠️ Context Health Warning
+Usage: 165,000 / 200,000 tokens (82.5%)
+Recommendation: Run /compact before continuing
+```
+
+### Compact When Needed
+
+```bash
+/wogi-compact
+```
+
+---
+
+## Key Configuration
+
+```json
+{
+  "contextMonitor": {
+    "enabled": true,
+    "warnAt": 0.7,
+    "criticalAt": 0.85,
+    "contextWindow": 200000,
+    "checkOnSessionStart": true,
+    "checkAfterTask": true
+  },
+  "sessionState": {
+    "enabled": true,
+    "autoRestore": true,
+    "maxGapHours": 24,
+    "trackFiles": true,
+    "trackDecisions": true
+  },
+  "memory": {
+    "enabled": true,
+    "localDb": ".workflow/memory/local.db",
+    "maxLocalFacts": 1000,
+    "autoRemember": false
+  },
+  "requestLog": {
+    "enabled": true,
+    "autoArchive": true,
+    "maxRecentEntries": 50
+  }
+}
+```
+
+---
+
+## Memory Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    MEMORY ARCHITECTURE                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐      │
+│   │   Context   │   │   Session   │   │   Request   │      │
+│   │   Monitor   │   │    State    │   │     Log     │      │
+│   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘      │
+│          │                 │                 │              │
+│          ▼                 ▼                 ▼              │
+│   ┌─────────────────────────────────────────────────┐      │
+│   │                  Memory Blocks                   │      │
+│   │  - Key facts                                    │      │
+│   │  - Recent files                                 │      │
+│   │  - Current task                                 │      │
+│   │  - Important decisions                          │      │
+│   └─────────────────────────────────────────────────┘      │
+│                          │                                  │
+│                          ▼                                  │
+│   ┌─────────────────────────────────────────────────┐      │
+│   │              Durable Session                     │      │
+│   │  - Crash recovery                               │      │
+│   │  - Step tracking                                │      │
+│   │  - Resume context                               │      │
+│   └─────────────────────────────────────────────────┘      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Context Thresholds
+
+| Level | Threshold | Behavior |
+|-------|-----------|----------|
+| Normal | < 70% | Continue normally |
+| Warning | 70-85% | Suggest compaction |
+| Critical | > 85% | Strongly recommend compact |
+
+---
+
+## Compaction Strategy
+
+When context is high:
+
+1. **Preserve**: Key facts, current task, recent decisions
+2. **Summarize**: Long conversations, completed work
+3. **Archive**: Old request log entries
+4. **Clear**: Temporary context, resolved issues
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/wogi-compact` | Compact conversation context |
+| `/wogi-standup` | Morning briefing with context |
+| `flow session status` | Check session state |
+| `flow session restore` | Restore previous session |
+
+---
+
+## Best Practices
+
+1. **Compact Regularly**: Every 2-3 tasks or 15-20 messages
+2. **Update Progress**: Before compacting, update progress.md
+3. **Log Changes**: Keep request-log current
+4. **Use Morning Briefing**: Start sessions with context
+5. **Trust the Warnings**: Compact when suggested
+
+---
+
+## Related
+
+- [Task Execution](../02-task-execution/) - Uses session context
+- [Self-Improvement](../03-self-improvement/) - Memory feeds learning
+- [Configuration](../configuration/all-options.md) - All memory settings

package/.claude/docs/knowledge-base/04-memory-context/context-management.md

@@ -0,0 +1,308 @@
+# Context Management
+
+Monitor context usage and compact when needed.
+
+---
+
+## Why Context Matters
+
+Claude has a context window limit. When exceeded:
+- Earlier conversation is lost
+- AI may hallucinate or repeat itself
+- Work quality degrades
+
+WogiFlow monitors context and helps you manage it.
+
+---
+
+## Configuration
+
+```json
+{
+  "contextMonitor": {
+    "enabled": true,
+    "warnAt": 0.7,              // Warn at 70%
+    "criticalAt": 0.85,         // Critical at 85%
+    "contextWindow": 200000,    // Token limit
+    "checkOnSessionStart": true,
+    "checkAfterTask": true,
+    "trackingMethod": "auto"    // auto, native, or estimated
+  }
+}
+```
+
+### Tracking Methods (v1.0.3+)
+
+| Method | Description |
+|--------|-------------|
+| `auto` | Uses native if available, falls back to estimated (default) |
+| `native` | Uses Claude Code's native context tracking (v1.0.52+) |
+| `estimated` | Uses token estimation from state files |
+
+Native tracking is more accurate but requires Claude Code v1.0.52+ and status line configuration via `/wogi-statusline-setup`.
+
+---
+
+## How Monitoring Works
+
+### Automatic Checks
+
+Context is checked:
+1. At session start (`checkOnSessionStart`)
+2. After task completion (`checkAfterTask`)
+3. Before large operations
+
+### Warning Levels
+
+```
+Usage: 45,000 / 200,000 (22.5%)
+Status: ✓ Healthy
+
+Usage: 145,000 / 200,000 (72.5%)
+Status: ⚠️ Warning - Consider compacting
+
+Usage: 175,000 / 200,000 (87.5%)
+Status: 🚨 Critical - Compact now
+```
+
+---
+
+## Compaction
+
+### What is Compaction?
+
+Compaction summarizes the conversation to free context space while preserving essential information.
+
+### When to Compact
+
+- After completing 2-3 tasks
+- After 15-20 messages
+- Before starting large tasks
+- When warned about context usage
+
+### How to Compact
+
+```bash
+/wogi-compact
+```
+
+### What's Preserved
+
+- Current task and acceptance criteria
+- Recent key facts
+- Important decisions made
+- Files currently being worked on
+
+### What's Summarized
+
+- Completed work details
+- Long code discussions
+- Exploration and research
+- Resolved issues
+
+---
+
+## Memory Blocks
+
+Key facts are stored in memory blocks:
+
+```javascript
+// From flow-memory-blocks.js
+
+const memoryBlocks = {
+  currentTask: {
+    id: "TASK-015",
+    title: "Add authentication"
+  },
+  keyFacts: [
+    "Using existing api wrapper from lib/api.ts",
+    "Auth tokens stored in localStorage"
+  ],
+  recentFiles: [
+    "src/services/AuthService.ts",
+    "src/components/LoginForm.tsx"
+  ],
+  decisions: [
+    "Use Zustand for auth state",
+    "JWT tokens with refresh"
+  ]
+};
+```
+
+### Adding Key Facts
+
+```javascript
+addKeyFact("Auth tokens expire after 1 hour");
+```
+
+### Clearing on Task Complete
+
+```javascript
+clearCurrentTask();
+```
+
+---
+
+## Pre-Compaction Checklist
+
+Before running `/compact`:
+
+1. **Update Progress**
+   ```bash
+   # Ensure progress.md reflects current state
+   cat .workflow/state/progress.md
+   ```
+
+2. **Log Completed Work**
+   ```bash
+   # Add entries to request-log
+   /wogi-log
+   ```
+
+3. **Commit Changes**
+   ```bash
+   git add -A && git commit -m "checkpoint before compact"
+   ```
+
+---
+
+## Compaction Strategy
+
+### Default Strategy
+
+```json
+{
+  "automaticMemory": {
+    "compactOnSessionEnd": true
+  }
+}
+```
+
+### Custom Strategies
+
+Available in config:
+- `entropyThreshold`: How aggressively to compact
+- `relevanceDecay`: How quickly old info loses relevance
+
+---
+
+## Tracking Context Health
+
+### CLI Check
+
+```bash
+flow context status
+
+# Output:
+# Context Health
+# ─────────────────────
+# Usage: 145,000 / 200,000 (72.5%)
+# Status: Warning
+# Last compaction: 2024-01-15 10:30
+# Recommendation: Compact before next large task
+```
+
+### In-Session Check
+
+After completing a task:
+```
+✓ Completed: TASK-015
+
+Context Health:
+  Usage: 72.5%
+  Status: ⚠️ Consider running /compact
+```
+
+---
+
+## Automatic Archival
+
+Old request log entries are archived automatically:
+
+```json
+{
+  "requestLog": {
+    "autoArchive": true,
+    "maxRecentEntries": 50,
+    "keepRecent": 30,
+    "createSummary": true
+  }
+}
+```
+
+### How It Works
+
+1. When entries exceed `maxRecentEntries`
+2. Old entries moved to archive
+3. Summary created if `createSummary` is true
+4. Archived entries still searchable
+
+---
+
+## Context Window Sizes
+
+| Model | Context Window |
+|-------|---------------|
+| Claude Opus | 200,000 |
+| Claude Sonnet | 200,000 |
+| Claude Haiku | 200,000 |
+| GPT-4 | 128,000 |
+| Local models | Varies (4K-128K) |
+
+Configure for your model:
+```json
+{
+  "contextMonitor": {
+    "contextWindow": 128000
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Compact Proactively**: Don't wait for critical
+2. **Save Before Compact**: Commit your work first
+3. **Use Memory Blocks**: Mark important facts
+4. **Review Compaction**: Check nothing important was lost
+5. **Adjust Thresholds**: Lower if you need more buffer
+
+---
+
+## Troubleshooting
+
+### Lost Context After Compact
+
+Check preserved data:
+- Memory blocks should retain key facts
+- Current task should be preserved
+- progress.md should have handoff notes
+
+### Context Growing Too Fast
+
+Consider:
+- Breaking large tasks into smaller ones
+- Using hybrid mode for boilerplate
+- More frequent compaction
+
+### Warning Not Appearing
+
+Check configuration:
+```json
+{
+  "contextMonitor": {
+    "enabled": true,
+    "checkOnSessionStart": true,
+    "checkAfterTask": true
+  }
+}
+```
+
+---
+
+## Related
+
+- [Session Persistence](./session-persistence.md) - Preserving across sessions
+- [Memory Systems](./memory-systems.md) - Fact storage and decay
+- [Compaction Command](../../commands.md) - Full command reference

package/.claude/docs/knowledge-base/04-memory-context/memory-commands.md

@@ -0,0 +1,176 @@
+# Memory Management Commands
+
+CLI commands for managing WogiFlow's memory system.
+
+---
+
+## Overview
+
+Memory management commands help monitor, maintain, and optimize the memory database and learned patterns.
+
+---
+
+## Entropy Monitor
+
+Track memory fragmentation and context efficiency.
+
+**Script**: `flow-entropy-monitor.js`
+
+```bash
+# Show memory entropy stats
+flow entropy
+
+# Auto-compact if entropy is high
+flow entropy --auto
+
+# Show entropy history
+flow entropy --history
+```
+
+### What is Entropy?
+
+Memory entropy measures:
+- Fragmentation of stored facts
+- Staleness of patterns
+- Context window efficiency
+
+High entropy (>0.7) suggests compaction needed.
+
+### Output Example
+
+```
+Memory Entropy Analysis
+════════════════════════════════════════
+Current Entropy:  0.45
+Threshold:        0.70
+Status:           ✓ Healthy
+
+Breakdown:
+  Facts:          234 (12 stale)
+  Patterns:       45 (3 low-confidence)
+  PRD Chunks:     89
+
+Recommendation:   No action needed
+```
+
+---
+
+## Memory Sync
+
+Promote high-confidence patterns to project rules.
+
+**Script**: `flow-memory-sync.js`
+
+```bash
+# Check for promotable patterns
+flow memory-sync
+
+# List candidates only
+flow memory-sync --list
+
+# Auto-promote without asking
+flow memory-sync --auto
+
+# Show sync status
+flow memory-sync --status
+
+# Promote specific fact
+flow memory-sync --promote <fact-id>
+```
+
+### Promotion Criteria
+
+A pattern is promotable when:
+- Relevance score ≥ 80%
+- Access count ≥ 3
+- Not already in `decisions.md`
+
+### Promotion Flow
+
+```
+Memory DB → Candidate Analysis → decisions.md → .claude/rules/
+```
+
+Promoted patterns become project rules that load automatically.
+
+---
+
+## Memory Database
+
+Direct database operations.
+
+```bash
+# Show memory stats
+flow memory stats
+
+# Output:
+# Facts: 234
+# Proposals: 12
+# PRD Chunks: 89
+# Database Size: 2.4 MB
+```
+
+### Database Location
+
+```
+.workflow/memory/local.db
+```
+
+SQLite database managed by `flow-memory-db.js`.
+
+---
+
+## Knowledge Router
+
+Route learnings to appropriate storage locations.
+
+**Script**: `flow-knowledge-router.js`
+
+```bash
+# Detect route for a learning
+flow knowledge-route detect "Always use explicit types"
+
+# Store with detected route
+flow knowledge-route store "Use kebab-case" project
+
+# Show all route types
+flow knowledge-route routes
+```
+
+### Route Types
+
+| Route | Storage Location |
+|-------|------------------|
+| `model-specific` | `.workflow/model-adapters/<model>.md` |
+| `skill:<name>` | `.claude/skills/<name>/knowledge/learnings.md` |
+| `project` | `.workflow/state/decisions.md` |
+| `team` | Team proposal queue (requires subscription) |
+
+---
+
+## Compact Memory
+
+Full memory compaction and optimization.
+
+```bash
+# Run full compaction
+flow compact-memory
+
+# Or via entropy command
+flow entropy --auto
+```
+
+### What Compaction Does
+
+1. Removes stale/low-relevance facts
+2. Deduplicates similar patterns
+3. Rebuilds embeddings index
+4. Vacuums SQLite database
+
+---
+
+## Related
+
+- [Memory Systems](./memory-systems.md) - Architecture overview
+- [Context Management](./context-management.md) - Token budgets
+- [PRD Management](./prd-management.md) - Document storage