Create Memory Files

Track important learnings and decisions in .claude/memory/ files.

When to Use

• Just implemented major feature or system
• Made important architectural decision
• Discovered critical project patterns
• User says "remember this" or "track this"
• Solved complex bug with important learnings
• Established new workflow or standard

Current Memory Files

.claude/memory/
├── research-first-enforcement.md  # How research-first is enforced
├── coding-standards.md            # TypeScript, style, errors
├── testing-standards.md           # NO MOCKS, Bun, Playwright
├── architecture-patterns.md       # Tech stack, patterns
├── common-workflows.md            # DB migrations, API, 3D, git
├── build-commands.md              # Dev, build, test commands
├── asset-forge-guide.md           # Project specifics
└── security-protocols.md          # Auth, API security, secrets

All imported in CLAUDE.md at root.

Memory File Template

# [Topic Name]

**Status**: [ACTIVE/DEPRECATED/IN-PROGRESS]
**Date**: [YYYY-MM-DD]
**Related**: [Other memory files, if any]

## Purpose

[Why this memory file exists - what problem does it solve?]

## Key Learnings

### 1. [Major Learning]
[Detailed explanation]

**Why it matters**: [Impact/importance]

### 2. [Major Learning]
[Detailed explanation]

**Example**:
\```[language]
[code example if applicable]
\```

## Implementation Details

[How this is actually implemented in the project]

**Files affected**:
- path/to/file1.ts
- path/to/file2.tsx

## Common Pitfalls

- ❌ [What NOT to do]
- ❌ [What NOT to do]
- ✅ [What to DO instead]

## Examples

### Good Example
\```[language]
[code showing correct pattern]
\```

### Bad Example
\```[language]
[code showing incorrect pattern]
\```

## Related Commands/Skills

- `/command-name` - [What it does]
- `skill-name` - [What it does]

## Future Considerations

[Things to watch out for, potential improvements]

Example Memory Files to Create

hyperscape-engine-integration.md

• How Hyperscape engine integrates with asset-forge
• Game world architecture
• Asset loading patterns

three-js-optimization-patterns.md

• LOD strategies
• Instancing for repeated models
• Material reuse
• Disposal patterns

privy-auth-integration.md

• JWT verification patterns
• User session management
• Auth middleware setup

drizzle-migration-workflow.md

• How we create migrations
• Schema change patterns
• Rollback strategies

api-testing-patterns.md

• How we test Elysia routes
• No-mock testing approach
• Integration test setup

After Creating Memory File

1. Add to CLAUDE.md imports:

## [Section Name]

@.claude/memory/new-file-name.md

2. Verify import:

grep "new-file-name" CLAUDE.md

Best Practices

• Be specific - Don't create vague "notes.md" files
• Include examples - Code examples make it memorable
• Date it - Track when learnings happened
• Update existing - Prefer updating existing memory over creating new
• Reference files - Link to actual code files affected
• Mark status - Is this current? Deprecated? In progress?

Memory File Lifecycle

1. Create - When major learning happens
2. Update - As patterns evolve
3. Reference - Import in CLAUDE.md
4. Deprecate - Mark outdated when patterns change
5. Archive - Delete if truly obsolete (rare)

Memory vs Documentation

Memory files are for Claude, not users:

• Internal patterns and decisions
• "Why we do X instead of Y"
• Critical learnings from past mistakes
• Project-specific conventions

Documentation is for users:

• README.md
• API docs
• User guides

Keep them separate.