memory-patterns

Memory Patterns

Claude Code's auto memory system persists knowledge across sessions via files in the memory directory. MEMORY.md is always loaded into context; topic files store detailed notes referenced from MEMORY.md.

When to Use

• User asks "remember this" or "always do X"
• User corrects a mistake that came from memory — update the source
• You discover stable project patterns worth persisting
• User asks about organizing cross-session knowledge
• You need to structure MEMORY.md or create topic files

Core Patterns

MEMORY.md Structure

MEMORY.md is the index file — always loaded, so it must stay concise (under 200 lines). Use it as a table of contents pointing to detailed topic files:

# Project Memory

## Project Overview
- Name: acme-api
- Stack: Node.js, Express, PostgreSQL, TypeScript
- Test framework: Vitest
- Package manager: pnpm

## Key Conventions
- Use Zod for all input validation
- Repository pattern for database access
- All API responses follow ApiResponse<T> interface
- Feature branches: feat/description, fix/description

## Architecture
- See [architecture.md](./architecture.md) for service layout
- See [database.md](./database.md) for schema notes

## User Preferences
- Prefers functional style over classes
- Always use named exports (no default exports)
- Run tests before committing

## Known Issues
- See [debugging.md](./debugging.md) for recurring problems

Topic File Organization

Create separate files for detailed knowledge. Link them from MEMORY.md:

memory/
  MEMORY.md              # Index (always loaded, < 200 lines)
  architecture.md        # Service layout, module boundaries
  database.md            # Schema notes, migration patterns
  debugging.md           # Recurring issues and solutions
  patterns.md            # Code patterns specific to this project
  api-conventions.md     # API design decisions

Each topic file should be self-contained:

# Architecture Notes

## Service Layout
- src/services/ — Business logic, one file per domain
- src/routes/ — Express route handlers, thin layer
- src/db/ — Database access via repository pattern
- src/middleware/ — Auth, validation, error handling

## Module Boundaries
- Services never import from routes
- Routes call services, never DB directly
- Middleware is stateless

## Key Dependencies
- src/services/auth.ts depends on src/db/users.ts
- src/services/billing.ts depends on external Stripe SDK