Orchestre Memory System Architecture

Overview

Orchestre employs a distributed memory system that leverages Claude Code's native CLAUDE.md files to maintain contextual knowledge across your project. Unlike traditional state management systems that rely on databases or JSON files, Orchestre's memory is:

• Distributed: Memory lives alongside the code it documents
• Git-tracked: All memory evolution is versioned
• Human-readable: Written in natural language, not configuration
• AI-native: Designed for LLM consumption and generation

Architecture Components

1. Distributed CLAUDE.md Architecture

The memory system consists of multiple CLAUDE.md files strategically placed throughout your project:

project/
├── CLAUDE.md                    # Root project memory
├── .orchestre/
│   ├── CLAUDE.md               # Orchestration-specific memory
│   └── memory-templates/       # Templates for consistent memory
├── src/
│   ├── features/
│   │   ├── auth/
│   │   │   └── CLAUDE.md      # Auth feature memory
│   │   └── billing/
│   │       └── CLAUDE.md      # Billing feature memory
│   └── components/
│       └── CLAUDE.md          # Component patterns memory
└── .claude/
    └── commands/              # Dynamic prompts that read memory

Root CLAUDE.md (Project-Level Memory)

The root CLAUDE.md serves as the primary memory for your entire project:

# Project Name - Project Memory

## Project Overview
High-level description of what this project does, its purpose, and key architectural decisions.

## Technology Stack
- Framework: Next.js 14 with App Router
- Database: Supabase (PostgreSQL)
- Styling: Tailwind CSS
- State: Zustand for client state

## Key Design Decisions
1. **Multi-tenancy**: Implemented at database level with RLS
2. **Authentication**: Using Supabase Auth with custom claims
3. **API Design**: RESTful with consistent error handling

## Development Patterns
- Feature-based architecture
- Composable components
- Server-first rendering

.orchestre/CLAUDE.md (Orchestration Memory)

This file contains Orchestre-specific context and workflow knowledge:

# Orchestration Memory

## Current Development Phase
Building MVP with core authentication and billing features

## Task History
- ✅ Project initialization with MakerKit template
- ✅ Authentication system implementation
- 🔄 Billing integration with Stripe
- ⏳ Admin dashboard

## Discovered Patterns
1. **API Routes**: All follow /api/[feature]/[action] pattern
2. **Component Structure**: Presentational/Container separation
3. **Error Handling**: Centralized error boundary with toast notifications

## Technical Insights
- Supabase RLS policies require careful ordering
- Next.js middleware handles tenant resolution
- Stripe webhooks need signed verification

Feature-Specific CLAUDE.md Files

Each major feature maintains its own memory:

# Authentication Feature Memory

## Implementation Details
- Using Supabase Auth with email/password and OAuth
- Custom claims stored in auth.users metadata
- Session management via cookies

## Key Components
- `AuthProvider`: React context for auth state
- `useAuth`: Hook for accessing auth functions
- `withAuth`: HOC for protected routes

## Known Issues & Solutions
1. **Issue**: OAuth redirect URLs in development
   **Solution**: Use separate Supabase projects for dev/prod

## Integration Points
- Billing: User subscription status checked on login
- Admin: Role-based access control via custom claims

2. Project vs Orchestre Memory Separation

Understanding what belongs in each memory location is crucial for effective knowledge management:

What Belongs in Root CLAUDE.md

Project-Level Knowledge:

• Overall architecture and design decisions
• Technology stack and framework choices
• Core business logic and domain models
• Development conventions and patterns
• Team agreements and coding standards

Example:

## Business Logic
- **Subscription Tiers**: Free, Pro ($29/mo), Enterprise (custom)
- **User Roles**: Owner, Admin, Member, Guest
- **Billing Cycle**: Monthly or annual with 20% discount

What Belongs in .orchestre/CLAUDE.md

Orchestration Knowledge:

• Current development status and phase
• Task tracking and completion history
• Discovered patterns during development
• Technical insights and learnings
• Session-specific context

Example:

