[Phase 4] Evaluate Task-Scoped Context vs. Agent-Level Context Tiers

[frankbria]

Summary

The current tiered memory system operates at the agent level, but context relevance is task-specific. Accumulating context across 10 tasks may carry irrelevant information from early tasks into later ones.

Problem Analysis

Current model (hypothesis):

• Worker agent has a context store with HOT/WARM/COLD tiers
• Context accumulates as worker handles multiple tasks in a session
• Tier promotion/demotion happens based on access patterns across all tasks

The problem:

• Task 3 involved debugging authentication. Worker loaded auth-related context into HOT tier.
• Task 10 involves building a data export feature. Auth context is still HOT (recent access).
• Worker's context window now has authentication details that are completely irrelevant to data export.

This is cross-task contamination: context that was relevant to a previous task pollutes the context for the current task.

State of the Art Comparison

From the subagent pattern:

"Each subagent gets a clean, isolated context window."

From 12-Factor Agents:

"Small focused agents, less than 100 tools, less than 20 steps."

The emphasis is on task-scoped context, not agent-scoped context.

Impact

1. Relevance dilution: Truly relevant context competes with stale context for attention
2. Token waste: Paying for context that provides no value to current task
3. Potential confusion: Model may reference old patterns/code that have since changed
4. Tier gaming: Frequently accessed across tasks ≠ relevant to current task

Proposed Solutions

Option A: Task-Scoped Tiers

Instead of agent-level tiers, maintain per-task context:

Worker
├── Project Context (shared, stable)
│   └── Architecture, patterns, conventions
├── Task 10 Context (active)
│   └── HOT/WARM/COLD specific to task 10
└── Task Archive (compressed)
    └── Summaries of tasks 1-9

At task start: fresh HOT/WARM/COLD tiers
At task end: summarize, archive, clear

Option B: Relevance Filtering

Keep agent-level tiers but filter by task relevance:

def get_context_for_task(agent_context, current_task):
    relevance_scores = compute_relevance(agent_context, current_task.description)
    return agent_context.filter(relevance > THRESHOLD)

Each LLM call gets only context scored as relevant to this task.

Option C: Hybrid Approach

• Project tier: Always included, never cleared (architecture, conventions)
• Session tier: Accumulates within session, cleared at session end
• Task tier: Fresh per task, aggressive management

Investigation Tasks

1. Measure cross-task contamination

   • Sample worker contexts at task N vs. task N+5
   • Identify context items from old tasks still in HOT tier
   • Quantify % of context that's not relevant to current task

2. Correlation analysis

   • Does task success rate decrease as workers handle more tasks?
   • Does token usage increase over session duration?
   • Do later tasks show more references to irrelevant files/code?

3. Prototype task-scoped context

   • Implement Option A or C for one worker type
   • Compare task success rate and token usage
   • Measure any downsides (lost cross-task learning?)

4. Define "project context" boundary

   • What should persist across all tasks? (Architecture docs, coding conventions)
   • What should be task-local? (File contents, error messages, intermediate results)

Success Criteria

• Quantified cross-task contamination rate
• Implemented task-scoped context management
• Measured improvement in later-task success rates
• Token usage doesn't grow linearly with tasks handled
• No regression in cross-task learning (project-level context preserved)

Trade-offs to Consider

Learning vs. Isolation: Some cross-task context is valuable ("we fixed a similar bug in task 3"). The solution should preserve this while eliminating noise.

Complexity vs. Benefit: Task-scoped tiers add complexity. Need to measure if the benefit justifies the engineering cost.

Summarization accuracy: If archiving old tasks via summarization, summary quality matters. Bad summaries = lost learning.

References

• The Rise of Subagents - Isolated context windows
• Context Engineering - Right information at right time
• CodeFRAME tiered memory architecture - existing implementation to extend

[traycerai]

Plan

Observations

The current tiered memory system (file:codeframe/lib/context_manager.py) operates at the agent level with (project_id, agent_id) scoping. Context items accumulate across multiple tasks without task-level isolation, leading to potential cross-task contamination. The context_items table lacks a task_id column, and importance scoring (file:codeframe/lib/importance_scorer.py) considers age, access frequency, and item type—but not task relevance. Worker agents (file:codeframe/agents/worker_agent.py) maintain self.current_task but don't use it for context scoping. This architecture may cause stale context from previous tasks to persist in HOT/WARM tiers, wasting tokens and diluting relevance.

Approach

This Phase 4 evaluation focuses on measuring and addressing cross-task contamination in the existing tiered memory system. The investigation is prerequisite to any implementation. If contamination is significant (>40% of HOT tier from previous tasks, or strong correlation with task failures), proceed with Option C: Hybrid Approach, which separates Project Context (architecture, conventions—always included), Session Context (accumulates within session, cleared at session end), and Task Context (fresh per task, aggressive management). This preserves cross-task learning while eliminating noise. The implementation is phased to allow rollback if metrics don't improve.

Implementation Plan

Phase 1: Investigation & Measurement (Prerequisite)

1.1 Implement contamination measurement tools

Create file:codeframe/lib/context_metrics.py:

• Implement measure_cross_task_contamination(project_id, agent_id, task_id):
  • Load all context items for agent at task start
  • Identify items created before current task started
  • Calculate % of HOT tier items from previous tasks
  • Calculate % of tokens spent on pre-task items
  • Return contamination metrics: {hot_contamination_pct, token_contamination_pct, items_from_previous_tasks, hot_tier_count, total_hot_tokens}
• Implement analyze_context_age_distribution(project_id, agent_id):
  • Group context items by creation time relative to current task
  • Return distribution: {same_task: count, previous_task: count, 2+_tasks_ago: count}
• Implement correlate_contamination_with_success(project_id, agent_type):
  • Sample 50+ multi-task sessions (10+ tasks each)
  • For each task N, measure contamination at task start
  • Correlate contamination % with task success rate (pass/fail)
  • Return correlation coefficient, p-value, and trend analysis
  • Identify threshold where contamination impacts success

1.2 Instrument worker agent for metrics collection

Modify file:codeframe/agents/worker_agent.py:

• Add _record_context_metrics(task) call at task start:
  • Call measure_cross_task_contamination() before any context loading
  • Store metrics in context_metrics table (new)
  • Log: logger.info(f"Task {task.id}: {hot_contamination_pct}% HOT tier from previous tasks")
• Add _analyze_context_effectiveness(task) call at task completion:
  • Track which context items were referenced in LLM calls
  • Identify unused items that consumed tokens
  • Calculate "context utilization rate" (used items / total items)
  • Store in database for post-session analysis

1.3 Create measurement dashboard

Extend file:web-ui/src/components/context/ContextPanel.tsx:

• Add "Contamination Analysis" tab showing:
  • Cross-task contamination % over session duration (line chart)
  • Token waste trend (tokens on irrelevant context vs. relevant)
  • Context age distribution (pie chart: same task vs. previous tasks vs. 2+ tasks ago)
  • Correlation scatter plot: contamination % vs. task success rate
  • Summary stats: avg contamination, max contamination, correlation coefficient
• Add real-time updates via WebSocket for active sessions

1.4 Run investigation on production data

• Collect metrics from 50+ multi-task sessions (10+ tasks each)
• Measure baseline contamination rate (mean, median, std dev)
• Identify correlation between contamination and task failures
• Analyze by agent type (backend, frontend, test)
• Document findings in file:CONTEXT_INVESTIGATION_RESULTS.md

Success criteria for Phase 1:

• Contamination measurement tools implemented and tested
• Metrics collected from 50+ sessions
• Correlation analysis completed with statistical significance
• Decision gate: If contamination < 20% AND no correlation (r < 0.2) with failures → STOP (problem not significant)
• Decision gate: If contamination > 40% OR strong correlation (r > 0.3) with failures → PROCEED to Phase 2

Phase 2: Database Schema Changes (Conditional on Phase 1 Results)

2.1 Add task_id column to context_items table

Create migration file:codeframe/persistence/migrations/migration_007_add_task_scoped_context.py:

• Add task_id INTEGER NULL column to context_items table with foreign key to tasks(id) ON DELETE CASCADE
• Add context_scope TEXT NOT NULL DEFAULT 'session' column with CHECK constraint for values: 'project', 'session', 'task'
• Add context_metrics table to store contamination measurements:
  • id INTEGER PRIMARY KEY
  • agent_id INTEGER NOT NULL
  • task_id INTEGER NOT NULL
  • hot_contamination_pct REAL
  • token_contamination_pct REAL
  • items_from_previous_tasks INTEGER
  • hot_tier_count INTEGER
  • total_hot_tokens INTEGER
  • context_utilization_rate REAL
  • task_success BOOLEAN
  • created_at TIMESTAMP
• Create composite index idx_context_agent_task_tier on (agent_id, task_id, current_tier) for fast task-scoped queries
• Create index idx_context_scope_tier on (context_scope, current_tier) for scope-based filtering
• Create index idx_metrics_agent_task on (agent_id, task_id) for metrics queries
• Backfill existing records: set context_scope='session' and task_id=NULL for all existing context items

2.2 Update Database class methods

Modify file:codeframe/persistence/database.py:

• Update create_context_item() to accept optional task_id and context_scope parameters
• Update list_context_items() to support filtering by task_id and context_scope
• Add record_context_metrics(agent_id, task_id, metrics_dict) method to store contamination measurements
• Add get_context_metrics(project_id, agent_id) method to retrieve metrics for analysis
• Add clear_task_context(project_id, agent_id, task_id) method to delete task-scoped items
• Add archive_task_context(project_id, agent_id, task_id) method to summarize and archive task context
• Update archive_cold_items() to respect context scope (don't archive project-scoped items)

2.3 Define context scope rules

Create file:codeframe/core/context_scopes.py:

• Define item type to default scope mapping (e.g., PRD_SECTION → PROJECT, TASK_DESCRIPTION → TASK, CODE_SNIPPET → TASK, ERROR_LOG → TASK)
• Define scope lifecycle: PROJECT (never cleared), SESSION (cleared at session end), TASK (cleared at task end)

Phase 3: Relevance Filtering (Conditional on Phase 1 Results)

3.1 Implement relevance scoring

Create file:codeframe/lib/relevance_scorer.py:

• Implement calculate_relevance_score(context_item, current_task) function:
  • Use semantic similarity between context content and task description (cosine similarity of embeddings)
  • Consider item type relevance (CODE items more relevant if task involves same files)
  • Consider temporal proximity (items from recent tasks more relevant)
  • Return score in range [0.0, 1.0]
  • Cache scores per task to avoid recalculation
• Define relevance threshold: RELEVANCE_THRESHOLD = 0.3 (configurable, tuned from Phase 1 data)
• Implement batch_calculate_relevance(context_items, task) for efficient bulk scoring

3.2 Integrate relevance filtering into context manager

Extend file:codeframe/lib/context_manager.py:

• Add load_relevant_session_context(project_id, agent_id, task) method:
  • Load all session-scoped items for agent
  • Calculate relevance score for each item relative to current task
  • Filter items with relevance_score >= RELEVANCE_THRESHOLD
  • Return filtered list ordered by importance_score * relevance_score
  • Log filtering results: logger.info(f"Filtered {total} items to {filtered} relevant items for task {task.id}")
• Update ContextManager to cache relevance scores per task (invalidate on task change)
• Add get_context_filtering_stats(task) to report filtering effectiveness

3.3 Implement context summarization

Create file:codeframe/lib/context_summarizer.py:

• Implement summarize_task_context(context_items, task) function:
  • Extract task-specific learnings (bugs fixed, patterns discovered, files modified)
  • Identify reusable patterns for future tasks
  • Compress to 20% of original token count
  • Return summary for session context
  • Track summary quality metrics (compression ratio, key learning count)
• Implement summarize_session_context(context_items) function:
  • Group items by type and relevance
  • Extract key patterns and learnings across all tasks
  • Compress to 20% of original token count
  • Return summary as single context item (scope=SESSION)

Phase 4: Task Lifecycle Integration (Conditional on Phase 1 Results)

4.1 Add task context initialization

Modify file:codeframe/agents/worker_agent.py:

• Update execute_task(task) method:
  • Call _initialize_task_context(task) at task start
  • Record baseline contamination metrics
  • Load project-scoped context (always included)
  • Load session-scoped context filtered by task relevance
  • Create initial task-scoped context item with task description
• Add _initialize_task_context(task) method:
  • Save task description as TASK_DESCRIPTION type with context_scope='task' and task_id=task.id
  • Load project context (scope=PROJECT, tier=HOT)
  • Load relevant session context (scope=SESSION, relevance_score > threshold)
  • Log context composition: logger.info(f"Task {task.id}: {project_items} project, {session_items} session, {task_items} task items")

4.2 Add task context cleanup

Modify file:codeframe/agents/worker_agent.py:

• Update complete_task(task, project_root) method:
  • Call _cleanup_task_context(task) after quality gates pass
  • Record final contamination metrics (for comparison with baseline)
  • Archive task summary to session context
  • Clear task-scoped items
• Add _cleanup_task_context(task) method:
  • Generate task summary (key learnings, patterns discovered, files modified, bugs fixed)
  • Save summary as session-scoped context item with context_scope='session'
  • Delete all task-scoped items for this task
  • Update session context importance scores
  • Log cleanup: logger.info(f"Task {task.id}: Archived summary, deleted {deleted_count} task items")

4.3 Add session-level context cleanup

Modify file:codeframe/core/session_manager.py:

• Add clear_session_context(project_id, agent_id) method:
  • Archive session summary (completed tasks, key learnings, patterns, metrics)
  • Delete all session-scoped context items
  • Retain project-scoped items
  • Store session summary in session_summaries table for future reference
• Update save_session(state) to include session context summary and metrics
• Update load_session() to restore session context from summary

Phase 5: Context Assembly for LLM Calls (Conditional on Phase 1 Results)

5.1 Implement scope-aware context loading

Modify file:codeframe/agents/worker_agent.py:

• Update load_context(tier) method to become load_context_for_task(task, tier):
  • Load project-scoped context (all tiers, always included)
  • Load session-scoped context filtered by relevance to task
  • Load task-scoped context (all tiers, specific to current task)
  • Combine and deduplicate by content hash
  • Order by: scope priority (project > session > task), then importance score
  • Log context composition: logger.info(f"Loaded {project_count} project, {session_count} session, {task_count} task items")
• Add _build_llm_context(task) helper method:
  • Assemble context from all three scopes
  • Apply token budget allocation: 30% project, 30% session, 40% task
  • Truncate if exceeds budget, prioritizing higher importance scores
  • Track token allocation by scope for metrics

Phase 6: Configuration & Tuning (Conditional on Phase 1 Results)

6.1 Add configuration parameters

Create file:codeframe/config/context_config.py:

• Define RELEVANCE_THRESHOLD = 0.3 (adjustable per deployment, tuned from Phase 1 data)
• Define TOKEN_BUDGET_ALLOCATION = {'project': 0.3, 'session': 0.3, 'task': 0.4}
• Define TASK_SUMMARY_COMPRESSION_RATIO = 0.2 (target 20% of original size)
• Define SESSION_CONTEXT_MAX_AGE_DAYS = 7 (auto-archive old session items)
• Define CONTAMINATION_THRESHOLD = 0.4 (trigger for task-scoped context enablement)
• Define CORRELATION_THRESHOLD = 0.3 (correlation coefficient for significance)

6.2 Add tuning utilities

Create file:codeframe/lib/context_tuner.py:

• Implement optimize_relevance_threshold(project_id):
  • Analyze historical task success rates vs. relevance thresholds
  • Recommend optimal threshold for project
  • Return recommendation with confidence interval
• Implement analyze_scope_distribution(project_id, agent_id):
  • Report token distribution across scopes
  • Identify scope imbalances
  • Suggest rebalancing if needed
• Implement generate_tuning_report(project_id):
  • Comprehensive analysis of context effectiveness
  • Recommendations for threshold adjustments
  • Comparison of baseline vs. optimized metrics

Phase 7: Testing Strategy (Conditional on Phase 1 Results)

7.1 Unit tests

Create file:tests/context/test_task_scoped_context.py:

• Test task context initialization and cleanup
• Test scope-aware tier assignment
• Test context summarization
• Test contamination metrics recording

Create file:tests/context/test_relevance_filtering.py:

• Test relevance score calculation
• Test threshold filtering
• Test session context filtering by task
• Test batch relevance scoring

Create file:tests/context/test_context_metrics.py:

• Test contamination measurement functions
• Test correlation analysis
• Test metrics storage and retrieval

7.2 Integration tests

Create file:tests/integration/test_multi_task_context.py:

• Test context isolation across 10 sequential tasks
• Verify Task 10 doesn't have Task 3 context in HOT tier
• Measure token reduction vs. baseline
• Verify task success rate maintained
• Verify cross-task learning preserved (project context available)

Create file:tests/integration/test_contamination_measurement.py:

• Test contamination metrics collection across multi-task session
• Verify metrics stored correctly in database
• Test correlation analysis on sample data

7.3 Performance tests

Create file:tests/performance/test_context_loading.py:

• Benchmark context loading with 1000+ items across scopes
• Verify relevance filtering completes in <100ms
• Measure memory overhead of scope separation
• Benchmark contamination measurement (<50ms per task)

Phase 8: Rollout & Monitoring (Conditional on Phase 1 Results)

8.1 Backward compatibility

• Existing context items default to context_scope='session' and task_id=NULL
• Agents without task assignment continue using session-scoped context
• Gradual migration: enable task-scoped context per agent type (backend → frontend → test)
• Feature flag: ENABLE_TASK_SCOPED_CONTEXT (default: false, enabled after Phase 1 decision)

8.2 Rollout phases

1. Phase 1 (Investigation): Measure contamination, collect data, make go/no-go decision
2. Phase 2 (Pilot): If go decision, deploy schema changes and enable for backend workers only
3. Phase 3 (Validation): Measure contamination reduction and token savings on backend workers
4. Phase 4 (Rollout): Enable for all worker types if metrics positive (contamination reduced >50%, no success rate regression)
5. Phase 5 (Deprecation): Deprecate pure session-scoped context (all items must have scope)

8.3 Rollback plan

• If task success rate drops >5%, disable task-scoped context via feature flag
• Revert to session-scoped context by setting all context_scope='session'
• Investigate relevance threshold tuning before re-enabling
• Preserve metrics data for post-mortem analysis

8.4 Monitoring & Alerting

• Dashboard metric: Cross-task contamination % (alert if > 50%)
• Dashboard metric: Task success rate (alert if drops > 5%)
• Dashboard metric: Token usage per task (alert if increases > 20%)
• Dashboard metric: Context utilization rate (alert if < 50%)
• Weekly report: Contamination trends, correlation analysis, recommendations

Decision Gate: Phase 1 Results

PROCEED to Phase 2-8 if:

• Cross-task contamination > 40% (significant noise in context)
• OR strong correlation (r > 0.3, p < 0.05) between contamination and task failures
• OR token waste > 30% (paying for irrelevant context)

STOP if:

• Cross-task contamination < 20% (acceptable noise level)
• AND no correlation with task failures (r < 0.2 or p > 0.05)
• AND token waste < 10% (acceptable overhead)

In the STOP case, document findings in file:CONTEXT_INVESTIGATION_RESULTS.md and monitor for future degradation.

Success Criteria (Post-Phase 1 Decision)

If proceeding to implementation:

Metric	Baseline	Target	Measurement
Cross-task contamination	Measured in Phase 1	<10%	% of HOT tier items from previous tasks
Token usage per task	Measured in Phase 1	Stable or -20%	Average tokens/task across 10-task session
Task success rate	Measured in Phase 1	≥ baseline	Maintain quality with reduced context
Context loading time	<50ms	<100ms	Scope-aware loading overhead
Token reduction	Measured in Phase 1	30-50%	Compare session vs. task-scoped context
Context utilization rate	Measured in Phase 1	>70%	% of loaded context actually used
Correlation (contamination vs. success)	Measured in Phase 1	<0.2	Reduce correlation to near-zero

Architecture Diagram (Post-Implementation)

graph TD
    A[Worker Agent] -->|Task Start| B[Initialize Task Context]
    B --> C[Record Baseline Metrics]
    C --> D[Load Project Context]
    B --> E[Load Relevant Session Context]
    B --> F[Create Task Context Item]
    
    D --> G[Context Assembly]
    E --> G
    F --> G
    
    G --> H[LLM Call with Scoped Context]
    
    H -->|Task Complete| I[Record Final Metrics]
    I --> J[Cleanup Task Context]
    J --> K[Generate Task Summary]
    K --> L[Save to Session Context]
    J --> M[Delete Task-Scoped Items]
    
    N[Session End] --> O[Archive Session Context]
    O --> P[Generate Session Summary]
    P --> Q[Clear Session Items]
    
    R[Project Context] -.->|Always Included| G
    S[Session Context] -.->|Relevance Filtered| G
    T[Task Context] -.->|Full Inclusion| G
    
    U[Metrics Dashboard] -.->|Real-time Updates| C
    U -.->|Real-time Updates| I
    
    style R fill:#90EE90
    style S fill:#FFD700
    style T fill:#FF6B6B
    style U fill:#87CEEB

Loading

Phase 4 Evaluation Scope

This Phase 4 ticket focuses exclusively on investigation and measurement (Phase 1 of the implementation plan). The decision to proceed with Phases 2-8 depends entirely on Phase 1 results. The investigation will:

1. Quantify cross-task contamination in the current system
2. Measure correlation between contamination and task failures
3. Identify token waste from irrelevant context
4. Provide data-driven decision gate for implementation

If Phase 1 results show contamination is not significant (< 20%) and no correlation with failures, the investigation concludes and no further implementation is needed. If contamination is significant, a follow-up ticket will be created for Phases 2-8 implementation.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current tiered memory system (`file:codeframe/lib/context_manager.py`) operates at the agent level with `(project_id, agent_id)` scoping. Context items accumulate across multiple tasks without task-level isolation, leading to potential cross-task contamination. The `context_items` table lacks a `task_id` column, and importance scoring (`file:codeframe/lib/importance_scorer.py`) considers age, access frequency, and item type—but not task relevance. Worker agents (`file:codeframe/agents/worker_agent.py`) maintain `self.current_task` but don't use it for context scoping. This architecture may cause stale context from previous tasks to persist in HOT/WARM tiers, wasting tokens and diluting relevance.

## Approach

This Phase 4 evaluation focuses on measuring and addressing cross-task contamination in the existing tiered memory system. The investigation is prerequisite to any implementation. If contamination is significant (>40% of HOT tier from previous tasks, or strong correlation with task failures), proceed with **Option C: Hybrid Approach**, which separates **Project Context** (architecture, conventions—always included), **Session Context** (accumulates within session, cleared at session end), and **Task Context** (fresh per task, aggressive management). This preserves cross-task learning while eliminating noise. The implementation is phased to allow rollback if metrics don't improve.

## Implementation Plan

### Phase 1: Investigation & Measurement (Prerequisite)

**1.1 Implement contamination measurement tools**

Create `file:codeframe/lib/context_metrics.py`:
- Implement `measure_cross_task_contamination(project_id, agent_id, task_id)`:
  - Load all context items for agent at task start
  - Identify items created before current task started
  - Calculate % of HOT tier items from previous tasks
  - Calculate % of tokens spent on pre-task items
  - Return contamination metrics: `{hot_contamination_pct, token_contamination_pct, items_from_previous_tasks, hot_tier_count, total_hot_tokens}`
- Implement `analyze_context_age_distribution(project_id, agent_id)`:
  - Group context items by creation time relative to current task
  - Return distribution: `{same_task: count, previous_task: count, 2+_tasks_ago: count}`
- Implement `correlate_contamination_with_success(project_id, agent_type)`:
  - Sample 50+ multi-task sessions (10+ tasks each)
  - For each task N, measure contamination at task start
  - Correlate contamination % with task success rate (pass/fail)
  - Return correlation coefficient, p-value, and trend analysis
  - Identify threshold where contamination impacts success

**1.2 Instrument worker agent for metrics collection**

Modify `file:codeframe/agents/worker_agent.py`:
- Add `_record_context_metrics(task)` call at task start:
  - Call `measure_cross_task_contamination()` before any context loading
  - Store metrics in `context_metrics` table (new)
  - Log: `logger.info(f"Task {task.id}: {hot_contamination_pct}% HOT tier from previous tasks")`
- Add `_analyze_context_effectiveness(task)` call at task completion:
  - Track which context items were referenced in LLM calls
  - Identify unused items that consumed tokens
  - Calculate "context utilization rate" (used items / total items)
  - Store in database for post-session analysis

**1.3 Create measurement dashboard**

Extend `file:web-ui/src/components/context/ContextPanel.tsx`:
- Add "Contamination Analysis" tab showing:
  - Cross-task contamination % over session duration (line chart)
  - Token waste trend (tokens on irrelevant context vs. relevant)
  - Context age distribution (pie chart: same task vs. previous tasks vs. 2+ tasks ago)
  - Correlation scatter plot: contamination % vs. task success rate
  - Summary stats: avg contamination, max contamination, correlation coefficient
- Add real-time updates via WebSocket for active sessions

**1.4 Run investigation on production data**

- Collect metrics from 50+ multi-task sessions (10+ tasks each)
- Measure baseline contamination rate (mean, median, std dev)
- Identify correlation between contamination and task failures
- Analyze by agent type (backend, frontend, test)
- Document findings in `file:CONTEXT_INVESTIGATION_RESULTS.md`

**Success criteria for Phase 1:**
- [ ] Contamination measurement tools implemented and tested
- [ ] Metrics collected from 50+ sessions
- [ ] Correlation analysis completed with statistical significance
- [ ] Decision gate: If contamination < 20% AND no correlation (r < 0.2) with failures → STOP (problem not significant)
- [ ] Decision gate: If contamination > 40% OR strong correlation (r > 0.3) with failures → PROCEED to Phase 2

### Phase 2: Database Schema Changes (Conditional on Phase 1 Results)

**2.1 Add task_id column to context_items table**

Create migration `file:codeframe/persistence/migrations/migration_007_add_task_scoped_context.py`:
- Add `task_id INTEGER NULL` column to `context_items` table with foreign key to `tasks(id)` ON DELETE CASCADE
- Add `context_scope TEXT NOT NULL DEFAULT 'session'` column with CHECK constraint for values: `'project'`, `'session'`, `'task'`
- Add `context_metrics` table to store contamination measurements:
  - `id INTEGER PRIMARY KEY`
  - `agent_id INTEGER NOT NULL`
  - `task_id INTEGER NOT NULL`
  - `hot_contamination_pct REAL`
  - `token_contamination_pct REAL`
  - `items_from_previous_tasks INTEGER`
  - `hot_tier_count INTEGER`
  - `total_hot_tokens INTEGER`
  - `context_utilization_rate REAL`
  - `task_success BOOLEAN`
  - `created_at TIMESTAMP`
- Create composite index `idx_context_agent_task_tier` on `(agent_id, task_id, current_tier)` for fast task-scoped queries
- Create index `idx_context_scope_tier` on `(context_scope, current_tier)` for scope-based filtering
- Create index `idx_metrics_agent_task` on `(agent_id, task_id)` for metrics queries
- Backfill existing records: set `context_scope='session'` and `task_id=NULL` for all existing context items

**2.2 Update Database class methods**

Modify `file:codeframe/persistence/database.py`:
- Update `create_context_item()` to accept optional `task_id` and `context_scope` parameters
- Update `list_context_items()` to support filtering by `task_id` and `context_scope`
- Add `record_context_metrics(agent_id, task_id, metrics_dict)` method to store contamination measurements
- Add `get_context_metrics(project_id, agent_id)` method to retrieve metrics for analysis
- Add `clear_task_context(project_id, agent_id, task_id)` method to delete task-scoped items
- Add `archive_task_context(project_id, agent_id, task_id)` method to summarize and archive task context
- Update `archive_cold_items()` to respect context scope (don't archive project-scoped items)

**2.3 Define context scope rules**

Create `file:codeframe/core/context_scopes.py`:
- Define item type to default scope mapping (e.g., `PRD_SECTION` → `PROJECT`, `TASK_DESCRIPTION` → `TASK`, `CODE_SNIPPET` → `TASK`, `ERROR_LOG` → `TASK`)
- Define scope lifecycle: PROJECT (never cleared), SESSION (cleared at session end), TASK (cleared at task end)

### Phase 3: Relevance Filtering (Conditional on Phase 1 Results)

**3.1 Implement relevance scoring**

Create `file:codeframe/lib/relevance_scorer.py`:
- Implement `calculate_relevance_score(context_item, current_task)` function:
  - Use semantic similarity between context content and task description (cosine similarity of embeddings)
  - Consider item type relevance (CODE items more relevant if task involves same files)
  - Consider temporal proximity (items from recent tasks more relevant)
  - Return score in range [0.0, 1.0]
  - Cache scores per task to avoid recalculation
- Define relevance threshold: `RELEVANCE_THRESHOLD = 0.3` (configurable, tuned from Phase 1 data)
- Implement `batch_calculate_relevance(context_items, task)` for efficient bulk scoring

**3.2 Integrate relevance filtering into context manager**

Extend `file:codeframe/lib/context_manager.py`:
- Add `load_relevant_session_context(project_id, agent_id, task)` method:
  - Load all session-scoped items for agent
  - Calculate relevance score for each item relative to current task
  - Filter items with `relevance_score >= RELEVANCE_THRESHOLD`
  - Return filtered list ordered by `importance_score * relevance_score`
  - Log filtering results: `logger.info(f"Filtered {total} items to {filtered} relevant items for task {task.id}")`
- Update `ContextManager` to cache relevance scores per task (invalidate on task change)
- Add `get_context_filtering_stats(task)` to report filtering effectiveness

**3.3 Implement context summarization**

Create `file:codeframe/lib/context_summarizer.py`:
- Implement `summarize_task_context(context_items, task)` function:
  - Extract task-specific learnings (bugs fixed, patterns discovered, files modified)
  - Identify reusable patterns for future tasks
  - Compress to 20% of original token count
  - Return summary for session context
  - Track summary quality metrics (compression ratio, key learning count)
- Implement `summarize_session_context(context_items)` function:
  - Group items by type and relevance
  - Extract key patterns and learnings across all tasks
  - Compress to 20% of original token count
  - Return summary as single context item (scope=SESSION)

### Phase 4: Task Lifecycle Integration (Conditional on Phase 1 Results)

**4.1 Add task context initialization**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `execute_task(task)` method:
  - Call `_initialize_task_context(task)` at task start
  - Record baseline contamination metrics
  - Load project-scoped context (always included)
  - Load session-scoped context filtered by task relevance
  - Create initial task-scoped context item with task description
- Add `_initialize_task_context(task)` method:
  - Save task description as `TASK_DESCRIPTION` type with `context_scope='task'` and `task_id=task.id`
  - Load project context (scope=PROJECT, tier=HOT)
  - Load relevant session context (scope=SESSION, relevance_score > threshold)
  - Log context composition: `logger.info(f"Task {task.id}: {project_items} project, {session_items} session, {task_items} task items")`

**4.2 Add task context cleanup**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `complete_task(task, project_root)` method:
  - Call `_cleanup_task_context(task)` after quality gates pass
  - Record final contamination metrics (for comparison with baseline)
  - Archive task summary to session context
  - Clear task-scoped items
- Add `_cleanup_task_context(task)` method:
  - Generate task summary (key learnings, patterns discovered, files modified, bugs fixed)
  - Save summary as session-scoped context item with `context_scope='session'`
  - Delete all task-scoped items for this task
  - Update session context importance scores
  - Log cleanup: `logger.info(f"Task {task.id}: Archived summary, deleted {deleted_count} task items")`

**4.3 Add session-level context cleanup**

Modify `file:codeframe/core/session_manager.py`:
- Add `clear_session_context(project_id, agent_id)` method:
  - Archive session summary (completed tasks, key learnings, patterns, metrics)
  - Delete all session-scoped context items
  - Retain project-scoped items
  - Store session summary in `session_summaries` table for future reference
- Update `save_session(state)` to include session context summary and metrics
- Update `load_session()` to restore session context from summary

### Phase 5: Context Assembly for LLM Calls (Conditional on Phase 1 Results)

**5.1 Implement scope-aware context loading**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `load_context(tier)` method to become `load_context_for_task(task, tier)`:
  - Load project-scoped context (all tiers, always included)
  - Load session-scoped context filtered by relevance to task
  - Load task-scoped context (all tiers, specific to current task)
  - Combine and deduplicate by content hash
  - Order by: scope priority (project > session > task), then importance score
  - Log context composition: `logger.info(f"Loaded {project_count} project, {session_count} session, {task_count} task items")`
- Add `_build_llm_context(task)` helper method:
  - Assemble context from all three scopes
  - Apply token budget allocation: 30% project, 30% session, 40% task
  - Truncate if exceeds budget, prioritizing higher importance scores
  - Track token allocation by scope for metrics

### Phase 6: Configuration & Tuning (Conditional on Phase 1 Results)

**6.1 Add configuration parameters**

Create `file:codeframe/config/context_config.py`:
- Define `RELEVANCE_THRESHOLD = 0.3` (adjustable per deployment, tuned from Phase 1 data)
- Define `TOKEN_BUDGET_ALLOCATION = {'project': 0.3, 'session': 0.3, 'task': 0.4}`
- Define `TASK_SUMMARY_COMPRESSION_RATIO = 0.2` (target 20% of original size)
- Define `SESSION_CONTEXT_MAX_AGE_DAYS = 7` (auto-archive old session items)
- Define `CONTAMINATION_THRESHOLD = 0.4` (trigger for task-scoped context enablement)
- Define `CORRELATION_THRESHOLD = 0.3` (correlation coefficient for significance)

**6.2 Add tuning utilities**

Create `file:codeframe/lib/context_tuner.py`:
- Implement `optimize_relevance_threshold(project_id)`:
  - Analyze historical task success rates vs. relevance thresholds
  - Recommend optimal threshold for project
  - Return recommendation with confidence interval
- Implement `analyze_scope_distribution(project_id, agent_id)`:
  - Report token distribution across scopes
  - Identify scope imbalances
  - Suggest rebalancing if needed
- Implement `generate_tuning_report(project_id)`:
  - Comprehensive analysis of context effectiveness
  - Recommendations for threshold adjustments
  - Comparison of baseline vs. optimized metrics

### Phase 7: Testing Strategy (Conditional on Phase 1 Results)

**7.1 Unit tests**

Create `file:tests/context/test_task_scoped_context.py`:
- Test task context initialization and cleanup
- Test scope-aware tier assignment
- Test context summarization
- Test contamination metrics recording

Create `file:tests/context/test_relevance_filtering.py`:
- Test relevance score calculation
- Test threshold filtering
- Test session context filtering by task
- Test batch relevance scoring

Create `file:tests/context/test_context_metrics.py`:
- Test contamination measurement functions
- Test correlation analysis
- Test metrics storage and retrieval

**7.2 Integration tests**

Create `file:tests/integration/test_multi_task_context.py`:
- Test context isolation across 10 sequential tasks
- Verify Task 10 doesn't have Task 3 context in HOT tier
- Measure token reduction vs. baseline
- Verify task success rate maintained
- Verify cross-task learning preserved (project context available)

Create `file:tests/integration/test_contamination_measurement.py`:
- Test contamination metrics collection across multi-task session
- Verify metrics stored correctly in database
- Test correlation analysis on sample data

**7.3 Performance tests**

Create `file:tests/performance/test_context_loading.py`:
- Benchmark context loading with 1000+ items across scopes
- Verify relevance filtering completes in <100ms
- Measure memory overhead of scope separation
- Benchmark contamination measurement (<50ms per task)

### Phase 8: Rollout & Monitoring (Conditional on Phase 1 Results)

**8.1 Backward compatibility**

- Existing context items default to `context_scope='session'` and `task_id=NULL`
- Agents without task assignment continue using session-scoped context
- Gradual migration: enable task-scoped context per agent type (backend → frontend → test)
- Feature flag: `ENABLE_TASK_SCOPED_CONTEXT` (default: false, enabled after Phase 1 decision)

**8.2 Rollout phases**

1. **Phase 1 (Investigation)**: Measure contamination, collect data, make go/no-go decision
2. **Phase 2 (Pilot)**: If go decision, deploy schema changes and enable for backend workers only
3. **Phase 3 (Validation)**: Measure contamination reduction and token savings on backend workers
4. **Phase 4 (Rollout)**: Enable for all worker types if metrics positive (contamination reduced >50%, no success rate regression)
5. **Phase 5 (Deprecation)**: Deprecate pure session-scoped context (all items must have scope)

**8.3 Rollback plan**

- If task success rate drops >5%, disable task-scoped context via feature flag
- Revert to session-scoped context by setting all `context_scope='session'`
- Investigate relevance threshold tuning before re-enabling
- Preserve metrics data for post-mortem analysis

**8.4 Monitoring & Alerting**

- Dashboard metric: Cross-task contamination % (alert if > 50%)
- Dashboard metric: Task success rate (alert if drops > 5%)
- Dashboard metric: Token usage per task (alert if increases > 20%)
- Dashboard metric: Context utilization rate (alert if < 50%)
- Weekly report: Contamination trends, correlation analysis, recommendations

## Decision Gate: Phase 1 Results

**PROCEED to Phase 2-8 if:**
- Cross-task contamination > 40% (significant noise in context)
- OR strong correlation (r > 0.3, p < 0.05) between contamination and task failures
- OR token waste > 30% (paying for irrelevant context)

**STOP if:**
- Cross-task contamination < 20% (acceptable noise level)
- AND no correlation with task failures (r < 0.2 or p > 0.05)
- AND token waste < 10% (acceptable overhead)

In the STOP case, document findings in `file:CONTEXT_INVESTIGATION_RESULTS.md` and monitor for future degradation.

## Success Criteria (Post-Phase 1 Decision)

If proceeding to implementation:

| Metric | Baseline | Target | Measurement |
|--------|----------|--------|-------------|
| Cross-task contamination | Measured in Phase 1 | <10% | % of HOT tier items from previous tasks |
| Token usage per task | Measured in Phase 1 | Stable or -20% | Average tokens/task across 10-task session |
| Task success rate | Measured in Phase 1 | ≥ baseline | Maintain quality with reduced context |
| Context loading time | <50ms | <100ms | Scope-aware loading overhead |
| Token reduction | Measured in Phase 1 | 30-50% | Compare session vs. task-scoped context |
| Context utilization rate | Measured in Phase 1 | >70% | % of loaded context actually used |
| Correlation (contamination vs. success) | Measured in Phase 1 | <0.2 | Reduce correlation to near-zero |

## Architecture Diagram (Post-Implementation)

```mermaid
graph TD
    A[Worker Agent] -->|Task Start| B[Initialize Task Context]
    B --> C[Record Baseline Metrics]
    C --> D[Load Project Context]
    B --> E[Load Relevant Session Context]
    B --> F[Create Task Context Item]
    
    D --> G[Context Assembly]
    E --> G
    F --> G
    
    G --> H[LLM Call with Scoped Context]
    
    H -->|Task Complete| I[Record Final Metrics]
    I --> J[Cleanup Task Context]
    J --> K[Generate Task Summary]
    K --> L[Save to Session Context]
    J --> M[Delete Task-Scoped Items]
    
    N[Session End] --> O[Archive Session Context]
    O --> P[Generate Session Summary]
    P --> Q[Clear Session Items]
    
    R[Project Context] -.->|Always Included| G
    S[Session Context] -.->|Relevance Filtered| G
    T[Task Context] -.->|Full Inclusion| G
    
    U[Metrics Dashboard] -.->|Real-time Updates| C
    U -.->|Real-time Updates| I
    
    style R fill:#90EE90
    style S fill:#FFD700
    style T fill:#FF6B6B
    style U fill:#87CEEB
```

## Phase 4 Evaluation Scope

This Phase 4 ticket focuses exclusively on **investigation and measurement** (Phase 1 of the implementation plan). The decision to proceed with Phases 2-8 depends entirely on Phase 1 results. The investigation will:

1. Quantify cross-task contamination in the current system
2. Measure correlation between contamination and task failures
3. Identify token waste from irrelevant context
4. Provide data-driven decision gate for implementation

If Phase 1 results show contamination is not significant (< 20%) and no correlation with failures, the investigation concludes and no further implementation is needed. If contamination is significant, a follow-up ticket will be created for Phases 2-8 implementation.

---

Execution Information

Branch: main
Commit: 4d894a6

---

💡 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.

[frankbria]

@traycerai Update plan

[traycerai]

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

New Plan

Observations

The current tiered memory system (file:codeframe/lib/context_manager.py) operates at the agent level with (project_id, agent_id) scoping. Context items accumulate across multiple tasks without task-level isolation, leading to cross-task contamination. The context_items table lacks a task_id column, and importance scoring (file:codeframe/lib/importance_scorer.py) considers age, access frequency, and item type—but not task relevance. Worker agents (file:codeframe/agents/worker_agent.py) maintain self.current_task but don't use it for context scoping. This architecture causes stale context from previous tasks to persist in HOT/WARM tiers, wasting tokens and diluting relevance.

Approach

Implement Option C: Hybrid Approach with three-tier context separation: Project Context (architecture, conventions—always included), Session Context (accumulates within session, cleared at session end), and Task Context (fresh per task, aggressive management). This preserves cross-task learning while eliminating noise. Add a task_id column to context_items, introduce task lifecycle hooks for context initialization/cleanup, and implement relevance scoring to filter session context by current task. Measure cross-task contamination before/after to validate improvement. This approach balances isolation with learning, avoids over-engineering, and aligns with the subagent pattern's emphasis on task-scoped context.

Implementation Plan

1. Database Schema Changes

Add task_id column to context_items table

Create migration file:codeframe/persistence/migrations/migration_006_add_task_scoped_context.py:

• Add task_id INTEGER NULL column to context_items table with foreign key to tasks(id) ON DELETE CASCADE
• Add context_scope TEXT NOT NULL DEFAULT 'session' column with CHECK constraint for values: 'project', 'session', 'task'
• Create composite index idx_context_agent_task_tier on (agent_id, task_id, current_tier) for fast task-scoped queries
• Create index idx_context_scope_tier on (context_scope, current_tier) for scope-based filtering
• Backfill existing records: set context_scope='session' and task_id=NULL for all existing context items

Update Database class methods

Modify file:codeframe/persistence/database.py:

• Update create_context_item() to accept optional task_id and context_scope parameters
• Update list_context_items() to support filtering by task_id and context_scope
• Add clear_task_context(project_id, agent_id, task_id) method to delete task-scoped items
• Add archive_task_context(project_id, agent_id, task_id) method to summarize and archive task context
• Update archive_cold_items() to respect context scope (don't archive project-scoped items)

2. Context Scope Management

Define context scope enum and rules

Create file:codeframe/core/context_scopes.py:

• Define ContextScope enum with values: PROJECT, SESSION, TASK
• Define scope retention rules:
  • PROJECT: Never cleared, persists across all sessions (architecture docs, coding conventions, project structure)
  • SESSION: Cleared at session end, accumulates within session (cross-task learnings, session-wide patterns)
  • TASK: Cleared at task completion, fresh per task (task description, task-specific code, task errors)
• Define item type to default scope mapping (e.g., PRD_SECTION → PROJECT, TASK → TASK, CODE → TASK)

Implement scope-aware context manager

Extend file:codeframe/lib/context_manager.py:

• Add recalculate_scores_for_task(project_id, agent_id, task_id) method to recalculate only task-scoped items
• Add clear_task_context(project_id, agent_id, task_id) method to remove task-scoped items after task completion
• Add archive_task_summary(project_id, agent_id, task_id) method to create compressed summary of task context before clearing
• Update flash_save() to preserve project-scoped items (never archive)
• Update update_tiers_for_agent() to handle scope-aware tier assignment (project items stay HOT)

3. Task Lifecycle Integration

Add task context initialization

Modify file:codeframe/agents/worker_agent.py:

• Update execute_task(task) method:
  • Call _initialize_task_context(task) at task start
  • Load project-scoped context (always included)
  • Load session-scoped context filtered by task relevance (see step 4)
  • Create initial task-scoped context item with task description
• Add _initialize_task_context(task) method:
  • Save task description as TASK type with context_scope='task' and task_id=task.id
  • Load project context (scope=PROJECT, tier=HOT)
  • Load relevant session context (scope=SESSION, relevance_score > threshold)

Add task context cleanup

Modify file:codeframe/agents/worker_agent.py:

• Update complete_task(task, project_root) method:
  • Call _cleanup_task_context(task) after quality gates pass
  • Archive task summary to session context
  • Clear task-scoped items
• Add _cleanup_task_context(task) method:
  • Generate task summary (key learnings, patterns discovered, files modified)
  • Save summary as session-scoped context item
  • Delete all task-scoped items for this task
  • Update session context importance scores

4. Relevance Filtering for Session Context

Implement relevance scoring

Create file:codeframe/lib/relevance_scorer.py:

• Implement calculate_relevance_score(context_item, current_task) function:
  • Use semantic similarity between context content and task description (cosine similarity of embeddings)
  • Consider item type relevance (CODE items more relevant if task involves same files)
  • Consider temporal proximity (items from recent tasks more relevant)
  • Return score in range [0.0, 1.0]
• Define relevance threshold: RELEVANCE_THRESHOLD = 0.3 (items below threshold excluded from task context)

Integrate relevance filtering

Extend file:codeframe/lib/context_manager.py:

• Add load_relevant_session_context(project_id, agent_id, task) method:
  • Load all session-scoped items for agent
  • Calculate relevance score for each item relative to current task
  • Filter items with relevance_score >= RELEVANCE_THRESHOLD
  • Return filtered list ordered by importance_score * relevance_score
• Update ContextManager to cache relevance scores per task (invalidate on task change)

5. Context Assembly for LLM Calls

Implement scope-aware context loading

Modify file:codeframe/agents/worker_agent.py:

• Update load_context(tier) method to become load_context_for_task(task, tier):
  • Load project-scoped context (all tiers, always included)
  • Load session-scoped context filtered by relevance to task
  • Load task-scoped context (all tiers, specific to current task)
  • Combine and deduplicate by content hash
  • Order by: scope priority (project > session > task), then importance score
• Add _build_llm_context(task) helper method:
  • Assemble context from all three scopes
  • Apply token budget allocation: 30% project, 30% session, 40% task
  • Truncate if exceeds budget, prioritizing higher importance scores

6. Session Management Integration

Add session-level context cleanup

Modify file:codeframe/core/session_manager.py:

• Add clear_session_context(project_id, agent_id) method:
  • Archive session summary (completed tasks, key learnings, patterns)
  • Delete all session-scoped context items
  • Retain project-scoped items
• Update save_session(state) to include session context summary
• Update load_session() to restore session context from summary

Add session context summarization

Create file:codeframe/lib/context_summarizer.py:

• Implement summarize_session_context(context_items) function:
  • Group items by type and relevance
  • Extract key patterns and learnings
  • Compress to 20% of original token count
  • Return summary as single context item (scope=SESSION)
• Implement summarize_task_context(context_items, task) function:
  • Extract task-specific learnings
  • Identify reusable patterns
  • Return summary for session context

7. Metrics and Monitoring

Add contamination tracking

Create file:codeframe/lib/context_metrics.py:

• Implement measure_cross_task_contamination(project_id, agent_id, task_id):
  • Calculate % of context items from previous tasks still in HOT tier
  • Calculate % of tokens spent on irrelevant context
  • Return contamination metrics
• Implement track_context_effectiveness(project_id, agent_id, task_id):
  • Measure task success rate vs. context size
  • Track token usage per task over session duration
  • Identify correlation between contamination and task failures

Add dashboard visualization

Extend file:web-ui/src/components/context/ContextPanel.tsx:

• Add scope breakdown chart (project/session/task distribution)
• Add task context timeline (show context evolution across tasks)
• Add contamination indicator (% of irrelevant context)
• Add relevance score distribution histogram

8. Configuration and Tuning

Add configuration parameters

Create file:codeframe/config/context_config.py:

• Define RELEVANCE_THRESHOLD = 0.3 (adjustable per deployment)
• Define TOKEN_BUDGET_ALLOCATION = {'project': 0.3, 'session': 0.3, 'task': 0.4}
• Define TASK_SUMMARY_COMPRESSION_RATIO = 0.2 (target 20% of original size)
• Define SESSION_CONTEXT_MAX_AGE_DAYS = 7 (auto-archive old session items)

Add tuning utilities

Create file:codeframe/lib/context_tuner.py:

• Implement optimize_relevance_threshold(project_id):
  • Analyze historical task success rates vs. relevance thresholds
  • Recommend optimal threshold for project
• Implement analyze_scope_distribution(project_id, agent_id):
  • Report token distribution across scopes
  • Identify scope imbalances

9. Testing Strategy

Unit tests

Create file:tests/context/test_task_scoped_context.py:

• Test task context initialization and cleanup
• Test scope-aware tier assignment
• Test relevance scoring algorithm
• Test context summarization

Create file:tests/context/test_relevance_filtering.py:

• Test relevance score calculation
• Test threshold filtering
• Test session context filtering by task

Integration tests

Create file:tests/integration/test_multi_task_context.py:

• Test context isolation across 10 sequential tasks
• Verify Task 10 doesn't have Task 3 context in HOT tier
• Measure token reduction vs. baseline
• Verify task success rate maintained

Performance tests

Create file:tests/performance/test_context_loading.py:

• Benchmark context loading with 1000+ items across scopes
• Verify relevance filtering completes in <100ms
• Measure memory overhead of scope separation

10. Migration and Rollout

Backward compatibility

• Existing context items default to context_scope='session' and task_id=NULL
• Agents without task assignment continue using session-scoped context
• Gradual migration: enable task-scoped context per agent type (backend → frontend → test)

Rollout phases

1. Phase 1: Deploy schema changes, backfill existing data
2. Phase 2: Enable task-scoped context for backend workers (pilot)
3. Phase 3: Measure contamination reduction and token savings
4. Phase 4: Enable for all worker types if metrics positive
5. Phase 5: Deprecate pure session-scoped context (all items must have scope)

Rollback plan

• If task success rate drops >5%, disable task-scoped context
• Revert to session-scoped context by setting all context_scope='session'
• Investigate relevance threshold tuning before re-enabling

Architecture Diagram

graph TD
    A[Worker Agent] -->|Task Start| B[Initialize Task Context]
    B --> C[Load Project Context]
    B --> D[Load Relevant Session Context]
    B --> E[Create Task Context Item]
    
    C --> F[Context Assembly]
    D --> F
    E --> F
    
    F --> G[LLM Call with Scoped Context]
    
    G -->|Task Complete| H[Cleanup Task Context]
    H --> I[Generate Task Summary]
    I --> J[Save to Session Context]
    H --> K[Delete Task-Scoped Items]
    
    L[Session End] --> M[Archive Session Context]
    M --> N[Generate Session Summary]
    N --> O[Clear Session Items]
    
    P[Project Context] -.->|Always Included| F
    Q[Session Context] -.->|Relevance Filtered| F
    R[Task Context] -.->|Full Inclusion| F
    
    style P fill:#90EE90
    style Q fill:#FFD700
    style R fill:#FF6B6B

Loading

Context Scope Lifecycle

sequenceDiagram
    participant Agent
    participant ContextManager
    participant Database
    participant LLM
    
    Note over Agent,Database: Task 3: Authentication
    Agent->>ContextManager: initialize_task_context(task_3)
    ContextManager->>Database: load_context(scope=PROJECT)
    ContextManager->>Database: load_context(scope=SESSION, relevance>0.3)
    ContextManager->>Database: create_context_item(scope=TASK, task_id=3)
    ContextManager-->>Agent: Context ready
    
    Agent->>LLM: execute_task(context)
    LLM-->>Agent: Task complete
    
    Agent->>ContextManager: cleanup_task_context(task_3)
    ContextManager->>Database: summarize_task_context(task_id=3)
    ContextManager->>Database: save_context_item(scope=SESSION, summary)
    ContextManager->>Database: delete_context_items(task_id=3)
    
    Note over Agent,Database: Task 10: Data Export
    Agent->>ContextManager: initialize_task_context(task_10)
    ContextManager->>Database: load_context(scope=PROJECT)
    ContextManager->>Database: load_context(scope=SESSION, relevance>0.3)
    Note right of ContextManager: Auth context filtered out<br/>(low relevance to export)
    ContextManager->>Database: create_context_item(scope=TASK, task_id=10)
    ContextManager-->>Agent: Clean context (no Task 3 pollution)

Loading

Success Criteria

Metric	Baseline	Target	Measurement
Cross-task contamination	~60% (estimated)	<10%	% of HOT tier items from previous tasks
Token usage per task	Grows linearly	Stable	Average tokens/task across 10-task session
Task success rate	90%	≥90%	Maintain quality with reduced context
Context loading time	<50ms	<100ms	Scope-aware loading overhead
Token reduction	Baseline	30-50%	Compare session vs. task-scoped context

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current tiered memory system (`file:codeframe/lib/context_manager.py`) operates at the agent level with `(project_id, agent_id)` scoping. Context items accumulate across multiple tasks without task-level isolation, leading to cross-task contamination. The `context_items` table lacks a `task_id` column, and importance scoring (`file:codeframe/lib/importance_scorer.py`) considers age, access frequency, and item type—but not task relevance. Worker agents (`file:codeframe/agents/worker_agent.py`) maintain `self.current_task` but don't use it for context scoping. This architecture causes stale context from previous tasks to persist in HOT/WARM tiers, wasting tokens and diluting relevance.

## Approach

Implement **Option C: Hybrid Approach** with three-tier context separation: **Project Context** (architecture, conventions—always included), **Session Context** (accumulates within session, cleared at session end), and **Task Context** (fresh per task, aggressive management). This preserves cross-task learning while eliminating noise. Add a `task_id` column to `context_items`, introduce task lifecycle hooks for context initialization/cleanup, and implement relevance scoring to filter session context by current task. Measure cross-task contamination before/after to validate improvement. This approach balances isolation with learning, avoids over-engineering, and aligns with the subagent pattern's emphasis on task-scoped context.

## Implementation Plan

### 1. Database Schema Changes

**Add task_id column to context_items table**

Create migration `file:codeframe/persistence/migrations/migration_006_add_task_scoped_context.py`:
- Add `task_id INTEGER NULL` column to `context_items` table with foreign key to `tasks(id)` ON DELETE CASCADE
- Add `context_scope TEXT NOT NULL DEFAULT 'session'` column with CHECK constraint for values: `'project'`, `'session'`, `'task'`
- Create composite index `idx_context_agent_task_tier` on `(agent_id, task_id, current_tier)` for fast task-scoped queries
- Create index `idx_context_scope_tier` on `(context_scope, current_tier)` for scope-based filtering
- Backfill existing records: set `context_scope='session'` and `task_id=NULL` for all existing context items

**Update Database class methods**

Modify `file:codeframe/persistence/database.py`:
- Update `create_context_item()` to accept optional `task_id` and `context_scope` parameters
- Update `list_context_items()` to support filtering by `task_id` and `context_scope`
- Add `clear_task_context(project_id, agent_id, task_id)` method to delete task-scoped items
- Add `archive_task_context(project_id, agent_id, task_id)` method to summarize and archive task context
- Update `archive_cold_items()` to respect context scope (don't archive project-scoped items)

### 2. Context Scope Management

**Define context scope enum and rules**

Create `file:codeframe/core/context_scopes.py`:
- Define `ContextScope` enum with values: `PROJECT`, `SESSION`, `TASK`
- Define scope retention rules:
  - `PROJECT`: Never cleared, persists across all sessions (architecture docs, coding conventions, project structure)
  - `SESSION`: Cleared at session end, accumulates within session (cross-task learnings, session-wide patterns)
  - `TASK`: Cleared at task completion, fresh per task (task description, task-specific code, task errors)
- Define item type to default scope mapping (e.g., `PRD_SECTION` → `PROJECT`, `TASK` → `TASK`, `CODE` → `TASK`)

**Implement scope-aware context manager**

Extend `file:codeframe/lib/context_manager.py`:
- Add `recalculate_scores_for_task(project_id, agent_id, task_id)` method to recalculate only task-scoped items
- Add `clear_task_context(project_id, agent_id, task_id)` method to remove task-scoped items after task completion
- Add `archive_task_summary(project_id, agent_id, task_id)` method to create compressed summary of task context before clearing
- Update `flash_save()` to preserve project-scoped items (never archive)
- Update `update_tiers_for_agent()` to handle scope-aware tier assignment (project items stay HOT)

### 3. Task Lifecycle Integration

**Add task context initialization**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `execute_task(task)` method:
  - Call `_initialize_task_context(task)` at task start
  - Load project-scoped context (always included)
  - Load session-scoped context filtered by task relevance (see step 4)
  - Create initial task-scoped context item with task description
- Add `_initialize_task_context(task)` method:
  - Save task description as `TASK` type with `context_scope='task'` and `task_id=task.id`
  - Load project context (scope=PROJECT, tier=HOT)
  - Load relevant session context (scope=SESSION, relevance_score > threshold)

**Add task context cleanup**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `complete_task(task, project_root)` method:
  - Call `_cleanup_task_context(task)` after quality gates pass
  - Archive task summary to session context
  - Clear task-scoped items
- Add `_cleanup_task_context(task)` method:
  - Generate task summary (key learnings, patterns discovered, files modified)
  - Save summary as session-scoped context item
  - Delete all task-scoped items for this task
  - Update session context importance scores

### 4. Relevance Filtering for Session Context

**Implement relevance scoring**

Create `file:codeframe/lib/relevance_scorer.py`:
- Implement `calculate_relevance_score(context_item, current_task)` function:
  - Use semantic similarity between context content and task description (cosine similarity of embeddings)
  - Consider item type relevance (CODE items more relevant if task involves same files)
  - Consider temporal proximity (items from recent tasks more relevant)
  - Return score in range [0.0, 1.0]
- Define relevance threshold: `RELEVANCE_THRESHOLD = 0.3` (items below threshold excluded from task context)

**Integrate relevance filtering**

Extend `file:codeframe/lib/context_manager.py`:
- Add `load_relevant_session_context(project_id, agent_id, task)` method:
  - Load all session-scoped items for agent
  - Calculate relevance score for each item relative to current task
  - Filter items with `relevance_score >= RELEVANCE_THRESHOLD`
  - Return filtered list ordered by `importance_score * relevance_score`
- Update `ContextManager` to cache relevance scores per task (invalidate on task change)

### 5. Context Assembly for LLM Calls

**Implement scope-aware context loading**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `load_context(tier)` method to become `load_context_for_task(task, tier)`:
  - Load project-scoped context (all tiers, always included)
  - Load session-scoped context filtered by relevance to task
  - Load task-scoped context (all tiers, specific to current task)
  - Combine and deduplicate by content hash
  - Order by: scope priority (project > session > task), then importance score
- Add `_build_llm_context(task)` helper method:
  - Assemble context from all three scopes
  - Apply token budget allocation: 30% project, 30% session, 40% task
  - Truncate if exceeds budget, prioritizing higher importance scores

### 6. Session Management Integration

**Add session-level context cleanup**

Modify `file:codeframe/core/session_manager.py`:
- Add `clear_session_context(project_id, agent_id)` method:
  - Archive session summary (completed tasks, key learnings, patterns)
  - Delete all session-scoped context items
  - Retain project-scoped items
- Update `save_session(state)` to include session context summary
- Update `load_session()` to restore session context from summary

**Add session context summarization**

Create `file:codeframe/lib/context_summarizer.py`:
- Implement `summarize_session_context(context_items)` function:
  - Group items by type and relevance
  - Extract key patterns and learnings
  - Compress to 20% of original token count
  - Return summary as single context item (scope=SESSION)
- Implement `summarize_task_context(context_items, task)` function:
  - Extract task-specific learnings
  - Identify reusable patterns
  - Return summary for session context

### 7. Metrics and Monitoring

**Add contamination tracking**

Create `file:codeframe/lib/context_metrics.py`:
- Implement `measure_cross_task_contamination(project_id, agent_id, task_id)`:
  - Calculate % of context items from previous tasks still in HOT tier
  - Calculate % of tokens spent on irrelevant context
  - Return contamination metrics
- Implement `track_context_effectiveness(project_id, agent_id, task_id)`:
  - Measure task success rate vs. context size
  - Track token usage per task over session duration
  - Identify correlation between contamination and task failures

**Add dashboard visualization**

Extend `file:web-ui/src/components/context/ContextPanel.tsx`:
- Add scope breakdown chart (project/session/task distribution)
- Add task context timeline (show context evolution across tasks)
- Add contamination indicator (% of irrelevant context)
- Add relevance score distribution histogram

### 8. Configuration and Tuning

**Add configuration parameters**

Create `file:codeframe/config/context_config.py`:
- Define `RELEVANCE_THRESHOLD = 0.3` (adjustable per deployment)
- Define `TOKEN_BUDGET_ALLOCATION = {'project': 0.3, 'session': 0.3, 'task': 0.4}`
- Define `TASK_SUMMARY_COMPRESSION_RATIO = 0.2` (target 20% of original size)
- Define `SESSION_CONTEXT_MAX_AGE_DAYS = 7` (auto-archive old session items)

**Add tuning utilities**

Create `file:codeframe/lib/context_tuner.py`:
- Implement `optimize_relevance_threshold(project_id)`:
  - Analyze historical task success rates vs. relevance thresholds
  - Recommend optimal threshold for project
- Implement `analyze_scope_distribution(project_id, agent_id)`:
  - Report token distribution across scopes
  - Identify scope imbalances

### 9. Testing Strategy

**Unit tests**

Create `file:tests/context/test_task_scoped_context.py`:
- Test task context initialization and cleanup
- Test scope-aware tier assignment
- Test relevance scoring algorithm
- Test context summarization

Create `file:tests/context/test_relevance_filtering.py`:
- Test relevance score calculation
- Test threshold filtering
- Test session context filtering by task

**Integration tests**

Create `file:tests/integration/test_multi_task_context.py`:
- Test context isolation across 10 sequential tasks
- Verify Task 10 doesn't have Task 3 context in HOT tier
- Measure token reduction vs. baseline
- Verify task success rate maintained

**Performance tests**

Create `file:tests/performance/test_context_loading.py`:
- Benchmark context loading with 1000+ items across scopes
- Verify relevance filtering completes in <100ms
- Measure memory overhead of scope separation

### 10. Migration and Rollout

**Backward compatibility**

- Existing context items default to `context_scope='session'` and `task_id=NULL`
- Agents without task assignment continue using session-scoped context
- Gradual migration: enable task-scoped context per agent type (backend → frontend → test)

**Rollout phases**

1. **Phase 1**: Deploy schema changes, backfill existing data
2. **Phase 2**: Enable task-scoped context for backend workers (pilot)
3. **Phase 3**: Measure contamination reduction and token savings
4. **Phase 4**: Enable for all worker types if metrics positive
5. **Phase 5**: Deprecate pure session-scoped context (all items must have scope)

**Rollback plan**

- If task success rate drops >5%, disable task-scoped context
- Revert to session-scoped context by setting all `context_scope='session'`
- Investigate relevance threshold tuning before re-enabling

## Architecture Diagram

```mermaid
graph TD
    A[Worker Agent] -->|Task Start| B[Initialize Task Context]
    B --> C[Load Project Context]
    B --> D[Load Relevant Session Context]
    B --> E[Create Task Context Item]
    
    C --> F[Context Assembly]
    D --> F
    E --> F
    
    F --> G[LLM Call with Scoped Context]
    
    G -->|Task Complete| H[Cleanup Task Context]
    H --> I[Generate Task Summary]
    I --> J[Save to Session Context]
    H --> K[Delete Task-Scoped Items]
    
    L[Session End] --> M[Archive Session Context]
    M --> N[Generate Session Summary]
    N --> O[Clear Session Items]
    
    P[Project Context] -.->|Always Included| F
    Q[Session Context] -.->|Relevance Filtered| F
    R[Task Context] -.->|Full Inclusion| F
    
    style P fill:#90EE90
    style Q fill:#FFD700
    style R fill:#FF6B6B
```

## Context Scope Lifecycle

```mermaid
sequenceDiagram
    participant Agent
    participant ContextManager
    participant Database
    participant LLM
    
    Note over Agent,Database: Task 3: Authentication
    Agent->>ContextManager: initialize_task_context(task_3)
    ContextManager->>Database: load_context(scope=PROJECT)
    ContextManager->>Database: load_context(scope=SESSION, relevance>0.3)
    ContextManager->>Database: create_context_item(scope=TASK, task_id=3)
    ContextManager-->>Agent: Context ready
    
    Agent->>LLM: execute_task(context)
    LLM-->>Agent: Task complete
    
    Agent->>ContextManager: cleanup_task_context(task_3)
    ContextManager->>Database: summarize_task_context(task_id=3)
    ContextManager->>Database: save_context_item(scope=SESSION, summary)
    ContextManager->>Database: delete_context_items(task_id=3)
    
    Note over Agent,Database: Task 10: Data Export
    Agent->>ContextManager: initialize_task_context(task_10)
    ContextManager->>Database: load_context(scope=PROJECT)
    ContextManager->>Database: load_context(scope=SESSION, relevance>0.3)
    Note right of ContextManager: Auth context filtered out<br/>(low relevance to export)
    ContextManager->>Database: create_context_item(scope=TASK, task_id=10)
    ContextManager-->>Agent: Clean context (no Task 3 pollution)
```

## Success Criteria

| Metric | Baseline | Target | Measurement |
|--------|----------|--------|-------------|
| Cross-task contamination | ~60% (estimated) | <10% | % of HOT tier items from previous tasks |
| Token usage per task | Grows linearly | Stable | Average tokens/task across 10-task session |
| Task success rate | 90% | ≥90% | Maintain quality with reduced context |
| Context loading time | <50ms | <100ms | Scope-aware loading overhead |
| Token reduction | Baseline | 30-50% | Compare session vs. task-scoped context |

---

Execution Information

Branch: main
Commit: 360e111

[traycerai]

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

Previous Plan

Observations

The current tiered memory system (file:codeframe/lib/context_manager.py) operates at the agent level with (project_id, agent_id) scoping. Context items accumulate across multiple tasks without task-level isolation, leading to cross-task contamination. The context_items table lacks a task_id column, and importance scoring (file:codeframe/lib/importance_scorer.py) considers age, access frequency, and item type—but not task relevance. Worker agents (file:codeframe/agents/worker_agent.py) maintain self.current_task but don't use it for context scoping. This architecture causes stale context from previous tasks to persist in HOT/WARM tiers, wasting tokens and diluting relevance.

Approach

Implement Option C: Hybrid Approach with three-tier context separation: Project Context (architecture, conventions—always included), Session Context (accumulates within session, cleared at session end), and Task Context (fresh per task, aggressive management). This preserves cross-task learning while eliminating noise. Add a task_id column to context_items, introduce task lifecycle hooks for context initialization/cleanup, and implement relevance scoring to filter session context by current task. Measure cross-task contamination before/after to validate improvement. This approach balances isolation with learning, avoids over-engineering, and aligns with the subagent pattern's emphasis on task-scoped context.

Implementation Plan

1. Database Schema Changes

Add task_id column to context_items table

Create migration file:codeframe/persistence/migrations/migration_006_add_task_scoped_context.py:

• Add task_id INTEGER NULL column to context_items table with foreign key to tasks(id) ON DELETE CASCADE
• Add context_scope TEXT NOT NULL DEFAULT 'session' column with CHECK constraint for values: 'project', 'session', 'task'
• Create composite index idx_context_agent_task_tier on (agent_id, task_id, current_tier) for fast task-scoped queries
• Create index idx_context_scope_tier on (context_scope, current_tier) for scope-based filtering
• Backfill existing records: set context_scope='session' and task_id=NULL for all existing context items

Update Database class methods

Modify file:codeframe/persistence/database.py:

• Update create_context_item() to accept optional task_id and context_scope parameters
• Update list_context_items() to support filtering by task_id and context_scope
• Add clear_task_context(project_id, agent_id, task_id) method to delete task-scoped items
• Add archive_task_context(project_id, agent_id, task_id) method to summarize and archive task context
• Update archive_cold_items() to respect context scope (don't archive project-scoped items)

2. Context Scope Management

Define context scope enum and rules

Create file:codeframe/core/context_scopes.py:

• Define ContextScope enum with values: PROJECT, SESSION, TASK
• Define scope retention rules:
  • PROJECT: Never cleared, persists across all sessions (architecture docs, coding conventions, project structure)
  • SESSION: Cleared at session end, accumulates within session (cross-task learnings, session-wide patterns)
  • TASK: Cleared at task completion, fresh per task (task description, task-specific code, task errors)
• Define item type to default scope mapping (e.g., PRD_SECTION → PROJECT, TASK → TASK, CODE → TASK)

Implement scope-aware context manager

Extend file:codeframe/lib/context_manager.py:

• Add recalculate_scores_for_task(project_id, agent_id, task_id) method to recalculate only task-scoped items
• Add clear_task_context(project_id, agent_id, task_id) method to remove task-scoped items after task completion
• Add archive_task_summary(project_id, agent_id, task_id) method to create compressed summary of task context before clearing
• Update flash_save() to preserve project-scoped items (never archive)
• Update update_tiers_for_agent() to handle scope-aware tier assignment (project items stay HOT)

3. Task Lifecycle Integration

Add task context initialization

Modify file:codeframe/agents/worker_agent.py:

• Update execute_task(task) method:
  • Call _initialize_task_context(task) at task start
  • Load project-scoped context (always included)
  • Load session-scoped context filtered by task relevance (see step 4)
  • Create initial task-scoped context item with task description
• Add _initialize_task_context(task) method:
  • Save task description as TASK type with context_scope='task' and task_id=task.id
  • Load project context (scope=PROJECT, tier=HOT)
  • Load relevant session context (scope=SESSION, relevance_score > threshold)

Add task context cleanup

Modify file:codeframe/agents/worker_agent.py:

• Update complete_task(task, project_root) method:
  • Call _cleanup_task_context(task) after quality gates pass
  • Archive task summary to session context
  • Clear task-scoped items
• Add _cleanup_task_context(task) method:
  • Generate task summary (key learnings, patterns discovered, files modified)
  • Save summary as session-scoped context item
  • Delete all task-scoped items for this task
  • Update session context importance scores

4. Relevance Filtering for Session Context

Implement relevance scoring

Create file:codeframe/lib/relevance_scorer.py:

• Implement calculate_relevance_score(context_item, current_task) function:
  • Use semantic similarity between context content and task description (cosine similarity of embeddings)
  • Consider item type relevance (CODE items more relevant if task involves same files)
  • Consider temporal proximity (items from recent tasks more relevant)
  • Return score in range [0.0, 1.0]
• Define relevance threshold: RELEVANCE_THRESHOLD = 0.3 (items below threshold excluded from task context)

Integrate relevance filtering

Extend file:codeframe/lib/context_manager.py:

• Add load_relevant_session_context(project_id, agent_id, task) method:
  • Load all session-scoped items for agent
  • Calculate relevance score for each item relative to current task
  • Filter items with relevance_score >= RELEVANCE_THRESHOLD
  • Return filtered list ordered by importance_score * relevance_score
• Update ContextManager to cache relevance scores per task (invalidate on task change)

5. Context Assembly for LLM Calls

Implement scope-aware context loading

Modify file:codeframe/agents/worker_agent.py:

• Update load_context(tier) method to become load_context_for_task(task, tier):
  • Load project-scoped context (all tiers, always included)
  • Load session-scoped context filtered by relevance to task
  • Load task-scoped context (all tiers, specific to current task)
  • Combine and deduplicate by content hash
  • Order by: scope priority (project > session > task), then importance score
• Add _build_llm_context(task) helper method:
  • Assemble context from all three scopes
  • Apply token budget allocation: 30% project, 30% session, 40% task
  • Truncate if exceeds budget, prioritizing higher importance scores

6. Session Management Integration

Add session-level context cleanup

Modify file:codeframe/core/session_manager.py:

• Add clear_session_context(project_id, agent_id) method:
  • Archive session summary (completed tasks, key learnings, patterns)
  • Delete all session-scoped context items
  • Retain project-scoped items
• Update save_session(state) to include session context summary
• Update load_session() to restore session context from summary

Add session context summarization

Create file:codeframe/lib/context_summarizer.py:

• Implement summarize_session_context(context_items) function:
  • Group items by type and relevance
  • Extract key patterns and learnings
  • Compress to 20% of original token count
  • Return summary as single context item (scope=SESSION)
• Implement summarize_task_context(context_items, task) function:
  • Extract task-specific learnings
  • Identify reusable patterns
  • Return summary for session context

7. Metrics and Monitoring

Add contamination tracking

Create file:codeframe/lib/context_metrics.py:

• Implement measure_cross_task_contamination(project_id, agent_id, task_id):
  • Calculate % of context items from previous tasks still in HOT tier
  • Calculate % of tokens spent on irrelevant context
  • Return contamination metrics
• Implement track_context_effectiveness(project_id, agent_id, task_id):
  • Measure task success rate vs. context size
  • Track token usage per task over session duration
  • Identify correlation between contamination and task failures

Add dashboard visualization

Extend file:web-ui/src/components/context/ContextPanel.tsx:

• Add scope breakdown chart (project/session/task distribution)
• Add task context timeline (show context evolution across tasks)
• Add contamination indicator (% of irrelevant context)
• Add relevance score distribution histogram

8. Configuration and Tuning

Add configuration parameters

Create file:codeframe/config/context_config.py:

• Define RELEVANCE_THRESHOLD = 0.3 (adjustable per deployment)
• Define TOKEN_BUDGET_ALLOCATION = {'project': 0.3, 'session': 0.3, 'task': 0.4}
• Define TASK_SUMMARY_COMPRESSION_RATIO = 0.2 (target 20% of original size)
• Define SESSION_CONTEXT_MAX_AGE_DAYS = 7 (auto-archive old session items)

Add tuning utilities

Create file:codeframe/lib/context_tuner.py:

• Implement optimize_relevance_threshold(project_id):
  • Analyze historical task success rates vs. relevance thresholds
  • Recommend optimal threshold for project
• Implement analyze_scope_distribution(project_id, agent_id):
  • Report token distribution across scopes
  • Identify scope imbalances

9. Testing Strategy

Unit tests

Create file:tests/context/test_task_scoped_context.py:

• Test task context initialization and cleanup
• Test scope-aware tier assignment
• Test relevance scoring algorithm
• Test context summarization

Create file:tests/context/test_relevance_filtering.py:

• Test relevance score calculation
• Test threshold filtering
• Test session context filtering by task

Integration tests

Create file:tests/integration/test_multi_task_context.py:

• Test context isolation across 10 sequential tasks
• Verify Task 10 doesn't have Task 3 context in HOT tier
• Measure token reduction vs. baseline
• Verify task success rate maintained

Performance tests

Create file:tests/performance/test_context_loading.py:

• Benchmark context loading with 1000+ items across scopes
• Verify relevance filtering completes in <100ms
• Measure memory overhead of scope separation

10. Migration and Rollout

Backward compatibility

• Existing context items default to context_scope='session' and task_id=NULL
• Agents without task assignment continue using session-scoped context
• Gradual migration: enable task-scoped context per agent type (backend → frontend → test)

Rollout phases

1. Phase 1: Deploy schema changes, backfill existing data
2. Phase 2: Enable task-scoped context for backend workers (pilot)
3. Phase 3: Measure contamination reduction and token savings
4. Phase 4: Enable for all worker types if metrics positive
5. Phase 5: Deprecate pure session-scoped context (all items must have scope)

Rollback plan

• If task success rate drops >5%, disable task-scoped context
• Revert to session-scoped context by setting all context_scope='session'
• Investigate relevance threshold tuning before re-enabling

Architecture Diagram

graph TD
    A[Worker Agent] -->|Task Start| B[Initialize Task Context]
    B --> C[Load Project Context]
    B --> D[Load Relevant Session Context]
    B --> E[Create Task Context Item]
    
    C --> F[Context Assembly]
    D --> F
    E --> F
    
    F --> G[LLM Call with Scoped Context]
    
    G -->|Task Complete| H[Cleanup Task Context]
    H --> I[Generate Task Summary]
    I --> J[Save to Session Context]
    H --> K[Delete Task-Scoped Items]
    
    L[Session End] --> M[Archive Session Context]
    M --> N[Generate Session Summary]
    N --> O[Clear Session Items]
    
    P[Project Context] -.->|Always Included| F
    Q[Session Context] -.->|Relevance Filtered| F
    R[Task Context] -.->|Full Inclusion| F
    
    style P fill:#90EE90
    style Q fill:#FFD700
    style R fill:#FF6B6B

Loading

Context Scope Lifecycle

sequenceDiagram
    participant Agent
    participant ContextManager
    participant Database
    participant LLM
    
    Note over Agent,Database: Task 3: Authentication
    Agent->>ContextManager: initialize_task_context(task_3)
    ContextManager->>Database: load_context(scope=PROJECT)
    ContextManager->>Database: load_context(scope=SESSION, relevance>0.3)
    ContextManager->>Database: create_context_item(scope=TASK, task_id=3)
    ContextManager-->>Agent: Context ready
    
    Agent->>LLM: execute_task(context)
    LLM-->>Agent: Task complete
    
    Agent->>ContextManager: cleanup_task_context(task_3)
    ContextManager->>Database: summarize_task_context(task_id=3)
    ContextManager->>Database: save_context_item(scope=SESSION, summary)
    ContextManager->>Database: delete_context_items(task_id=3)
    
    Note over Agent,Database: Task 10: Data Export
    Agent->>ContextManager: initialize_task_context(task_10)
    ContextManager->>Database: load_context(scope=PROJECT)
    ContextManager->>Database: load_context(scope=SESSION, relevance>0.3)
    Note right of ContextManager: Auth context filtered out<br/>(low relevance to export)
    ContextManager->>Database: create_context_item(scope=TASK, task_id=10)
    ContextManager-->>Agent: Clean context (no Task 3 pollution)

Loading

Success Criteria

Metric	Baseline	Target	Measurement
Cross-task contamination	~60% (estimated)	<10%	% of HOT tier items from previous tasks
Token usage per task	Grows linearly	Stable	Average tokens/task across 10-task session
Task success rate	90%	≥90%	Maintain quality with reduced context
Context loading time	<50ms	<100ms	Scope-aware loading overhead
Token reduction	Baseline	30-50%	Compare session vs. task-scoped context

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current tiered memory system (`file:codeframe/lib/context_manager.py`) operates at the agent level with `(project_id, agent_id)` scoping. Context items accumulate across multiple tasks without task-level isolation, leading to cross-task contamination. The `context_items` table lacks a `task_id` column, and importance scoring (`file:codeframe/lib/importance_scorer.py`) considers age, access frequency, and item type—but not task relevance. Worker agents (`file:codeframe/agents/worker_agent.py`) maintain `self.current_task` but don't use it for context scoping. This architecture causes stale context from previous tasks to persist in HOT/WARM tiers, wasting tokens and diluting relevance.

## Approach

Implement **Option C: Hybrid Approach** with three-tier context separation: **Project Context** (architecture, conventions—always included), **Session Context** (accumulates within session, cleared at session end), and **Task Context** (fresh per task, aggressive management). This preserves cross-task learning while eliminating noise. Add a `task_id` column to `context_items`, introduce task lifecycle hooks for context initialization/cleanup, and implement relevance scoring to filter session context by current task. Measure cross-task contamination before/after to validate improvement. This approach balances isolation with learning, avoids over-engineering, and aligns with the subagent pattern's emphasis on task-scoped context.

## Implementation Plan

### 1. Database Schema Changes

**Add task_id column to context_items table**

Create migration `file:codeframe/persistence/migrations/migration_006_add_task_scoped_context.py`:
- Add `task_id INTEGER NULL` column to `context_items` table with foreign key to `tasks(id)` ON DELETE CASCADE
- Add `context_scope TEXT NOT NULL DEFAULT 'session'` column with CHECK constraint for values: `'project'`, `'session'`, `'task'`
- Create composite index `idx_context_agent_task_tier` on `(agent_id, task_id, current_tier)` for fast task-scoped queries
- Create index `idx_context_scope_tier` on `(context_scope, current_tier)` for scope-based filtering
- Backfill existing records: set `context_scope='session'` and `task_id=NULL` for all existing context items

**Update Database class methods**

Modify `file:codeframe/persistence/database.py`:
- Update `create_context_item()` to accept optional `task_id` and `context_scope` parameters
- Update `list_context_items()` to support filtering by `task_id` and `context_scope`
- Add `clear_task_context(project_id, agent_id, task_id)` method to delete task-scoped items
- Add `archive_task_context(project_id, agent_id, task_id)` method to summarize and archive task context
- Update `archive_cold_items()` to respect context scope (don't archive project-scoped items)

### 2. Context Scope Management

**Define context scope enum and rules**

Create `file:codeframe/core/context_scopes.py`:
- Define `ContextScope` enum with values: `PROJECT`, `SESSION`, `TASK`
- Define scope retention rules:
  - `PROJECT`: Never cleared, persists across all sessions (architecture docs, coding conventions, project structure)
  - `SESSION`: Cleared at session end, accumulates within session (cross-task learnings, session-wide patterns)
  - `TASK`: Cleared at task completion, fresh per task (task description, task-specific code, task errors)
- Define item type to default scope mapping (e.g., `PRD_SECTION` → `PROJECT`, `TASK` → `TASK`, `CODE` → `TASK`)

**Implement scope-aware context manager**

Extend `file:codeframe/lib/context_manager.py`:
- Add `recalculate_scores_for_task(project_id, agent_id, task_id)` method to recalculate only task-scoped items
- Add `clear_task_context(project_id, agent_id, task_id)` method to remove task-scoped items after task completion
- Add `archive_task_summary(project_id, agent_id, task_id)` method to create compressed summary of task context before clearing
- Update `flash_save()` to preserve project-scoped items (never archive)
- Update `update_tiers_for_agent()` to handle scope-aware tier assignment (project items stay HOT)

### 3. Task Lifecycle Integration

**Add task context initialization**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `execute_task(task)` method:
  - Call `_initialize_task_context(task)` at task start
  - Load project-scoped context (always included)
  - Load session-scoped context filtered by task relevance (see step 4)
  - Create initial task-scoped context item with task description
- Add `_initialize_task_context(task)` method:
  - Save task description as `TASK` type with `context_scope='task'` and `task_id=task.id`
  - Load project context (scope=PROJECT, tier=HOT)
  - Load relevant session context (scope=SESSION, relevance_score > threshold)

**Add task context cleanup**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `complete_task(task, project_root)` method:
  - Call `_cleanup_task_context(task)` after quality gates pass
  - Archive task summary to session context
  - Clear task-scoped items
- Add `_cleanup_task_context(task)` method:
  - Generate task summary (key learnings, patterns discovered, files modified)
  - Save summary as session-scoped context item
  - Delete all task-scoped items for this task
  - Update session context importance scores

### 4. Relevance Filtering for Session Context

**Implement relevance scoring**

Create `file:codeframe/lib/relevance_scorer.py`:
- Implement `calculate_relevance_score(context_item, current_task)` function:
  - Use semantic similarity between context content and task description (cosine similarity of embeddings)
  - Consider item type relevance (CODE items more relevant if task involves same files)
  - Consider temporal proximity (items from recent tasks more relevant)
  - Return score in range [0.0, 1.0]
- Define relevance threshold: `RELEVANCE_THRESHOLD = 0.3` (items below threshold excluded from task context)

**Integrate relevance filtering**

Extend `file:codeframe/lib/context_manager.py`:
- Add `load_relevant_session_context(project_id, agent_id, task)` method:
  - Load all session-scoped items for agent
  - Calculate relevance score for each item relative to current task
  - Filter items with `relevance_score >= RELEVANCE_THRESHOLD`
  - Return filtered list ordered by `importance_score * relevance_score`
- Update `ContextManager` to cache relevance scores per task (invalidate on task change)

### 5. Context Assembly for LLM Calls

**Implement scope-aware context loading**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `load_context(tier)` method to become `load_context_for_task(task, tier)`:
  - Load project-scoped context (all tiers, always included)
  - Load session-scoped context filtered by relevance to task
  - Load task-scoped context (all tiers, specific to current task)
  - Combine and deduplicate by content hash
  - Order by: scope priority (project > session > task), then importance score
- Add `_build_llm_context(task)` helper method:
  - Assemble context from all three scopes
  - Apply token budget allocation: 30% project, 30% session, 40% task
  - Truncate if exceeds budget, prioritizing higher importance scores

### 6. Session Management Integration

**Add session-level context cleanup**

Modify `file:codeframe/core/session_manager.py`:
- Add `clear_session_context(project_id, agent_id)` method:
  - Archive session summary (completed tasks, key learnings, patterns)
  - Delete all session-scoped context items
  - Retain project-scoped items
- Update `save_session(state)` to include session context summary
- Update `load_session()` to restore session context from summary

**Add session context summarization**

Create `file:codeframe/lib/context_summarizer.py`:
- Implement `summarize_session_context(context_items)` function:
  - Group items by type and relevance
  - Extract key patterns and learnings
  - Compress to 20% of original token count
  - Return summary as single context item (scope=SESSION)
- Implement `summarize_task_context(context_items, task)` function:
  - Extract task-specific learnings
  - Identify reusable patterns
  - Return summary for session context

### 7. Metrics and Monitoring

**Add contamination tracking**

Create `file:codeframe/lib/context_metrics.py`:
- Implement `measure_cross_task_contamination(project_id, agent_id, task_id)`:
  - Calculate % of context items from previous tasks still in HOT tier
  - Calculate % of tokens spent on irrelevant context
  - Return contamination metrics
- Implement `track_context_effectiveness(project_id, agent_id, task_id)`:
  - Measure task success rate vs. context size
  - Track token usage per task over session duration
  - Identify correlation between contamination and task failures

**Add dashboard visualization**

Extend `file:web-ui/src/components/context/ContextPanel.tsx`:
- Add scope breakdown chart (project/session/task distribution)
- Add task context timeline (show context evolution across tasks)
- Add contamination indicator (% of irrelevant context)
- Add relevance score distribution histogram

### 8. Configuration and Tuning

**Add configuration parameters**

Create `file:codeframe/config/context_config.py`:
- Define `RELEVANCE_THRESHOLD = 0.3` (adjustable per deployment)
- Define `TOKEN_BUDGET_ALLOCATION = {'project': 0.3, 'session': 0.3, 'task': 0.4}`
- Define `TASK_SUMMARY_COMPRESSION_RATIO = 0.2` (target 20% of original size)
- Define `SESSION_CONTEXT_MAX_AGE_DAYS = 7` (auto-archive old session items)

**Add tuning utilities**

Create `file:codeframe/lib/context_tuner.py`:
- Implement `optimize_relevance_threshold(project_id)`:
  - Analyze historical task success rates vs. relevance thresholds
  - Recommend optimal threshold for project
- Implement `analyze_scope_distribution(project_id, agent_id)`:
  - Report token distribution across scopes
  - Identify scope imbalances

### 9. Testing Strategy

**Unit tests**

Create `file:tests/context/test_task_scoped_context.py`:
- Test task context initialization and cleanup
- Test scope-aware tier assignment
- Test relevance scoring algorithm
- Test context summarization

Create `file:tests/context/test_relevance_filtering.py`:
- Test relevance score calculation
- Test threshold filtering
- Test session context filtering by task

**Integration tests**

Create `file:tests/integration/test_multi_task_context.py`:
- Test context isolation across 10 sequential tasks
- Verify Task 10 doesn't have Task 3 context in HOT tier
- Measure token reduction vs. baseline
- Verify task success rate maintained

**Performance tests**

Create `file:tests/performance/test_context_loading.py`:
- Benchmark context loading with 1000+ items across scopes
- Verify relevance filtering completes in <100ms
- Measure memory overhead of scope separation

### 10. Migration and Rollout

**Backward compatibility**

- Existing context items default to `context_scope='session'` and `task_id=NULL`
- Agents without task assignment continue using session-scoped context
- Gradual migration: enable task-scoped context per agent type (backend → frontend → test)

**Rollout phases**

1. **Phase 1**: Deploy schema changes, backfill existing data
2. **Phase 2**: Enable task-scoped context for backend workers (pilot)
3. **Phase 3**: Measure contamination reduction and token savings
4. **Phase 4**: Enable for all worker types if metrics positive
5. **Phase 5**: Deprecate pure session-scoped context (all items must have scope)

**Rollback plan**

- If task success rate drops >5%, disable task-scoped context
- Revert to session-scoped context by setting all `context_scope='session'`
- Investigate relevance threshold tuning before re-enabling

## Architecture Diagram

```mermaid
graph TD
    A[Worker Agent] -->|Task Start| B[Initialize Task Context]
    B --> C[Load Project Context]
    B --> D[Load Relevant Session Context]
    B --> E[Create Task Context Item]
    
    C --> F[Context Assembly]
    D --> F
    E --> F
    
    F --> G[LLM Call with Scoped Context]
    
    G -->|Task Complete| H[Cleanup Task Context]
    H --> I[Generate Task Summary]
    I --> J[Save to Session Context]
    H --> K[Delete Task-Scoped Items]
    
    L[Session End] --> M[Archive Session Context]
    M --> N[Generate Session Summary]
    N --> O[Clear Session Items]
    
    P[Project Context] -.->|Always Included| F
    Q[Session Context] -.->|Relevance Filtered| F
    R[Task Context] -.->|Full Inclusion| F
    
    style P fill:#90EE90
    style Q fill:#FFD700
    style R fill:#FF6B6B
```

## Context Scope Lifecycle

```mermaid
sequenceDiagram
    participant Agent
    participant ContextManager
    participant Database
    participant LLM
    
    Note over Agent,Database: Task 3: Authentication
    Agent->>ContextManager: initialize_task_context(task_3)
    ContextManager->>Database: load_context(scope=PROJECT)
    ContextManager->>Database: load_context(scope=SESSION, relevance>0.3)
    ContextManager->>Database: create_context_item(scope=TASK, task_id=3)
    ContextManager-->>Agent: Context ready
    
    Agent->>LLM: execute_task(context)
    LLM-->>Agent: Task complete
    
    Agent->>ContextManager: cleanup_task_context(task_3)
    ContextManager->>Database: summarize_task_context(task_id=3)
    ContextManager->>Database: save_context_item(scope=SESSION, summary)
    ContextManager->>Database: delete_context_items(task_id=3)
    
    Note over Agent,Database: Task 10: Data Export
    Agent->>ContextManager: initialize_task_context(task_10)
    ContextManager->>Database: load_context(scope=PROJECT)
    ContextManager->>Database: load_context(scope=SESSION, relevance>0.3)
    Note right of ContextManager: Auth context filtered out<br/>(low relevance to export)
    ContextManager->>Database: create_context_item(scope=TASK, task_id=10)
    ContextManager-->>Agent: Clean context (no Task 3 pollution)
```

## Success Criteria

| Metric | Baseline | Target | Measurement |
|--------|----------|--------|-------------|
| Cross-task contamination | ~60% (estimated) | <10% | % of HOT tier items from previous tasks |
| Token usage per task | Grows linearly | Stable | Average tokens/task across 10-task session |
| Task success rate | 90% | ≥90% | Maintain quality with reduced context |
| Context loading time | <50ms | <100ms | Scope-aware loading overhead |
| Token reduction | Baseline | 30-50% | Compare session vs. task-scoped context |

---

Execution Information

Branch: main
Commit: 360e111

New Plan

Observations

The current tiered memory system (file:codeframe/lib/context_manager.py) operates at the agent level with (project_id, agent_id) scoping. Context items accumulate across multiple tasks without task-level isolation, leading to potential cross-task contamination. The context_items table lacks a task_id column, and importance scoring (file:codeframe/lib/importance_scorer.py) considers age, access frequency, and item type—but not task relevance. Worker agents (file:codeframe/agents/worker_agent.py) maintain self.current_task but don't use it for context scoping. This architecture may cause stale context from previous tasks to persist in HOT/WARM tiers, wasting tokens and diluting relevance.

Approach

Conduct a measurement-first investigation to quantify cross-task contamination before committing to implementation. Implement Option C: Hybrid Approach only if investigation confirms the problem is significant. The hybrid model separates Project Context (architecture, conventions—always included), Session Context (accumulates within session, cleared at session end), and Task Context (fresh per task, aggressive management). This preserves cross-task learning while eliminating noise. Investigation will measure contamination rate, token waste, and task success correlation to justify engineering effort.

Implementation Plan

Phase 1: Investigation & Measurement (Prerequisite)

1.1 Implement contamination measurement tools

Create file:codeframe/lib/context_metrics.py:

• Implement measure_cross_task_contamination(project_id, agent_id, task_id):
  • Load all context items for agent
  • Identify items created before current task started
  • Calculate % of HOT tier items from previous tasks
  • Calculate % of tokens spent on pre-task items
  • Return contamination metrics: {hot_contamination_pct, token_contamination_pct, items_from_previous_tasks}
• Implement analyze_context_age_distribution(project_id, agent_id):
  • Group context items by creation time relative to current task
  • Return distribution: {same_task: count, previous_task: count, 2+_tasks_ago: count}
• Implement correlate_contamination_with_success(project_id, agent_type):
  • Sample 20+ multi-task sessions
  • For each task N, measure contamination at task start
  • Correlate contamination % with task success rate
  • Return correlation coefficient and trend analysis

1.2 Instrument worker agent for metrics collection

Modify file:codeframe/agents/worker_agent.py:

• Add _record_context_metrics(task) call at task start:
  • Measure contamination before task execution
  • Store metrics in database for analysis
• Add _analyze_context_effectiveness(task) call at task completion:
  • Measure which context items were actually used
  • Identify unused items that consumed tokens
  • Track for post-session analysis

1.3 Create measurement dashboard

Extend file:web-ui/src/components/context/ContextPanel.tsx:

• Add "Contamination Analysis" tab showing:
  • Cross-task contamination % over session duration
  • Token waste trend (tokens on irrelevant context)
  • Context age distribution (pie chart: same task vs. previous tasks)
  • Correlation scatter plot: contamination % vs. task success rate

1.4 Run investigation on production data

• Collect metrics from 50+ multi-task sessions (10+ tasks each)
• Measure baseline contamination rate
• Identify correlation between contamination and task failures
• Document findings in file:CONTEXT_INVESTIGATION_RESULTS.md

Success criteria for Phase 1:

• Contamination measurement tools implemented and tested
• Metrics collected from 50+ sessions
• Correlation analysis completed
• Decision gate: If contamination < 20% AND no correlation with failures → STOP (problem not significant)
• Decision gate: If contamination > 40% OR strong correlation with failures → PROCEED to Phase 2

Phase 2: Database Schema Changes (Conditional on Phase 1 Results)

2.1 Add task_id column to context_items table

Create migration file:codeframe/persistence/migrations/migration_007_add_task_scoped_context.py:

• Add task_id INTEGER NULL column to context_items table with foreign key to tasks(id) ON DELETE CASCADE
• Add context_scope TEXT NOT NULL DEFAULT 'session' column with CHECK constraint for values: 'project', 'session', 'task'
• Create composite index idx_context_agent_task_tier on (agent_id, task_id, current_tier) for fast task-scoped queries
• Create index idx_context_scope_tier on (context_scope, current_tier) for scope-based filtering
• Backfill existing records: set context_scope='session' and task_id=NULL for all existing context items

2.2 Update Database class methods

Modify file:codeframe/persistence/database.py:

• Update create_context_item() to accept optional task_id and context_scope parameters
• Update list_context_items() to support filtering by task_id and context_scope
• Add clear_task_context(project_id, agent_id, task_id) method to delete task-scoped items
• Add archive_task_context(project_id, agent_id, task_id) method to summarize and archive task context
• Update archive_cold_items() to respect context scope (don't archive project-scoped items)

2.3 Define context scope rules

Create file:codeframe/core/context_scopes.py:

• Define item type to default scope mapping (e.g., PRD_SECTION → PROJECT, TASK → TASK, CODE → TASK)

Phase 3: Relevance Filtering (Conditional on Phase 1 Results)

3.1 Implement relevance scoring

Create file:codeframe/lib/relevance_scorer.py:

• Implement calculate_relevance_score(context_item, current_task) function:
  • Use semantic similarity between context content and task description (cosine similarity of embeddings)
  • Consider item type relevance (CODE items more relevant if task involves same files)
  • Consider temporal proximity (items from recent tasks more relevant)
  • Return score in range [0.0, 1.0]
• Define relevance threshold: RELEVANCE_THRESHOLD = 0.3 (configurable, tuned from Phase 1 data)

3.2 Integrate relevance filtering into context manager

Extend file:codeframe/lib/context_manager.py:

• Add load_relevant_session_context(project_id, agent_id, task) method:
  • Load all session-scoped items for agent
  • Calculate relevance score for each item relative to current task
  • Filter items with relevance_score >= RELEVANCE_THRESHOLD
  • Return filtered list ordered by importance_score * relevance_score
• Update ContextManager to cache relevance scores per task (invalidate on task change)

3.3 Implement context summarization

Create file:codeframe/lib/context_summarizer.py:

• Implement summarize_task_context(context_items, task) function:
  • Extract task-specific learnings
  • Identify reusable patterns
  • Compress to 20% of original token count
  • Return summary for session context
• Implement summarize_session_context(context_items) function:
  • Group items by type and relevance
  • Extract key patterns and learnings
  • Compress to 20% of original token count
  • Return summary as single context item (scope=SESSION)

Phase 4: Task Lifecycle Integration (Conditional on Phase 1 Results)

4.1 Add task context initialization

Modify file:codeframe/agents/worker_agent.py:

• Update execute_task(task) method:
  • Call _initialize_task_context(task) at task start
  • Load project-scoped context (always included)
  • Load session-scoped context filtered by task relevance
  • Create initial task-scoped context item with task description
• Add _initialize_task_context(task) method:
  • Save task description as TASK type with context_scope='task' and task_id=task.id
  • Load project context (scope=PROJECT, tier=HOT)
  • Load relevant session context (scope=SESSION, relevance_score > threshold)

4.2 Add task context cleanup

Modify file:codeframe/agents/worker_agent.py:

• Update complete_task(task, project_root) method:
  • Call _cleanup_task_context(task) after quality gates pass
  • Archive task summary to session context
  • Clear task-scoped items
• Add _cleanup_task_context(task) method:
  • Generate task summary (key learnings, patterns discovered, files modified)
  • Save summary as session-scoped context item
  • Delete all task-scoped items for this task
  • Update session context importance scores

4.3 Add session-level context cleanup

Modify file:codeframe/core/session_manager.py:

• Add clear_session_context(project_id, agent_id) method:
  • Archive session summary (completed tasks, key learnings, patterns)
  • Delete all session-scoped context items
  • Retain project-scoped items
• Update save_session(state) to include session context summary
• Update load_session() to restore session context from summary

Phase 5: Context Assembly for LLM Calls (Conditional on Phase 1 Results)

5.1 Implement scope-aware context loading

Modify file:codeframe/agents/worker_agent.py:

• Update load_context(tier) method to become load_context_for_task(task, tier):
  • Load project-scoped context (all tiers, always included)
  • Load session-scoped context filtered by relevance to task
  • Load task-scoped context (all tiers, specific to current task)
  • Combine and deduplicate by content hash
  • Order by: scope priority (project > session > task), then importance score
• Add _build_llm_context(task) helper method:
  • Assemble context from all three scopes
  • Apply token budget allocation: 30% project, 30% session, 40% task
  • Truncate if exceeds budget, prioritizing higher importance scores

Phase 6: Configuration & Tuning (Conditional on Phase 1 Results)

6.1 Add configuration parameters

Create file:codeframe/config/context_config.py:

• Define RELEVANCE_THRESHOLD = 0.3 (adjustable per deployment, tuned from Phase 1)
• Define TOKEN_BUDGET_ALLOCATION = {'project': 0.3, 'session': 0.3, 'task': 0.4}
• Define TASK_SUMMARY_COMPRESSION_RATIO = 0.2 (target 20% of original size)
• Define SESSION_CONTEXT_MAX_AGE_DAYS = 7 (auto-archive old session items)

6.2 Add tuning utilities

Create file:codeframe/lib/context_tuner.py:

• Implement optimize_relevance_threshold(project_id):
  • Analyze historical task success rates vs. relevance thresholds
  • Recommend optimal threshold for project
• Implement analyze_scope_distribution(project_id, agent_id):
  • Report token distribution across scopes
  • Identify scope imbalances

Phase 7: Testing Strategy (Conditional on Phase 1 Results)

7.1 Unit tests

Create file:tests/context/test_task_scoped_context.py:

• Test task context initialization and cleanup
• Test scope-aware tier assignment
• Test context summarization

Create file:tests/context/test_relevance_filtering.py:

• Test relevance score calculation
• Test threshold filtering
• Test session context filtering by task

7.2 Integration tests

Create file:tests/integration/test_multi_task_context.py:

• Test context isolation across 10 sequential tasks
• Verify Task 10 doesn't have Task 3 context in HOT tier
• Measure token reduction vs. baseline
• Verify task success rate maintained

7.3 Performance tests

Create file:tests/performance/test_context_loading.py:

• Benchmark context loading with 1000+ items across scopes
• Verify relevance filtering completes in <100ms
• Measure memory overhead of scope separation

Phase 8: Rollout & Monitoring (Conditional on Phase 1 Results)

8.1 Backward compatibility

• Existing context items default to context_scope='session' and task_id=NULL
• Agents without task assignment continue using session-scoped context
• Gradual migration: enable task-scoped context per agent type (backend → frontend → test)

8.2 Rollout phases

1. Phase 1 (Investigation): Measure contamination, collect data, make go/no-go decision
2. Phase 2 (Pilot): If go decision, deploy schema changes and enable for backend workers
3. Phase 3 (Validation): Measure contamination reduction and token savings
4. Phase 4 (Rollout): Enable for all worker types if metrics positive
5. Phase 5 (Deprecation): Deprecate pure session-scoped context (all items must have scope)

8.3 Rollback plan

• If task success rate drops >5%, disable task-scoped context
• Revert to session-scoped context by setting all context_scope='session'
• Investigate relevance threshold tuning before re-enabling

Decision Gate: Phase 1 Results

PROCEED to Phase 2-8 if:

• Cross-task contamination > 40% (significant noise in context)
• OR strong correlation (r > 0.3) between contamination and task failures
• OR token waste > 30% (paying for irrelevant context)

STOP if:

• Cross-task contamination < 20% (acceptable noise level)
• AND no correlation with task failures
• AND token waste < 10% (acceptable overhead)

In the STOP case, document findings and monitor for future degradation.

Success Criteria (Post-Phase 1 Decision)

If proceeding to implementation:

Metric	Baseline	Target	Measurement
Cross-task contamination	Measured in Phase 1	<10%	% of HOT tier items from previous tasks
Token usage per task	Measured in Phase 1	Stable	Average tokens/task across 10-task session
Task success rate	Measured in Phase 1	≥ baseline	Maintain quality with reduced context
Context loading time	<50ms	<100ms	Scope-aware loading overhead
Token reduction	Measured in Phase 1	30-50%	Compare session vs. task-scoped context

Architecture Diagram (Post-Implementation)

graph TD
    A[Worker Agent] -->|Task Start| B[Initialize Task Context]
    B --> C[Load Project Context]
    B --> D[Load Relevant Session Context]
    B --> E[Create Task Context Item]
    
    C --> F[Context Assembly]
    D --> F
    E --> F
    
    F --> G[LLM Call with Scoped Context]
    
    G -->|Task Complete| H[Cleanup Task Context]
    H --> I[Generate Task Summary]
    I --> J[Save to Session Context]
    H --> K[Delete Task-Scoped Items]
    
    L[Session End] --> M[Archive Session Context]
    M --> N[Generate Session Summary]
    N --> O[Clear Session Items]
    
    P[Project Context] -.->|Always Included| F
    Q[Session Context] -.->|Relevance Filtered| F
    R[Task Context] -.->|Full Inclusion| F
    
    style P fill:#90EE90
    style Q fill:#FFD700
    style R fill:#FF6B6B

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current tiered memory system (`file:codeframe/lib/context_manager.py`) operates at the agent level with `(project_id, agent_id)` scoping. Context items accumulate across multiple tasks without task-level isolation, leading to potential cross-task contamination. The `context_items` table lacks a `task_id` column, and importance scoring (`file:codeframe/lib/importance_scorer.py`) considers age, access frequency, and item type—but not task relevance. Worker agents (`file:codeframe/agents/worker_agent.py`) maintain `self.current_task` but don't use it for context scoping. This architecture may cause stale context from previous tasks to persist in HOT/WARM tiers, wasting tokens and diluting relevance.

## Approach

Conduct a **measurement-first investigation** to quantify cross-task contamination before committing to implementation. Implement **Option C: Hybrid Approach** only if investigation confirms the problem is significant. The hybrid model separates **Project Context** (architecture, conventions—always included), **Session Context** (accumulates within session, cleared at session end), and **Task Context** (fresh per task, aggressive management). This preserves cross-task learning while eliminating noise. Investigation will measure contamination rate, token waste, and task success correlation to justify engineering effort.

## Implementation Plan

### Phase 1: Investigation & Measurement (Prerequisite)

**1.1 Implement contamination measurement tools**

Create `file:codeframe/lib/context_metrics.py`:
- Implement `measure_cross_task_contamination(project_id, agent_id, task_id)`:
  - Load all context items for agent
  - Identify items created before current task started
  - Calculate % of HOT tier items from previous tasks
  - Calculate % of tokens spent on pre-task items
  - Return contamination metrics: `{hot_contamination_pct, token_contamination_pct, items_from_previous_tasks}`
- Implement `analyze_context_age_distribution(project_id, agent_id)`:
  - Group context items by creation time relative to current task
  - Return distribution: `{same_task: count, previous_task: count, 2+_tasks_ago: count}`
- Implement `correlate_contamination_with_success(project_id, agent_type)`:
  - Sample 20+ multi-task sessions
  - For each task N, measure contamination at task start
  - Correlate contamination % with task success rate
  - Return correlation coefficient and trend analysis

**1.2 Instrument worker agent for metrics collection**

Modify `file:codeframe/agents/worker_agent.py`:
- Add `_record_context_metrics(task)` call at task start:
  - Measure contamination before task execution
  - Store metrics in database for analysis
- Add `_analyze_context_effectiveness(task)` call at task completion:
  - Measure which context items were actually used
  - Identify unused items that consumed tokens
  - Track for post-session analysis

**1.3 Create measurement dashboard**

Extend `file:web-ui/src/components/context/ContextPanel.tsx`:
- Add "Contamination Analysis" tab showing:
  - Cross-task contamination % over session duration
  - Token waste trend (tokens on irrelevant context)
  - Context age distribution (pie chart: same task vs. previous tasks)
  - Correlation scatter plot: contamination % vs. task success rate

**1.4 Run investigation on production data**

- Collect metrics from 50+ multi-task sessions (10+ tasks each)
- Measure baseline contamination rate
- Identify correlation between contamination and task failures
- Document findings in `file:CONTEXT_INVESTIGATION_RESULTS.md`

**Success criteria for Phase 1:**
- [ ] Contamination measurement tools implemented and tested
- [ ] Metrics collected from 50+ sessions
- [ ] Correlation analysis completed
- [ ] Decision gate: If contamination < 20% AND no correlation with failures → STOP (problem not significant)
- [ ] Decision gate: If contamination > 40% OR strong correlation with failures → PROCEED to Phase 2

### Phase 2: Database Schema Changes (Conditional on Phase 1 Results)

**2.1 Add task_id column to context_items table**

Create migration `file:codeframe/persistence/migrations/migration_007_add_task_scoped_context.py`:
- Add `task_id INTEGER NULL` column to `context_items` table with foreign key to `tasks(id)` ON DELETE CASCADE
- Add `context_scope TEXT NOT NULL DEFAULT 'session'` column with CHECK constraint for values: `'project'`, `'session'`, `'task'`
- Create composite index `idx_context_agent_task_tier` on `(agent_id, task_id, current_tier)` for fast task-scoped queries
- Create index `idx_context_scope_tier` on `(context_scope, current_tier)` for scope-based filtering
- Backfill existing records: set `context_scope='session'` and `task_id=NULL` for all existing context items

**2.2 Update Database class methods**

Modify `file:codeframe/persistence/database.py`:
- Update `create_context_item()` to accept optional `task_id` and `context_scope` parameters
- Update `list_context_items()` to support filtering by `task_id` and `context_scope`
- Add `clear_task_context(project_id, agent_id, task_id)` method to delete task-scoped items
- Add `archive_task_context(project_id, agent_id, task_id)` method to summarize and archive task context
- Update `archive_cold_items()` to respect context scope (don't archive project-scoped items)

**2.3 Define context scope rules**

Create `file:codeframe/core/context_scopes.py`:
- Define item type to default scope mapping (e.g., `PRD_SECTION` → `PROJECT`, `TASK` → `TASK`, `CODE` → `TASK`)

### Phase 3: Relevance Filtering (Conditional on Phase 1 Results)

**3.1 Implement relevance scoring**

Create `file:codeframe/lib/relevance_scorer.py`:
- Implement `calculate_relevance_score(context_item, current_task)` function:
  - Use semantic similarity between context content and task description (cosine similarity of embeddings)
  - Consider item type relevance (CODE items more relevant if task involves same files)
  - Consider temporal proximity (items from recent tasks more relevant)
  - Return score in range [0.0, 1.0]
- Define relevance threshold: `RELEVANCE_THRESHOLD = 0.3` (configurable, tuned from Phase 1 data)

**3.2 Integrate relevance filtering into context manager**

Extend `file:codeframe/lib/context_manager.py`:
- Add `load_relevant_session_context(project_id, agent_id, task)` method:
  - Load all session-scoped items for agent
  - Calculate relevance score for each item relative to current task
  - Filter items with `relevance_score >= RELEVANCE_THRESHOLD`
  - Return filtered list ordered by `importance_score * relevance_score`
- Update `ContextManager` to cache relevance scores per task (invalidate on task change)

**3.3 Implement context summarization**

Create `file:codeframe/lib/context_summarizer.py`:
- Implement `summarize_task_context(context_items, task)` function:
  - Extract task-specific learnings
  - Identify reusable patterns
  - Compress to 20% of original token count
  - Return summary for session context
- Implement `summarize_session_context(context_items)` function:
  - Group items by type and relevance
  - Extract key patterns and learnings
  - Compress to 20% of original token count
  - Return summary as single context item (scope=SESSION)

### Phase 4: Task Lifecycle Integration (Conditional on Phase 1 Results)

**4.1 Add task context initialization**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `execute_task(task)` method:
  - Call `_initialize_task_context(task)` at task start
  - Load project-scoped context (always included)
  - Load session-scoped context filtered by task relevance
  - Create initial task-scoped context item with task description
- Add `_initialize_task_context(task)` method:
  - Save task description as `TASK` type with `context_scope='task'` and `task_id=task.id`
  - Load project context (scope=PROJECT, tier=HOT)
  - Load relevant session context (scope=SESSION, relevance_score > threshold)

**4.2 Add task context cleanup**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `complete_task(task, project_root)` method:
  - Call `_cleanup_task_context(task)` after quality gates pass
  - Archive task summary to session context
  - Clear task-scoped items
- Add `_cleanup_task_context(task)` method:
  - Generate task summary (key learnings, patterns discovered, files modified)
  - Save summary as session-scoped context item
  - Delete all task-scoped items for this task
  - Update session context importance scores

**4.3 Add session-level context cleanup**

Modify `file:codeframe/core/session_manager.py`:
- Add `clear_session_context(project_id, agent_id)` method:
  - Archive session summary (completed tasks, key learnings, patterns)
  - Delete all session-scoped context items
  - Retain project-scoped items
- Update `save_session(state)` to include session context summary
- Update `load_session()` to restore session context from summary

### Phase 5: Context Assembly for LLM Calls (Conditional on Phase 1 Results)

**5.1 Implement scope-aware context loading**

Modify `file:codeframe/agents/worker_agent.py`:
- Update `load_context(tier)` method to become `load_context_for_task(task, tier)`:
  - Load project-scoped context (all tiers, always included)
  - Load session-scoped context filtered by relevance to task
  - Load task-scoped context (all tiers, specific to current task)
  - Combine and deduplicate by content hash
  - Order by: scope priority (project > session > task), then importance score
- Add `_build_llm_context(task)` helper method:
  - Assemble context from all three scopes
  - Apply token budget allocation: 30% project, 30% session, 40% task
  - Truncate if exceeds budget, prioritizing higher importance scores

### Phase 6: Configuration & Tuning (Conditional on Phase 1 Results)

**6.1 Add configuration parameters**

Create `file:codeframe/config/context_config.py`:
- Define `RELEVANCE_THRESHOLD = 0.3` (adjustable per deployment, tuned from Phase 1)
- Define `TOKEN_BUDGET_ALLOCATION = {'project': 0.3, 'session': 0.3, 'task': 0.4}`
- Define `TASK_SUMMARY_COMPRESSION_RATIO = 0.2` (target 20% of original size)
- Define `SESSION_CONTEXT_MAX_AGE_DAYS = 7` (auto-archive old session items)

**6.2 Add tuning utilities**

Create `file:codeframe/lib/context_tuner.py`:
- Implement `optimize_relevance_threshold(project_id)`:
  - Analyze historical task success rates vs. relevance thresholds
  - Recommend optimal threshold for project
- Implement `analyze_scope_distribution(project_id, agent_id)`:
  - Report token distribution across scopes
  - Identify scope imbalances

### Phase 7: Testing Strategy (Conditional on Phase 1 Results)

**7.1 Unit tests**

Create `file:tests/context/test_task_scoped_context.py`:
- Test task context initialization and cleanup
- Test scope-aware tier assignment
- Test context summarization

Create `file:tests/context/test_relevance_filtering.py`:
- Test relevance score calculation
- Test threshold filtering
- Test session context filtering by task

**7.2 Integration tests**

Create `file:tests/integration/test_multi_task_context.py`:
- Test context isolation across 10 sequential tasks
- Verify Task 10 doesn't have Task 3 context in HOT tier
- Measure token reduction vs. baseline
- Verify task success rate maintained

**7.3 Performance tests**

Create `file:tests/performance/test_context_loading.py`:
- Benchmark context loading with 1000+ items across scopes
- Verify relevance filtering completes in <100ms
- Measure memory overhead of scope separation

### Phase 8: Rollout & Monitoring (Conditional on Phase 1 Results)

**8.1 Backward compatibility**

- Existing context items default to `context_scope='session'` and `task_id=NULL`
- Agents without task assignment continue using session-scoped context
- Gradual migration: enable task-scoped context per agent type (backend → frontend → test)

**8.2 Rollout phases**

1. **Phase 1 (Investigation)**: Measure contamination, collect data, make go/no-go decision
2. **Phase 2 (Pilot)**: If go decision, deploy schema changes and enable for backend workers
3. **Phase 3 (Validation)**: Measure contamination reduction and token savings
4. **Phase 4 (Rollout)**: Enable for all worker types if metrics positive
5. **Phase 5 (Deprecation)**: Deprecate pure session-scoped context (all items must have scope)

**8.3 Rollback plan**

- If task success rate drops >5%, disable task-scoped context
- Revert to session-scoped context by setting all `context_scope='session'`
- Investigate relevance threshold tuning before re-enabling

## Decision Gate: Phase 1 Results

**PROCEED to Phase 2-8 if:**
- Cross-task contamination > 40% (significant noise in context)
- OR strong correlation (r > 0.3) between contamination and task failures
- OR token waste > 30% (paying for irrelevant context)

**STOP if:**
- Cross-task contamination < 20% (acceptable noise level)
- AND no correlation with task failures
- AND token waste < 10% (acceptable overhead)

In the STOP case, document findings and monitor for future degradation.

## Success Criteria (Post-Phase 1 Decision)

If proceeding to implementation:

| Metric | Baseline | Target | Measurement |
|--------|----------|--------|-------------|
| Cross-task contamination | Measured in Phase 1 | <10% | % of HOT tier items from previous tasks |
| Token usage per task | Measured in Phase 1 | Stable | Average tokens/task across 10-task session |
| Task success rate | Measured in Phase 1 | ≥ baseline | Maintain quality with reduced context |
| Context loading time | <50ms | <100ms | Scope-aware loading overhead |
| Token reduction | Measured in Phase 1 | 30-50% | Compare session vs. task-scoped context |

## Architecture Diagram (Post-Implementation)

```mermaid
graph TD
    A[Worker Agent] -->|Task Start| B[Initialize Task Context]
    B --> C[Load Project Context]
    B --> D[Load Relevant Session Context]
    B --> E[Create Task Context Item]
    
    C --> F[Context Assembly]
    D --> F
    E --> F
    
    F --> G[LLM Call with Scoped Context]
    
    G -->|Task Complete| H[Cleanup Task Context]
    H --> I[Generate Task Summary]
    I --> J[Save to Session Context]
    H --> K[Delete Task-Scoped Items]
    
    L[Session End] --> M[Archive Session Context]
    M --> N[Generate Session Summary]
    N --> O[Clear Session Items]
    
    P[Project Context] -.->|Always Included| F
    Q[Session Context] -.->|Relevance Filtered| F
    R[Task Context] -.->|Full Inclusion| F
    
    style P fill:#90EE90
    style Q fill:#FFD700
    style R fill:#FF6B6B
```

---

Execution Information

Branch: main
Commit: 1260477