Memory Bank System - johnpeterman72/CursorRIPER GitHub Wiki

Memory Bank System

The Memory Bank is a core component of the CursorRIPER Framework that provides persistent context across coding sessions. This page explains how to effectively use and maintain your Memory Bank.

Purpose and Overview

The Memory Bank solves a fundamental limitation of AI assistants: their lack of persistent memory between sessions. By maintaining a structured set of markdown files with project information, the Memory Bank enables:

  • Continuous work across multiple sessions
  • Consistent understanding of project requirements
  • Tracking of decisions and progress
  • Maintenance of context for long-running projects
flowchart TD
    A[Memory Bank] --> B[projectbrief.md]
    A --> C[systemPatterns.md]
    A --> D[techContext.md]
    A --> E[activeContext.md]
    A --> F[progress.md]
    
    B -->|Project<br>Foundation| G[AI Assistant]
    C -->|Architecture<br>& Patterns| G
    D -->|Technical<br>Context| G
    E -->|Current<br>Status| G
    F -->|Progress<br>Tracking| G
    
    G -->|Updates| E
    G -->|Updates| F

Core Memory Files

projectbrief.md

Purpose: Defines core requirements and goals of the project.

Key Sections:

  • Project Overview
  • Core Requirements
  • Success Criteria
  • Scope (In/Out)
  • Timeline
  • Stakeholders

When to Update:

  • At the beginning of the project
  • When major requirements change
  • When project scope evolves

Example Content:

# Project Brief: User Authentication System
*Version: 1.0*
*Created: April 5, 2025*
*Last Updated: April 5, 2025*

## Project Overview
A secure authentication system for our web application that handles user registration, login, password management, and account verification.

## Core Requirements
- Secure password storage using bcrypt hashing
- Email verification for new accounts
- Password reset functionality
- OAuth integration with Google and GitHub
- Session management with JWT

## Success Criteria
- User registration and login working with 99.9% uptime
- Password reset emails delivered within 30 seconds
- Less than 1% of users requiring support for authentication issues

## Scope
### In Scope
- User registration and login flows
- Email verification system
- Password reset mechanism
- OAuth integration
- Session management

### Out of Scope
- User profile management
- Role-based access control
- Two-factor authentication (future phase)

## Timeline
- Initial implementation: April 20, 2025
- Testing phase: April 21-27, 2025
- Production deployment: May 1, 2025

## Stakeholders
- Development Team: Implementers
- Security Team: Reviewers
- Product Management: Requirements

systemPatterns.md

Purpose: Documents system architecture and design patterns.

Key Sections:

  • Architecture Overview
  • Key Components
  • Design Patterns in Use
  • Data Flow
  • Key Technical Decisions
  • Component Relationships

When to Update:

  • After architectural decisions
  • When new patterns are established
  • When component relationships change

Example Content:

# System Patterns: User Authentication System
*Version: 1.0*
*Created: April 5, 2025*
*Last Updated: April 5, 2025*

## Architecture Overview
The authentication system uses a layered architecture with separation of concerns between authentication logic, data access, and external integrations.

## Key Components
- AuthController: Handles HTTP requests for authentication operations
- AuthService: Implements core authentication business logic
- UserRepository: Manages user data persistence
- EmailService: Handles sending verification and reset emails
- OAuthProvider: Abstracts third-party authentication providers

## Design Patterns in Use
- Repository Pattern: For data access abstraction
- Strategy Pattern: For different authentication methods
- Factory Pattern: For creating authentication providers
- Observer Pattern: For handling post-authentication events

## Data Flow
1. Client makes authentication request
2. AuthController validates input
3. AuthService processes authentication logic
4. UserRepository persists or retrieves user data
5. JWT token generated and returned to client

## Key Technical Decisions
- JWT for stateless authentication: Allows for scalability without shared session storage
- bcrypt for password hashing: Provides security with adjustable work factor
- Redis for rate limiting: Prevents brute force attacks
- Separate service for email delivery: Ensures reliable delivery and retry logic

## Component Relationships
AuthController depends on AuthService, which depends on UserRepository and EmailService. OAuthProvider is used by AuthService when external authentication is requested.

