Memory Management - johnpeterman72/CursorRIPER.sigma GitHub Wiki

๐Ÿ’พ 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


โ† Mode Transitions | Home | Protection Workflow โ†’