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:
- Review weekly for accuracy
- Mark deprecated requirements
- Add new requirements with clear IDs
- Update success criteria
- 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:
- Document all architectural decisions
- Track pattern implementations
- Update component relationships
- Version design changes
- 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:
- Track dependency versions
- Monitor security updates
- Document environment configs
- Update setup instructions
- 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:
- Update focus at mode switches
- Track work progress
- Manage context references
- Clear completed items
- 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:
- Update completion percentages
- Track milestone progress
- Manage issue lifecycle
- Update metrics
- 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:
- Track all protections
- Document protection reasons
- Log approved changes
- Monitor violations
- 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