💾 Memory Management Guide

Learn how to effectively manage your project's memory system - the six files that serve as your project's persistent knowledge base throughout development.

🎯 Memory Management Goals

Effective memory management ensures:

• 📊 Accurate project state
• 🔄 Traceable decisions
• 📎 Clear requirements
• 🎯 Measurable progress
• 🛡️ Protected code registry

Without good management:

• 🚫 Lost requirements
• 🚫 Forgotten decisions
• 🚫 Unclear progress
• 🚫 Missing context

📁 Memory File Overview

/memory-bank/
├── σ₁: projectbrief.md      # Requirements & scope
├── σ₂: systemPatterns.md    # Architecture & patterns
├── σ₃: techContext.md       # Technology stack
├── σ₄: activeContext.md     # Current focus
├── σ₅: progress.md          # Status & milestones
├── σ₆: protection.md        # Protected regions
└── backups/                 # Automatic backups

📝 Managing Each Memory File

σ₁: Project Brief Management

Purpose: Central requirements document

Update Frequency: Low (milestone changes)

Key Sections to Maintain:

## 📋 Requirements
- [R₁] ACTIVE: User authentication required
- [R₂] ACTIVE: Data encryption mandatory
- [R₃] DEPRECATED: See [R₇] for updated requirement
- [R₇] ACTIVE: Enhanced data encryption with AES-256

Management Tasks:

1. Review weekly for accuracy
2. Mark deprecated requirements
3. Add new requirements with clear IDs
4. Update success criteria
5. Cross-reference implementations

Best Practices:

• Use consistent ID format (R₁, R₂...)
• Add creation/update dates
• Link to implementations
• Keep requirements atomic
• Version major changes

σ₂: System Patterns Management

Purpose: Architecture and design decisions

Update Frequency: Medium (design changes)

Key Sections to Maintain:

## 🏛️ Architecture Decisions
- [D₁] 2024-01-10: Chose microservices over monolith
  - Rationale: Scalability requirements [↗️σ₁:R₈]
  - Impact: Separate service deployment
  - Status: ACTIVE

- [D₂] 2024-01-15: JWT over sessions
  - Rationale: Stateless architecture
  - Supersedes: [D₁] partially
  - Status: ACTIVE

Management Tasks:

1. Document all architectural decisions
2. Track pattern implementations
3. Update component relationships
4. Version design changes
5. Link to requirements

Best Practices:

• Include decision date
• Document rationale
• Track superseded decisions
• Maintain pattern catalog
• Regular architecture reviews

σ₃: Tech Context Management

Purpose: Technology stack and environment

Update Frequency: Medium (stack changes)

Key Sections to Maintain:

## 📦 Dependencies
### Production
- express: ^4.18.0 ✅ (security updates current)
- jsonwebtoken: ^9.0.0 ⚠️ (update available: 9.0.1)
- bcrypt: ^5.1.0 ✅

### Development
- jest: ^29.0.0 ✅
- eslint: ^8.0.0 ⚠️ (config needs update)

Management Tasks:

1. Track dependency versions
2. Monitor security updates
3. Document environment configs
4. Update setup instructions
5. Track technical debt

Best Practices:

• Regular dependency audits
• Security update tracking
• Environment parity docs
• Configuration management
• Technical debt log

σ₄: Active Context Management

Purpose: Current focus and working context

Update Frequency: High (continuous)

Key Sections to Maintain:

## 🔮 Current Focus
Working on: JWT refresh token implementation
Started: 2024-01-15 10:00
Target: Complete by EOD

## 📝 Recent Changes
- ✅ Implemented token generation
- ✅ Added refresh endpoint
- ⏳ Working on token rotation
- 🔜 Need to add rate limiting

## 📎 Context References
### 📄 Active Files
- src/auth/jwt.service.ts 🟢 (actively editing)
- src/auth/refresh.ts 🟢 (implementing)
- tests/auth.test.ts 🟡 (will update)

Management Tasks:

1. Update focus at mode switches
2. Track work progress
3. Manage context references
4. Clear completed items
5. Archive old context

Best Practices:

• Update immediately
• Use status indicators
• Time-stamp entries
• Regular cleanup
• Context rotation

σ₅: Progress Management

Purpose: Track project status and milestones

Update Frequency: Medium (feature completion)

Key Sections to Maintain:

## 📈 Project Status
Overall: 65% complete
Sprint: 3 of 5

## 🎯 Milestones
- [M₁] ✅ Project Setup (100%) - Completed 2024-01-05
- [M₂] ⏳ Authentication (75%) - Due 2024-01-20
  - [F₁] ✅ User registration
  - [F₂] ✅ Login endpoint
  - [F₃] ⏳ Token refresh (in progress)
  - [F₄] 🔜 Password reset
- [M₃] 🔜 Core API (0%) - Due 2024-02-01

## 🐛 Issue Tracking
### Active Issues
- [I₁] HIGH: Token expiry not configurable
  - Discovered: 2024-01-14
  - Assigned: In PLAN mode
  - Fix: [↗️σ₄:current]

### Resolved Issues
- [I₂] ✅ RESOLVED: Login fails with special chars
  - Fixed: 2024-01-13
  - Solution: Input sanitization

Management Tasks:

1. Update completion percentages
2. Track milestone progress
3. Manage issue lifecycle
4. Update metrics
5. Archive completed items