techContext.md

Purpose: Describes technologies used and development setup.

Key Sections:

  • Technology Stack
  • Development Environment Setup
  • Dependencies
  • Technical Constraints
  • Build and Deployment
  • Testing Approach

When to Update:

  • When adding new technologies
  • After updating dependencies
  • When changing build processes
  • When modifying development environment

Example Content:

# Technical Context: User Authentication System
*Version: 1.0*
*Created: April 5, 2025*
*Last Updated: April 5, 2025*

## Technology Stack
- Frontend: React with TypeScript
- Backend: Node.js with Express
- Database: MongoDB
- Infrastructure: AWS (ECS, RDS, SES)

## Development Environment Setup
```bash
# Clone repository
git clone https://github.com/company/auth-service.git

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env

# Start development server
npm run dev

Dependencies

  • express: 4.18.2 - Web framework
  • jsonwebtoken: 9.0.1 - JWT implementation
  • bcrypt: 5.1.0 - Password hashing
  • mongoose: 7.3.4 - MongoDB ODM
  • nodemailer: 6.9.3 - Email sending
  • passport: 0.6.0 - Authentication middleware

Technical Constraints

  • Must work with existing MongoDB database
  • Maximum response time of 300ms for auth operations
  • Must support horizontal scaling
  • Rate limiting required on all public endpoints

Build and Deployment

  • Build Process: npm run build (transpiles TS to JS)
  • Deployment Procedure: CI/CD via GitHub Actions
  • CI/CD: Tests → Build → Deploy to staging → Manual promotion to production

Testing Approach

  • Unit Testing: Jest for service and utility functions
  • Integration Testing: Supertest for API endpoints
  • E2E Testing: Cypress for complete flows
  • Security Testing: OWASP ZAP scans in CI pipeline

### activeContext.md

**Purpose**: Tracks current work focus and immediate next steps.

**Key Sections**:
- Current Focus
- Recent Changes
- Active Decisions
- Next Steps
- Current Challenges
- Implementation Progress

**When to Update**:
- At the start of each work session
- After completing significant tasks
- When switching focus areas
- When encountering new challenges

**Example Content**:
```markdown
# Active Context: User Authentication System
*Version: 1.2*
*Created: April 5, 2025*
*Last Updated: April 6, 2025*
*Current RIPER Mode: PLAN*

## Current Focus
Implementing the password reset functionality including email delivery and secure token generation.

## Recent Changes
- April 6, 2025 - Completed user registration endpoint
- April 6, 2025 - Added email verification service
- April 5, 2025 - Set up project structure and basic auth routes

## Active Decisions
- Token Expiration: DECIDED - 24 hours for reset tokens, 7 days for session tokens
- Email Provider: PENDING - Evaluating between AWS SES and SendGrid
- Rate Limiting: DECIDED - 5 requests per minute for password reset

## Next Steps
1. Implement password reset token generation
2. Create email template for password reset
3. Develop reset token validation endpoint
4. Build password update functionality
5. Add rate limiting to prevent abuse

## Current Challenges
- Email deliverability testing in development environment
- Secure storage of reset tokens
- Handling edge cases in token expiration

## Implementation Progress
- [✓] User registration endpoint
- [✓] Login endpoint with JWT generation
- [✓] Email verification flow
- [ ] Password reset token generation
- [ ] Password reset email delivery
- [ ] Password reset completion endpoint

progress.md

Purpose: Tracks what works, what's in progress, and what's left to build.

Key Sections:

  • Project Status
  • What Works
  • What's In Progress
  • What's Left To Build
  • Known Issues
  • Milestones

When to Update:

  • After completing features
  • When starting new work
  • When discovering issues
  • When reaching milestones

Example Content:

# Progress Tracker: User Authentication System
*Version: 1.1*
*Created: April 5, 2025*
*Last Updated: April 6, 2025*

## Project Status
Overall Completion: 35%

## What Works
- User Registration: COMPLETE - Users can register with email and password
- Email Verification: COMPLETE - Verification emails are sent and tokens can be validated
- Basic Login: COMPLETE - Users can log in and receive a JWT

