How to Manage Memory in Orchestre

This guide explains how to effectively use Orchestre's distributed memory system with CLAUDE.md files for maintaining project context and knowledge.

Understanding the Memory System

Orchestre leverages Claude Code's native CLAUDE.md files to create a distributed memory system. Instead of a centralized database, knowledge lives alongside your code in markdown files that Claude can read and understand.

Memory File Types

1. Root CLAUDE.md

Location: /CLAUDE.md (project root) Purpose: Project-wide context and instructions

# Project Name - Context for Claude

## Overview
Brief description of the project, its purpose, and main technologies.

## Architecture
High-level architecture decisions and patterns used.

## Key Conventions
- Code style guidelines
- Naming conventions
- Project-specific patterns

## Current State
- Active features being developed
- Known issues or limitations
- Recent changes or decisions

2. Orchestration Memory

Location: /.orchestre/CLAUDE.mdPurpose: Orchestration-specific context and workflow history

# Orchestration Context

## Development Workflow
- How we use Orchestre commands
- Common task patterns
- Team conventions

## Command History
- Frequently used commands
- Custom workflows developed
- Lessons learned

3. Feature Memory

Location: /src/features/[feature]/CLAUDE.mdPurpose: Feature-specific documentation and context

# Feature: User Authentication

## Implementation Details
- Authentication strategy used
- Session management approach
- Security considerations

## Integration Points
- How other features interact
- API endpoints exposed
- Events emitted

## Known Issues
- Current limitations
- Planned improvements
- Technical debt

4. Module Memory

Location: Alongside complex modules Purpose: Deep technical context for specific components

# Payment Processing Module

## Business Logic
- Payment flow states
- Validation rules
- Error handling strategy

## External Dependencies
- Stripe API integration details
- Webhook handling
- Rate limiting considerations

## Testing Strategy
- Key test scenarios
- Edge cases covered
- Performance benchmarks

When to Create Memory Files

Always Create Memory For:

1. New Features

   /src/features/notifications/
   ├── index.ts
   ├── CLAUDE.md  # Feature memory
   └── components/

2. Complex Modules

   /src/lib/analytics/
   ├── tracker.ts
   ├── CLAUDE.md  # Module context
   └── providers/

3. Integration Points

   /src/integrations/stripe/
   ├── client.ts
   ├── CLAUDE.md  # Integration details
   └── webhooks/

4. Architectural Decisions

   /docs/architecture/
   ├── decisions/
   │   ├── 001-auth-strategy.md
   │   └── CLAUDE.md  # Decision context

Skip Memory Files For:

• Simple utility functions
• Standard CRUD operations
• Well-documented third-party integrations
• Temporary or experimental code

Memory Templates

Orchestre provides templates for consistent memory structure:

Feature Template

# Feature: [Name]

## Purpose
What problem does this feature solve?

## Architecture
- Key components
- Data flow
- State management

## API
- Public interfaces
- Events/hooks
- Configuration options

## Dependencies
- Internal modules used
- External services
- Environment requirements

## Maintenance Notes
- Common issues
- Performance considerations
- Future improvements

Integration Template

# Integration: [Service Name]

## Configuration
- Required environment variables
- Setup instructions
- Authentication details

## API Coverage
- Endpoints used
- Rate limits
- Error codes

## Error Handling
- Retry strategies
- Fallback behavior
- Logging approach

## Testing
- Mock strategies
- Test credentials
- Sandbox environment

Best Practices

1. Keep Memory Fresh

Update CLAUDE.md files when:

• Architecture changes
• New patterns emerge
• Decisions are made
• Issues are discovered

2. Be Concise but Complete

# Good: Concise but informative
## Authentication
Uses JWT with 15-minute access tokens and 7-day refresh tokens.
Tokens stored in httpOnly cookies. See auth.config.ts for details.

# Bad: Too verbose
## Authentication
We use JSON Web Tokens for authentication. Access tokens expire
after 15 minutes and refresh tokens after 7 days. We store them
in httpOnly cookies for security. The configuration can be found
in the auth.config.ts file where all the settings are defined...

3. Link Related Context

## Related Context
- See `/src/auth/CLAUDE.md` for authentication details
- Database schema in `/prisma/CLAUDE.md`
- API conventions in `/docs/api/CLAUDE.md`

4. Document Decisions

## Decision Log
- 2024-01-15: Switched from REST to GraphQL for better type safety
- 2024-01-20: Added Redis for session storage (performance)
- 2024-01-25: Implemented soft deletes for all user data (compliance)

5. Include Examples

## Usage Examples

