Memory System

💾 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

• Framework Overview
• RIPER Modes
• Cross-References
• Backup System

---

← RIPER Modes | Home | Symbolic Notation →