[Phase 4] Implement Procedural Memory for Agent Learning

[frankbria]

Summary

CodeFRAME has semantic memory (project facts) and episodic memory (task history), but lacks procedural memory—"how I learned to do things." When agents discover effective patterns, that learning should persist.

Background: Memory Types

From Philipp Schmid's "Memory in Agents":

Semantic Memory ("What"): Retaining specific facts, concepts, and structured knowledge about users, e.g. user prefers Python over JavaScript.

Episodic Memory ("When" and "Where"): Recall past events or specific experiences to accomplish tasks by looking at past interactions.

Procedural Memory ("How"): Internalized rules and instructions on how an agent performs tasks, e.g. "My summaries are too long" if multiple users provide feedback to be shorter.

CodeFRAME likely has:

• ✅ Semantic: Project architecture, tech stack, conventions (in CLAUDE.md, context tiers)
• ✅ Episodic: Task history, blocker resolutions, test results
• ❓ Procedural: ???

What Procedural Memory Looks Like

Examples of procedural learning:

Discovery During Task	Procedural Memory Entry
"This test kept failing until I mocked the database"	"When testing DB-dependent code in this project, always mock the connection"
"The API rate limits at 100 req/s"	"Add exponential backoff when calling external API X"
"TypeScript strict mode catches errors early"	"Run tsc --strict before committing TypeScript changes"
"Human preferred shorter summaries in blockers"	"Keep blocker descriptions under 3 sentences"

This isn't just "what happened" (episodic)—it's "how to do things better" extracted from experience.

Why This Matters

Without procedural memory:

• Agents repeat the same mistakes across sessions
• Successful patterns aren't codified
• Human guidance (blocker resolutions) is forgotten
• Each task starts from zero knowledge of "how this codebase works"

With procedural memory:

• Agent gets better over time
• Patterns that work are reinforced
• Human teaching persists
• Compound improvement across sessions

Implementation Approaches

Option A: Explicit Procedure Extraction

After each task or blocker resolution, extract procedural learning:

def extract_procedure(task_result, blocker_resolutions):
    prompt = f"""
    Task completed: {task_result.summary}
    Challenges encountered: {task_result.challenges}
    Solutions that worked: {task_result.solutions}
    Human guidance received: {blocker_resolutions}
    
    Extract 0-3 procedural rules that should guide future similar tasks.
    Format: IF [condition] THEN [action] BECAUSE [reason]
    Only extract genuinely reusable patterns, not task-specific details.
    """
    return llm.extract(prompt)

Option B: Pattern Detection from History

Periodically analyze episodic memory for patterns:

def detect_patterns(episodic_memory):
    # Find repeated failure → success patterns
    # Identify common blocker types and their resolutions
    # Extract recurring human guidance themes

Option C: Human-Labeled Procedures

When humans resolve blockers, option to mark as "remember this":

Blocker: "How should I handle API authentication?"
Resolution: "Use the refresh token pattern in auth_utils.py"
☑️ Remember this for future similar situations

Option D: Procedure Library Integration