Best Practices:

• Weekly progress reviews
• Accurate percentages
• Issue prioritization
• Metric tracking
• Regular archival

σ₆: Protection Registry Management

Purpose: Track and manage protected code

Update Frequency: Low (protection changes)

Key Sections to Maintain:

## 🛡️ Protected Regions

### By File
#### src/config/keys.js
- Lines 10-15: [Ψ₁] API Keys (PROTECTED)
- Lines 20-25: [Ψ₂] Database config (GUARDED)

#### src/auth/crypto.js  
- Entire file: [Ψ₆] Encryption logic (CRITICAL)

## ✅ Approved Modifications
- 2024-01-15: Updated user schema [Ψ₂]
  - Reason: Added email verification
  - Approved by: @lead-dev
  - Changes: Added `emailVerified` field

Management Tasks:

1. Track all protections
2. Document protection reasons
3. Log approved changes
4. Monitor violations
5. Review protection coverage

Best Practices:

• Clear protection reasons
• Regular coverage review
• Approval documentation
• Violation tracking
• Protection cleanup

🔄 Memory Update Workflows

Mode-Based Updates

Each mode automatically updates specific files:

Σ_update(mode) = {
  Ω₁: σ₃ += technical_details, σ₄ = current_focus,
  Ω₂: σ₄ += potential_approaches, σ₂ += design_ideas,
  Ω₃: σ₄ += planned_changes, σ₅ += expected_outcomes,
  Ω₄: σ₅ += implementation_progress, σ₄ += completed,
  Ω₅: σ₅ += review_findings, σ₄ += issues_found
}

Update Timing

Immediate Updates:

• Current focus changes
• Issue discovery
• Protection additions
• Context changes

Session Updates:

• Progress percentages
• Completed features
• Architecture decisions
• Technical changes

Periodic Updates:

• Requirement reviews
• Dependency audits
• Protection coverage
• Progress metrics

💡 Memory Management Best Practices

1. Consistent Formatting

Use standard formats across all files:

## Section Headers
- Items with IDs: [X₁]
- Status indicators: ✅ ⏳ 🔜 ⚠️ ❌
- Dates: YYYY-MM-DD
- Cross-references: [↗️σₙ:Xᵢ]

2. Regular Reviews

Schedule periodic reviews:

Frequency	Files	Focus
Daily	σ₄	Current context
Weekly	σ₁, σ₅	Requirements, progress
Bi-weekly	σ₂, σ₃	Architecture, tech
Monthly	σ₆	Protection coverage

3. Archival Strategy

Keep memory files manageable:

# Archive completed items
mkdir -p /memory-bank/archive/2024-Q1
mv completed-features.md /memory-bank/archive/2024-Q1/

# Keep active files lean
- Remove completed milestones
- Archive resolved issues  
- Clean old context
- Consolidate decisions

4. Cross-Reference Maintenance

Maintain reference integrity:

When updating [R₃] in σ₁:
1. Find all [↗️σ₁:R₃] references
2. Update or note changes
3. Check implementation links
4. Verify pattern references

5. Version Control Integration

Track memory changes:

# Daily commits
git add /memory-bank/
git commit -m "Memory update: $(date +%Y-%m-%d)"

# Tag milestones
git tag -a "milestone-M1-complete" -m "Authentication done"

🛠️ Memory Management Tools

Quick Commands

View current memory state:

"Show current requirements"
"What's our progress?"
"List protected code"

Update memory:

"Add requirement: API rate limiting"
"Update progress: Auth 80% complete"  
"Mark issue I₁ as resolved"

Memory health check:

"Check memory file status"
"Find outdated references"
"Show memory update frequency"

Memory Templates

Maintain consistent structure:

<!-- Requirement Template -->
- [R{n}] {STATUS}: {Description}
  - Created: {DATE}
  - Priority: {HIGH|MEDIUM|LOW}
  - Implementation: [↗️σ₄:{file}]
  
<!-- Issue Template -->
- [I{n}] {SEVERITY}: {Description}
  - Discovered: {DATE}
  - Status: {ACTIVE|ASSIGNED|RESOLVED}
  - Fix: [↗️σ₄:{location}]

🚨 Common Memory Issues

1. Stale Information

Problem: Outdated requirements/progress Solution: Weekly review checklist

2. Lost References

Problem: Broken cross-references Solution: Reference validation script

3. Memory Bloat

Problem: Files too large Solution: Regular archival process

4. Inconsistent Updates

Problem: Some files updated, others not Solution: Mode-based update checklist

📊 Memory Health Metrics

Track memory system health:

## Memory Health Report
- Last full review: 3 days ago
- Broken references: 0
- Stale items: 2 (marked for review)
- File sizes: All < 50KB ✅
- Update frequency: Within targets ✅

🎯 Memory Management Checklist

Daily

• Update activeContext.md
• Check current focus accuracy
• Update task progress

Weekly

• Review requirements (σ₁)
• Update progress metrics (σ₅)
• Clean completed context (σ₄)
• Check protection coverage (σ₆)

Monthly

• Architecture review (σ₂)
• Dependency audit (σ₃)
• Archive completed work
• Memory health check
• Cross-reference validation

📚 Related Topics

• Memory System
• Cross-References
• Backup System
• Mode Transitions

---

← Mode Transitions | Home | Protection Workflow →