Memory System - johnpeterman72/CursorRIPER.sigma GitHub Wiki
๐พ CursorRIPERโฆฮฃ Memory System
The memory system is your project's persistent knowledge base - six structured files that automatically track every aspect of your development process.
๐ Overview
The memory system (ฮฃ) consists of six core files:
Symbol | File | Purpose | Updated By |
---|---|---|---|
ฯโ | projectbrief.md |
Requirements & scope | Research, Planning |
ฯโ | systemPatterns.md |
Architecture & design | Innovate, Planning |
ฯโ | techContext.md |
Technology stack | Research, Execute |
ฯโ | activeContext.md |
Current focus & context | All modes |
ฯโ | progress.md |
Status & milestones | Execute, Review |
ฯโ | protection.md |
Protected code registry | Execute, Review |
๐๏ธ File Structure
/memory-bank/
โโโ projectbrief.md (ฯโ)
โโโ systemPatterns.md (ฯโ)
โโโ techContext.md (ฯโ)
โโโ activeContext.md (ฯโ)
โโโ progress.md (ฯโ
)
โโโ protection.md (ฯโ)
โโโ backups/
โโโ YYYY-MM-DD/
โโโ *.bak
๐ Memory File Details
projectbrief.md
)
ฯโ: Project Brief (Purpose: Central requirements document
Structure:
# ฯโ: Project Brief
*v1.0 | Created: {DATE} | Updated: {DATE}*
*ฮ : {PHASE} | ฮฉ: {MODE}*
## ๐ Overview
[High-level project description]
## ๐ Requirements
- [Rโ] User authentication required
- [Rโ] Data must be encrypted
- [Rโ] API response time <200ms
...
## ๐ฏ Success Criteria
- [Cโ] All tests passing
- [Cโ] Performance benchmarks met
- [Cโ] Security audit passed
## ๐ซ Out of Scope
- Mobile app development
- Third-party integrations
Updated During:
- ๐ Research: Requirements gathered
- ๐ Plan: Requirements refined
- ๐ Review: Requirements validated
Key Sections:
- Overview: Project vision
- Requirements: Numbered list (Rโ, Rโ...)
- Success Criteria: Measurable goals
- Scope Boundaries: What's excluded
- Stakeholders: Key people
- Constraints: Limitations
systemPatterns.md
)
ฯโ: System Patterns (Purpose: Architecture and design decisions
Structure:
# ฯโ: System Patterns
*v1.0 | Created: {DATE} | Updated: {DATE}*
*ฮ : {PHASE} | ฮฉ: {MODE}*
## ๐๏ธ Architecture Overview
[High-level architecture diagram in ASCII]
## ๐งฉ Core Components
### Authentication Service
- Pattern: JWT with refresh tokens
- Rationale: Stateless, scalable
- Dependencies: jsonwebtoken, bcrypt
### Data Layer
- Pattern: Repository pattern
- Rationale: Abstraction, testability
- Implementation: TypeORM
## ๐ Design Patterns
- [Pโ] Singleton: Database connection
- [Pโ] Factory: User creation
- [Pโ] Observer: Event system
## ๐๏ธ Architectural Decisions
- [Dโ] Microservices over monolith
- [Dโ] PostgreSQL over MongoDB
- [Dโ] REST over GraphQL
Updated During:
- ๐ก Innovate: Patterns explored
- ๐ Plan: Architecture defined
- โ๏ธ Execute: Patterns implemented
Key Sections:
- Architecture: System design
- Components: Major parts
- Patterns: Design patterns used
- Decisions: ADRs (Architecture Decision Records)
- Interfaces: API contracts
- Dependencies: Component relationships
techContext.md
)
ฯโ: Technical Context (Purpose: Technology stack and environment
Structure:
# ฯโ: Technical Context
*v1.0 | Created: {DATE} | Updated: {DATE}*
*ฮ : {PHASE} | ฮฉ: {MODE}*
## ๐ ๏ธ Technology Stack
### Backend
- Runtime: Node.js v18.x
- Framework: Express 4.x
- Database: PostgreSQL 14
- ORM: TypeORM
### Frontend
- Framework: React 18
- State: Redux Toolkit
- Styling: Tailwind CSS
## ๐ Environment Setup
### Development
- Node.js 18.x required
- PostgreSQL local instance
- Redis for caching
### Production
- AWS EC2 deployment
- RDS PostgreSQL
- ElastiCache Redis
## ๐ฆ Dependencies
### Core
- express: ^4.18.0
- typeorm: ^0.3.0
- jsonwebtoken: ^9.0.0
### Development
- jest: ^29.0.0
- eslint: ^8.0.0
Updated During:
- ๐ Research: Stack identified
- โ๏ธ Execute: Dependencies added
- ๐ Review: Versions verified
Key Sections:
- Stack: Technologies used
- Environment: Setup requirements
- Dependencies: Package list
- Configuration: Settings
- Infrastructure: Deployment details
- Tools: Development tools
activeContext.md
)
ฯโ: Active Context (Purpose: Current focus and context references
Structure:
# ฯโ: Active Context
*v1.1 | Created: {DATE} | Updated: {DATE}*
*ฮ : {PHASE} | ฮฉ: {MODE}*
## ๐ฎ Current Focus
Working on JWT authentication implementation
## ๐ Recent Changes
- Implemented token generation
- Added refresh token endpoint
- Updated middleware
## ๐ฏ Next Steps
1. Add token rotation
2. Implement rate limiting
3. Write integration tests
## ๐ Context References
### ๐ Active Files
- src/auth/jwt.service.ts ๐ข
- src/auth/auth.controller.ts ๐ข
- src/middleware/auth.middleware.ts ๐ก
### ๐ป Active Code
- generateToken() ๐ข
- verifyToken() ๐ข
- refreshToken() ๐ฃ
### ๐ Active Docs
- JWT Best Practices ๐ข
- OAuth2 Specification ๐ก
## ๐ก Context Status
- ๐ข Active: Currently working
- ๐ก Partially Relevant: May need
- ๐ฃ Essential: Core reference
- ๐ด Deprecated: No longer needed
Updated During:
- All modes continuously
Key Sections:
- Current Focus: What we're doing
- Recent Changes: What was done
- Next Steps: What's coming
- Context References: Active items
- Context Status: Relevance indicators
- Notes: Quick thoughts
progress.md
)
ฯโ
: Progress Tracker (Purpose: Project status and milestones
Structure:
# ฯโ
: Progress Tracker
*v1.0 | Created: {DATE} | Updated: {DATE}*
*ฮ : {PHASE} | ฮฉ: {MODE}*
## ๐ Project Status
Overall Completion: 45%
### ๐ฏ Milestones
- [Mโ] Project Setup โ
100%
- [Mโ] Authentication โณ 75%
- [Mโ] Core API ๐ 0%
- [Mโ] Testing ๐ 0%
## โ
Completed Features
- [Fโ] Database schema
- [Fโ] User registration
- [Fโ] Login endpoint
## ๐ง In Progress
- [Fโ] JWT refresh tokens (75%)
- [Fโ
] Rate limiting (25%)
## ๐ Known Issues
- [Iโ] Token expiry not configurable
- [Iโ] Missing password validation
## ๐ Metrics
- Tests: 24 passing, 2 failing
- Coverage: 67%
- Performance: API avg 125ms
Updated During:
- โ๏ธ Execute: Progress logged
- ๐ Review: Status verified
Key Sections:
- Overall Status: Completion percentage
- Milestones: Major checkpoints
- Features: Completed/In-progress
- Issues: Known problems
- Metrics: Measurable data
- Timeline: Schedule tracking
protection.md
)
ฯโ: Protection Registry (Purpose: Track protected code regions
Structure:
# ฯโ: Protection Registry
*v1.0 | Created: {DATE} | Updated: {DATE}*
*ฮ : {PHASE} | ฮฉ: {MODE}*
## ๐ก๏ธ Protected Regions
### ๐ PROTECTED (ฮจโ)
Never modify these sections:
- `src/auth/jwt.service.ts:15-25` - JWT secret handling
- `src/config/database.ts:8-20` - Database credentials
### ๐ก๏ธ GUARDED (ฮจโ)
Ask before modifying:
- `src/models/user.model.ts:30-45` - User schema
- `src/utils/crypto.ts:*` - Encryption utilities
### โ ๏ธ CRITICAL (ฮจโ)
Business logic protection:
- `src/services/payment.ts:50-120` - Payment processing
- `src/services/auth.ts:200-250` - Auth validation
## ๐ Protection History
- 2024-01-15: Added JWT secret protection
- 2024-01-16: Protected payment logic
## โ
Modification Approvals
- 2024-01-17: Approved update to user schema
- Reason: Added email verification field
- Approved by: Team Lead
## โ ๏ธ Permission Violations
- 2024-01-18 14:30: Attempted modification of protected JWT secret
- Mode: EXECUTE
- Action: Blocked, reverted to safe state
Updated During:
- โ๏ธ Execute: Protections added
- ๐ Review: Registry verified
Key Sections:
- Protected Regions: By level
- History: Protection timeline
- Approvals: Authorized changes
- Violations: Blocked attempts
- Guidelines: Protection rules
๐ Memory Operations
Automatic Updates
The framework automatically updates memory based on mode:
ฮฃ_update(mode) = {
ฮฉโ: ฯโ += findings, ฯโ = focus,
ฮฉโ: ฯโ += ideas, ฯโ += patterns,
ฮฉโ: ฯโ += plan, ฯโ
+= milestones,
ฮฉโ: ฯโ
+= progress, ฯโ += completed,
ฮฉโ
: ฯโ
+= results, ฯโ += issues
}
Cross-References
Memory files reference each other:
[โ๏ธฯโ:Rโ] - Link to requirement 1
[โ๏ธฯโ:Pโ] - Link to pattern 3
[โ๏ธฯโ
:Iโ] - Link to issue 2
Backup System
Automatic backups on:
- Mode transitions
- Destructive operations
- Manual trigger
/memory-bank/backups/
โโโ 2024-01-15/
โโโ projectbrief.md.bak
โโโ systemPatterns.md.bak
โโโ ...
๐ก Best Practices
1. Keep Memory Current
- Update immediately after changes
- Don't wait for mode switches
- Use clear, concise language
2. Use Consistent Indexing
- Requirements: Rโ, Rโ, Rโ...
- Features: Fโ, Fโ, Fโ...
- Issues: Iโ, Iโ, Iโ...
- Milestones: Mโ, Mโ, Mโ...
3. Cross-Reference Liberally
- Link related items
- Maintain traceability
- Enable easy navigation
4. Regular Reviews
- Check accuracy weekly
- Prune outdated info
- Update progress metrics
5. Protect Early
- Add protection during coding
- Document protection reasons
- Review protection coverage
๐ ๏ธ Memory Commands
Viewing Memory
Show current requirements from projectbrief.md
Display active context
What's our current progress?
Updating Memory
Add requirement: API must support pagination
Update progress: Authentication 80% complete
Mark issue Iโ as resolved
Cross-Referencing
This implements requirement [โ๏ธฯโ:Rโ]
Following pattern [โ๏ธฯโ:Pโ]
Addresses issue [โ๏ธฯโ
:Iโ]
๐จ Common Issues
Memory Not Updating
- Cause: Mode permissions
- Fix: Check mode with
!ckp
Lost Context
- Cause: Not saved before switch
- Fix: Check backups folder
Conflicting Information
- Cause: Manual edits
- Fix: Reconcile in PLAN mode
Missing Cross-References
- Cause: Forgot to link
- Fix: Add references in current mode
๐ฏ Memory Strategy
Phase-Based Focus
Initialization (ฮ โ)
- Fill ฯโ (requirements)
- Define ฯโ (tech stack)
- Set ฯโ (milestones)
Development (ฮ โ)
- Update ฯโ (patterns)
- Track ฯโ (context)
- Monitor ฯโ (progress)
Maintenance (ฮ โ)
- Maintain ฯโ (protection)
- Archive ฯโ (context)
- Finalize ฯโ (metrics)
Mode-Specific Updates
Research: Facts โ Memory Innovate: Ideas โ Patterns Plan: Design โ Context Execute: Code โ Progress Review: Results โ Status