Memory Templates Guide

Memory templates are a core feature of Orchestre's distributed memory system. They provide structured formats for documenting different aspects of your project, ensuring consistent and comprehensive knowledge capture.

Understanding Memory Templates

What are Memory Templates?

Memory templates are pre-structured markdown files that guide you in documenting specific types of project knowledge. They act as intelligent forms that prompt you to capture the right information at the right time, ensuring nothing important is forgotten.

Why Use Templates?

1. Consistency: Every feature, pattern, or decision is documented the same way
2. Completeness: Templates ensure you capture all relevant aspects
3. Discoverability: Structured format makes information easy to find
4. Onboarding: New team members quickly understand the project
5. AI Context: Claude Code can better understand and work with structured information

Where to Find Templates

Memory templates are automatically created in your project when you initialize with Orchestre:

your-project/
└── .orchestre/
    └── memory-templates/
        ├── feature-memory.md
        ├── pattern-memory.md
        ├── decision-memory.md
        ├── problem-memory.md
        └── integration-memory.md

Using Memory Templates

How to Apply Templates

1. Copy the template to the appropriate location in your project
2. Rename it to reflect what you're documenting
3. Fill in the sections with your specific information
4. Remove any sections that don't apply
5. Add custom sections as needed

Customizing Templates for Your Needs

Templates are starting points, not rigid requirements:

• Add sections specific to your domain
• Modify prompts to match your team's language
• Create variations for different contexts
• Keep the structure that works, change what doesn't

Example: Filling Out a Feature Template

Before (Template):

# Feature: [Feature Name]

## Overview
[Brief description of what this feature does]

## User Stories
- As a [user type], I want to [action] so that [benefit]

## Technical Implementation
### Architecture
[How is this feature structured?]

### Key Components
- [Component 1]: [Purpose]
- [Component 2]: [Purpose]

After (Filled Out):

# Feature: User Authentication

## Overview
Secure authentication system using JWT tokens with refresh token rotation and multi-factor authentication support.

## User Stories
- As a user, I want to sign up with email/password so that I can create an account
- As a user, I want to enable 2FA so that my account is more secure
- As an admin, I want to revoke user sessions so that I can manage security

## Technical Implementation
### Architecture
JWT-based authentication with separate access and refresh tokens. Access tokens expire in 15 minutes, refresh tokens in 7 days with rotation on use.

### Key Components
- AuthProvider: React context for authentication state
- authMiddleware: Express middleware for route protection
- TokenService: JWT generation and validation
- SessionStore: Redis-based session management

Available Templates

1. Feature Memory Template (feature-memory.md)

Purpose: Document new features comprehensively

Key Sections:

• Overview and purpose
• User stories and requirements
• Technical implementation details
• API endpoints and data models
• Testing strategy
• Performance considerations
• Security implications

When to Use: Creating any new user-facing or system feature

2. Pattern Memory Template (pattern-memory.md)

Purpose: Capture reusable patterns and best practices

Key Sections:

• Pattern name and category
• Problem it solves
• Solution approach
• Implementation example
• When to use / when not to use
• Related patterns

When to Use: Identifying recurring solutions or establishing conventions

3. Decision Memory Template (decision-memory.md)

Purpose: Record architectural and technical decisions

Key Sections:

• Decision title and date
• Context and constraints
• Options considered
• Decision made and rationale
• Consequences and trade-offs
• Review date

When to Use: Making significant technical choices that affect the project

4. Problem Memory Template (problem-memory.md)

Purpose: Document problems and their solutions

Key Sections:

• Problem description
• Root cause analysis
• Solution implemented
• Prevention strategies
• Monitoring and alerts
• Related issues

When to Use: Solving bugs, performance issues, or system problems

5. Integration Memory Template (integration-memory.md)

Purpose: Document external service integrations

Key Sections:

• Service overview
• Authentication method
• API endpoints used
• Data flow and mapping
• Error handling
• Rate limits and quotas
• Monitoring and debugging

When to Use: Integrating third-party services or APIs

Creating Custom Templates

When to Create New Templates

Create custom templates when you have:

• Recurring documentation needs not covered by existing templates
• Domain-specific knowledge structures
• Team-specific workflows or processes
• Compliance or regulatory requirements

Template Structure Guidelines

Good templates follow these principles:

1. Clear Headers: Use descriptive section titles
2. Guiding Questions: Include prompts that guide thinking
3. Examples: Show what good documentation looks like
4. Flexibility: Make sections optional where appropriate
5. Searchability: Use consistent terminology

Example: Creating a Custom Template

Migration Memory Template for database migrations:

# Migration: [Migration Name]

## Migration ID
[timestamp]_[descriptive_name]

## Purpose
[Why is this migration needed?]

## Changes
### Schema Changes
- [Table/Column changes]

### Data Changes
- [Data transformations]

### Index Changes
- [New/Modified indexes]

## Rollback Strategy
[How to safely rollback if needed]

## Performance Impact
- Estimated runtime: [duration]
- Lock requirements: [what gets locked]
- Peak time considerations: [when to run]

## Verification
### Pre-migration Checks
- [ ] [Check 1]
- [ ] [Check 2]

### Post-migration Validation
- [ ] [Validation 1]
- [ ] [Validation 2]

## Dependencies
- Depends on: [previous migrations]
- Required by: [future changes]

Sharing Templates with Teams

1. Store in Version Control: Keep templates in .orchestre/memory-templates/
2. Document Usage: Create a README in the templates directory
3. Review Regularly: Update templates based on team feedback
4. Share Examples: Include filled-out examples in your documentation
5. Automate Where Possible: Use scripts to generate initial memory files

Best Practices

DO:

• ✅ Use templates as starting points
• ✅ Customize for your specific needs
• ✅ Keep documentation close to code
• ✅ Update memory files as features evolve
• ✅ Link between related memory files

DON'T:

• ❌ Force every detail into a template
• ❌ Create templates for one-off documentation
• ❌ Let templates become outdated
• ❌ Duplicate information across templates
• ❌ Make templates too complex

Integration with Commands

Many Orchestre commands automatically use templates:

• /document-feature - Uses feature-memory.md template
• /discover-context - Generates memory from existing code
• /extract-patterns - Creates pattern documentation
• /learn - Updates relevant memory files

These commands understand the template structure and can help fill them out based on code analysis and AI insights.

Conclusion

Memory templates transform documentation from a chore into a natural part of development. By providing structure without rigidity, they ensure your project's knowledge is captured, organized, and accessible—both to your team and to AI assistants like Claude Code.

Start with the provided templates, customize them for your needs, and watch as your project's collective memory grows into a powerful development asset.