[Phase 4] Implement Memory Eviction Strategy for COLD Tier

[frankbria]

Summary

Design and implement explicit eviction policies for the tiered memory system to prevent COLD tier bloat and ensure long-term system health during multi-day autonomous sessions.

Background: State of the Art

From Philipp Schmid's "Memory in Agents":

"Memory Bloat: An agent that remembers everything eventually remembers nothing useful. Storing every detail leads to 'bloat' making it more expensive to search, and harder to navigate."

"Need to Forget: The value of information decays. Acting on outdated preferences or facts becomes unreliable. Designing eviction strategies to discard noise without accidentally deleting crucial, long-term context is difficult."

The challenge: delayed feedback loops. Bad eviction decisions only surface later, making iteration difficult.

Key insight: Memory systems need explicit "forgetting" mechanisms, not just retention policies.

Current State in CodeFRAME

The HOT/WARM/COLD tiered system implies decay (items demote over time), but several questions remain:

1. COLD tier growth: What happens to items that reach COLD and stay there?
2. Eviction triggers: Is there a max size? Time-based expiry? Relevance threshold?
3. Protected items: Are some contexts "pinned" and never evicted?
4. Cross-session accumulation: Over 8+ hour sessions or multiple days, how large does the context store grow?

Without explicit eviction, COLD tier becomes a write-only log that degrades retrieval performance and increases storage costs.

Investigation Tasks

1. Measure current growth patterns

   • Instrument context store size over a multi-task session
   • Track items entering COLD tier vs. ever being retrieved again
   • Identify "dead" context (written but never read)

2. Define eviction policy categories

   • Time-based: Items older than X hours without access
   • Access-based: Items with access count below threshold
   • Relevance-based: Items with importance score below threshold
   • Size-based: Evict oldest/lowest-scored when tier exceeds limit

3. Implement eviction strategies

   • LRU (Least Recently Used) for each tier
   • Importance-weighted eviction (low score + old = evict first)
   • "Summarize before eviction" - compress episodic memory into semantic facts

4. Design protection mechanisms

   • Pin critical context (project architecture, key decisions)
   • Require explicit "forget" vs. automatic eviction for sensitive items
   • Eviction audit log for debugging

5. Handle the feedback loop problem

   • Log eviction decisions for later analysis
   • Build "eviction regret" metric: was evicted content later re-requested?
   • Tune policies based on regret rate

Success Criteria

• Documented current context growth rates over extended sessions
• Implemented configurable eviction policy (time/access/relevance/size)
• COLD tier maintains bounded size under continuous operation
• Eviction audit log for debugging and tuning
• Measured "eviction regret" rate < 5%

Design Considerations

Summarize before eviction: Instead of deleting episodic memory ("on task 47, agent tried X and it failed"), summarize into semantic memory ("approach X doesn't work for this codebase") before eviction. This preserves learning while reducing storage.

Session boundaries: Consider more aggressive eviction at session end, but preserve cross-session learning.

References

• Memory in Agents - Philipp Schmid
• Elasticsearch hot/warm/cold/frozen tiers as precedent for data lifecycle
• Redis eviction policies (LRU, LFU, TTL) as implementation patterns

[traycerai]

Plan

Observations

The current CodeFRAME tiered memory system (HOT/WARM/COLD) implements importance-based scoring and flash save archival, but lacks explicit eviction policies for long-term system health during multi-day autonomous sessions. The COLD tier grows unbounded as items demote from WARM, and flash save only archives COLD items during token threshold events (144k/180k). No mechanisms exist for time-based expiration, size limits, eviction audit logging, or "eviction regret" tracking. The system uses exponential decay scoring (λ=0.5, ~1.4 day half-life) but doesn't enforce maximum age or access-based cleanup. Database schema supports all necessary fields (created_at, last_accessed, access_count, importance_score) but lacks eviction metadata columns.

Approach

Implement a multi-strategy eviction system that extends the existing tiered architecture without disrupting current flash save functionality. Add configurable eviction policies (time-based, access-based, size-based) that operate independently of flash save, with audit logging and regret tracking to measure effectiveness. Introduce a new EvictionManager class that coordinates policies, logs decisions, and provides metrics. Extend database schema with eviction audit tables and add configuration options to ContextManagementConfig. This approach preserves the existing importance scoring and tier assignment logic while adding explicit lifecycle management for COLD tier items. The implementation prioritizes measuring current growth patterns first, then implements configurable eviction with protection mechanisms, and finally validates effectiveness through regret tracking.

Implementation Steps

1. Measurement and Instrumentation (Phase 1)

Create new file file:codeframe/lib/context_growth_tracker.py:

Implement ContextGrowthTracker class to measure current patterns:

• track_cold_tier_growth(project_id, agent_id) - Record COLD tier size and growth rate
• identify_dead_context(project_id, agent_id) - Find items written but never accessed
• get_growth_report(project_id, agent_id, days) - Generate growth analysis report
• calculate_tier_distribution(project_id, agent_id) - Percentage of items in each tier
• estimate_session_bloat(project_id, agent_id, session_hours) - Project growth over extended sessions

Add metrics to database:

CREATE TABLE IF NOT EXISTS context_growth_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    measurement_timestamp TEXT NOT NULL,
    cold_tier_count INTEGER NOT NULL,
    cold_tier_tokens INTEGER NOT NULL,
    warm_tier_count INTEGER NOT NULL,
    hot_tier_count INTEGER NOT NULL,
    dead_context_count INTEGER NOT NULL,
    avg_item_age_days REAL NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Extend codeframe/lib/context_manager.py:

• Add measure_context_growth(project_id, agent_id) method
• Call measurement after tier updates to track patterns
• Log growth metrics for analysis

2. Database Schema Extensions

Extend file:codeframe/persistence/schema_manager.py in the _create_memory_context_tables() method:

Add new table for context growth metrics (from Phase 1):

CREATE TABLE IF NOT EXISTS context_growth_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    measurement_timestamp TEXT NOT NULL,
    cold_tier_count INTEGER NOT NULL,
    cold_tier_tokens INTEGER NOT NULL,
    warm_tier_count INTEGER NOT NULL,
    hot_tier_count INTEGER NOT NULL,
    dead_context_count INTEGER NOT NULL,
    avg_item_age_days REAL NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Add new table for eviction audit log:

CREATE TABLE IF NOT EXISTS context_eviction_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    item_type TEXT NOT NULL,
    eviction_reason TEXT NOT NULL,  -- 'time_expired', 'access_threshold', 'size_limit', 'manual'
    importance_score REAL NOT NULL,
    age_days REAL NOT NULL,
    access_count INTEGER NOT NULL,
    last_accessed TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    content_summary TEXT,  -- First 200 chars for debugging
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Add table for eviction regret tracking:

CREATE TABLE IF NOT EXISTS context_eviction_regret (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    re_requested_at TEXT NOT NULL,
    regret_type TEXT NOT NULL,  -- 'exact_match', 'similar_content', 'same_type'
    regret_score REAL NOT NULL,  -- 0.0-1.0 similarity
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Add indexes for performance:

CREATE INDEX IF NOT EXISTS idx_eviction_log_agent ON context_eviction_log(agent_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_log_project ON context_eviction_log(project_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_regret_item ON context_eviction_regret(item_id);

Add new database methods:

• log_eviction(item_id, reason, metadata) - Record eviction decision
• check_eviction_regret(content, item_type, agent_id) - Check if similar content was recently evicted
• get_eviction_stats(project_id, agent_id, days) - Aggregate eviction metrics
• get_regret_rate(project_id, agent_id, days) - Calculate regret percentage

3. Configuration Extensions

Extend file:codeframe/core/config.py in the ContextManagementConfig class:

Add eviction policy configuration:

class EvictionPolicyConfig(BaseModel):
    """Eviction policy configuration for COLD tier."""
    
    enabled: bool = True
    
    # Time-based eviction
    max_age_days: int = 7  # Evict items older than 7 days
    
    # Access-based eviction
    min_access_count: int = 1  # Evict items never accessed
    min_access_days: int = 3  # Must be accessed within 3 days
    
    # Size-based eviction
    cold_tier_max_items: int = 1000  # Max items in COLD tier
    cold_tier_max_tokens: int = 100000  # Max tokens in COLD tier
    
    # Protection mechanisms
    protected_types: List[str] = ["TASK", "PRD_SECTION"]  # Never auto-evict
    manual_pin_protected: bool = True  # Respect manual_pin flag
    
    # Eviction strategy
    strategy: str = "hybrid"  # 'lru', 'importance_weighted', 'hybrid'
    
    # Audit and monitoring
    log_evictions: bool = True
    track_regret: bool = True
    regret_window_days: int = 7  # Track regret for 7 days after eviction

class ContextManagementConfig(BaseModel):
    """Virtual Project context configuration."""
    
    enabled: bool = True
    hot_tier_max_tokens: int = 20000
    warm_tier_max_tokens: int = 40000
    importance_threshold_hot: float = 0.8
    importance_threshold_warm: float = 0.4
    
    # NEW: Eviction policy
    eviction_policy: EvictionPolicyConfig = Field(default_factory=EvictionPolicyConfig)

4. Eviction Manager Implementation

Create new file file:codeframe/lib/eviction_manager.py:

Implement EvictionManager class with methods:

• __init__(db, config) - Initialize with database and config
• should_evict_item(item) - Evaluate if item meets eviction criteria
• select_eviction_candidates(project_id, agent_id) - Query COLD tier items for eviction
• evict_items(candidates, reason) - Execute eviction with audit logging
• check_size_limits(project_id, agent_id) - Enforce COLD tier size limits
• run_eviction_cycle(project_id, agent_id) - Main eviction workflow
• calculate_eviction_priority(item) - Score items for eviction (lower = evict first)
• is_protected(item) - Check if item is protected from eviction
• log_eviction_decision(item, reason) - Write to audit log
• track_regret_if_needed(content, item_type, agent_id) - Check for regret on new context creation

Eviction priority calculation (hybrid strategy):

priority = (importance_score * 0.4) + (recency_score * 0.3) + (access_score * 0.3)

where:
- recency_score = 1.0 - (age_days / max_age_days)
- access_score = min(access_count / 10, 1.0)
- Lower priority = evict first

5. Integration with Context Manager

Extend file:codeframe/lib/context_manager.py:

Add eviction manager integration:

• Import EvictionManager in __init__
• Add run_eviction_if_needed(project_id, agent_id) method
• Call eviction check after tier updates in update_tiers_for_agent()
• Add get_eviction_stats(project_id, agent_id) method for metrics
• Add force_eviction(project_id, agent_id, reason) for manual triggers
• Integrate ContextGrowthTracker to measure patterns during normal operation

Modify flash_save() to log evictions:

• Before archiving COLD items, log each as eviction with reason='flash_save'
• This provides continuity with existing behavior while adding audit trail

6. Eviction Strategies Implementation

In file:codeframe/lib/eviction_manager.py, implement strategy classes:

LRUStrategy:

• Sort by last_accessed ascending
• Evict oldest accessed items first
• Ignore importance scores

ImportanceWeightedStrategy:

• Sort by importance_score ascending
• Evict lowest scored items first
• Consider age as tiebreaker

HybridStrategy (default):

• Calculate composite priority score
• Balance importance, recency, and access patterns
• Configurable weights via config

Each strategy implements:

• select_candidates(items, count) - Choose items to evict
• calculate_priority(item) - Score for eviction order

7. Regret Tracking Implementation

In file:codeframe/lib/eviction_manager.py:

Add regret detection logic:

• On create_context_item(), check if similar content was recently evicted
• Use fuzzy matching (Levenshtein distance) for content similarity
• Log regret event if similarity > 0.8 within regret window
• Track regret types: exact_match (same content), similar_content (>0.8 similarity), same_type (same item_type)

Add regret metrics:

• get_regret_rate(days) - Percentage of evicted items re-requested
• get_regret_by_strategy(days) - Compare regret rates across strategies
• get_high_regret_patterns() - Identify frequently re-requested item types

8. API Endpoints

Extend file:codeframe/ui/server.py:

Add new endpoints:

• GET /api/context/growth-metrics - Current context growth analysis
• POST /api/context/evict - Manual eviction trigger
• GET /api/context/eviction-stats - Eviction metrics and regret rate
• GET /api/context/eviction-log - Paginated eviction audit log
• POST /api/context/pin/{item_id} - Pin item to prevent eviction
• DELETE /api/context/pin/{item_id} - Unpin item

Response models in file:codeframe/core/models.py:

class EvictionStats(BaseModel):
    agent_id: str
    total_evictions: int
    evictions_by_reason: Dict[str, int]
    regret_rate: float
    avg_age_at_eviction: float
    protected_items_count: int

class EvictionLogEntry(BaseModel):
    id: int
    item_id: str
    eviction_reason: str
    importance_score: float
    age_days: float
    access_count: int
    evicted_at: datetime

9. Background Eviction Task

Create new file file:codeframe/tasks/eviction_task.py:

Implement periodic eviction task:

• Run every 1 hour (configurable)
• Iterate through all active agents
• Call EvictionManager.run_eviction_cycle() for each
• Call ContextGrowthTracker.track_cold_tier_growth() for measurement
• Log summary metrics
• Send WebSocket events for eviction updates

Integration with task scheduler (if exists) or standalone cron job.

10. Metrics and Monitoring

Extend file:codeframe/lib/metrics_tracker.py:

Add eviction metrics tracking:

• record_eviction_event(project_id, agent_id, count, reason) - Track eviction events
• get_eviction_trends(project_id, days) - Time-series eviction data
• get_cold_tier_health(project_id, agent_id) - Size, growth rate, eviction rate

Dashboard metrics:

• COLD tier size over time
• Eviction rate (items/day)
• Regret rate percentage
• Protected items count
• Average item lifetime in COLD tier

11. Testing Strategy

Create test files:

file:tests/context/test_eviction_manager.py:

• Test eviction criteria evaluation
• Test strategy selection and execution
• Test protection mechanisms
• Test size limit enforcement
• Test audit logging

file:tests/context/test_eviction_regret.py:

• Test regret detection on re-creation
• Test similarity matching
• Test regret rate calculation
• Test regret window expiration

file:tests/integration/test_eviction_workflow.py:

• Test full eviction cycle
• Test interaction with flash save
• Test background task execution
• Test API endpoints

12. Documentation Updates

Update documentation files:

file:CLAUDE.md:

• Add section on context growth measurement
• Document eviction policies and configuration
• Explain regret tracking
• Provide examples of manual eviction
• Include growth analysis interpretation guide

file:PRD.md:

• Update context management section
• Add eviction policy requirements
• Document success criteria
• Include measurement methodology

Create new documentation:
file:docs/context-eviction-guide.md:

• Detailed eviction policy explanation
• Configuration tuning guide
• Troubleshooting eviction issues
• Interpreting regret metrics
• Growth pattern analysis methodology

file:docs/context-growth-analysis.md:

• How to measure context growth over sessions
• Identifying dead context patterns
• Projecting bloat over multi-day sessions
• Using growth metrics to tune eviction policies

Architecture Diagram

sequenceDiagram
    participant CM as ContextManager
    participant EM as EvictionManager
    participant DB as Database
    participant AL as AuditLog
    participant RT as RegretTracker
    
    Note over CM,RT: Periodic Eviction Cycle
    
    CM->>EM: run_eviction_cycle(project_id, agent_id)
    EM->>DB: list_context_items(tier=COLD)
    DB-->>EM: cold_items[]
    
    EM->>EM: check_size_limits()
    alt Size limit exceeded
        EM->>EM: select_eviction_candidates()
        EM->>EM: calculate_eviction_priority()
        EM->>EM: filter_protected_items()
    end
    
    loop For each candidate
        EM->>AL: log_eviction(item, reason)
        EM->>DB: delete_context_item(item_id)
    end
    
    EM-->>CM: eviction_result{count, reason}
    
    Note over CM,RT: Context Creation with Regret Check
    
    CM->>RT: check_eviction_regret(content, type)
    RT->>DB: query recent evictions
    DB-->>RT: evicted_items[]
    RT->>RT: calculate_similarity()
    
    alt High similarity found
        RT->>DB: log_regret_event()
        RT-->>CM: regret_detected=true
    end
    
    CM->>DB: create_context_item()

Loading

Eviction Decision Flow

flowchart TD
    A[Start Eviction Cycle] --> B{Size Limit<br/>Exceeded?}
    B -->|No| C{Time-Based<br/>Eviction?}
    B -->|Yes| D[Calculate Items<br/>to Evict]
    
    C -->|Yes| E[Find Items<br/>> Max Age]
    C -->|No| F[End Cycle]
    
    D --> G[Select by Strategy]
    E --> G
    
    G --> H{Item<br/>Protected?}
    H -->|Yes| I[Skip Item]
    H -->|No| J[Check Access<br/>Threshold]
    
    J --> K{Meets<br/>Criteria?}
    K -->|Yes| L[Log Eviction]
    K -->|No| I
    
    L --> M[Delete Item]
    M --> N{More<br/>Candidates?}
    N -->|Yes| H
    N -->|No| O[Update Metrics]
    O --> F
    
    I --> N

Loading

Configuration Example

# .codeframe/config.json
{
  "context_management": {
    "enabled": true,
    "hot_tier_max_tokens": 20000,
    "warm_tier_max_tokens": 40000,
    "eviction_policy": {
      "enabled": true,
      "max_age_days": 7,
      "min_access_count": 1,
      "min_access_days": 3,
      "cold_tier_max_items": 1000,
      "cold_tier_max_tokens": 100000,
      "protected_types": ["TASK", "PRD_SECTION"],
      "strategy": "hybrid",
      "log_evictions": true,
      "track_regret": true,
      "regret_window_days": 7
    }
  }
}

Success Metrics

Track these metrics to validate eviction effectiveness:

Metric	Target	Measurement
Growth rate documented	Baseline established	SELECT * FROM context_growth_metrics over 8+ hour session
Dead context identified	< 20% of COLD tier	Items in COLD with access_count=0
COLD tier size	< 1000 items	SELECT COUNT(*) FROM context_items WHERE current_tier='cold'
Regret rate	< 5%	(regret_events / total_evictions) * 100
Avg item lifetime	3-7 days	AVG(evicted_at - created_at) from eviction log
Protected items	< 10% of COLD	Count of pinned or protected type items
Eviction latency	< 100ms	Time to execute eviction cycle
Session bloat prevention	< 50% growth/day	Growth rate from metrics table over extended sessions

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current CodeFRAME tiered memory system (HOT/WARM/COLD) implements importance-based scoring and flash save archival, but lacks explicit eviction policies for long-term system health during multi-day autonomous sessions. The COLD tier grows unbounded as items demote from WARM, and flash save only archives COLD items during token threshold events (144k/180k). No mechanisms exist for time-based expiration, size limits, eviction audit logging, or "eviction regret" tracking. The system uses exponential decay scoring (λ=0.5, ~1.4 day half-life) but doesn't enforce maximum age or access-based cleanup. Database schema supports all necessary fields (created_at, last_accessed, access_count, importance_score) but lacks eviction metadata columns.

## Approach

Implement a multi-strategy eviction system that extends the existing tiered architecture without disrupting current flash save functionality. Add configurable eviction policies (time-based, access-based, size-based) that operate independently of flash save, with audit logging and regret tracking to measure effectiveness. Introduce a new `EvictionManager` class that coordinates policies, logs decisions, and provides metrics. Extend database schema with eviction audit tables and add configuration options to `ContextManagementConfig`. This approach preserves the existing importance scoring and tier assignment logic while adding explicit lifecycle management for COLD tier items. The implementation prioritizes measuring current growth patterns first, then implements configurable eviction with protection mechanisms, and finally validates effectiveness through regret tracking.

## Implementation Steps

### 1. Measurement and Instrumentation (Phase 1)

**Create new file `file:codeframe/lib/context_growth_tracker.py`**:

Implement `ContextGrowthTracker` class to measure current patterns:
- `track_cold_tier_growth(project_id, agent_id)` - Record COLD tier size and growth rate
- `identify_dead_context(project_id, agent_id)` - Find items written but never accessed
- `get_growth_report(project_id, agent_id, days)` - Generate growth analysis report
- `calculate_tier_distribution(project_id, agent_id)` - Percentage of items in each tier
- `estimate_session_bloat(project_id, agent_id, session_hours)` - Project growth over extended sessions

Add metrics to database:
```sql
CREATE TABLE IF NOT EXISTS context_growth_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    measurement_timestamp TEXT NOT NULL,
    cold_tier_count INTEGER NOT NULL,
    cold_tier_tokens INTEGER NOT NULL,
    warm_tier_count INTEGER NOT NULL,
    hot_tier_count INTEGER NOT NULL,
    dead_context_count INTEGER NOT NULL,
    avg_item_age_days REAL NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

**Extend `codeframe/lib/context_manager.py`**:
- Add `measure_context_growth(project_id, agent_id)` method
- Call measurement after tier updates to track patterns
- Log growth metrics for analysis

### 2. Database Schema Extensions

**Extend `file:codeframe/persistence/schema_manager.py`** in the `_create_memory_context_tables()` method:

Add new table for context growth metrics (from Phase 1):
```sql
CREATE TABLE IF NOT EXISTS context_growth_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    measurement_timestamp TEXT NOT NULL,
    cold_tier_count INTEGER NOT NULL,
    cold_tier_tokens INTEGER NOT NULL,
    warm_tier_count INTEGER NOT NULL,
    hot_tier_count INTEGER NOT NULL,
    dead_context_count INTEGER NOT NULL,
    avg_item_age_days REAL NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

Add new table for eviction audit log:
```sql
CREATE TABLE IF NOT EXISTS context_eviction_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    item_type TEXT NOT NULL,
    eviction_reason TEXT NOT NULL,  -- 'time_expired', 'access_threshold', 'size_limit', 'manual'
    importance_score REAL NOT NULL,
    age_days REAL NOT NULL,
    access_count INTEGER NOT NULL,
    last_accessed TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    content_summary TEXT,  -- First 200 chars for debugging
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

Add table for eviction regret tracking:
```sql
CREATE TABLE IF NOT EXISTS context_eviction_regret (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    re_requested_at TEXT NOT NULL,
    regret_type TEXT NOT NULL,  -- 'exact_match', 'similar_content', 'same_type'
    regret_score REAL NOT NULL,  -- 0.0-1.0 similarity
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

Add indexes for performance:
```sql
CREATE INDEX IF NOT EXISTS idx_eviction_log_agent ON context_eviction_log(agent_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_log_project ON context_eviction_log(project_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_regret_item ON context_eviction_regret(item_id);
```

Add new database methods:
- `log_eviction(item_id, reason, metadata)` - Record eviction decision
- `check_eviction_regret(content, item_type, agent_id)` - Check if similar content was recently evicted
- `get_eviction_stats(project_id, agent_id, days)` - Aggregate eviction metrics
- `get_regret_rate(project_id, agent_id, days)` - Calculate regret percentage

### 3. Configuration Extensions

**Extend `file:codeframe/core/config.py`** in the `ContextManagementConfig` class:

Add eviction policy configuration:
```python
class EvictionPolicyConfig(BaseModel):
    """Eviction policy configuration for COLD tier."""
    
    enabled: bool = True
    
    # Time-based eviction
    max_age_days: int = 7  # Evict items older than 7 days
    
    # Access-based eviction
    min_access_count: int = 1  # Evict items never accessed
    min_access_days: int = 3  # Must be accessed within 3 days
    
    # Size-based eviction
    cold_tier_max_items: int = 1000  # Max items in COLD tier
    cold_tier_max_tokens: int = 100000  # Max tokens in COLD tier
    
    # Protection mechanisms
    protected_types: List[str] = ["TASK", "PRD_SECTION"]  # Never auto-evict
    manual_pin_protected: bool = True  # Respect manual_pin flag
    
    # Eviction strategy
    strategy: str = "hybrid"  # 'lru', 'importance_weighted', 'hybrid'
    
    # Audit and monitoring
    log_evictions: bool = True
    track_regret: bool = True
    regret_window_days: int = 7  # Track regret for 7 days after eviction

class ContextManagementConfig(BaseModel):
    """Virtual Project context configuration."""
    
    enabled: bool = True
    hot_tier_max_tokens: int = 20000
    warm_tier_max_tokens: int = 40000
    importance_threshold_hot: float = 0.8
    importance_threshold_warm: float = 0.4
    
    # NEW: Eviction policy
    eviction_policy: EvictionPolicyConfig = Field(default_factory=EvictionPolicyConfig)
```

### 4. Eviction Manager Implementation

**Create new file `file:codeframe/lib/eviction_manager.py`**:

Implement `EvictionManager` class with methods:
- `__init__(db, config)` - Initialize with database and config
- `should_evict_item(item)` - Evaluate if item meets eviction criteria
- `select_eviction_candidates(project_id, agent_id)` - Query COLD tier items for eviction
- `evict_items(candidates, reason)` - Execute eviction with audit logging
- `check_size_limits(project_id, agent_id)` - Enforce COLD tier size limits
- `run_eviction_cycle(project_id, agent_id)` - Main eviction workflow
- `calculate_eviction_priority(item)` - Score items for eviction (lower = evict first)
- `is_protected(item)` - Check if item is protected from eviction
- `log_eviction_decision(item, reason)` - Write to audit log
- `track_regret_if_needed(content, item_type, agent_id)` - Check for regret on new context creation

Eviction priority calculation (hybrid strategy):
```
priority = (importance_score * 0.4) + (recency_score * 0.3) + (access_score * 0.3)

where:
- recency_score = 1.0 - (age_days / max_age_days)
- access_score = min(access_count / 10, 1.0)
- Lower priority = evict first
```

### 5. Integration with Context Manager

**Extend `file:codeframe/lib/context_manager.py`**:

Add eviction manager integration:
- Import `EvictionManager` in `__init__`
- Add `run_eviction_if_needed(project_id, agent_id)` method
- Call eviction check after tier updates in `update_tiers_for_agent()`
- Add `get_eviction_stats(project_id, agent_id)` method for metrics
- Add `force_eviction(project_id, agent_id, reason)` for manual triggers
- Integrate `ContextGrowthTracker` to measure patterns during normal operation

Modify `flash_save()` to log evictions:
- Before archiving COLD items, log each as eviction with reason='flash_save'
- This provides continuity with existing behavior while adding audit trail

### 6. Eviction Strategies Implementation

**In `file:codeframe/lib/eviction_manager.py`**, implement strategy classes:

**LRUStrategy**:
- Sort by `last_accessed` ascending
- Evict oldest accessed items first
- Ignore importance scores

**ImportanceWeightedStrategy**:
- Sort by `importance_score` ascending
- Evict lowest scored items first
- Consider age as tiebreaker

**HybridStrategy** (default):
- Calculate composite priority score
- Balance importance, recency, and access patterns
- Configurable weights via config

Each strategy implements:
- `select_candidates(items, count)` - Choose items to evict
- `calculate_priority(item)` - Score for eviction order

### 7. Regret Tracking Implementation

**In `file:codeframe/lib/eviction_manager.py`**:

Add regret detection logic:
- On `create_context_item()`, check if similar content was recently evicted
- Use fuzzy matching (Levenshtein distance) for content similarity
- Log regret event if similarity > 0.8 within regret window
- Track regret types: exact_match (same content), similar_content (>0.8 similarity), same_type (same item_type)

Add regret metrics:
- `get_regret_rate(days)` - Percentage of evicted items re-requested
- `get_regret_by_strategy(days)` - Compare regret rates across strategies
- `get_high_regret_patterns()` - Identify frequently re-requested item types

### 8. API Endpoints

**Extend `file:codeframe/ui/server.py`**:

Add new endpoints:
- `GET /api/context/growth-metrics` - Current context growth analysis
- `POST /api/context/evict` - Manual eviction trigger
- `GET /api/context/eviction-stats` - Eviction metrics and regret rate
- `GET /api/context/eviction-log` - Paginated eviction audit log
- `POST /api/context/pin/{item_id}` - Pin item to prevent eviction
- `DELETE /api/context/pin/{item_id}` - Unpin item

Response models in `file:codeframe/core/models.py`:
```python
class EvictionStats(BaseModel):
    agent_id: str
    total_evictions: int
    evictions_by_reason: Dict[str, int]
    regret_rate: float
    avg_age_at_eviction: float
    protected_items_count: int

class EvictionLogEntry(BaseModel):
    id: int
    item_id: str
    eviction_reason: str
    importance_score: float
    age_days: float
    access_count: int
    evicted_at: datetime
```

### 9. Background Eviction Task

**Create new file `file:codeframe/tasks/eviction_task.py`**:

Implement periodic eviction task:
- Run every 1 hour (configurable)
- Iterate through all active agents
- Call `EvictionManager.run_eviction_cycle()` for each
- Call `ContextGrowthTracker.track_cold_tier_growth()` for measurement
- Log summary metrics
- Send WebSocket events for eviction updates

Integration with task scheduler (if exists) or standalone cron job.

### 10. Metrics and Monitoring

**Extend `file:codeframe/lib/metrics_tracker.py`**:

Add eviction metrics tracking:
- `record_eviction_event(project_id, agent_id, count, reason)` - Track eviction events
- `get_eviction_trends(project_id, days)` - Time-series eviction data
- `get_cold_tier_health(project_id, agent_id)` - Size, growth rate, eviction rate

Dashboard metrics:
- COLD tier size over time
- Eviction rate (items/day)
- Regret rate percentage
- Protected items count
- Average item lifetime in COLD tier

### 11. Testing Strategy

**Create test files**:

`file:tests/context/test_eviction_manager.py`:
- Test eviction criteria evaluation
- Test strategy selection and execution
- Test protection mechanisms
- Test size limit enforcement
- Test audit logging

`file:tests/context/test_eviction_regret.py`:
- Test regret detection on re-creation
- Test similarity matching
- Test regret rate calculation
- Test regret window expiration

`file:tests/integration/test_eviction_workflow.py`:
- Test full eviction cycle
- Test interaction with flash save
- Test background task execution
- Test API endpoints

### 12. Documentation Updates

**Update documentation files**:

`file:CLAUDE.md`:
- Add section on context growth measurement
- Document eviction policies and configuration
- Explain regret tracking
- Provide examples of manual eviction
- Include growth analysis interpretation guide

`file:PRD.md`:
- Update context management section
- Add eviction policy requirements
- Document success criteria
- Include measurement methodology

Create new documentation:
`file:docs/context-eviction-guide.md`:
- Detailed eviction policy explanation
- Configuration tuning guide
- Troubleshooting eviction issues
- Interpreting regret metrics
- Growth pattern analysis methodology

`file:docs/context-growth-analysis.md`:
- How to measure context growth over sessions
- Identifying dead context patterns
- Projecting bloat over multi-day sessions
- Using growth metrics to tune eviction policies

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CM as ContextManager
    participant EM as EvictionManager
    participant DB as Database
    participant AL as AuditLog
    participant RT as RegretTracker
    
    Note over CM,RT: Periodic Eviction Cycle
    
    CM->>EM: run_eviction_cycle(project_id, agent_id)
    EM->>DB: list_context_items(tier=COLD)
    DB-->>EM: cold_items[]
    
    EM->>EM: check_size_limits()
    alt Size limit exceeded
        EM->>EM: select_eviction_candidates()
        EM->>EM: calculate_eviction_priority()
        EM->>EM: filter_protected_items()
    end
    
    loop For each candidate
        EM->>AL: log_eviction(item, reason)
        EM->>DB: delete_context_item(item_id)
    end
    
    EM-->>CM: eviction_result{count, reason}
    
    Note over CM,RT: Context Creation with Regret Check
    
    CM->>RT: check_eviction_regret(content, type)
    RT->>DB: query recent evictions
    DB-->>RT: evicted_items[]
    RT->>RT: calculate_similarity()
    
    alt High similarity found
        RT->>DB: log_regret_event()
        RT-->>CM: regret_detected=true
    end
    
    CM->>DB: create_context_item()
```

## Eviction Decision Flow

```mermaid
flowchart TD
    A[Start Eviction Cycle] --> B{Size Limit<br/>Exceeded?}
    B -->|No| C{Time-Based<br/>Eviction?}
    B -->|Yes| D[Calculate Items<br/>to Evict]
    
    C -->|Yes| E[Find Items<br/>> Max Age]
    C -->|No| F[End Cycle]
    
    D --> G[Select by Strategy]
    E --> G
    
    G --> H{Item<br/>Protected?}
    H -->|Yes| I[Skip Item]
    H -->|No| J[Check Access<br/>Threshold]
    
    J --> K{Meets<br/>Criteria?}
    K -->|Yes| L[Log Eviction]
    K -->|No| I
    
    L --> M[Delete Item]
    M --> N{More<br/>Candidates?}
    N -->|Yes| H
    N -->|No| O[Update Metrics]
    O --> F
    
    I --> N
```

## Configuration Example

```python
# .codeframe/config.json
{
  "context_management": {
    "enabled": true,
    "hot_tier_max_tokens": 20000,
    "warm_tier_max_tokens": 40000,
    "eviction_policy": {
      "enabled": true,
      "max_age_days": 7,
      "min_access_count": 1,
      "min_access_days": 3,
      "cold_tier_max_items": 1000,
      "cold_tier_max_tokens": 100000,
      "protected_types": ["TASK", "PRD_SECTION"],
      "strategy": "hybrid",
      "log_evictions": true,
      "track_regret": true,
      "regret_window_days": 7
    }
  }
}
```

## Success Metrics

Track these metrics to validate eviction effectiveness:

| Metric | Target | Measurement |
|--------|--------|-------------|
| Growth rate documented | Baseline established | `SELECT * FROM context_growth_metrics` over 8+ hour session |
| Dead context identified | < 20% of COLD tier | Items in COLD with access_count=0 |
| COLD tier size | < 1000 items | `SELECT COUNT(*) FROM context_items WHERE current_tier='cold'` |
| Regret rate | < 5% | `(regret_events / total_evictions) * 100` |
| Avg item lifetime | 3-7 days | `AVG(evicted_at - created_at)` from eviction log |
| Protected items | < 10% of COLD | Count of pinned or protected type items |
| Eviction latency | < 100ms | Time to execute eviction cycle |
| Session bloat prevention | < 50% growth/day | Growth rate from metrics table over extended sessions |

---

Execution Information

Branch: main
Commit: 4202976

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

Warning

Something went wrong while processing your request.

Reference ID: 50a0f69e-2d16-47ce-b10c-e81a17137d57

Please try again or contact support if the issue persists, referencing this ID.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The current CodeFRAME tiered memory system (HOT/WARM/COLD) implements importance-based scoring and flash save archival, but lacks explicit eviction policies for long-term system health. The COLD tier grows unbounded as items demote from WARM, and flash save only archives COLD items during token threshold events (144k/180k). No mechanisms exist for time-based expiration, size limits, eviction audit logging, or "eviction regret" tracking. The system uses exponential decay scoring (λ=0.5, ~1.4 day half-life) but doesn't enforce maximum age or access-based cleanup. Database schema supports all necessary fields (created_at, last_accessed, access_count, importance_score) but lacks eviction metadata columns.

Approach

Implement a multi-strategy eviction system that extends the existing tiered architecture without disrupting current flash save functionality. Add configurable eviction policies (time-based, access-based, size-based) that operate independently of flash save, with audit logging and regret tracking to measure effectiveness. Introduce a new EvictionManager class that coordinates policies, logs decisions, and provides metrics. Extend database schema with eviction audit tables and add configuration options to ContextManagementConfig. This approach preserves the existing importance scoring and tier assignment logic while adding explicit lifecycle management for COLD tier items.

Implementation Steps

1. Database Schema Extensions

Extend file:codeframe/persistence/database.py in the _create_schema() method:

Add new table for eviction audit log:

CREATE TABLE IF NOT EXISTS context_eviction_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    item_type TEXT NOT NULL,
    eviction_reason TEXT NOT NULL,  -- 'time_expired', 'access_threshold', 'size_limit', 'manual'
    importance_score REAL NOT NULL,
    age_days REAL NOT NULL,
    access_count INTEGER NOT NULL,
    last_accessed TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    content_summary TEXT,  -- First 200 chars for debugging
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Add table for eviction regret tracking:

CREATE TABLE IF NOT EXISTS context_eviction_regret (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    re_requested_at TEXT NOT NULL,
    regret_type TEXT NOT NULL,  -- 'exact_match', 'similar_content', 'same_type'
    regret_score REAL NOT NULL,  -- 0.0-1.0 similarity
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Add indexes for performance:

CREATE INDEX IF NOT EXISTS idx_eviction_log_agent ON context_eviction_log(agent_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_log_project ON context_eviction_log(project_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_regret_item ON context_eviction_regret(item_id);

Add new database methods:

• log_eviction(item_id, reason, metadata) - Record eviction decision
• check_eviction_regret(content, item_type, agent_id) - Check if similar content was recently evicted
• get_eviction_stats(project_id, agent_id, days) - Aggregate eviction metrics
• get_regret_rate(project_id, agent_id, days) - Calculate regret percentage

2. Configuration Extensions

Extend file:codeframe/core/config.py in the ContextManagementConfig class:

Add eviction policy configuration:

class EvictionPolicyConfig(BaseModel):
    """Eviction policy configuration for COLD tier."""
    
    enabled: bool = True
    
    # Time-based eviction
    max_age_days: int = 7  # Evict items older than 7 days
    
    # Access-based eviction
    min_access_count: int = 1  # Evict items never accessed
    min_access_days: int = 3  # Must be accessed within 3 days
    
    # Size-based eviction
    cold_tier_max_items: int = 1000  # Max items in COLD tier
    cold_tier_max_tokens: int = 100000  # Max tokens in COLD tier
    
    # Protection mechanisms
    protected_types: List[str] = ["TASK", "PRD_SECTION"]  # Never auto-evict
    manual_pin_protected: bool = True  # Respect manual_pin flag
    
    # Eviction strategy
    strategy: str = "hybrid"  # 'lru', 'importance_weighted', 'hybrid'
    
    # Audit and monitoring
    log_evictions: bool = True
    track_regret: bool = True
    regret_window_days: int = 7  # Track regret for 7 days after eviction

class ContextManagementConfig(BaseModel):
    """Virtual Project context configuration."""
    
    enabled: bool = True
    hot_tier_max_tokens: int = 20000
    warm_tier_max_tokens: int = 40000
    importance_threshold_hot: float = 0.8
    importance_threshold_warm: float = 0.4
    
    # NEW: Eviction policy
    eviction_policy: EvictionPolicyConfig = Field(default_factory=EvictionPolicyConfig)

3. Eviction Manager Implementation

Create new file file:codeframe/lib/eviction_manager.py:

Implement EvictionManager class with methods:

• __init__(db, config) - Initialize with database and config
• should_evict_item(item) - Evaluate if item meets eviction criteria
• select_eviction_candidates(project_id, agent_id) - Query COLD tier items for eviction
• evict_items(candidates, reason) - Execute eviction with audit logging
• check_size_limits(project_id, agent_id) - Enforce COLD tier size limits
• run_eviction_cycle(project_id, agent_id) - Main eviction workflow
• calculate_eviction_priority(item) - Score items for eviction (lower = evict first)
• is_protected(item) - Check if item is protected from eviction
• log_eviction_decision(item, reason) - Write to audit log
• track_regret_if_needed(content, item_type, agent_id) - Check for regret on new context creation

Eviction priority calculation (hybrid strategy):

priority = (importance_score * 0.4) + (recency_score * 0.3) + (access_score * 0.3)

where:
- recency_score = 1.0 - (age_days / max_age_days)
- access_score = min(access_count / 10, 1.0)
- Lower priority = evict first

4. Integration with Context Manager

Extend file:codeframe/lib/context_manager.py:

Add eviction manager integration:

• Import EvictionManager in __init__
• Add run_eviction_if_needed(project_id, agent_id) method
• Call eviction check after tier updates in update_tiers_for_agent()
• Add get_eviction_stats(project_id, agent_id) method for metrics
• Add force_eviction(project_id, agent_id, reason) for manual triggers

Modify flash_save() to log evictions:

• Before archiving COLD items, log each as eviction with reason='flash_save'
• This provides continuity with existing behavior while adding audit trail

5. Eviction Strategies Implementation

In file:codeframe/lib/eviction_manager.py, implement strategy classes:

LRUStrategy:

• Sort by last_accessed ascending
• Evict oldest accessed items first
• Ignore importance scores

ImportanceWeightedStrategy:

• Sort by importance_score ascending
• Evict lowest scored items first
• Consider age as tiebreaker

HybridStrategy (default):

• Calculate composite priority score
• Balance importance, recency, and access patterns
• Configurable weights via config

Each strategy implements:

• select_candidates(items, count) - Choose items to evict
• calculate_priority(item) - Score for eviction order

6. Regret Tracking Implementation

In file:codeframe/lib/eviction_manager.py:

Add regret detection logic:

• On create_context_item(), check if similar content was recently evicted
• Use fuzzy matching (Levenshtein distance) for content similarity
• Log regret event if similarity > 0.8 within regret window
• Track regret types: exact_match (same content), similar_content (>0.8 similarity), same_type (same item_type)

Add regret metrics:

• get_regret_rate(days) - Percentage of evicted items re-requested
• get_regret_by_strategy(days) - Compare regret rates across strategies
• get_high_regret_patterns() - Identify frequently re-requested item types

7. API Endpoints

Extend file:codeframe/ui/server.py:

Add new endpoints:

• POST /api/context/evict - Manual eviction trigger
• GET /api/context/eviction-stats - Eviction metrics and regret rate
• GET /api/context/eviction-log - Paginated eviction audit log
• POST /api/context/pin/{item_id} - Pin item to prevent eviction
• DELETE /api/context/pin/{item_id} - Unpin item

Response models in file:codeframe/core/models.py:

class EvictionStats(BaseModel):
    agent_id: str
    total_evictions: int
    evictions_by_reason: Dict[str, int]
    regret_rate: float
    avg_age_at_eviction: float
    protected_items_count: int

class EvictionLogEntry(BaseModel):
    id: int
    item_id: str
    eviction_reason: str
    importance_score: float
    age_days: float
    access_count: int
    evicted_at: datetime

8. Background Eviction Task

Create new file file:codeframe/tasks/eviction_task.py:

Implement periodic eviction task:

• Run every 1 hour (configurable)
• Iterate through all active agents
• Call EvictionManager.run_eviction_cycle() for each
• Log summary metrics
• Send WebSocket events for eviction updates

Integration with task scheduler (if exists) or standalone cron job.

9. Metrics and Monitoring

Extend file:codeframe/lib/metrics_tracker.py:

Add eviction metrics tracking:

• record_eviction_event(project_id, agent_id, count, reason) - Track eviction events
• get_eviction_trends(project_id, days) - Time-series eviction data
• get_cold_tier_health(project_id, agent_id) - Size, growth rate, eviction rate

Dashboard metrics:

• COLD tier size over time
• Eviction rate (items/day)
• Regret rate percentage
• Protected items count
• Average item lifetime in COLD tier

10. Testing Strategy

Create test files:

file:tests/context/test_eviction_manager.py:

• Test eviction criteria evaluation
• Test strategy selection and execution
• Test protection mechanisms
• Test size limit enforcement
• Test audit logging

file:tests/context/test_eviction_regret.py:

• Test regret detection on re-creation
• Test similarity matching
• Test regret rate calculation
• Test regret window expiration

file:tests/integration/test_eviction_workflow.py:

• Test full eviction cycle
• Test interaction with flash save
• Test background task execution
• Test API endpoints

11. Documentation Updates

Update documentation files:

file:CLAUDE.md:

• Add section on eviction policies
• Document configuration options
• Explain regret tracking
• Provide examples of manual eviction

file:PRD.md:

• Update context management section
• Add eviction policy requirements
• Document success criteria

Create new documentation:
file:docs/context-eviction-guide.md:

• Detailed eviction policy explanation
• Configuration tuning guide
• Troubleshooting eviction issues
• Interpreting regret metrics

Architecture Diagram

sequenceDiagram
    participant CM as ContextManager
    participant EM as EvictionManager
    participant DB as Database
    participant AL as AuditLog
    participant RT as RegretTracker
    
    Note over CM,RT: Periodic Eviction Cycle
    
    CM->>EM: run_eviction_cycle(project_id, agent_id)
    EM->>DB: list_context_items(tier=COLD)
    DB-->>EM: cold_items[]
    
    EM->>EM: check_size_limits()
    alt Size limit exceeded
        EM->>EM: select_eviction_candidates()
        EM->>EM: calculate_eviction_priority()
        EM->>EM: filter_protected_items()
    end
    
    loop For each candidate
        EM->>AL: log_eviction(item, reason)
        EM->>DB: delete_context_item(item_id)
    end
    
    EM-->>CM: eviction_result{count, reason}
    
    Note over CM,RT: Context Creation with Regret Check
    
    CM->>RT: check_eviction_regret(content, type)
    RT->>DB: query recent evictions
    DB-->>RT: evicted_items[]
    RT->>RT: calculate_similarity()
    
    alt High similarity found
        RT->>DB: log_regret_event()
        RT-->>CM: regret_detected=true
    end
    
    CM->>DB: create_context_item()

Loading

Eviction Decision Flow

flowchart TD
    A[Start Eviction Cycle] --> B{Size Limit<br/>Exceeded?}
    B -->|No| C{Time-Based<br/>Eviction?}
    B -->|Yes| D[Calculate Items<br/>to Evict]
    
    C -->|Yes| E[Find Items<br/>> Max Age]
    C -->|No| F[End Cycle]
    
    D --> G[Select by Strategy]
    E --> G
    
    G --> H{Item<br/>Protected?}
    H -->|Yes| I[Skip Item]
    H -->|No| J[Check Access<br/>Threshold]
    
    J --> K{Meets<br/>Criteria?}
    K -->|Yes| L[Log Eviction]
    K -->|No| I
    
    L --> M[Delete Item]
    M --> N{More<br/>Candidates?}
    N -->|Yes| H
    N -->|No| O[Update Metrics]
    O --> F
    
    I --> N

Loading

Configuration Example

# .codeframe/config.json
{
  "context_management": {
    "enabled": true,
    "hot_tier_max_tokens": 20000,
    "warm_tier_max_tokens": 40000,
    "eviction_policy": {
      "enabled": true,
      "max_age_days": 7,
      "min_access_count": 1,
      "min_access_days": 3,
      "cold_tier_max_items": 1000,
      "cold_tier_max_tokens": 100000,
      "protected_types": ["TASK", "PRD_SECTION"],
      "strategy": "hybrid",
      "log_evictions": true,
      "track_regret": true,
      "regret_window_days": 7
    }
  }
}

Success Metrics

Track these metrics to validate eviction effectiveness:

Metric	Target	Measurement
COLD tier size	< 1000 items	SELECT COUNT(*) FROM context_items WHERE current_tier='cold'
Regret rate	< 5%	(regret_events / total_evictions) * 100
Avg item lifetime	3-7 days	AVG(evicted_at - created_at) from eviction log
Protected items	< 10% of COLD	Count of pinned or protected type items
Eviction latency	< 100ms	Time to execute eviction cycle

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current CodeFRAME tiered memory system (HOT/WARM/COLD) implements importance-based scoring and flash save archival, but lacks explicit eviction policies for long-term system health. The COLD tier grows unbounded as items demote from WARM, and flash save only archives COLD items during token threshold events (144k/180k). No mechanisms exist for time-based expiration, size limits, eviction audit logging, or "eviction regret" tracking. The system uses exponential decay scoring (λ=0.5, ~1.4 day half-life) but doesn't enforce maximum age or access-based cleanup. Database schema supports all necessary fields (created_at, last_accessed, access_count, importance_score) but lacks eviction metadata columns.

## Approach

Implement a multi-strategy eviction system that extends the existing tiered architecture without disrupting current flash save functionality. Add configurable eviction policies (time-based, access-based, size-based) that operate independently of flash save, with audit logging and regret tracking to measure effectiveness. Introduce a new `EvictionManager` class that coordinates policies, logs decisions, and provides metrics. Extend database schema with eviction audit tables and add configuration options to `ContextManagementConfig`. This approach preserves the existing importance scoring and tier assignment logic while adding explicit lifecycle management for COLD tier items.

## Implementation Steps

### 1. Database Schema Extensions

**Extend `file:codeframe/persistence/database.py`** in the `_create_schema()` method:

Add new table for eviction audit log:
```sql
CREATE TABLE IF NOT EXISTS context_eviction_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    item_type TEXT NOT NULL,
    eviction_reason TEXT NOT NULL,  -- 'time_expired', 'access_threshold', 'size_limit', 'manual'
    importance_score REAL NOT NULL,
    age_days REAL NOT NULL,
    access_count INTEGER NOT NULL,
    last_accessed TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    content_summary TEXT,  -- First 200 chars for debugging
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

Add table for eviction regret tracking:
```sql
CREATE TABLE IF NOT EXISTS context_eviction_regret (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    re_requested_at TEXT NOT NULL,
    regret_type TEXT NOT NULL,  -- 'exact_match', 'similar_content', 'same_type'
    regret_score REAL NOT NULL,  -- 0.0-1.0 similarity
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

Add indexes for performance:
```sql
CREATE INDEX IF NOT EXISTS idx_eviction_log_agent ON context_eviction_log(agent_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_log_project ON context_eviction_log(project_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_regret_item ON context_eviction_regret(item_id);
```

Add new database methods:
- `log_eviction(item_id, reason, metadata)` - Record eviction decision
- `check_eviction_regret(content, item_type, agent_id)` - Check if similar content was recently evicted
- `get_eviction_stats(project_id, agent_id, days)` - Aggregate eviction metrics
- `get_regret_rate(project_id, agent_id, days)` - Calculate regret percentage

### 2. Configuration Extensions

**Extend `file:codeframe/core/config.py`** in the `ContextManagementConfig` class:

Add eviction policy configuration:
```python
class EvictionPolicyConfig(BaseModel):
    """Eviction policy configuration for COLD tier."""
    
    enabled: bool = True
    
    # Time-based eviction
    max_age_days: int = 7  # Evict items older than 7 days
    
    # Access-based eviction
    min_access_count: int = 1  # Evict items never accessed
    min_access_days: int = 3  # Must be accessed within 3 days
    
    # Size-based eviction
    cold_tier_max_items: int = 1000  # Max items in COLD tier
    cold_tier_max_tokens: int = 100000  # Max tokens in COLD tier
    
    # Protection mechanisms
    protected_types: List[str] = ["TASK", "PRD_SECTION"]  # Never auto-evict
    manual_pin_protected: bool = True  # Respect manual_pin flag
    
    # Eviction strategy
    strategy: str = "hybrid"  # 'lru', 'importance_weighted', 'hybrid'
    
    # Audit and monitoring
    log_evictions: bool = True
    track_regret: bool = True
    regret_window_days: int = 7  # Track regret for 7 days after eviction

class ContextManagementConfig(BaseModel):
    """Virtual Project context configuration."""
    
    enabled: bool = True
    hot_tier_max_tokens: int = 20000
    warm_tier_max_tokens: int = 40000
    importance_threshold_hot: float = 0.8
    importance_threshold_warm: float = 0.4
    
    # NEW: Eviction policy
    eviction_policy: EvictionPolicyConfig = Field(default_factory=EvictionPolicyConfig)
```

### 3. Eviction Manager Implementation

**Create new file `file:codeframe/lib/eviction_manager.py`**:

Implement `EvictionManager` class with methods:
- `__init__(db, config)` - Initialize with database and config
- `should_evict_item(item)` - Evaluate if item meets eviction criteria
- `select_eviction_candidates(project_id, agent_id)` - Query COLD tier items for eviction
- `evict_items(candidates, reason)` - Execute eviction with audit logging
- `check_size_limits(project_id, agent_id)` - Enforce COLD tier size limits
- `run_eviction_cycle(project_id, agent_id)` - Main eviction workflow
- `calculate_eviction_priority(item)` - Score items for eviction (lower = evict first)
- `is_protected(item)` - Check if item is protected from eviction
- `log_eviction_decision(item, reason)` - Write to audit log
- `track_regret_if_needed(content, item_type, agent_id)` - Check for regret on new context creation

Eviction priority calculation (hybrid strategy):
```
priority = (importance_score * 0.4) + (recency_score * 0.3) + (access_score * 0.3)

where:
- recency_score = 1.0 - (age_days / max_age_days)
- access_score = min(access_count / 10, 1.0)
- Lower priority = evict first
```

### 4. Integration with Context Manager

**Extend `file:codeframe/lib/context_manager.py`**:

Add eviction manager integration:
- Import `EvictionManager` in `__init__`
- Add `run_eviction_if_needed(project_id, agent_id)` method
- Call eviction check after tier updates in `update_tiers_for_agent()`
- Add `get_eviction_stats(project_id, agent_id)` method for metrics
- Add `force_eviction(project_id, agent_id, reason)` for manual triggers

Modify `flash_save()` to log evictions:
- Before archiving COLD items, log each as eviction with reason='flash_save'
- This provides continuity with existing behavior while adding audit trail

### 5. Eviction Strategies Implementation

**In `file:codeframe/lib/eviction_manager.py`**, implement strategy classes:

**LRUStrategy**:
- Sort by `last_accessed` ascending
- Evict oldest accessed items first
- Ignore importance scores

**ImportanceWeightedStrategy**:
- Sort by `importance_score` ascending
- Evict lowest scored items first
- Consider age as tiebreaker

**HybridStrategy** (default):
- Calculate composite priority score
- Balance importance, recency, and access patterns
- Configurable weights via config

Each strategy implements:
- `select_candidates(items, count)` - Choose items to evict
- `calculate_priority(item)` - Score for eviction order

### 6. Regret Tracking Implementation

**In `file:codeframe/lib/eviction_manager.py`**:

Add regret detection logic:
- On `create_context_item()`, check if similar content was recently evicted
- Use fuzzy matching (Levenshtein distance) for content similarity
- Log regret event if similarity > 0.8 within regret window
- Track regret types: exact_match (same content), similar_content (>0.8 similarity), same_type (same item_type)

Add regret metrics:
- `get_regret_rate(days)` - Percentage of evicted items re-requested
- `get_regret_by_strategy(days)` - Compare regret rates across strategies
- `get_high_regret_patterns()` - Identify frequently re-requested item types

### 7. API Endpoints

**Extend `file:codeframe/ui/server.py`**:

Add new endpoints:
- `POST /api/context/evict` - Manual eviction trigger
- `GET /api/context/eviction-stats` - Eviction metrics and regret rate
- `GET /api/context/eviction-log` - Paginated eviction audit log
- `POST /api/context/pin/{item_id}` - Pin item to prevent eviction
- `DELETE /api/context/pin/{item_id}` - Unpin item

Response models in `file:codeframe/core/models.py`:
```python
class EvictionStats(BaseModel):
    agent_id: str
    total_evictions: int
    evictions_by_reason: Dict[str, int]
    regret_rate: float
    avg_age_at_eviction: float
    protected_items_count: int

class EvictionLogEntry(BaseModel):
    id: int
    item_id: str
    eviction_reason: str
    importance_score: float
    age_days: float
    access_count: int
    evicted_at: datetime
```

### 8. Background Eviction Task

**Create new file `file:codeframe/tasks/eviction_task.py`**:

Implement periodic eviction task:
- Run every 1 hour (configurable)
- Iterate through all active agents
- Call `EvictionManager.run_eviction_cycle()` for each
- Log summary metrics
- Send WebSocket events for eviction updates

Integration with task scheduler (if exists) or standalone cron job.

### 9. Metrics and Monitoring

**Extend `file:codeframe/lib/metrics_tracker.py`**:

Add eviction metrics tracking:
- `record_eviction_event(project_id, agent_id, count, reason)` - Track eviction events
- `get_eviction_trends(project_id, days)` - Time-series eviction data
- `get_cold_tier_health(project_id, agent_id)` - Size, growth rate, eviction rate

Dashboard metrics:
- COLD tier size over time
- Eviction rate (items/day)
- Regret rate percentage
- Protected items count
- Average item lifetime in COLD tier

### 10. Testing Strategy

**Create test files**:

`file:tests/context/test_eviction_manager.py`:
- Test eviction criteria evaluation
- Test strategy selection and execution
- Test protection mechanisms
- Test size limit enforcement
- Test audit logging

`file:tests/context/test_eviction_regret.py`:
- Test regret detection on re-creation
- Test similarity matching
- Test regret rate calculation
- Test regret window expiration

`file:tests/integration/test_eviction_workflow.py`:
- Test full eviction cycle
- Test interaction with flash save
- Test background task execution
- Test API endpoints

### 11. Documentation Updates

**Update documentation files**:

`file:CLAUDE.md`:
- Add section on eviction policies
- Document configuration options
- Explain regret tracking
- Provide examples of manual eviction

`file:PRD.md`:
- Update context management section
- Add eviction policy requirements
- Document success criteria

Create new documentation:
`file:docs/context-eviction-guide.md`:
- Detailed eviction policy explanation
- Configuration tuning guide
- Troubleshooting eviction issues
- Interpreting regret metrics

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CM as ContextManager
    participant EM as EvictionManager
    participant DB as Database
    participant AL as AuditLog
    participant RT as RegretTracker
    
    Note over CM,RT: Periodic Eviction Cycle
    
    CM->>EM: run_eviction_cycle(project_id, agent_id)
    EM->>DB: list_context_items(tier=COLD)
    DB-->>EM: cold_items[]
    
    EM->>EM: check_size_limits()
    alt Size limit exceeded
        EM->>EM: select_eviction_candidates()
        EM->>EM: calculate_eviction_priority()
        EM->>EM: filter_protected_items()
    end
    
    loop For each candidate
        EM->>AL: log_eviction(item, reason)
        EM->>DB: delete_context_item(item_id)
    end
    
    EM-->>CM: eviction_result{count, reason}
    
    Note over CM,RT: Context Creation with Regret Check
    
    CM->>RT: check_eviction_regret(content, type)
    RT->>DB: query recent evictions
    DB-->>RT: evicted_items[]
    RT->>RT: calculate_similarity()
    
    alt High similarity found
        RT->>DB: log_regret_event()
        RT-->>CM: regret_detected=true
    end
    
    CM->>DB: create_context_item()
```

## Eviction Decision Flow

```mermaid
flowchart TD
    A[Start Eviction Cycle] --> B{Size Limit<br/>Exceeded?}
    B -->|No| C{Time-Based<br/>Eviction?}
    B -->|Yes| D[Calculate Items<br/>to Evict]
    
    C -->|Yes| E[Find Items<br/>> Max Age]
    C -->|No| F[End Cycle]
    
    D --> G[Select by Strategy]
    E --> G
    
    G --> H{Item<br/>Protected?}
    H -->|Yes| I[Skip Item]
    H -->|No| J[Check Access<br/>Threshold]
    
    J --> K{Meets<br/>Criteria?}
    K -->|Yes| L[Log Eviction]
    K -->|No| I
    
    L --> M[Delete Item]
    M --> N{More<br/>Candidates?}
    N -->|Yes| H
    N -->|No| O[Update Metrics]
    O --> F
    
    I --> N
```

## Configuration Example

```python
# .codeframe/config.json
{
  "context_management": {
    "enabled": true,
    "hot_tier_max_tokens": 20000,
    "warm_tier_max_tokens": 40000,
    "eviction_policy": {
      "enabled": true,
      "max_age_days": 7,
      "min_access_count": 1,
      "min_access_days": 3,
      "cold_tier_max_items": 1000,
      "cold_tier_max_tokens": 100000,
      "protected_types": ["TASK", "PRD_SECTION"],
      "strategy": "hybrid",
      "log_evictions": true,
      "track_regret": true,
      "regret_window_days": 7
    }
  }
}
```

## Success Metrics

Track these metrics to validate eviction effectiveness:

| Metric | Target | Measurement |
|--------|--------|-------------|
| COLD tier size | < 1000 items | `SELECT COUNT(*) FROM context_items WHERE current_tier='cold'` |
| Regret rate | < 5% | `(regret_events / total_evictions) * 100` |
| Avg item lifetime | 3-7 days | `AVG(evicted_at - created_at)` from eviction log |
| Protected items | < 10% of COLD | Count of pinned or protected type items |
| Eviction latency | < 100ms | Time to execute eviction cycle |

---

Execution Information

Branch: main
Commit: 08bbb8e

New Plan

Observations

The current CodeFRAME tiered memory system (HOT/WARM/COLD) implements importance-based scoring and flash save archival, but lacks explicit eviction policies for long-term system health during multi-day autonomous sessions. The COLD tier grows unbounded as items demote from WARM, and flash save only archives COLD items during token threshold events (144k/180k). No mechanisms exist for time-based expiration, size limits, eviction audit logging, or "eviction regret" tracking. The system uses exponential decay scoring (λ=0.5, ~1.4 day half-life) but doesn't enforce maximum age or access-based cleanup. Database schema supports all necessary fields (created_at, last_accessed, access_count, importance_score) but lacks eviction metadata columns.

Approach

Implement a multi-strategy eviction system that extends the existing tiered architecture without disrupting current flash save functionality. Add configurable eviction policies (time-based, access-based, size-based) that operate independently of flash save, with audit logging and regret tracking to measure effectiveness. Introduce a new EvictionManager class that coordinates policies, logs decisions, and provides metrics. Extend database schema with eviction audit tables and add configuration options to ContextManagementConfig. This approach preserves the existing importance scoring and tier assignment logic while adding explicit lifecycle management for COLD tier items. The implementation prioritizes measuring current growth patterns first, then implements configurable eviction with protection mechanisms, and finally validates effectiveness through regret tracking.

Implementation Steps

1. Measurement and Instrumentation (Phase 1)

Create new file file:codeframe/lib/context_growth_tracker.py:

Implement ContextGrowthTracker class to measure current patterns:

• track_cold_tier_growth(project_id, agent_id) - Record COLD tier size and growth rate
• identify_dead_context(project_id, agent_id) - Find items written but never accessed
• get_growth_report(project_id, agent_id, days) - Generate growth analysis report
• calculate_tier_distribution(project_id, agent_id) - Percentage of items in each tier
• estimate_session_bloat(project_id, agent_id, session_hours) - Project growth over extended sessions

Add metrics to database:

CREATE TABLE IF NOT EXISTS context_growth_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    measurement_timestamp TEXT NOT NULL,
    cold_tier_count INTEGER NOT NULL,
    cold_tier_tokens INTEGER NOT NULL,
    warm_tier_count INTEGER NOT NULL,
    hot_tier_count INTEGER NOT NULL,
    dead_context_count INTEGER NOT NULL,
    avg_item_age_days REAL NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Extend codeframe/lib/context_manager.py:

• Add measure_context_growth(project_id, agent_id) method
• Call measurement after tier updates to track patterns
• Log growth metrics for analysis

2. Database Schema Extensions

Extend file:codeframe/persistence/schema_manager.py in the _create_memory_context_tables() method:

Add new table for context growth metrics (from Phase 1):

CREATE TABLE IF NOT EXISTS context_growth_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    measurement_timestamp TEXT NOT NULL,
    cold_tier_count INTEGER NOT NULL,
    cold_tier_tokens INTEGER NOT NULL,
    warm_tier_count INTEGER NOT NULL,
    hot_tier_count INTEGER NOT NULL,
    dead_context_count INTEGER NOT NULL,
    avg_item_age_days REAL NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Add new table for eviction audit log:

CREATE TABLE IF NOT EXISTS context_eviction_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    item_type TEXT NOT NULL,
    eviction_reason TEXT NOT NULL,  -- 'time_expired', 'access_threshold', 'size_limit', 'manual'
    importance_score REAL NOT NULL,
    age_days REAL NOT NULL,
    access_count INTEGER NOT NULL,
    last_accessed TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    content_summary TEXT,  -- First 200 chars for debugging
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Add table for eviction regret tracking:

CREATE TABLE IF NOT EXISTS context_eviction_regret (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    re_requested_at TEXT NOT NULL,
    regret_type TEXT NOT NULL,  -- 'exact_match', 'similar_content', 'same_type'
    regret_score REAL NOT NULL,  -- 0.0-1.0 similarity
    FOREIGN KEY (project_id) REFERENCES projects(id)
)

Add indexes for performance:

CREATE INDEX IF NOT EXISTS idx_eviction_log_agent ON context_eviction_log(agent_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_log_project ON context_eviction_log(project_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_regret_item ON context_eviction_regret(item_id);

Add new database methods:

• log_eviction(item_id, reason, metadata) - Record eviction decision
• check_eviction_regret(content, item_type, agent_id) - Check if similar content was recently evicted
• get_eviction_stats(project_id, agent_id, days) - Aggregate eviction metrics
• get_regret_rate(project_id, agent_id, days) - Calculate regret percentage

3. Configuration Extensions

Extend file:codeframe/core/config.py in the ContextManagementConfig class:

Add eviction policy configuration:

class EvictionPolicyConfig(BaseModel):
    """Eviction policy configuration for COLD tier."""
    
    enabled: bool = True
    
    # Time-based eviction
    max_age_days: int = 7  # Evict items older than 7 days
    
    # Access-based eviction
    min_access_count: int = 1  # Evict items never accessed
    min_access_days: int = 3  # Must be accessed within 3 days
    
    # Size-based eviction
    cold_tier_max_items: int = 1000  # Max items in COLD tier
    cold_tier_max_tokens: int = 100000  # Max tokens in COLD tier
    
    # Protection mechanisms
    protected_types: List[str] = ["TASK", "PRD_SECTION"]  # Never auto-evict
    manual_pin_protected: bool = True  # Respect manual_pin flag
    
    # Eviction strategy
    strategy: str = "hybrid"  # 'lru', 'importance_weighted', 'hybrid'
    
    # Audit and monitoring
    log_evictions: bool = True
    track_regret: bool = True
    regret_window_days: int = 7  # Track regret for 7 days after eviction

class ContextManagementConfig(BaseModel):
    """Virtual Project context configuration."""
    
    enabled: bool = True
    hot_tier_max_tokens: int = 20000
    warm_tier_max_tokens: int = 40000
    importance_threshold_hot: float = 0.8
    importance_threshold_warm: float = 0.4
    
    # NEW: Eviction policy
    eviction_policy: EvictionPolicyConfig = Field(default_factory=EvictionPolicyConfig)

4. Eviction Manager Implementation

Create new file file:codeframe/lib/eviction_manager.py:

Implement EvictionManager class with methods:

• __init__(db, config) - Initialize with database and config
• should_evict_item(item) - Evaluate if item meets eviction criteria
• select_eviction_candidates(project_id, agent_id) - Query COLD tier items for eviction
• evict_items(candidates, reason) - Execute eviction with audit logging
• check_size_limits(project_id, agent_id) - Enforce COLD tier size limits
• run_eviction_cycle(project_id, agent_id) - Main eviction workflow
• calculate_eviction_priority(item) - Score items for eviction (lower = evict first)
• is_protected(item) - Check if item is protected from eviction
• log_eviction_decision(item, reason) - Write to audit log
• track_regret_if_needed(content, item_type, agent_id) - Check for regret on new context creation

Eviction priority calculation (hybrid strategy):

priority = (importance_score * 0.4) + (recency_score * 0.3) + (access_score * 0.3)

where:
- recency_score = 1.0 - (age_days / max_age_days)
- access_score = min(access_count / 10, 1.0)
- Lower priority = evict first

5. Integration with Context Manager

Extend file:codeframe/lib/context_manager.py:

Add eviction manager integration:

• Import EvictionManager in __init__
• Add run_eviction_if_needed(project_id, agent_id) method
• Call eviction check after tier updates in update_tiers_for_agent()
• Add get_eviction_stats(project_id, agent_id) method for metrics
• Add force_eviction(project_id, agent_id, reason) for manual triggers
• Integrate ContextGrowthTracker to measure patterns during normal operation

Modify flash_save() to log evictions:

• Before archiving COLD items, log each as eviction with reason='flash_save'
• This provides continuity with existing behavior while adding audit trail

6. Eviction Strategies Implementation

In file:codeframe/lib/eviction_manager.py, implement strategy classes:

LRUStrategy:

• Sort by last_accessed ascending
• Evict oldest accessed items first
• Ignore importance scores

ImportanceWeightedStrategy:

• Sort by importance_score ascending
• Evict lowest scored items first
• Consider age as tiebreaker

HybridStrategy (default):

• Calculate composite priority score
• Balance importance, recency, and access patterns
• Configurable weights via config

Each strategy implements:

• select_candidates(items, count) - Choose items to evict
• calculate_priority(item) - Score for eviction order

7. Regret Tracking Implementation

In file:codeframe/lib/eviction_manager.py:

Add regret detection logic:

• On create_context_item(), check if similar content was recently evicted
• Use fuzzy matching (Levenshtein distance) for content similarity
• Log regret event if similarity > 0.8 within regret window
• Track regret types: exact_match (same content), similar_content (>0.8 similarity), same_type (same item_type)

Add regret metrics:

• get_regret_rate(days) - Percentage of evicted items re-requested
• get_regret_by_strategy(days) - Compare regret rates across strategies
• get_high_regret_patterns() - Identify frequently re-requested item types

8. API Endpoints

Extend file:codeframe/ui/server.py:

Add new endpoints:

• GET /api/context/growth-metrics - Current context growth analysis
• POST /api/context/evict - Manual eviction trigger
• GET /api/context/eviction-stats - Eviction metrics and regret rate
• GET /api/context/eviction-log - Paginated eviction audit log
• POST /api/context/pin/{item_id} - Pin item to prevent eviction
• DELETE /api/context/pin/{item_id} - Unpin item

Response models in file:codeframe/core/models.py:

class EvictionStats(BaseModel):
    agent_id: str
    total_evictions: int
    evictions_by_reason: Dict[str, int]
    regret_rate: float
    avg_age_at_eviction: float
    protected_items_count: int

class EvictionLogEntry(BaseModel):
    id: int
    item_id: str
    eviction_reason: str
    importance_score: float
    age_days: float
    access_count: int
    evicted_at: datetime

9. Background Eviction Task

Create new file file:codeframe/tasks/eviction_task.py:

Implement periodic eviction task:

• Run every 1 hour (configurable)
• Iterate through all active agents
• Call EvictionManager.run_eviction_cycle() for each
• Call ContextGrowthTracker.track_cold_tier_growth() for measurement
• Log summary metrics
• Send WebSocket events for eviction updates

Integration with task scheduler (if exists) or standalone cron job.

10. Metrics and Monitoring

Extend file:codeframe/lib/metrics_tracker.py:

Add eviction metrics tracking:

• record_eviction_event(project_id, agent_id, count, reason) - Track eviction events
• get_eviction_trends(project_id, days) - Time-series eviction data
• get_cold_tier_health(project_id, agent_id) - Size, growth rate, eviction rate

Dashboard metrics:

• COLD tier size over time
• Eviction rate (items/day)
• Regret rate percentage
• Protected items count
• Average item lifetime in COLD tier

11. Testing Strategy

Create test files:

file:tests/context/test_eviction_manager.py:

• Test eviction criteria evaluation
• Test strategy selection and execution
• Test protection mechanisms
• Test size limit enforcement
• Test audit logging

file:tests/context/test_eviction_regret.py:

• Test regret detection on re-creation
• Test similarity matching
• Test regret rate calculation
• Test regret window expiration

file:tests/integration/test_eviction_workflow.py:

• Test full eviction cycle
• Test interaction with flash save
• Test background task execution
• Test API endpoints

12. Documentation Updates

Update documentation files:

file:CLAUDE.md:

• Add section on context growth measurement
• Document eviction policies and configuration
• Explain regret tracking
• Provide examples of manual eviction
• Include growth analysis interpretation guide

file:PRD.md:

• Update context management section
• Add eviction policy requirements
• Document success criteria
• Include measurement methodology

Create new documentation:
file:docs/context-eviction-guide.md:

• Detailed eviction policy explanation
• Configuration tuning guide
• Troubleshooting eviction issues
• Interpreting regret metrics
• Growth pattern analysis methodology

file:docs/context-growth-analysis.md:

• How to measure context growth over sessions
• Identifying dead context patterns
• Projecting bloat over multi-day sessions
• Using growth metrics to tune eviction policies

Architecture Diagram

sequenceDiagram
    participant CM as ContextManager
    participant EM as EvictionManager
    participant DB as Database
    participant AL as AuditLog
    participant RT as RegretTracker
    
    Note over CM,RT: Periodic Eviction Cycle
    
    CM->>EM: run_eviction_cycle(project_id, agent_id)
    EM->>DB: list_context_items(tier=COLD)
    DB-->>EM: cold_items[]
    
    EM->>EM: check_size_limits()
    alt Size limit exceeded
        EM->>EM: select_eviction_candidates()
        EM->>EM: calculate_eviction_priority()
        EM->>EM: filter_protected_items()
    end
    
    loop For each candidate
        EM->>AL: log_eviction(item, reason)
        EM->>DB: delete_context_item(item_id)
    end
    
    EM-->>CM: eviction_result{count, reason}
    
    Note over CM,RT: Context Creation with Regret Check
    
    CM->>RT: check_eviction_regret(content, type)
    RT->>DB: query recent evictions
    DB-->>RT: evicted_items[]
    RT->>RT: calculate_similarity()
    
    alt High similarity found
        RT->>DB: log_regret_event()
        RT-->>CM: regret_detected=true
    end
    
    CM->>DB: create_context_item()

Loading

Eviction Decision Flow

flowchart TD
    A[Start Eviction Cycle] --> B{Size Limit<br/>Exceeded?}
    B -->|No| C{Time-Based<br/>Eviction?}
    B -->|Yes| D[Calculate Items<br/>to Evict]
    
    C -->|Yes| E[Find Items<br/>> Max Age]
    C -->|No| F[End Cycle]
    
    D --> G[Select by Strategy]
    E --> G
    
    G --> H{Item<br/>Protected?}
    H -->|Yes| I[Skip Item]
    H -->|No| J[Check Access<br/>Threshold]
    
    J --> K{Meets<br/>Criteria?}
    K -->|Yes| L[Log Eviction]
    K -->|No| I
    
    L --> M[Delete Item]
    M --> N{More<br/>Candidates?}
    N -->|Yes| H
    N -->|No| O[Update Metrics]
    O --> F
    
    I --> N

Loading

Configuration Example

# .codeframe/config.json
{
  "context_management": {
    "enabled": true,
    "hot_tier_max_tokens": 20000,
    "warm_tier_max_tokens": 40000,
    "eviction_policy": {
      "enabled": true,
      "max_age_days": 7,
      "min_access_count": 1,
      "min_access_days": 3,
      "cold_tier_max_items": 1000,
      "cold_tier_max_tokens": 100000,
      "protected_types": ["TASK", "PRD_SECTION"],
      "strategy": "hybrid",
      "log_evictions": true,
      "track_regret": true,
      "regret_window_days": 7
    }
  }
}

Success Metrics

Track these metrics to validate eviction effectiveness:

Metric	Target	Measurement
Growth rate documented	Baseline established	SELECT * FROM context_growth_metrics over 8+ hour session
Dead context identified	< 20% of COLD tier	Items in COLD with access_count=0
COLD tier size	< 1000 items	SELECT COUNT(*) FROM context_items WHERE current_tier='cold'
Regret rate	< 5%	(regret_events / total_evictions) * 100
Avg item lifetime	3-7 days	AVG(evicted_at - created_at) from eviction log
Protected items	< 10% of COLD	Count of pinned or protected type items
Eviction latency	< 100ms	Time to execute eviction cycle
Session bloat prevention	< 50% growth/day	Growth rate from metrics table over extended sessions

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current CodeFRAME tiered memory system (HOT/WARM/COLD) implements importance-based scoring and flash save archival, but lacks explicit eviction policies for long-term system health during multi-day autonomous sessions. The COLD tier grows unbounded as items demote from WARM, and flash save only archives COLD items during token threshold events (144k/180k). No mechanisms exist for time-based expiration, size limits, eviction audit logging, or "eviction regret" tracking. The system uses exponential decay scoring (λ=0.5, ~1.4 day half-life) but doesn't enforce maximum age or access-based cleanup. Database schema supports all necessary fields (created_at, last_accessed, access_count, importance_score) but lacks eviction metadata columns.

## Approach

Implement a multi-strategy eviction system that extends the existing tiered architecture without disrupting current flash save functionality. Add configurable eviction policies (time-based, access-based, size-based) that operate independently of flash save, with audit logging and regret tracking to measure effectiveness. Introduce a new `EvictionManager` class that coordinates policies, logs decisions, and provides metrics. Extend database schema with eviction audit tables and add configuration options to `ContextManagementConfig`. This approach preserves the existing importance scoring and tier assignment logic while adding explicit lifecycle management for COLD tier items. The implementation prioritizes measuring current growth patterns first, then implements configurable eviction with protection mechanisms, and finally validates effectiveness through regret tracking.

## Implementation Steps

### 1. Measurement and Instrumentation (Phase 1)

**Create new file `file:codeframe/lib/context_growth_tracker.py`**:

Implement `ContextGrowthTracker` class to measure current patterns:
- `track_cold_tier_growth(project_id, agent_id)` - Record COLD tier size and growth rate
- `identify_dead_context(project_id, agent_id)` - Find items written but never accessed
- `get_growth_report(project_id, agent_id, days)` - Generate growth analysis report
- `calculate_tier_distribution(project_id, agent_id)` - Percentage of items in each tier
- `estimate_session_bloat(project_id, agent_id, session_hours)` - Project growth over extended sessions

Add metrics to database:
```sql
CREATE TABLE IF NOT EXISTS context_growth_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    measurement_timestamp TEXT NOT NULL,
    cold_tier_count INTEGER NOT NULL,
    cold_tier_tokens INTEGER NOT NULL,
    warm_tier_count INTEGER NOT NULL,
    hot_tier_count INTEGER NOT NULL,
    dead_context_count INTEGER NOT NULL,
    avg_item_age_days REAL NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

**Extend `codeframe/lib/context_manager.py`**:
- Add `measure_context_growth(project_id, agent_id)` method
- Call measurement after tier updates to track patterns
- Log growth metrics for analysis

### 2. Database Schema Extensions

**Extend `file:codeframe/persistence/schema_manager.py`** in the `_create_memory_context_tables()` method:

Add new table for context growth metrics (from Phase 1):
```sql
CREATE TABLE IF NOT EXISTS context_growth_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    measurement_timestamp TEXT NOT NULL,
    cold_tier_count INTEGER NOT NULL,
    cold_tier_tokens INTEGER NOT NULL,
    warm_tier_count INTEGER NOT NULL,
    hot_tier_count INTEGER NOT NULL,
    dead_context_count INTEGER NOT NULL,
    avg_item_age_days REAL NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

Add new table for eviction audit log:
```sql
CREATE TABLE IF NOT EXISTS context_eviction_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    item_type TEXT NOT NULL,
    eviction_reason TEXT NOT NULL,  -- 'time_expired', 'access_threshold', 'size_limit', 'manual'
    importance_score REAL NOT NULL,
    age_days REAL NOT NULL,
    access_count INTEGER NOT NULL,
    last_accessed TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    content_summary TEXT,  -- First 200 chars for debugging
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

Add table for eviction regret tracking:
```sql
CREATE TABLE IF NOT EXISTS context_eviction_regret (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    project_id INTEGER NOT NULL,
    agent_id TEXT NOT NULL,
    evicted_at TEXT NOT NULL,
    re_requested_at TEXT NOT NULL,
    regret_type TEXT NOT NULL,  -- 'exact_match', 'similar_content', 'same_type'
    regret_score REAL NOT NULL,  -- 0.0-1.0 similarity
    FOREIGN KEY (project_id) REFERENCES projects(id)
)
```

Add indexes for performance:
```sql
CREATE INDEX IF NOT EXISTS idx_eviction_log_agent ON context_eviction_log(agent_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_log_project ON context_eviction_log(project_id, evicted_at);
CREATE INDEX IF NOT EXISTS idx_eviction_regret_item ON context_eviction_regret(item_id);
```

Add new database methods:
- `log_eviction(item_id, reason, metadata)` - Record eviction decision
- `check_eviction_regret(content, item_type, agent_id)` - Check if similar content was recently evicted
- `get_eviction_stats(project_id, agent_id, days)` - Aggregate eviction metrics
- `get_regret_rate(project_id, agent_id, days)` - Calculate regret percentage

### 3. Configuration Extensions

**Extend `file:codeframe/core/config.py`** in the `ContextManagementConfig` class:

Add eviction policy configuration:
```python
class EvictionPolicyConfig(BaseModel):
    """Eviction policy configuration for COLD tier."""
    
    enabled: bool = True
    
    # Time-based eviction
    max_age_days: int = 7  # Evict items older than 7 days
    
    # Access-based eviction
    min_access_count: int = 1  # Evict items never accessed
    min_access_days: int = 3  # Must be accessed within 3 days
    
    # Size-based eviction
    cold_tier_max_items: int = 1000  # Max items in COLD tier
    cold_tier_max_tokens: int = 100000  # Max tokens in COLD tier
    
    # Protection mechanisms
    protected_types: List[str] = ["TASK", "PRD_SECTION"]  # Never auto-evict
    manual_pin_protected: bool = True  # Respect manual_pin flag
    
    # Eviction strategy
    strategy: str = "hybrid"  # 'lru', 'importance_weighted', 'hybrid'
    
    # Audit and monitoring
    log_evictions: bool = True
    track_regret: bool = True
    regret_window_days: int = 7  # Track regret for 7 days after eviction

class ContextManagementConfig(BaseModel):
    """Virtual Project context configuration."""
    
    enabled: bool = True
    hot_tier_max_tokens: int = 20000
    warm_tier_max_tokens: int = 40000
    importance_threshold_hot: float = 0.8
    importance_threshold_warm: float = 0.4
    
    # NEW: Eviction policy
    eviction_policy: EvictionPolicyConfig = Field(default_factory=EvictionPolicyConfig)
```

### 4. Eviction Manager Implementation

**Create new file `file:codeframe/lib/eviction_manager.py`**:

Implement `EvictionManager` class with methods:
- `__init__(db, config)` - Initialize with database and config
- `should_evict_item(item)` - Evaluate if item meets eviction criteria
- `select_eviction_candidates(project_id, agent_id)` - Query COLD tier items for eviction
- `evict_items(candidates, reason)` - Execute eviction with audit logging
- `check_size_limits(project_id, agent_id)` - Enforce COLD tier size limits
- `run_eviction_cycle(project_id, agent_id)` - Main eviction workflow
- `calculate_eviction_priority(item)` - Score items for eviction (lower = evict first)
- `is_protected(item)` - Check if item is protected from eviction
- `log_eviction_decision(item, reason)` - Write to audit log
- `track_regret_if_needed(content, item_type, agent_id)` - Check for regret on new context creation

Eviction priority calculation (hybrid strategy):
```
priority = (importance_score * 0.4) + (recency_score * 0.3) + (access_score * 0.3)

where:
- recency_score = 1.0 - (age_days / max_age_days)
- access_score = min(access_count / 10, 1.0)
- Lower priority = evict first
```

### 5. Integration with Context Manager

**Extend `file:codeframe/lib/context_manager.py`**:

Add eviction manager integration:
- Import `EvictionManager` in `__init__`
- Add `run_eviction_if_needed(project_id, agent_id)` method
- Call eviction check after tier updates in `update_tiers_for_agent()`
- Add `get_eviction_stats(project_id, agent_id)` method for metrics
- Add `force_eviction(project_id, agent_id, reason)` for manual triggers
- Integrate `ContextGrowthTracker` to measure patterns during normal operation

Modify `flash_save()` to log evictions:
- Before archiving COLD items, log each as eviction with reason='flash_save'
- This provides continuity with existing behavior while adding audit trail

### 6. Eviction Strategies Implementation

**In `file:codeframe/lib/eviction_manager.py`**, implement strategy classes:

**LRUStrategy**:
- Sort by `last_accessed` ascending
- Evict oldest accessed items first
- Ignore importance scores

**ImportanceWeightedStrategy**:
- Sort by `importance_score` ascending
- Evict lowest scored items first
- Consider age as tiebreaker

**HybridStrategy** (default):
- Calculate composite priority score
- Balance importance, recency, and access patterns
- Configurable weights via config

Each strategy implements:
- `select_candidates(items, count)` - Choose items to evict
- `calculate_priority(item)` - Score for eviction order

### 7. Regret Tracking Implementation

**In `file:codeframe/lib/eviction_manager.py`**:

Add regret detection logic:
- On `create_context_item()`, check if similar content was recently evicted
- Use fuzzy matching (Levenshtein distance) for content similarity
- Log regret event if similarity > 0.8 within regret window
- Track regret types: exact_match (same content), similar_content (>0.8 similarity), same_type (same item_type)

Add regret metrics:
- `get_regret_rate(days)` - Percentage of evicted items re-requested
- `get_regret_by_strategy(days)` - Compare regret rates across strategies
- `get_high_regret_patterns()` - Identify frequently re-requested item types

### 8. API Endpoints

**Extend `file:codeframe/ui/server.py`**:

Add new endpoints:
- `GET /api/context/growth-metrics` - Current context growth analysis
- `POST /api/context/evict` - Manual eviction trigger
- `GET /api/context/eviction-stats` - Eviction metrics and regret rate
- `GET /api/context/eviction-log` - Paginated eviction audit log
- `POST /api/context/pin/{item_id}` - Pin item to prevent eviction
- `DELETE /api/context/pin/{item_id}` - Unpin item

Response models in `file:codeframe/core/models.py`:
```python
class EvictionStats(BaseModel):
    agent_id: str
    total_evictions: int
    evictions_by_reason: Dict[str, int]
    regret_rate: float
    avg_age_at_eviction: float
    protected_items_count: int

class EvictionLogEntry(BaseModel):
    id: int
    item_id: str
    eviction_reason: str
    importance_score: float
    age_days: float
    access_count: int
    evicted_at: datetime
```

### 9. Background Eviction Task

**Create new file `file:codeframe/tasks/eviction_task.py`**:

Implement periodic eviction task:
- Run every 1 hour (configurable)
- Iterate through all active agents
- Call `EvictionManager.run_eviction_cycle()` for each
- Call `ContextGrowthTracker.track_cold_tier_growth()` for measurement
- Log summary metrics
- Send WebSocket events for eviction updates

Integration with task scheduler (if exists) or standalone cron job.

### 10. Metrics and Monitoring

**Extend `file:codeframe/lib/metrics_tracker.py`**:

Add eviction metrics tracking:
- `record_eviction_event(project_id, agent_id, count, reason)` - Track eviction events
- `get_eviction_trends(project_id, days)` - Time-series eviction data
- `get_cold_tier_health(project_id, agent_id)` - Size, growth rate, eviction rate

Dashboard metrics:
- COLD tier size over time
- Eviction rate (items/day)
- Regret rate percentage
- Protected items count
- Average item lifetime in COLD tier

### 11. Testing Strategy

**Create test files**:

`file:tests/context/test_eviction_manager.py`:
- Test eviction criteria evaluation
- Test strategy selection and execution
- Test protection mechanisms
- Test size limit enforcement
- Test audit logging

`file:tests/context/test_eviction_regret.py`:
- Test regret detection on re-creation
- Test similarity matching
- Test regret rate calculation
- Test regret window expiration

`file:tests/integration/test_eviction_workflow.py`:
- Test full eviction cycle
- Test interaction with flash save
- Test background task execution
- Test API endpoints

### 12. Documentation Updates

**Update documentation files**:

`file:CLAUDE.md`:
- Add section on context growth measurement
- Document eviction policies and configuration
- Explain regret tracking
- Provide examples of manual eviction
- Include growth analysis interpretation guide

`file:PRD.md`:
- Update context management section
- Add eviction policy requirements
- Document success criteria
- Include measurement methodology

Create new documentation:
`file:docs/context-eviction-guide.md`:
- Detailed eviction policy explanation
- Configuration tuning guide
- Troubleshooting eviction issues
- Interpreting regret metrics
- Growth pattern analysis methodology

`file:docs/context-growth-analysis.md`:
- How to measure context growth over sessions
- Identifying dead context patterns
- Projecting bloat over multi-day sessions
- Using growth metrics to tune eviction policies

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CM as ContextManager
    participant EM as EvictionManager
    participant DB as Database
    participant AL as AuditLog
    participant RT as RegretTracker
    
    Note over CM,RT: Periodic Eviction Cycle
    
    CM->>EM: run_eviction_cycle(project_id, agent_id)
    EM->>DB: list_context_items(tier=COLD)
    DB-->>EM: cold_items[]
    
    EM->>EM: check_size_limits()
    alt Size limit exceeded
        EM->>EM: select_eviction_candidates()
        EM->>EM: calculate_eviction_priority()
        EM->>EM: filter_protected_items()
    end
    
    loop For each candidate
        EM->>AL: log_eviction(item, reason)
        EM->>DB: delete_context_item(item_id)
    end
    
    EM-->>CM: eviction_result{count, reason}
    
    Note over CM,RT: Context Creation with Regret Check
    
    CM->>RT: check_eviction_regret(content, type)
    RT->>DB: query recent evictions
    DB-->>RT: evicted_items[]
    RT->>RT: calculate_similarity()
    
    alt High similarity found
        RT->>DB: log_regret_event()
        RT-->>CM: regret_detected=true
    end
    
    CM->>DB: create_context_item()
```

## Eviction Decision Flow

```mermaid
flowchart TD
    A[Start Eviction Cycle] --> B{Size Limit<br/>Exceeded?}
    B -->|No| C{Time-Based<br/>Eviction?}
    B -->|Yes| D[Calculate Items<br/>to Evict]
    
    C -->|Yes| E[Find Items<br/>> Max Age]
    C -->|No| F[End Cycle]
    
    D --> G[Select by Strategy]
    E --> G
    
    G --> H{Item<br/>Protected?}
    H -->|Yes| I[Skip Item]
    H -->|No| J[Check Access<br/>Threshold]
    
    J --> K{Meets<br/>Criteria?}
    K -->|Yes| L[Log Eviction]
    K -->|No| I
    
    L --> M[Delete Item]
    M --> N{More<br/>Candidates?}
    N -->|Yes| H
    N -->|No| O[Update Metrics]
    O --> F
    
    I --> N
```

## Configuration Example

```python
# .codeframe/config.json
{
  "context_management": {
    "enabled": true,
    "hot_tier_max_tokens": 20000,
    "warm_tier_max_tokens": 40000,
    "eviction_policy": {
      "enabled": true,
      "max_age_days": 7,
      "min_access_count": 1,
      "min_access_days": 3,
      "cold_tier_max_items": 1000,
      "cold_tier_max_tokens": 100000,
      "protected_types": ["TASK", "PRD_SECTION"],
      "strategy": "hybrid",
      "log_evictions": true,
      "track_regret": true,
      "regret_window_days": 7
    }
  }
}
```

## Success Metrics

Track these metrics to validate eviction effectiveness:

| Metric | Target | Measurement |
|--------|--------|-------------|
| Growth rate documented | Baseline established | `SELECT * FROM context_growth_metrics` over 8+ hour session |
| Dead context identified | < 20% of COLD tier | Items in COLD with access_count=0 |
| COLD tier size | < 1000 items | `SELECT COUNT(*) FROM context_items WHERE current_tier='cold'` |
| Regret rate | < 5% | `(regret_events / total_evictions) * 100` |
| Avg item lifetime | 3-7 days | `AVG(evicted_at - created_at)` from eviction log |
| Protected items | < 10% of COLD | Count of pinned or protected type items |
| Eviction latency | < 100ms | Time to execute eviction cycle |
| Session bloat prevention | < 50% growth/day | Growth rate from metrics table over extended sessions |

---

Execution Information

Branch: main
Commit: 4202976