### Creating a notification
```typescript
await notify.send({
  userId: user.id,
  type: 'payment_received',
  data: { amount: 99.99 }
});

## Memory Organization Patterns

### 1. Domain-Driven Structure

/src/ ├── domains/ │ ├── user/ │ │ ├── CLAUDE.md # User domain context │ │ └── features/ │ │ ├── profile/ │ │ │ └── CLAUDE.md │ │ └── settings/ │ │ └── CLAUDE.md

### 2. Layer-Based Structure

/src/ ├── presentation/ │ └── CLAUDE.md # UI patterns and conventions ├── business/ │ └── CLAUDE.md # Business logic rules ├── data/ │ └── CLAUDE.md # Data access patterns

### 3. Feature-Based Structure

/src/ ├── features/ │ ├── CLAUDE.md # Feature development guide │ ├── auth/ │ │ └── CLAUDE.md │ ├── payments/ │ │ └── CLAUDE.md │ └── notifications/ │ └── CLAUDE.md

## Practical Examples

### Example 1: Adding a New Payment Provider

1. Create integration memory:
```bash
# Create memory file
touch src/integrations/paypal/CLAUDE.md

2. Document the integration:

# PayPal Integration

## Setup
- Client ID: PAYPAL_CLIENT_ID
- Secret: PAYPAL_SECRET
- Webhook URL: /api/webhooks/paypal

## Implementation Notes
- Using PayPal Checkout v2 SDK
- Supports one-time and subscription payments
- Webhook verification using PayPal-Transmission-Sig header

## Error Handling
- Retry failed captures up to 3 times
- Log all webhook events to payments_audit table
- Send alerts for disputed transactions

Example 2: Complex Feature Development

When building a complex feature like real-time collaboration:

1. Start with high-level memory:

# Real-time Collaboration Feature

## Overview
Enables multiple users to edit documents simultaneously using WebSockets.

## Technical Approach
- Conflict resolution: Operational Transformation (OT)
- Transport: Socket.io with Redis adapter
- Persistence: PostgreSQL with event sourcing

2. Add implementation details as you build:

## Implementation Progress
- ✅ WebSocket infrastructure
- ✅ Basic OT algorithm
- 🚧 Conflict resolution UI
- ⏳ Presence indicators
- ⏳ Cursor sharing

## Discovered Issues
- Need to handle reconnection gracefully
- Large documents cause performance issues
- Consider implementing lazy loading

Memory Maintenance

Regular Reviews

Schedule regular memory reviews:

• Weekly: Update active feature memories
• Monthly: Review and consolidate project-level memory
• Quarterly: Archive outdated memories

Memory Cleanup

# Find outdated CLAUDE.md files
find . -name "CLAUDE.md" -mtime +90 -print

# Archive old memories
mkdir -p .orchestre/archive/2024-Q1
mv old-feature/CLAUDE.md .orchestre/archive/2024-Q1/

Version Control

• Commit CLAUDE.md files with related code changes
• Use meaningful commit messages for memory updates
• Review memory changes in pull requests

Advanced Techniques

1. Memory Hierarchies

Create inheritance in memory files:

# Component: DataTable

## Extends
- See `/src/components/base/CLAUDE.md` for base component patterns
- Follows `/docs/ui/CLAUDE.md` design system guidelines

## Specializations
- Adds sorting, filtering, and pagination
- Supports virtual scrolling for large datasets

2. Cross-References

Build a knowledge graph:

## Related Systems
- Authentication: `/src/auth/CLAUDE.md`
- Permissions: `/src/permissions/CLAUDE.md`
- Audit Logging: `/src/audit/CLAUDE.md`

## Dependents
- Admin Panel: `/src/admin/CLAUDE.md`
- API Gateway: `/src/api/CLAUDE.md`

3. Memory Queries

Use Orchestre commands to query memory:

/discover-context "payment processing"

Troubleshooting

Common Issues

Issue: Claude not seeing memory files

• Ensure files are named exactly CLAUDE.md
• Check file permissions
• Verify files are committed to git

Issue: Conflicting information

• More specific memory overrides general
• Recent updates take precedence
• Use clear timestamps in decision logs

Issue: Memory getting too large

• Split into feature-specific files
• Archive historical information
• Focus on current state and decisions

Summary

Effective memory management in Orchestre:

1. Creates persistent project knowledge
2. Improves Claude's understanding and suggestions
3. Documents decisions and context
4. Facilitates team collaboration
5. Evolves naturally with your codebase

Remember: Memory files are for Claude, but they also serve as excellent documentation for your team. Write them clearly and keep them current.