## What's In Progress
- Password Reset: 40% - Token generation implemented, email delivery in progress
- OAuth Integration: 15% - Basic setup complete, Google provider in progress
- Session Management: 25% - JWT generation working, refresh token flow in development

## What's Left To Build
- Account Locking: HIGH - Implement account locking after failed attempts
- Admin Override: MEDIUM - Allow admins to reset passwords and unlock accounts
- Login Audit Log: LOW - Track login attempts and successes

## Known Issues
- Issue #12: HIGH - Email deliverability inconsistent in development environment
- Issue #15: MEDIUM - JWT expiration not handled gracefully on client
- Issue #17: LOW - Registration form allows weak passwords

## Milestones
- Basic Authentication: April 10, 2025 - ON TRACK
- OAuth Integration: April 20, 2025 - AT RISK
- Complete System: May 1, 2025 - ON TRACK

Memory Bank Management

Directory Structure

The standard memory bank is organized in the project root:

project-root/
├── memory-bank/
│   ├── projectbrief.md
│   ├── systemPatterns.md
│   ├── techContext.md
│   ├── activeContext.md
│   └── progress.md
├── ...other project files

Automatic Updates

The framework can automatically update memory files based on customization settings:

  • AUTO_UPDATE_MEMORY: Controls whether automatic updates are enabled
  • MEMORY_UPDATE_FREQUENCY: Controls when updates occur
  • REQUIRED_MEMORY_FILES: Specifies which files must exist

Manual Updates

You can manually update memory files by:

  1. Editing the files directly
  2. Asking the AI to update specific files

Example command:

Please update the progress.md file to reflect that we've completed the user authentication feature.

Backups

The framework can create automatic backups of your memory bank:

  1. Set BACKUP_FREQUENCY in customization.mdc
  2. Backups are stored in memory-bank/backups/
  3. KEEP_BACKUP_COUNT controls how many backups to retain

To restore from a backup:

Please restore the memory bank from the backup dated [DATE].

Best Practices

Keeping Information Current

  1. Update activeContext.md at the start of each session
  2. Document decisions as they are made
  3. Update progress.md after completing features
  4. Review and refresh projectbrief.md periodically

Effective Documentation Techniques

  1. Use clear and consistent formatting
  2. Include version numbers and dates
  3. Be specific with file paths and function names
  4. Use checklists for tracking progress
  5. Document rationales for important decisions

Version History

Track changes to memory files with:

  1. Version numbers (e.g., "Version: 1.2")
  2. Creation date ("Created: April 5, 2025")
  3. Last update date ("Last Updated: April 6, 2025")
  4. Change logs in complex documents

Mode-Specific Updates

Different RIPER modes typically update different memory files:

  • RESEARCH: Updates techContext.md with discoveries
  • INNOVATE: Records alternatives in systemPatterns.md
  • PLAN: Updates activeContext.md with plans
  • EXECUTE: Updates progress.md with completions
  • REVIEW: Records findings in all relevant files

Troubleshooting

Missing Files

If memory files are missing:

  1. Check if .cursor/rules/start-phase.mdc is loaded
  2. Verify directory permissions
  3. Run /start to initiate or complete setup

Inconsistent State

If memory files and project state don't match:

  1. Check state.mdc for current PROJECT_PHASE
  2. Verify memory file timestamps
  3. Run /research to re-establish context

Corrupted Files

If memory files become corrupted:

  1. Check for backup files in memory-bank/backups/
  2. Restore from most recent backup
  3. If no backup exists, ask the AI to regenerate the file structure

Advanced Usage

Custom Memory Files

You can extend the memory bank with custom files:

memory-bank/
├── ...standard files
├── components/
│   ├── component1.md
│   └── component2.md
├── userStories.md
└── securityReview.md

Memory Analysis

Periodically review your memory bank to:

  1. Identify inconsistencies
  2. Remove outdated information
  3. Add missing details
  4. Ensure alignment with current project state

Integration with External Tools

Export memory bank content for use in:

  1. Project documentation
  2. Status reports
  3. Team handoffs
  4. Knowledge bases

CursorRIPER: Adaptive development, persistent intelligence.