## Current Sprint Focus
Implementing Stripe billing integration
- Payment method management
- Subscription lifecycle handling
- Invoice generation

## Recent Discoveries
- Stripe Customer Portal simplifies subscription management
- Webhook events must be idempotent
- Test mode data doesn't sync to production

What Belongs in Feature CLAUDE.md

Feature-Specific Knowledge:

• Implementation details and decisions
• Component structure and relationships
• API endpoints and data flow
• Known issues and workarounds
• Testing strategies

Example:

## Billing Feature Architecture

### Components
- `PricingTable`: Displays available plans
- `SubscriptionManager`: Handles plan changes
- `PaymentMethodForm`: Stripe Elements integration

### API Routes
- POST /api/billing/create-subscription
- POST /api/billing/update-subscription
- POST /api/billing/cancel-subscription
- POST /api/billing/webhook (Stripe events)

Memory Hierarchy Diagram

3. Memory Templates and Their Purpose

Memory templates provide consistent structure for different types of memory files, ensuring important context isn't forgotten.

Location

All memory templates are stored in .orchestre/memory-templates/:

.orchestre/memory-templates/
├── feature-memory.md      # Template for feature CLAUDE.md
├── component-memory.md    # Template for component documentation
├── api-memory.md         # Template for API route documentation
└── integration-memory.md  # Template for third-party integrations

Feature Memory Template Example

# [Feature Name] Feature Memory

## Overview
Brief description of what this feature does and why it exists.

## Architecture Decisions
- Why we chose this approach
- Alternatives considered
- Trade-offs accepted

## Implementation Details

### Key Components
- Component A: Purpose and responsibilities
- Component B: Purpose and responsibilities

### Data Flow
1. User action triggers...
2. Component processes...
3. API updates...
4. State reflects...

### API Endpoints
- GET /api/feature/list - Returns paginated items
- POST /api/feature/create - Creates new item
- PUT /api/feature/[id] - Updates existing item

## State Management
How this feature manages state (context, hooks, stores)

## Error Handling
- Common errors and how they're handled
- User-facing error messages
- Recovery strategies

## Testing Strategy
- Unit tests for utilities
- Integration tests for API
- E2E tests for critical paths

## Known Issues & Workarounds
1. Issue: Description
   Workaround: Solution
   
## Future Improvements
- Enhancement ideas
- Technical debt to address
- Performance optimizations

## Integration Points
- How this feature connects with others
- Dependencies and dependents
- Shared utilities or components

How to Use Memory Templates

1. When Creating a New Feature:

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

2. Fill Out Sections Progressively:

   • Start with Overview during planning
   • Add Architecture Decisions during design
   • Document Implementation Details while coding
   • Update Known Issues as discovered

3. Keep Templates Updated:

   • If you find yourself adding the same sections repeatedly, update the template
   • Templates should evolve with your project's needs

Template Examples from Different Project Types

MakerKit SaaS Template Memory:

## SaaS-Specific Patterns
- Multi-tenancy: Organization-based isolation
- Billing: Subscription lifecycle management
- Onboarding: Progressive user activation
- Admin: Super-admin capabilities

Cloudflare Workers Template Memory:

## Edge Computing Constraints
- No file system access
- 50ms CPU time limit
- KV storage for persistence
- Durable Objects for state

React Native Template Memory:

## Mobile-Specific Considerations
- Platform differences (iOS vs Android)
- Navigation stack management
- Offline-first architecture
- Push notification handling

4. How Memory Influences Prompts

Orchestre's commands are designed to discover and utilize memory dynamically, adapting their behavior based on accumulated knowledge.

Memory Discovery Pattern

Commands typically follow this pattern:

// From /execute-task command
"First, check for context in these locations:
1. Root CLAUDE.md for project conventions
2. .orchestre/CLAUDE.md for task history
3. Feature-specific CLAUDE.md files
4. Any related documentation"

Adapting Behavior Based on Memory

Example 1: Code Generation When the /execute-task command finds established patterns in memory:

# In root CLAUDE.md
## API Patterns
All API routes follow:
- Input validation with Zod
- Consistent error responses
- Rate limiting with Redis