Integrate with external procedure library (like Claude Code's CLAUDE.md pattern):

• Procedures stored in version-controlled file
• Agents can read and propose additions
• Human reviews procedure additions

Storage and Retrieval

procedural_memory/
├── project_procedures.md      # Project-specific learned procedures
├── codebase_patterns.json     # Detected code patterns
└── human_guidance_log.json    # Extracted from blocker resolutions

# Retrieval: Include relevant procedures in context based on task type
def get_procedures_for_task(task):
    task_type = classify_task(task)  # "testing", "api_integration", "frontend", etc.
    return procedure_store.query(task_type)

Success Criteria

• Defined procedural memory schema
• Implemented extraction mechanism (Option A, B, or C)
• Procedures included in relevant task contexts
• Measured: fewer repeated mistakes across sessions
• Measured: faster task completion for similar task types

Metrics

• Procedure extraction rate: Procedures learned per N tasks
• Procedure utilization: % of tasks that receive relevant procedural context
• Repeat mistake rate: Same failure pattern occurring across sessions (should decrease)
• Human re-guidance rate: Humans answering similar blockers repeatedly (should decrease)

Integration with Existing Systems

• Blocker system: Rich source of human guidance → procedural extraction
• Quality gates: Failures could trigger procedure review ("did we have a procedure for this?")
• Tiered memory: Procedures could be a distinct tier (always HOT when relevant)
• Checkpoints: Procedure library should be part of checkpoint snapshots

References

• Memory in Agents - Philipp Schmid
• Learning from experience patterns in reinforcement learning
• CLAUDE.md as a form of human-curated procedural memory
• Mem0, Letta frameworks for memory implementation patterns

[traycerai]

Plan

Observations

CodeFRAME has a well-structured memory architecture with semantic memory (context tiers, PRD) and episodic memory (task history, blocker resolutions, test results). The existing memory table already includes a 'pattern' category that's underutilized. The blocker system captures rich human guidance through question/answer pairs, and the correction_attempts table tracks self-correction patterns. The tiered context system (HOT/WARM/COLD) provides a proven model for importance-based storage. The migration system (file:codeframe/persistence/migrations/) follows a clear pattern for schema evolution, and the database layer (file:codeframe/persistence/database.py) has comprehensive CRUD operations.

Approach

Procedural memory is a Phase 4 (Future) feature that represents sophisticated AI/ML learning beyond v1/v2 scope. The implementation plan establishes the architectural foundation and patterns that will support procedural memory when prioritized, without requiring changes to core systems in the near term. The strategy combines Option A (explicit extraction after task completion) with Option C (human-labeled procedures during blocker resolution) as the most pragmatic path. Store procedures in the existing memory table using the 'pattern' category, enhanced with structured metadata. Design extraction hooks for future integration into task completion and blocker resolution workflows, but defer implementation. Use the proven importance scoring algorithm from context management (file:codeframe/lib/importance_scorer.py) as the model for future procedure prioritization. This approach preserves existing infrastructure while creating a clear roadmap for implementation when resources allow.

Implementation Steps

Phase 1: Foundation & Schema Design (No Migration Yet)

Design the procedural memory schema and models without implementing database migration yet:

1. Schema design for future migration:

   • Enhance memory table with columns: procedure_type, condition_pattern, action_pattern, reasoning, confidence_score, usage_count, success_count, last_used_at, source_type, source_id
   • Procedure types: 'test_pattern', 'api_pattern', 'error_resolution', 'human_guidance', 'quality_gate', 'general'
   • Source types: 'blocker_resolution', 'task_completion', 'correction_attempt', 'manual'
   • Confidence scoring: 0.0-1.0 based on success rate (initial 0.5, +0.1 per success, -0.2 per failure)
   • Indexes: idx_memory_procedures, idx_memory_confidence, idx_memory_last_used

2. Document schema design in file:specs/073-procedural-memory/data-model.md:

   • Detailed column definitions and constraints
   • Confidence scoring algorithm
   • Index strategy for retrieval performance
   • Migration strategy (when to implement)

3. Add Pydantic models to file:codeframe/core/models.py (for future use):

   • ProcedureType enum
   • ProcedureSourceType enum
   • ProceduralMemory model with validation
   • ProcedureExtractionResult model
   • ProcedureMatch model for retrieval
   • Mark as "Future: Phase 4" in docstrings

Phase 2: Extraction Engine Design (Deferred Implementation)

Design the procedural extraction system without implementing yet:

1. ProceduralExtractor class design (document in file:specs/073-procedural-memory/spec.md):

   • Methods: extract_from_blocker(), extract_from_task(), extract_from_correction()
   • LLM integration: Use Claude to identify reusable patterns
   • Validation: Ensure patterns are genuinely reusable, not task-specific
   • Confidence scoring: Initial 0.5, +0.1 per success, -0.2 per failure, archive <0.2

2. Extraction prompt template (document in file:specs/073-procedural-memory/examples.md):

   Given this resolved issue:
   - Context: {task/blocker context}
   - Problem: {what went wrong}
   - Solution: {what worked}
   - Outcome: {test results, quality gates}
   
   Extract 0-2 procedural rules that should guide future similar situations.
   Format: IF [condition] THEN [action] BECAUSE [reason]
   Only extract genuinely reusable patterns, not task-specific details.
   

3. Validation rules (document in file:specs/073-procedural-memory/spec.md):

   • Reject task-specific details (e.g., "fix bug in file X")
   • Require generalizable conditions (e.g., "when testing DB-dependent code")
   • Require actionable steps (e.g., "mock the database connection")
   • Require reasoning (e.g., "tests kept failing until database was mocked")

Phase 3: Database Operations Design (Deferred Implementation)

Design database operations for future implementation:

1. Procedure CRUD operations (document in file:specs/073-procedural-memory/spec.md):

   • create_procedure() - Store new procedure with initial confidence 0.5
   • get_procedure() - Retrieve single procedure with usage history
   • list_procedures() - List with filtering by type, confidence, recency
   • update_procedure_usage() - Update confidence score and usage stats
   • archive_low_confidence_procedures() - Soft delete procedures <0.2 confidence

2. Procedure retrieval strategy (document in file:specs/073-procedural-memory/spec.md):

   • Keyword matching on condition_pattern (v1)
   • Future: Semantic similarity using embeddings
   • Filter by procedure_type and task context
   • Rank by confidence_score and last_used_at

3. Analytics queries (document in file:specs/073-procedural-memory/spec.md):

   • Procedures learned per N tasks
   • Procedures by type and confidence distribution
   • Usage trends over time
   • Success rate by procedure type

Phase 4: Integration Points Design (Deferred Implementation)

Design integration points without modifying core systems:

1. Task completion integration (document in file:specs/073-procedural-memory/spec.md):

   • Hook point: After quality gates pass in complete_task()
   • Action: Call extract_from_task() to learn from successful completion
   • Tracking: Record which procedures were applied and their success
   • No changes to file:codeframe/agents/worker_agent.py until Phase 4 implementation

2. Blocker resolution integration (document in file:specs/073-procedural-memory/spec.md):

   • Hook point: When blocker is marked RESOLVED with human answer
   • Action: Option to mark answer as "remember this" (human-labeled, Option C)
   • Extraction: Extract procedure from human guidance if marked
   • No changes to file:codeframe/persistence/database.py until Phase 4 implementation

3. Context loading integration (document in file:specs/073-procedural-memory/spec.md):

   • Hook point: When building agent context in context_manager.py
   • Action: Include top 5 relevant procedures in system prompt
   • Tier assignment: High confidence (>0.7) → HOT, medium → WARM, low → COLD
   • No changes to file:codeframe/lib/context_manager.py until Phase 4 implementation

Phase 5: API Endpoints Design (Deferred Implementation)

Design API endpoints for future implementation:

1. Endpoints (document in file:specs/073-procedural-memory/spec.md):

   • GET /api/projects/{id}/procedures - List with filtering and pagination
   • GET /api/procedures/{id} - Get single procedure with usage history
   • POST /api/procedures - Manually create procedure (human-labeled)
   • PUT /api/procedures/{id} - Update procedure details
   • DELETE /api/procedures/{id} - Archive procedure
   • GET /api/projects/{id}/procedures/stats - Analytics and trends

2. Response models (document in file:specs/073-procedural-memory/spec.md):

   • ProcedureListResponse with pagination
   • ProcedureDetailResponse with usage history
   • ProcedureStatsResponse with metrics

Phase 6: Frontend Dashboard Design (Deferred Implementation)

Design UI components for future implementation:

1. ProceduresPanel.tsx - Main container:

   • Tabs: "Active Procedures", "Recently Used", "Low Confidence"
   • Filter by procedure_type and confidence range
   • Sort by confidence, usage_count, last_used_at

2. ProcedureCard.tsx - Individual procedure display:

   • Shows: IF condition → THEN action (BECAUSE reasoning)
   • Confidence badge with color coding
   • Usage stats: "Applied 12 times, 10 successful (83%)"
   • Source link: "Learned from Blocker Implement TaskTreeView dependency rendering #42"

3. ProcedureEditor.tsx - Manual procedure creation:

   • Form fields: procedure_type, condition, action, reasoning
   • Validation: ensure patterns are generalizable

4. ProcedureStatsChart.tsx - Analytics visualization:

   • Procedures learned over time
   • Procedures by type distribution
   • Top procedures by usage

Phase 7: Testing Strategy (Deferred Implementation)

Design comprehensive testing approach:

1. Unit tests (document in file:specs/073-procedural-memory/spec.md):

   • Extraction logic: 50 tests
   • Database operations: 40 tests
   • Confidence scoring: 20 tests
   • Validation rules: 15 tests

2. Integration tests:

   • Task completion → procedure extraction: 20 tests
   • Blocker resolution → procedure extraction: 15 tests
   • Context loading → procedure inclusion: 15 tests

3. API tests:

   • CRUD endpoints: 25 tests
   • Filtering and pagination: 15 tests
   • Analytics queries: 10 tests

4. Frontend tests:

   • Component rendering: 20 tests
   • User interactions: 15 tests
   • Data visualization: 10 tests

Target: 200+ tests, 90%+ coverage when implemented

Phase 8: Documentation

Create specification documents in file:specs/073-procedural-memory/:

1. spec.md - Complete specification:

   • Requirements and success criteria
   • Architecture and design decisions
   • Integration points with existing systems
   • API endpoint specifications
   • Data model and schema

2. data-model.md - Schema design:

   • Memory table enhancements
   • Column definitions and constraints
   • Confidence scoring algorithm
   • Index strategy
   • Migration plan

3. examples.md - Real-world examples:

   • Example procedures from different domains
   • Extraction prompt examples
   • Validation rule examples
   • UI mockups and screenshots

4. implementation-roadmap.md - Phase 4 roadmap:

   • Prioritized implementation order
   • Estimated effort per component
   • Dependencies and blockers
   • Success metrics and measurement approach

Update file:CLAUDE.md:

1. Add "Procedural Memory System (Phase 4)" section:
   • Overview of the feature
   • Current status: Design phase, deferred implementation
   • Integration points with existing systems
   • Future work and roadmap

Update file:PRD.md:

1. Add procedural memory to memory types section:
   • Explain the three memory types: semantic, episodic, procedural
   • Note that procedural memory is Phase 4 future work
   • Link to detailed specification

Architecture Overview

Procedural memory operates as a learning system that extracts generalizable patterns from task execution and human guidance, stores them with confidence scoring, and provides them to agents during future task execution.

Key Design Principles:

• Non-invasive: No changes to core systems until Phase 4 implementation
• Confidence-based: Procedures are scored based on success rate and refined over time
• Human-labeled: Humans can explicitly mark important guidance as procedures
• Retrieval-optimized: Procedures are matched to task context and included in agent prompts
• Measurable: Track extraction rate, utilization rate, and impact on task success

Data Flow (Future Implementation):

1. Task completion or blocker resolution triggers extraction
2. LLM identifies reusable patterns from context
3. Validation ensures patterns are generalizable
4. Procedures stored in memory table with confidence 0.5
5. Future tasks retrieve matching procedures
6. Agent applies procedures; success/failure updates confidence
7. Low-confidence procedures (<0.2) are archived

Integration Points (Future Implementation):

• Task completion: Extract after quality gates pass
• Blocker resolution: Extract from human guidance (human-labeled)
• Context loading: Include top 5 relevant procedures in agent prompt
• Confidence tracking: Update scores based on application outcomes

Success Metrics (Phase 4 Implementation)

When procedural memory is implemented in Phase 4, measure:

Metric	Target	Measurement
Procedure extraction rate	0.3-0.5 procedures per completed task	Count procedures created / tasks completed
Procedure utilization	60%+ of tasks receive relevant procedures	Count tasks with procedures loaded / total tasks
Repeat mistake rate	Decrease by 40% after 20 tasks	Track same blocker type recurring
Human re-guidance rate	Decrease by 50% after 30 tasks	Track similar blocker questions
Procedure confidence	Average >0.6 after 10 uses	Average confidence_score of used procedures
Test coverage	90%+ for procedural memory code	pytest coverage report

Future Implementation Roadmap

Phase 4 Implementation Order (when prioritized):

1. Database migration (1-2 days)

   • Create migration_010_procedural_memory.py
   • Add columns and indexes to memory table
   • Deploy and verify schema

2. Extraction engine (3-4 days)

   • Implement ProceduralExtractor class
   • LLM integration for pattern extraction
   • Validation rules for reusable patterns

3. Database operations (2-3 days)

   • Implement CRUD methods
   • Retrieval and matching logic
   • Confidence scoring updates

4. Integration hooks (2-3 days)

   • Task completion integration
   • Blocker resolution integration
   • Context loading integration

5. API endpoints (2-3 days)

   • Implement REST endpoints
   • Response models and validation
   • Error handling

6. Frontend dashboard (4-5 days)

   • Components for viewing procedures
   • Manual procedure creation UI
   • Analytics visualization

7. Testing (3-4 days)

   • Unit tests for extraction logic
   • Integration tests for workflows
   • API and frontend tests

8. Documentation (1-2 days)

   • Update CLAUDE.md and PRD.md
   • Create user guides
   • Document procedures for common patterns

Estimated Total Effort: 18-26 days (3-4 weeks)

Current Status

Phase 1 (Design): ✅ Complete

• Schema design documented
• Models defined
• Integration points identified
• Examples and use cases documented

Phase 2-8 (Implementation): ⏳ Deferred to Phase 4

• No code changes to core systems
• Specification documents created
• Ready for implementation when prioritized

Import In IDE

🤖 Prompt for AI Agents

## Observations

CodeFRAME has a well-structured memory architecture with semantic memory (context tiers, PRD) and episodic memory (task history, blocker resolutions, test results). The existing `memory` table already includes a 'pattern' category that's underutilized. The blocker system captures rich human guidance through question/answer pairs, and the `correction_attempts` table tracks self-correction patterns. The tiered context system (HOT/WARM/COLD) provides a proven model for importance-based storage. The migration system (file:codeframe/persistence/migrations/) follows a clear pattern for schema evolution, and the database layer (file:codeframe/persistence/database.py) has comprehensive CRUD operations.

## Approach

Procedural memory is a Phase 4 (Future) feature that represents sophisticated AI/ML learning beyond v1/v2 scope. The implementation plan establishes the architectural foundation and patterns that will support procedural memory when prioritized, without requiring changes to core systems in the near term. The strategy combines Option A (explicit extraction after task completion) with Option C (human-labeled procedures during blocker resolution) as the most pragmatic path. Store procedures in the existing `memory` table using the 'pattern' category, enhanced with structured metadata. Design extraction hooks for future integration into task completion and blocker resolution workflows, but defer implementation. Use the proven importance scoring algorithm from context management (file:codeframe/lib/importance_scorer.py) as the model for future procedure prioritization. This approach preserves existing infrastructure while creating a clear roadmap for implementation when resources allow.

## Implementation Steps

### Phase 1: Foundation & Schema Design (No Migration Yet)

Design the procedural memory schema and models without implementing database migration yet:

1. **Schema design** for future migration:
   - Enhance `memory` table with columns: `procedure_type`, `condition_pattern`, `action_pattern`, `reasoning`, `confidence_score`, `usage_count`, `success_count`, `last_used_at`, `source_type`, `source_id`
   - Procedure types: 'test_pattern', 'api_pattern', 'error_resolution', 'human_guidance', 'quality_gate', 'general'
   - Source types: 'blocker_resolution', 'task_completion', 'correction_attempt', 'manual'
   - Confidence scoring: 0.0-1.0 based on success rate (initial 0.5, +0.1 per success, -0.2 per failure)
   - Indexes: `idx_memory_procedures`, `idx_memory_confidence`, `idx_memory_last_used`

2. **Document schema design** in file:specs/073-procedural-memory/data-model.md:
   - Detailed column definitions and constraints
   - Confidence scoring algorithm
   - Index strategy for retrieval performance
   - Migration strategy (when to implement)

3. **Add Pydantic models** to file:codeframe/core/models.py (for future use):
   - `ProcedureType` enum
   - `ProcedureSourceType` enum  
   - `ProceduralMemory` model with validation
   - `ProcedureExtractionResult` model
   - `ProcedureMatch` model for retrieval
   - Mark as "Future: Phase 4" in docstrings

### Phase 2: Extraction Engine Design (Deferred Implementation)

Design the procedural extraction system without implementing yet:

1. **ProceduralExtractor class design** (document in file:specs/073-procedural-memory/spec.md):
   - Methods: `extract_from_blocker()`, `extract_from_task()`, `extract_from_correction()`
   - LLM integration: Use Claude to identify reusable patterns
   - Validation: Ensure patterns are genuinely reusable, not task-specific
   - Confidence scoring: Initial 0.5, +0.1 per success, -0.2 per failure, archive <0.2

2. **Extraction prompt template** (document in file:specs/073-procedural-memory/examples.md):
   ```
   Given this resolved issue:
   - Context: {task/blocker context}
   - Problem: {what went wrong}
   - Solution: {what worked}
   - Outcome: {test results, quality gates}
   
   Extract 0-2 procedural rules that should guide future similar situations.
   Format: IF [condition] THEN [action] BECAUSE [reason]
   Only extract genuinely reusable patterns, not task-specific details.
   ```

3. **Validation rules** (document in file:specs/073-procedural-memory/spec.md):
   - Reject task-specific details (e.g., "fix bug in file X")
   - Require generalizable conditions (e.g., "when testing DB-dependent code")
   - Require actionable steps (e.g., "mock the database connection")
   - Require reasoning (e.g., "tests kept failing until database was mocked")

### Phase 3: Database Operations Design (Deferred Implementation)

Design database operations for future implementation:

1. **Procedure CRUD operations** (document in file:specs/073-procedural-memory/spec.md):
   - `create_procedure()` - Store new procedure with initial confidence 0.5
   - `get_procedure()` - Retrieve single procedure with usage history
   - `list_procedures()` - List with filtering by type, confidence, recency
   - `update_procedure_usage()` - Update confidence score and usage stats
   - `archive_low_confidence_procedures()` - Soft delete procedures <0.2 confidence

2. **Procedure retrieval strategy** (document in file:specs/073-procedural-memory/spec.md):
   - Keyword matching on condition_pattern (v1)
   - Future: Semantic similarity using embeddings
   - Filter by procedure_type and task context
   - Rank by confidence_score and last_used_at

3. **Analytics queries** (document in file:specs/073-procedural-memory/spec.md):
   - Procedures learned per N tasks
   - Procedures by type and confidence distribution
   - Usage trends over time
   - Success rate by procedure type

### Phase 4: Integration Points Design (Deferred Implementation)

Design integration points without modifying core systems:

1. **Task completion integration** (document in file:specs/073-procedural-memory/spec.md):
   - Hook point: After quality gates pass in `complete_task()`
   - Action: Call `extract_from_task()` to learn from successful completion
   - Tracking: Record which procedures were applied and their success
   - No changes to file:codeframe/agents/worker_agent.py until Phase 4 implementation

2. **Blocker resolution integration** (document in file:specs/073-procedural-memory/spec.md):
   - Hook point: When blocker is marked RESOLVED with human answer
   - Action: Option to mark answer as "remember this" (human-labeled, Option C)
   - Extraction: Extract procedure from human guidance if marked
   - No changes to file:codeframe/persistence/database.py until Phase 4 implementation

3. **Context loading integration** (document in file:specs/073-procedural-memory/spec.md):
   - Hook point: When building agent context in context_manager.py
   - Action: Include top 5 relevant procedures in system prompt
   - Tier assignment: High confidence (>0.7) → HOT, medium → WARM, low → COLD
   - No changes to file:codeframe/lib/context_manager.py until Phase 4 implementation

### Phase 5: API Endpoints Design (Deferred Implementation)

Design API endpoints for future implementation:

1. **Endpoints** (document in file:specs/073-procedural-memory/spec.md):
   - `GET /api/projects/{id}/procedures` - List with filtering and pagination
   - `GET /api/procedures/{id}` - Get single procedure with usage history
   - `POST /api/procedures` - Manually create procedure (human-labeled)
   - `PUT /api/procedures/{id}` - Update procedure details
   - `DELETE /api/procedures/{id}` - Archive procedure
   - `GET /api/projects/{id}/procedures/stats` - Analytics and trends

2. **Response models** (document in file:specs/073-procedural-memory/spec.md):
   - `ProcedureListResponse` with pagination
   - `ProcedureDetailResponse` with usage history
   - `ProcedureStatsResponse` with metrics

### Phase 6: Frontend Dashboard Design (Deferred Implementation)

Design UI components for future implementation:

1. **ProceduresPanel.tsx** - Main container:
   - Tabs: "Active Procedures", "Recently Used", "Low Confidence"
   - Filter by procedure_type and confidence range
   - Sort by confidence, usage_count, last_used_at

2. **ProcedureCard.tsx** - Individual procedure display:
   - Shows: IF condition → THEN action (BECAUSE reasoning)
   - Confidence badge with color coding
   - Usage stats: "Applied 12 times, 10 successful (83%)"
   - Source link: "Learned from Blocker #42"

3. **ProcedureEditor.tsx** - Manual procedure creation:
   - Form fields: procedure_type, condition, action, reasoning
   - Validation: ensure patterns are generalizable

4. **ProcedureStatsChart.tsx** - Analytics visualization:
   - Procedures learned over time
   - Procedures by type distribution
   - Top procedures by usage

### Phase 7: Testing Strategy (Deferred Implementation)

Design comprehensive testing approach:

1. **Unit tests** (document in file:specs/073-procedural-memory/spec.md):
   - Extraction logic: 50 tests
   - Database operations: 40 tests
   - Confidence scoring: 20 tests
   - Validation rules: 15 tests

2. **Integration tests**:
   - Task completion → procedure extraction: 20 tests
   - Blocker resolution → procedure extraction: 15 tests
   - Context loading → procedure inclusion: 15 tests

3. **API tests**:
   - CRUD endpoints: 25 tests
   - Filtering and pagination: 15 tests
   - Analytics queries: 10 tests

4. **Frontend tests**:
   - Component rendering: 20 tests
   - User interactions: 15 tests
   - Data visualization: 10 tests

**Target: 200+ tests, 90%+ coverage when implemented**

### Phase 8: Documentation

Create specification documents in file:specs/073-procedural-memory/:

1. **spec.md** - Complete specification:
   - Requirements and success criteria
   - Architecture and design decisions
   - Integration points with existing systems
   - API endpoint specifications
   - Data model and schema

2. **data-model.md** - Schema design:
   - Memory table enhancements
   - Column definitions and constraints
   - Confidence scoring algorithm
   - Index strategy
   - Migration plan

3. **examples.md** - Real-world examples:
   - Example procedures from different domains
   - Extraction prompt examples
   - Validation rule examples
   - UI mockups and screenshots

4. **implementation-roadmap.md** - Phase 4 roadmap:
   - Prioritized implementation order
   - Estimated effort per component
   - Dependencies and blockers
   - Success metrics and measurement approach

Update file:CLAUDE.md:

1. Add "Procedural Memory System (Phase 4)" section:
   - Overview of the feature
   - Current status: Design phase, deferred implementation
   - Integration points with existing systems
   - Future work and roadmap

Update file:PRD.md:

1. Add procedural memory to memory types section:
   - Explain the three memory types: semantic, episodic, procedural
   - Note that procedural memory is Phase 4 future work
   - Link to detailed specification

## Architecture Overview

Procedural memory operates as a learning system that extracts generalizable patterns from task execution and human guidance, stores them with confidence scoring, and provides them to agents during future task execution.

**Key Design Principles:**
- **Non-invasive**: No changes to core systems until Phase 4 implementation
- **Confidence-based**: Procedures are scored based on success rate and refined over time
- **Human-labeled**: Humans can explicitly mark important guidance as procedures
- **Retrieval-optimized**: Procedures are matched to task context and included in agent prompts
- **Measurable**: Track extraction rate, utilization rate, and impact on task success

**Data Flow (Future Implementation):**
1. Task completion or blocker resolution triggers extraction
2. LLM identifies reusable patterns from context
3. Validation ensures patterns are generalizable
4. Procedures stored in memory table with confidence 0.5
5. Future tasks retrieve matching procedures
6. Agent applies procedures; success/failure updates confidence
7. Low-confidence procedures (<0.2) are archived

**Integration Points (Future Implementation):**
- Task completion: Extract after quality gates pass
- Blocker resolution: Extract from human guidance (human-labeled)
- Context loading: Include top 5 relevant procedures in agent prompt
- Confidence tracking: Update scores based on application outcomes

## Success Metrics (Phase 4 Implementation)

When procedural memory is implemented in Phase 4, measure:

| Metric | Target | Measurement |
|--------|--------|-------------|
| Procedure extraction rate | 0.3-0.5 procedures per completed task | Count procedures created / tasks completed |
| Procedure utilization | 60%+ of tasks receive relevant procedures | Count tasks with procedures loaded / total tasks |
| Repeat mistake rate | Decrease by 40% after 20 tasks | Track same blocker type recurring |
| Human re-guidance rate | Decrease by 50% after 30 tasks | Track similar blocker questions |
| Procedure confidence | Average >0.6 after 10 uses | Average confidence_score of used procedures |
| Test coverage | 90%+ for procedural memory code | pytest coverage report |

## Future Implementation Roadmap

**Phase 4 Implementation Order (when prioritized):**

1. **Database migration** (1-2 days)
   - Create migration_010_procedural_memory.py
   - Add columns and indexes to memory table
   - Deploy and verify schema

2. **Extraction engine** (3-4 days)
   - Implement ProceduralExtractor class
   - LLM integration for pattern extraction
   - Validation rules for reusable patterns

3. **Database operations** (2-3 days)
   - Implement CRUD methods
   - Retrieval and matching logic
   - Confidence scoring updates

4. **Integration hooks** (2-3 days)
   - Task completion integration
   - Blocker resolution integration
   - Context loading integration

5. **API endpoints** (2-3 days)
   - Implement REST endpoints
   - Response models and validation
   - Error handling

6. **Frontend dashboard** (4-5 days)
   - Components for viewing procedures
   - Manual procedure creation UI
   - Analytics visualization

7. **Testing** (3-4 days)
   - Unit tests for extraction logic
   - Integration tests for workflows
   - API and frontend tests

8. **Documentation** (1-2 days)
   - Update CLAUDE.md and PRD.md
   - Create user guides
   - Document procedures for common patterns

**Estimated Total Effort:** 18-26 days (3-4 weeks)

## Current Status

**Phase 1 (Design):** ✅ Complete
- Schema design documented
- Models defined
- Integration points identified
- Examples and use cases documented

**Phase 2-8 (Implementation):** ⏳ Deferred to Phase 4
- No code changes to core systems
- Specification documents created
- Ready for implementation when prioritized

---

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

CodeFRAME has a well-structured memory architecture with semantic memory (context tiers, PRD) and episodic memory (task history, blocker resolutions, test results). The existing memory table already includes a 'pattern' category that's underutilized. The blocker system captures rich human guidance through question/answer pairs, and the correction_attempts table tracks self-correction patterns. The tiered context system (HOT/WARM/COLD) provides a proven model for importance-based storage. The migration system (file:codeframe/persistence/migrations/) follows a clear pattern for schema evolution, and the database layer (file:codeframe/persistence/database.py) has comprehensive CRUD operations.

Approach

Implement procedural memory as a hybrid extraction system that combines Option A (explicit extraction after task completion) with Option B (pattern detection from blocker resolutions). Store procedures in the existing memory table using the 'pattern' category, enhanced with structured metadata. Integrate extraction hooks into the task completion workflow (file:codeframe/agents/worker_agent.py complete_task()) and blocker resolution flow (file:codeframe/persistence/database.py blocker methods). Use the proven importance scoring algorithm from context management (file:codeframe/lib/importance_scorer.py) to prioritize procedures. Provide procedures to agents via the existing context loading mechanism, treating them as a specialized context item type. This approach leverages existing infrastructure while adding minimal new complexity.

Implementation Steps

Phase 1: Database Schema & Models (Migration 010)

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

1. Enhance memory table with new columns:

   • Add procedure_type TEXT CHECK(procedure_type IN ('test_pattern', 'api_pattern', 'error_resolution', 'human_guidance', 'quality_gate', 'general'))
   • Add condition_pattern TEXT (the "IF" part - when to apply)
   • Add action_pattern TEXT (the "THEN" part - what to do)
   • Add reasoning TEXT (the "BECAUSE" part - why it works)
   • Add confidence_score FLOAT (0.0-1.0, based on success rate)
   • Add usage_count INTEGER (how many times applied)
   • Add success_count INTEGER (how many times it worked)
   • Add last_used_at TIMESTAMP
   • Add source_type TEXT CHECK(source_type IN ('blocker_resolution', 'task_completion', 'correction_attempt', 'manual'))
   • Add source_id INTEGER (references blocker_id, task_id, etc.)

2. Create indexes for efficient retrieval:

   • idx_memory_procedures ON memory(category, procedure_type) WHERE category='pattern'
   • idx_memory_confidence ON memory(confidence_score DESC, usage_count DESC) WHERE category='pattern'
   • idx_memory_last_used ON memory(last_used_at DESC) WHERE category='pattern'

3. Add Pydantic models to file:codeframe/core/models.py:

   • ProcedureType enum
   • ProcedureSourceType enum
   • ProceduralMemory model with validation
   • ProcedureExtractionResult model
   • ProcedureMatch model for retrieval

Phase 2: Extraction Engine

Create file:codeframe/lib/procedural_extractor.py:

1. ProceduralExtractor class with methods:

   • extract_from_blocker(blocker_id) - Extract procedure from resolved blocker
   • extract_from_task(task_id) - Extract procedure from completed task with quality gate results
   • extract_from_correction(correction_attempt_id) - Extract procedure from self-correction loop
   • _call_llm_for_extraction(context) - Use Claude to identify reusable patterns
   • _validate_procedure(procedure) - Ensure procedure is genuinely reusable, not task-specific

2. Extraction prompt template:

   Given this resolved issue:
   - Context: {task/blocker context}
   - Problem: {what went wrong}
   - Solution: {what worked}
   - Outcome: {test results, quality gates}
   
   Extract 0-2 procedural rules that should guide future similar situations.
   Format: IF [condition] THEN [action] BECAUSE [reason]
   Only extract genuinely reusable patterns, not task-specific details.
   

3. Confidence scoring logic:

   • Initial confidence: 0.5 (unproven)
   • Increase by 0.1 per successful application (max 0.95)
   • Decrease by 0.2 per failed application (min 0.1)
   • Archive procedures with confidence < 0.2

Phase 3: Database Operations

Extend file:codeframe/persistence/database.py with methods:

1. Procedure CRUD:

   • create_procedure(project_id, procedure_type, condition, action, reasoning, source_type, source_id) - Returns procedure_id
   • get_procedure(procedure_id) - Returns ProceduralMemory model
   • list_procedures(project_id, procedure_type=None, min_confidence=0.3, limit=50) - Returns list sorted by confidence
   • update_procedure_usage(procedure_id, success) - Updates usage_count, success_count, confidence_score, last_used_at
   • archive_low_confidence_procedures(project_id, threshold=0.2) - Soft delete procedures that don't work

2. Procedure retrieval:

   • find_matching_procedures(project_id, task_context, limit=5) - Use semantic similarity (simple keyword matching initially, can enhance with embeddings later)
   • get_procedures_for_task_type(project_id, task_type, limit=10) - Filter by procedure_type

3. Analytics:

   • get_procedure_stats(project_id) - Returns counts by type, average confidence, usage trends

Phase 4: Integration with Task Completion

Modify file:codeframe/agents/worker_agent.py:

1. In complete_task() method (after quality gates pass):

   # Extract procedural learning
   if quality_result.passed:
       extractor = ProceduralExtractor(db=self.db)
       procedures = await extractor.extract_from_task(task.id)
       for proc in procedures:
           logger.info(f"Learned procedure: {proc.condition_pattern} → {proc.action_pattern}")

2. In execute_task() method (before starting work):

   # Load relevant procedures
   procedures = self.db.find_matching_procedures(
       project_id=task.project_id,
       task_context=task.description,
       limit=5
   )
   # Include procedures in agent context/prompt

3. Track procedure application:

   • When agent applies a procedure, call update_procedure_usage(procedure_id, success=True/False)
   • Success determined by: task completed without blockers, quality gates passed

Phase 5: Integration with Blocker Resolution

Modify file:codeframe/persistence/database.py blocker methods:

1. In resolve_blocker() method (after setting status to RESOLVED):

   # Extract procedural learning from human guidance
   extractor = ProceduralExtractor(db=self)
   procedures = await extractor.extract_from_blocker(blocker_id)
   # Procedures automatically stored in memory table

2. Blocker extraction logic:

   • Only extract from SYNC blockers (critical decisions)
   • Require answer length > 50 chars (substantial guidance)
   • Skip generic answers like "ok", "done", "resolved"

Phase 6: API Endpoints

Create file:codeframe/ui/routers/procedures.py:

1. Endpoints:

   • GET /api/projects/{id}/procedures - List procedures with filtering (type, min_confidence)
   • GET /api/procedures/{id} - Get single procedure details
   • POST /api/procedures - Manually create procedure (human-labeled)
   • PUT /api/procedures/{id} - Update procedure (edit condition/action/reasoning)
   • DELETE /api/procedures/{id} - Archive procedure
   • GET /api/projects/{id}/procedures/stats - Get analytics

2. Response models:

   • ProcedureListResponse with pagination
   • ProcedureDetailResponse with usage history
   • ProcedureStatsResponse with charts data

Phase 7: Frontend Dashboard

Create file:web-ui/src/components/procedures/:

1. ProceduresPanel.tsx - Main container:

   • Tabs: "Active Procedures", "Recently Used", "Low Confidence"
   • Filter by procedure_type
   • Sort by confidence, usage_count, last_used_at

2. ProcedureCard.tsx - Individual procedure display:

   • Shows: IF condition → THEN action (BECAUSE reasoning)
   • Confidence badge with color coding (green >0.7, yellow 0.4-0.7, red <0.4)
   • Usage stats: "Applied 12 times, 10 successful (83%)"
   • Source link: "Learned from Blocker Implement TaskTreeView dependency rendering #42" or "Learned from Task 📝 Add docstrings to 013-context-panel-integration #27"

3. ProcedureEditor.tsx - Manual procedure creation:

   • Form fields: procedure_type, condition, action, reasoning
   • Validation: ensure patterns are specific enough

4. ProcedureStatsChart.tsx - Analytics visualization:

   • Procedures learned over time (line chart)
   • Procedures by type (pie chart)
   • Top 10 most used procedures (bar chart)

Phase 8: Context Integration

Modify file:codeframe/lib/context_manager.py:

1. Add procedure loading to context:

   • When building agent context, include top 5 relevant procedures
   • Format procedures as markdown in system prompt:

     ## Learned Procedures
     
     1. **Testing Database Code**
        IF: Testing code that depends on database
        THEN: Mock the database connection
        BECAUSE: Tests kept failing until database was mocked
        Confidence: 85% (applied 8 times, 7 successful)
     

2. Procedure tier assignment:

   • High confidence (>0.7) + recent use (<7 days) → HOT tier
   • Medium confidence (0.4-0.7) or older use → WARM tier
   • Low confidence (<0.4) → COLD tier (archived)

Phase 9: Testing

Create test files:

1. file:tests/lib/test_procedural_extractor.py (50 tests):

   • Test extraction from blockers, tasks, corrections
   • Test LLM prompt formatting
   • Test confidence scoring logic
   • Test procedure validation (reject task-specific patterns)

2. file:tests/persistence/test_procedures.py (40 tests):

   • Test CRUD operations
   • Test procedure matching/retrieval
   • Test confidence updates
   • Test archival of low-confidence procedures

3. file:tests/agents/test_worker_agent_procedures.py (30 tests):

   • Test procedure extraction during task completion
   • Test procedure loading during task execution
   • Test procedure application tracking

4. file:tests/api/test_procedures_api.py (25 tests):

   • Test all API endpoints
   • Test pagination, filtering, sorting
   • Test manual procedure creation

5. file:web-ui/tests/components/ProceduresPanel.test.tsx (20 tests):

   • Test component rendering
   • Test filtering and sorting
   • Test procedure card display

Target: 165 tests, 90%+ coverage

Phase 10: Documentation

Update documentation files:

1. file:CLAUDE.md - Add "Procedural Memory System" section:

   • Overview of how procedures are learned
   • Examples of procedure patterns
   • How to manually create procedures
   • Confidence scoring explanation

2. file:PRD.md - Add procedural memory to memory types:

   • Update section 5 (Core System Overview)
   • Add E2E workflow for procedure learning

3. file:specs/073-procedural-memory/ - Create spec directory:

   • spec.md - Requirements and design
   • plan.md - This implementation plan
   • data-model.md - Schema and models
   • examples.md - Real-world procedure examples

Architecture Diagram

sequenceDiagram
    participant Agent as Worker Agent
    participant QG as Quality Gates
    participant Ext as Procedural Extractor
    participant DB as Database
    participant LLM as Claude API
    
    Agent->>Agent: execute_task(task)
    Agent->>DB: find_matching_procedures(task_context)
    DB-->>Agent: [relevant procedures]
    Agent->>Agent: Include procedures in context
    
    Agent->>QG: complete_task(task)
    QG->>QG: Run quality gates
    
    alt Quality gates pass
        QG-->>Agent: success
        Agent->>Ext: extract_from_task(task_id)
        Ext->>DB: Get task context + results
        DB-->>Ext: task data
        Ext->>LLM: Extract reusable patterns
        LLM-->>Ext: [procedures]
        Ext->>DB: create_procedure(...)
        DB-->>Ext: procedure_id
    else Quality gates fail
        QG->>DB: create_blocker(...)
        DB-->>QG: blocker_id
        Note over Agent: Human resolves blocker
        Agent->>DB: resolve_blocker(answer)
        DB->>Ext: extract_from_blocker(blocker_id)
        Ext->>LLM: Extract from human guidance
        LLM-->>Ext: [procedures]
        Ext->>DB: create_procedure(...)
    end
    
    Note over Agent,DB: Future tasks benefit from learned procedures

Loading

Data Flow

graph TD
    A[Task Completion] -->|success| B[Procedural Extractor]
    C[Blocker Resolution] -->|human answer| B
    D[Correction Attempt] -->|fix worked| B
    
    B -->|LLM analysis| E[Extract Patterns]
    E -->|validate| F{Reusable?}
    
    F -->|yes| G[Store in memory table]
    F -->|no| H[Discard]
    
    G --> I[Confidence: 0.5]
    
    J[Future Task] -->|load context| K[Find Matching Procedures]
    K -->|retrieve| G
    G -->|top 5| L[Include in Agent Context]
    
    L --> M[Agent Applies Procedure]
    M -->|success| N[Update: confidence +0.1]
    M -->|failure| O[Update: confidence -0.2]
    
    N --> G
    O --> G
    
    O -->|confidence < 0.2| P[Archive Procedure]

Loading

Success Metrics

Metric	Target	Measurement
Procedure extraction rate	0.3-0.5 procedures per completed task	Count procedures created / tasks completed
Procedure utilization	60%+ of tasks receive relevant procedures	Count tasks with procedures loaded / total tasks
Repeat mistake rate	Decrease by 40% after 20 tasks	Track same blocker type recurring
Human re-guidance rate	Decrease by 50% after 30 tasks	Track similar blocker questions
Procedure confidence	Average >0.6 after 10 uses	Average confidence_score of used procedures
Test coverage	90%+ for procedural memory code	pytest coverage report

Integration Points

System	Integration Method	File Location
Task Completion	Hook in complete_task()	file:codeframe/agents/worker_agent.py
Blocker Resolution	Hook in resolve_blocker()	file:codeframe/persistence/database.py
Context Loading	Add to context building	file:codeframe/lib/context_manager.py
Quality Gates	Extract from failures	file:codeframe/lib/quality_gates.py
Checkpoints	Include procedures in snapshots	file:codeframe/lib/checkpoint_manager.py
Dashboard	New procedures panel	file:web-ui/src/components/procedures/

Import In IDE

🤖 Prompt for AI Agents

## Observations

CodeFRAME has a well-structured memory architecture with semantic memory (context tiers, PRD) and episodic memory (task history, blocker resolutions, test results). The existing `memory` table already includes a 'pattern' category that's underutilized. The blocker system captures rich human guidance through question/answer pairs, and the `correction_attempts` table tracks self-correction patterns. The tiered context system (HOT/WARM/COLD) provides a proven model for importance-based storage. The migration system (file:codeframe/persistence/migrations/) follows a clear pattern for schema evolution, and the database layer (file:codeframe/persistence/database.py) has comprehensive CRUD operations.

## Approach

Implement procedural memory as a **hybrid extraction system** that combines Option A (explicit extraction after task completion) with Option B (pattern detection from blocker resolutions). Store procedures in the existing `memory` table using the 'pattern' category, enhanced with structured metadata. Integrate extraction hooks into the task completion workflow (file:codeframe/agents/worker_agent.py `complete_task()`) and blocker resolution flow (file:codeframe/persistence/database.py blocker methods). Use the proven importance scoring algorithm from context management (file:codeframe/lib/importance_scorer.py) to prioritize procedures. Provide procedures to agents via the existing context loading mechanism, treating them as a specialized context item type. This approach leverages existing infrastructure while adding minimal new complexity.

## Implementation Steps

### Phase 1: Database Schema & Models (Migration 010)

Create migration file `file:codeframe/persistence/migrations/migration_010_procedural_memory.py`:

1. **Enhance memory table** with new columns:
   - Add `procedure_type` TEXT CHECK(procedure_type IN ('test_pattern', 'api_pattern', 'error_resolution', 'human_guidance', 'quality_gate', 'general'))
   - Add `condition_pattern` TEXT (the "IF" part - when to apply)
   - Add `action_pattern` TEXT (the "THEN" part - what to do)
   - Add `reasoning` TEXT (the "BECAUSE" part - why it works)
   - Add `confidence_score` FLOAT (0.0-1.0, based on success rate)
   - Add `usage_count` INTEGER (how many times applied)
   - Add `success_count` INTEGER (how many times it worked)
   - Add `last_used_at` TIMESTAMP
   - Add `source_type` TEXT CHECK(source_type IN ('blocker_resolution', 'task_completion', 'correction_attempt', 'manual'))
   - Add `source_id` INTEGER (references blocker_id, task_id, etc.)

2. **Create indexes** for efficient retrieval:
   - `idx_memory_procedures` ON memory(category, procedure_type) WHERE category='pattern'
   - `idx_memory_confidence` ON memory(confidence_score DESC, usage_count DESC) WHERE category='pattern'
   - `idx_memory_last_used` ON memory(last_used_at DESC) WHERE category='pattern'

3. **Add Pydantic models** to file:codeframe/core/models.py:
   - `ProcedureType` enum
   - `ProcedureSourceType` enum  
   - `ProceduralMemory` model with validation
   - `ProcedureExtractionResult` model
   - `ProcedureMatch` model for retrieval

### Phase 2: Extraction Engine

Create file:codeframe/lib/procedural_extractor.py:

1. **ProceduralExtractor class** with methods:
   - `extract_from_blocker(blocker_id)` - Extract procedure from resolved blocker
   - `extract_from_task(task_id)` - Extract procedure from completed task with quality gate results
   - `extract_from_correction(correction_attempt_id)` - Extract procedure from self-correction loop
   - `_call_llm_for_extraction(context)` - Use Claude to identify reusable patterns
   - `_validate_procedure(procedure)` - Ensure procedure is genuinely reusable, not task-specific

2. **Extraction prompt template**:
   ```
   Given this resolved issue:
   - Context: {task/blocker context}
   - Problem: {what went wrong}
   - Solution: {what worked}
   - Outcome: {test results, quality gates}
   
   Extract 0-2 procedural rules that should guide future similar situations.
   Format: IF [condition] THEN [action] BECAUSE [reason]
   Only extract genuinely reusable patterns, not task-specific details.
   ```

3. **Confidence scoring logic**:
   - Initial confidence: 0.5 (unproven)
   - Increase by 0.1 per successful application (max 0.95)
   - Decrease by 0.2 per failed application (min 0.1)
   - Archive procedures with confidence < 0.2

### Phase 3: Database Operations

Extend file:codeframe/persistence/database.py with methods:

1. **Procedure CRUD**:
   - `create_procedure(project_id, procedure_type, condition, action, reasoning, source_type, source_id)` - Returns procedure_id
   - `get_procedure(procedure_id)` - Returns ProceduralMemory model
   - `list_procedures(project_id, procedure_type=None, min_confidence=0.3, limit=50)` - Returns list sorted by confidence
   - `update_procedure_usage(procedure_id, success)` - Updates usage_count, success_count, confidence_score, last_used_at
   - `archive_low_confidence_procedures(project_id, threshold=0.2)` - Soft delete procedures that don't work

2. **Procedure retrieval**:
   - `find_matching_procedures(project_id, task_context, limit=5)` - Use semantic similarity (simple keyword matching initially, can enhance with embeddings later)
   - `get_procedures_for_task_type(project_id, task_type, limit=10)` - Filter by procedure_type

3. **Analytics**:
   - `get_procedure_stats(project_id)` - Returns counts by type, average confidence, usage trends

### Phase 4: Integration with Task Completion

Modify file:codeframe/agents/worker_agent.py:

1. **In `complete_task()` method** (after quality gates pass):
   ```python
   # Extract procedural learning
   if quality_result.passed:
       extractor = ProceduralExtractor(db=self.db)
       procedures = await extractor.extract_from_task(task.id)
       for proc in procedures:
           logger.info(f"Learned procedure: {proc.condition_pattern} → {proc.action_pattern}")
   ```

2. **In `execute_task()` method** (before starting work):
   ```python
   # Load relevant procedures
   procedures = self.db.find_matching_procedures(
       project_id=task.project_id,
       task_context=task.description,
       limit=5
   )
   # Include procedures in agent context/prompt
   ```

3. **Track procedure application**:
   - When agent applies a procedure, call `update_procedure_usage(procedure_id, success=True/False)`
   - Success determined by: task completed without blockers, quality gates passed

### Phase 5: Integration with Blocker Resolution

Modify file:codeframe/persistence/database.py blocker methods:

1. **In `resolve_blocker()` method** (after setting status to RESOLVED):
   ```python
   # Extract procedural learning from human guidance
   extractor = ProceduralExtractor(db=self)
   procedures = await extractor.extract_from_blocker(blocker_id)
   # Procedures automatically stored in memory table
   ```

2. **Blocker extraction logic**:
   - Only extract from SYNC blockers (critical decisions)
   - Require answer length > 50 chars (substantial guidance)
   - Skip generic answers like "ok", "done", "resolved"

### Phase 6: API Endpoints

Create file:codeframe/ui/routers/procedures.py:

1. **Endpoints**:
   - `GET /api/projects/{id}/procedures` - List procedures with filtering (type, min_confidence)
   - `GET /api/procedures/{id}` - Get single procedure details
   - `POST /api/procedures` - Manually create procedure (human-labeled)
   - `PUT /api/procedures/{id}` - Update procedure (edit condition/action/reasoning)
   - `DELETE /api/procedures/{id}` - Archive procedure
   - `GET /api/projects/{id}/procedures/stats` - Get analytics

2. **Response models**:
   - `ProcedureListResponse` with pagination
   - `ProcedureDetailResponse` with usage history
   - `ProcedureStatsResponse` with charts data

### Phase 7: Frontend Dashboard

Create file:web-ui/src/components/procedures/:

1. **ProceduresPanel.tsx** - Main container:
   - Tabs: "Active Procedures", "Recently Used", "Low Confidence"
   - Filter by procedure_type
   - Sort by confidence, usage_count, last_used_at

2. **ProcedureCard.tsx** - Individual procedure display:
   - Shows: IF condition → THEN action (BECAUSE reasoning)
   - Confidence badge with color coding (green >0.7, yellow 0.4-0.7, red <0.4)
   - Usage stats: "Applied 12 times, 10 successful (83%)"
   - Source link: "Learned from Blocker #42" or "Learned from Task #27"

3. **ProcedureEditor.tsx** - Manual procedure creation:
   - Form fields: procedure_type, condition, action, reasoning
   - Validation: ensure patterns are specific enough

4. **ProcedureStatsChart.tsx** - Analytics visualization:
   - Procedures learned over time (line chart)
   - Procedures by type (pie chart)
   - Top 10 most used procedures (bar chart)

### Phase 8: Context Integration

Modify file:codeframe/lib/context_manager.py:

1. **Add procedure loading to context**:
   - When building agent context, include top 5 relevant procedures
   - Format procedures as markdown in system prompt:
     ```
     ## Learned Procedures
     
     1. **Testing Database Code**
        IF: Testing code that depends on database
        THEN: Mock the database connection
        BECAUSE: Tests kept failing until database was mocked
        Confidence: 85% (applied 8 times, 7 successful)
     ```

2. **Procedure tier assignment**:
   - High confidence (>0.7) + recent use (<7 days) → HOT tier
   - Medium confidence (0.4-0.7) or older use → WARM tier
   - Low confidence (<0.4) → COLD tier (archived)

### Phase 9: Testing

Create test files:

1. **file:tests/lib/test_procedural_extractor.py** (50 tests):
   - Test extraction from blockers, tasks, corrections
   - Test LLM prompt formatting
   - Test confidence scoring logic
   - Test procedure validation (reject task-specific patterns)

2. **file:tests/persistence/test_procedures.py** (40 tests):
   - Test CRUD operations
   - Test procedure matching/retrieval
   - Test confidence updates
   - Test archival of low-confidence procedures

3. **file:tests/agents/test_worker_agent_procedures.py** (30 tests):
   - Test procedure extraction during task completion
   - Test procedure loading during task execution
   - Test procedure application tracking

4. **file:tests/api/test_procedures_api.py** (25 tests):
   - Test all API endpoints
   - Test pagination, filtering, sorting
   - Test manual procedure creation

5. **file:web-ui/__tests__/components/ProceduresPanel.test.tsx** (20 tests):
   - Test component rendering
   - Test filtering and sorting
   - Test procedure card display

**Target: 165 tests, 90%+ coverage**

### Phase 10: Documentation

Update documentation files:

1. **file:CLAUDE.md** - Add "Procedural Memory System" section:
   - Overview of how procedures are learned
   - Examples of procedure patterns
   - How to manually create procedures
   - Confidence scoring explanation

2. **file:PRD.md** - Add procedural memory to memory types:
   - Update section 5 (Core System Overview)
   - Add E2E workflow for procedure learning

3. **file:specs/073-procedural-memory/** - Create spec directory:
   - `spec.md` - Requirements and design
   - `plan.md` - This implementation plan
   - `data-model.md` - Schema and models
   - `examples.md` - Real-world procedure examples

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Agent as Worker Agent
    participant QG as Quality Gates
    participant Ext as Procedural Extractor
    participant DB as Database
    participant LLM as Claude API
    
    Agent->>Agent: execute_task(task)
    Agent->>DB: find_matching_procedures(task_context)
    DB-->>Agent: [relevant procedures]
    Agent->>Agent: Include procedures in context
    
    Agent->>QG: complete_task(task)
    QG->>QG: Run quality gates
    
    alt Quality gates pass
        QG-->>Agent: success
        Agent->>Ext: extract_from_task(task_id)
        Ext->>DB: Get task context + results
        DB-->>Ext: task data
        Ext->>LLM: Extract reusable patterns
        LLM-->>Ext: [procedures]
        Ext->>DB: create_procedure(...)
        DB-->>Ext: procedure_id
    else Quality gates fail
        QG->>DB: create_blocker(...)
        DB-->>QG: blocker_id
        Note over Agent: Human resolves blocker
        Agent->>DB: resolve_blocker(answer)
        DB->>Ext: extract_from_blocker(blocker_id)
        Ext->>LLM: Extract from human guidance
        LLM-->>Ext: [procedures]
        Ext->>DB: create_procedure(...)
    end
    
    Note over Agent,DB: Future tasks benefit from learned procedures
```

## Data Flow

```mermaid
graph TD
    A[Task Completion] -->|success| B[Procedural Extractor]
    C[Blocker Resolution] -->|human answer| B
    D[Correction Attempt] -->|fix worked| B
    
    B -->|LLM analysis| E[Extract Patterns]
    E -->|validate| F{Reusable?}
    
    F -->|yes| G[Store in memory table]
    F -->|no| H[Discard]
    
    G --> I[Confidence: 0.5]
    
    J[Future Task] -->|load context| K[Find Matching Procedures]
    K -->|retrieve| G
    G -->|top 5| L[Include in Agent Context]
    
    L --> M[Agent Applies Procedure]
    M -->|success| N[Update: confidence +0.1]
    M -->|failure| O[Update: confidence -0.2]
    
    N --> G
    O --> G
    
    O -->|confidence < 0.2| P[Archive Procedure]
```

## Success Metrics

| Metric | Target | Measurement |
|--------|--------|-------------|
| Procedure extraction rate | 0.3-0.5 procedures per completed task | Count procedures created / tasks completed |
| Procedure utilization | 60%+ of tasks receive relevant procedures | Count tasks with procedures loaded / total tasks |
| Repeat mistake rate | Decrease by 40% after 20 tasks | Track same blocker type recurring |
| Human re-guidance rate | Decrease by 50% after 30 tasks | Track similar blocker questions |
| Procedure confidence | Average >0.6 after 10 uses | Average confidence_score of used procedures |
| Test coverage | 90%+ for procedural memory code | pytest coverage report |

## Integration Points

| System | Integration Method | File Location |
|--------|-------------------|---------------|
| Task Completion | Hook in `complete_task()` | file:codeframe/agents/worker_agent.py |
| Blocker Resolution | Hook in `resolve_blocker()` | file:codeframe/persistence/database.py |
| Context Loading | Add to context building | file:codeframe/lib/context_manager.py |
| Quality Gates | Extract from failures | file:codeframe/lib/quality_gates.py |
| Checkpoints | Include procedures in snapshots | file:codeframe/lib/checkpoint_manager.py |
| Dashboard | New procedures panel | file:web-ui/src/components/procedures/ |

---

Execution Information

Branch: main
Commit: 360e111

[frankbria]

Re-labeled from P3 to Future based on UX/UI committee review. Procedural memory is a sophisticated AI/ML feature that is beyond v1/v2 scope. This represents valuable future work but should not distract from core journey completion.