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

ฯƒโ‚: Project Brief (projectbrief.md)

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

ฯƒโ‚‚: System Patterns (systemPatterns.md)

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

ฯƒโ‚ƒ: Technical Context (techContext.md)

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

ฯƒโ‚„: Active Context (activeContext.md)

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 Tracker (progress.md)

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 Registry (protection.md)

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

๐Ÿ“š Related Topics


โ† RIPER Modes | Home | Symbolic Notation โ†’