Memory System

Orchestre V3 uses a distributed memory system based on Claude Code's native CLAUDE.md files. This guide explains how to effectively use this system to build a living knowledge base that grows with your project.

Core Concepts

What is Distributed Memory?

Unlike traditional centralized state management, Orchestre's memory system:

Lives with the code: Documentation is colocated with the features it describes
Evolves naturally: Updates happen during development, not as a separate task
Integrates with git: All changes are tracked through version control
Leverages Claude Code: Uses the native CLAUDE.md memory features

Why CLAUDE.md Files?

CLAUDE.md files are Claude Code's native way of maintaining contextual memory:

Automatically discovered by Claude Code
Human and AI readable
Markdown format for easy editing
Git-friendly for team collaboration

Overview

The Orchestre memory system is built on four key principles:

Distributed: Knowledge lives where it's needed
Git-Friendly: All memory is version controlled
Human-Readable: Documentation that serves both AI and humans
Progressive: Knowledge accumulates naturally during development

Memory Structure

Typical Project Layout

Root CLAUDE.md

The root CLAUDE.md serves as the project's main memory hub:

markdown

# Project Name

## Project Overview
High-level description and business goals

## Architecture Decisions
- **Decision**: Reasoning and context
- **Date**: When the decision was made
- **Impact**: How it affects the project

## Technology Stack
- Framework choices and why
- Key libraries and their purposes
- Infrastructure decisions

## Key Patterns
Reusable patterns discovered during development

## Development Workflow
How the team works on this project

## Consolidated Insights
Learnings extracted from feature-specific CLAUDE.md files

Feature CLAUDE.md

Each feature or module should have its own CLAUDE.md:

markdown

# Feature Name

## Overview
What this feature does and why it exists

## Implementation Details
- **Created**: Date
- **Type**: user-facing/internal/api
- **Key Decisions**: Why built this way

## Architecture
How this feature is structured

## Integration Points
How it connects with other parts

## Testing Strategy
How this feature is tested

## Known Issues
Current limitations or technical debt

## Future Improvements
Planned enhancements

How It Works

The CLAUDE.md Convention

Claude Code automatically discovers and reads CLAUDE.md files throughout your project. Orchestre leverages this to create contextual documentation.

Memory Types

1. Project Memory (`/CLAUDE.md`)

The root CLAUDE.md file contains high-level project information:

markdown

# Project: E-Commerce Platform

## Architecture Overview
This is a microservices-based e-commerce platform built with:
- Frontend: Next.js 14 with App Router
- Backend: Node.js microservices
- Database: PostgreSQL with Redis cache
- Message Queue: RabbitMQ
- Deployment: Kubernetes on AWS

## Key Decisions
- **2024-01-15**: Chose microservices over monolith for scalability
- **2024-01-20**: Selected PostgreSQL over MongoDB for ACID compliance
- **2024-02-01**: Implemented JWT with refresh tokens for auth

## Conventions
- All API endpoints follow REST principles
- Use camelCase for JavaScript/TypeScript
- Database tables use snake_case
- Environment variables prefixed with APP_

## Current State
- Phase: Beta testing
- Main focus: Performance optimization
- Next milestone: Production deployment

2. Feature Memory (`src/feature/CLAUDE.md`)

Feature-specific context and implementation details:

markdown

# Authentication System

## Overview
JWT-based authentication with refresh tokens and role-based access control.

## Implementation Details
- Tokens stored in httpOnly cookies
- Refresh tokens rotate on use
- 15-minute access token lifetime
- 7-day refresh token lifetime

## Security Measures
- bcrypt with 12 rounds for passwords
- Rate limiting: 5 attempts per 15 minutes
- CSRF protection on all mutations
- Session invalidation on password change

## API Endpoints
- POST /auth/register - User registration
- POST /auth/login - User login
- POST /auth/refresh - Token refresh
- POST /auth/logout - Session termination

## Known Issues
- TODO: Implement 2FA support
- TODO: Add OAuth providers

## Related Files
- middleware/auth.ts - Authentication middleware
- utils/jwt.ts - Token generation/validation
- models/User.ts - User model with auth methods

3. Pattern Memory (`.orchestre/patterns/`)

Discovered and extracted patterns:

markdown

# API Error Handling Pattern

## Pattern
All API errors follow this structure:

\```typescript
{
  error: {
    code: 'ERROR_CODE',
    message: 'Human readable message',
    details: {}, // Optional additional context
    timestamp: '2024-01-15T10:30:00Z'
  }
}
\```

## Usage Examples
- auth/middleware.ts:45 - Token validation errors
- api/users/route.ts:78 - Validation errors
- api/orders/route.ts:92 - Business logic errors

## Consistency Rules
- Error codes are SCREAMING_SNAKE_CASE
- Messages are user-friendly
- Always include timestamp
- Log full error, return safe subset

Memory Creation

Automatic Creation

Orchestre automatically suggests memory creation during:

Project Initialization

bash

/create makerkit my-app
# Creates initial CLAUDE.md with template info

Feature Implementation

bash

/execute-task "Add payment processing"
# Suggests creating src/payments/CLAUDE.md

Decision Points

bash

/orchestrate "Choose between REST and GraphQL"
# Documents decision in CLAUDE.md

Manual Creation

Use dedicated commands for explicit documentation:

bash

# Document a completed feature
/document-feature "authentication system"

# Discover and document existing patterns
/discover-context

# Update project state
/update-state "Completed phase 1, moving to optimization"

Using Memory Templates

Orchestre provides ready-to-use memory templates for different scenarios:

Available Templates

Feature Memory (feature-memory.md)
- For new features or modules
- Includes sections for architecture, integration, testing
API Memory (api-memory.md)
- For API endpoints and services
- Documents routes, validation, security
Integration Memory (integration-memory.md)
- For third-party integrations
- Covers authentication, webhooks, data sync

Using Templates

When creating new documentation:

bash

# Copy appropriate template
cp .orchestre/memory-templates/feature-memory.md src/features/new-feature/CLAUDE.md

# Customize for your feature
# Fill in placeholders with actual information

Memory Evolution

Progressive Enhancement

Memory grows naturally during development:

Example Evolution

Day 1: Basic feature documentation

markdown

# User Management

## Overview
CRUD operations for users.

Week 1: Patterns emerge

markdown

# User Management

## Overview
CRUD operations for users with role-based access.

## Patterns
- All queries use pagination (limit/offset)
- Soft deletes with deleted_at timestamp
- Audit trail for all modifications

Month 1: Deep knowledge

markdown

# User Management

## Overview
CRUD operations for users with role-based access.

## Patterns
- All queries use pagination (limit/offset)
- Soft deletes with deleted_at timestamp
- Audit trail for all modifications

## Performance Optimizations
- Indexed on email, username
- Cached user profiles in Redis (5min TTL)
- Batch operations for bulk updates

## Lessons Learned
- Username uniqueness should be case-insensitive
- Email validation needs to handle Unicode
- Password reset tokens need expiration

Examples

Good Documentation

markdown

# Authentication Module

## Overview
JWT-based authentication with refresh tokens for our multi-tenant SaaS.
Chosen over sessions for horizontal scalability and mobile app support.

## Architecture Decisions

### JWT with Refresh Tokens (2024-12-01)
- **Context**: Need stateless auth for API and mobile
- **Decision**: JWT (15min) + Refresh tokens (7 days)
- **Consequences**: Must handle token rotation carefully
- **Alternatives**: Considered sessions but rejected due to scaling

### Redis for Token Blacklist (2024-12-05)
- **Context**: Need to revoke tokens before expiry
- **Decision**: Redis SET with TTL matching token expiry
- **Trade-off**: Additional infrastructure for security

## Integration Points
- **API Routes**: All use `withAuth()` middleware
- **Frontend**: `useAuth()` hook manages tokens
- **Mobile**: Stores in secure keychain

## Security Considerations
- Tokens signed with RS256 (public key verification)
- Refresh tokens rotated on use (one-time use)
- Rate limiting: 5 login attempts per 15 minutes

## Common Gotchas
- Token refresh race conditions in parallel requests
  - Solution: Request coalescing in auth middleware
- Clock skew between servers
  - Solution: 30-second grace period in validation

## Testing
- Unit: `src/auth/__tests__/tokens.test.ts`
- Integration: `e2e/auth-flow.spec.ts`
- Load testing: Handles 10K concurrent authentications

Poor Documentation

markdown

# Auth

Uses JWT.

## Setup
Configure environment variables.

## Issues
Some bugs with tokens.

Best Practices

1. Write for Future You

Document as if you'll forget everything in 6 months:

markdown

## Why We Chose PostgreSQL
Initially considered MongoDB for flexibility, but chose PostgreSQL because:
1. Need ACID compliance for financial transactions
2. Complex relationships between entities
3. Team expertise with SQL
4. Better tooling for our use case

2. Record the Why, Not Just the What

❌ Poor Documentation

markdown

Using JWT for authentication.

✅ Good Documentation

markdown

Using JWT for authentication because:
- Stateless scaling for microservices
- Easy to implement across services
- Standard libraries available
- Refresh token pattern handles expiration gracefully

3. Keep It Living

Update documentation as you code:

bash

# After implementing a feature
/document-feature "payment processing"

# After making a decision
/update-state "Switched from Stripe to Paddle for tax compliance"

# After discovering a pattern
/extract-patterns "error handling"

4. Use Consistent Structure

Maintain consistent sections across similar files:

Overview
Key Decisions
Implementation Details
Patterns
Security Considerations
Performance Notes
Future Improvements

Create connections between related concepts:

markdown

## Related Documentation
- See `src/auth/CLAUDE.md` for authentication details
- See `docs/API.md` for endpoint specifications
- See `.orchestre/patterns/error-handling.md` for error patterns

Memory Patterns

For New Projects

Initialize with /create - creates root CLAUDE.md
Use /orchestrate to set up memory structure
Document features with /execute-task
Review and consolidate with /learn

For Existing Projects

Run /discover-context to understand current state
Use /document-feature for undocumented areas
Gradually build memory during development
Consolidate insights periodically

For Team Projects

Include CLAUDE.md files in code reviews
Update documentation with code changes
Share patterns through root CLAUDE.md
Use git history to track knowledge evolution

Memory Commands

Core Memory Commands

Command	Purpose	Example
`/document-feature`	Create comprehensive feature documentation	`/document-feature "user authentication"`
`/discover-context`	Analyze and document existing code	`/discover-context src/api`
`/update-state`	Record project state changes	`/update-state "Entered beta testing"`
`/extract-patterns`	Identify and document patterns	`/extract-patterns "API structure"`

Memory-Aware Commands

All Orchestre commands interact with memory:

/orchestrate - Reads existing context before planning
/execute-task - Updates relevant CLAUDE.md files
/review - Considers documented patterns
/learn - Extracts new patterns to memory

Git Integration

Version Control Benefits

Since all memory is in markdown files:

✅ Track Changes

bash

git log --follow src/auth/CLAUDE.md
# See evolution of authentication decisions

✅ Review in PRs

diff

+ ## Security Update (2024-03-01)
+ Implemented rate limiting after security audit:
+ - 5 login attempts per 15 minutes
+ - Exponential backoff for repeated failures

✅ Branch-Specific Context

bash

# Feature branch has its own context
git checkout feature/new-payment-provider
# CLAUDE.md includes experimental decisions

✅ Merge Knowledge

bash

# Knowledge from different branches combines
git merge feature/oauth-integration
# OAuth documentation merges into auth/CLAUDE.md

Team Collaboration

Shared Understanding

Team members contribute to collective knowledge:

markdown

## Team Notes

### @alice (2024-03-01)
Discovered that our JWT implementation wasn't validating the 
algorithm. Fixed in commit abc123. Always specify allowed algorithms!

### @bob (2024-03-05)  
Performance testing showed auth middleware adds 15ms latency.
Acceptable for now, but consider caching decoded tokens if we
need to optimize further.

### @carol (2024-03-10)
Added integration tests for edge cases in password reset flow.
See tests/auth/password-reset.test.ts for scenarios.

Knowledge Transfer

New team members get up to speed quickly:

Read root CLAUDE.md for project overview
Explore feature-specific CLAUDE.md files
Review patterns directory
Check decision history in git

Advanced Usage

Multi-Module Projects

For large projects with many modules:

src/
├── modules/
│   ├── user/
│   │   ├── CLAUDE.md      # User module overview
│   │   ├── auth/
│   │   │   └── CLAUDE.md  # Auth-specific docs
│   │   └── profile/
│   │       └── CLAUDE.md  # Profile-specific docs
│   └── billing/
│       ├── CLAUDE.md      # Billing overview
│       ├── stripe/
│       │   └── CLAUDE.md  # Stripe integration
│       └── invoices/
│           └── CLAUDE.md  # Invoice handling

Pattern Libraries

Build reusable pattern documentation:

.orchestre/
├── patterns/
│   ├── error-handling.md
│   ├── data-fetching.md
│   └── testing-strategy.md

Migration Documentation

Track major changes:

markdown

## Migration History

### 2024-12-15: Moved from REST to GraphQL
- **Reason**: Complex nested data requirements
- **Approach**: Gradual migration with Federation
- **Gotchas**: Watch for N+1 queries
- **Timeline**: 3 months
- **Lessons**: Start with read queries

Custom Memory Templates

Create project-specific templates:

bash

# .orchestre/memory-templates/microservice.md
# Microservice: {NAME}

## Service Purpose
{PURPOSE}

## API Contract
### Publishes
- {EVENT_TYPE}: {DESCRIPTION}

### Subscribes  
- {EVENT_TYPE}: {DESCRIPTION}

## Database
- Schema: {SCHEMA_NAME}
- Tables: {TABLES}

## Configuration
- Port: {PORT}
- Environment: {ENV_VARS}

## Monitoring
- Health check: {ENDPOINT}
- Metrics: {METRICS_ENDPOINT}
- Alerts: {ALERT_RULES}

Memory Queries

Use commands to query memory:

bash

# Find all security-related decisions
/discover-context "security"

# Summarize authentication knowledge
/interpret-state "authentication system"

# Extract all API patterns
/extract-patterns "api"

Memory Synthesis

Combine knowledge from multiple sources:

bash

# Create architecture overview from all CLAUDE.md files
/compose-prompt "Create an architecture diagram based on all documented components"

Troubleshooting

Common Issues

Q: Where should I create CLAUDE.md files? A: In the same directory as the code it documents. Each logical module or feature should have one.

Q: How detailed should documentation be? A: Detailed enough that you could understand it 6 months later. Focus on decisions and context.

Q: Should I document everything? A: No. Document what's not obvious from the code: decisions, trade-offs, integration points, gotchas.

Q: How often should I update? A: Whenever you make significant changes or learn something important. Use /update-state regularly.

Q: Can I use other markdown files? A: Yes, but CLAUDE.md files are special - they're automatically discovered by Claude Code.

Future of Memory

The Orchestre memory system will continue evolving:

🔮 Automatic Pattern Learning: AI identifies patterns without prompting
🔮 Cross-Project Knowledge: Learn from all your projects
🔮 Team Intelligence: Aggregate knowledge across teams
🔮 Semantic Search: Find information by meaning, not keywords

Conclusion

The Orchestre V3 memory system transforms documentation from a chore into a natural part of development. By leveraging Claude Code's native capabilities and distributing knowledge where it's needed, teams can build and maintain a living knowledge base that truly serves their needs.

Remember: The best documentation is the one that gets written and stays current. Orchestre's approach ensures both happen naturally.

Next Steps

MCP Integration - Understand the technical foundation
Documentation Prompts - Master memory management
Custom Commands - Create memory-aware commands

Memory System ​

Core Concepts ​

What is Distributed Memory? ​

Why CLAUDE.md Files? ​

Overview ​

Memory Structure ​

Typical Project Layout ​

Root CLAUDE.md ​

Feature CLAUDE.md ​

How It Works ​

The CLAUDE.md Convention ​

Memory Types ​

1. Project Memory (/CLAUDE.md) ​

2. Feature Memory (src/feature/CLAUDE.md) ​

3. Pattern Memory (.orchestre/patterns/) ​

Memory Creation ​

Automatic Creation ​

Manual Creation ​

Using Memory Templates ​

Available Templates ​

Using Templates ​

Memory Evolution ​

Progressive Enhancement ​

Example Evolution ​

Examples ​

Good Documentation ​

Poor Documentation ​

Best Practices ​

1. Write for Future You ​

2. Record the Why, Not Just the What ​

3. Keep It Living ​

4. Use Consistent Structure ​

5. Link Related Information ​

Memory Patterns ​

For New Projects ​

For Existing Projects ​

For Team Projects ​

Memory Commands ​

Core Memory Commands ​

Memory-Aware Commands ​

Git Integration ​

Version Control Benefits ​

Team Collaboration ​

Shared Understanding ​

Knowledge Transfer ​

Advanced Usage ​

Multi-Module Projects ​

Pattern Libraries ​

Migration Documentation ​

Custom Memory Templates ​

Memory Queries ​

Memory Synthesis ​

Troubleshooting ​

Common Issues ​

Future of Memory ​

Conclusion ​

Next Steps ​

Memory System

Core Concepts

What is Distributed Memory?

Why CLAUDE.md Files?

Overview

Memory Structure

Typical Project Layout

Root CLAUDE.md

Feature CLAUDE.md

How It Works

The CLAUDE.md Convention

Memory Types

1. Project Memory (`/CLAUDE.md`)

2. Feature Memory (`src/feature/CLAUDE.md`)

3. Pattern Memory (`.orchestre/patterns/`)

Memory Creation

Automatic Creation

Manual Creation

Using Memory Templates

Available Templates

Using Templates

Memory Evolution

Progressive Enhancement

Example Evolution

Examples

Good Documentation

Poor Documentation

Best Practices

1. Write for Future You

2. Record the Why, Not Just the What

3. Keep It Living

4. Use Consistent Structure

5. Link Related Information

Memory Patterns

For New Projects

For Existing Projects

For Team Projects

Memory Commands

Core Memory Commands

Memory-Aware Commands

Git Integration

Version Control Benefits

Team Collaboration

Shared Understanding

Knowledge Transfer

Advanced Usage

Multi-Module Projects

Pattern Libraries

Migration Documentation

Custom Memory Templates

Memory Queries

Memory Synthesis

Troubleshooting

Common Issues

Future of Memory

Conclusion

Next Steps