The command will generate code following these patterns:

// Generated API route follows discovered patterns
import { z } from 'zod';
import { rateLimit } from '@/lib/rate-limit';
import { ApiError } from '@/lib/errors';

const schema = z.object({
  // Validation schema as per pattern
});

export async function POST(req: Request) {
  // Rate limiting as documented
  await rateLimit(req);
  
  // Consistent error handling
  try {
    const body = schema.parse(await req.json());
    // Implementation
  } catch (error) {
    throw new ApiError(400, 'Validation failed');
  }
}

Example 2: Architecture Decisions When /add-enterprise-feature reads memory about multi-tenancy:

# In .orchestre/CLAUDE.md
## Discovered Patterns
- Tenant isolation via database RLS
- Tenant ID in JWT claims
- All queries scoped by tenant

The command adapts to use RLS instead of application-level filtering.

Memory Evolution Over Time

Memory naturally evolves as the project develops:

Initial State:

## Technology Stack
- Framework: Next.js (version TBD)
- Database: PostgreSQL (considering Supabase)
- Styling: Undecided

After Implementation:

## Technology Stack
- Framework: Next.js 14.2.3 with App Router
- Database: Supabase (PostgreSQL 15)
- Styling: Tailwind CSS v3.4 with Radix UI
- State: Zustand for client, Server Components for server

After Optimization:

## Technology Stack
- Framework: Next.js 14.2.3 with App Router
  - Partial prerendering for marketing pages
  - Dynamic rendering for dashboard
- Database: Supabase (PostgreSQL 15)
  - Connection pooling via Prisma
  - Read replicas for analytics

Real Examples of Memory Influence

1. Pattern Recognition The /extract-patterns command identifies recurring patterns and documents them:

# Added to .orchestre/CLAUDE.md after pattern extraction
## Identified Patterns
1. **Form Handling**: All forms use react-hook-form with Zod validation
2. **Data Fetching**: Consistent use of SWR with error boundaries
3. **Component Structure**: Co-located styles, tests, and stories

Future commands will follow these patterns automatically.

2. Context-Aware Suggestions The /suggest-improvements command reads performance issues from memory:

# In feature CLAUDE.md
## Known Issues
- Product list query slow with 1000+ items
- No pagination implemented

And suggests specific improvements:

• Implement cursor-based pagination
• Add database indexes
• Consider infinite scroll

3. Preventing Repeated Mistakes Memory captures lessons learned:

# In .orchestre/CLAUDE.md
## Technical Insights
- ❌ Don't use dynamic imports in Server Components
- ✅ Use next/dynamic only for Client Components
- ❌ Avoid large data in useEffect dependencies
- ✅ Use useMemo for expensive computations

Commands check these insights before generating code.

Best Practices

1. Write for Future AI Consumption

• Use clear, descriptive headings
• Include code examples where helpful
• Explain "why" not just "what"
• Document edge cases and exceptions

2. Keep Memory Fresh

• Update memory as you learn
• Remove outdated information
• Consolidate duplicate knowledge
• Regular memory review sessions

3. Leverage Memory Templates

• Start with templates for consistency
• Customize for your project needs
• Share templates across team
• Version control template changes

4. Memory Hierarchy

• Global patterns → Root CLAUDE.md
• Orchestration → .orchestre/CLAUDE.md
• Feature details → Feature CLAUDE.md
• Don't duplicate, reference upward

5. Natural Language Over Configuration

# Good: Natural description
Authentication uses Supabase with email/password and Google OAuth.
Sessions expire after 7 days of inactivity.

# Avoid: Configuration-style
auth.provider: supabase
auth.methods: [email, google]
auth.session.expiry: 604800

Conclusion

Orchestre's distributed memory system transforms how AI assistants understand and work with your codebase. By maintaining contextual knowledge in natural language throughout your project, every command and interaction becomes more intelligent and context-aware. The system grows smarter over time, learning from your decisions and adapting to your patterns, creating a truly collaborative AI development experience.