memory-management

Memory Management

Master Claude Code's memory system for persistent context across sessions, projects, and teams.

Quick Reference

Memory Hierarchy

Claude Code reads memory files in this order (later overrides earlier):

~/.claude/CLAUDE.md           # Your global preferences
  |
  v
./CLAUDE.md                   # Project root instructions
  |
  v
./.claude/CLAUDE.md           # Project config directory
  |
  v
./.claude/rules/*.md          # Conditional rules (when matched)

Priority Rules

1. Rules always win - When a rule file matches, its instructions take precedence
2. Project overrides global - Project CLAUDE.md supersedes global settings
3. Later loads override earlier - Last-loaded content has highest priority
4. Explicit beats implicit - Specific rules override general guidelines

When to Use Each Memory Type

Use Global Memory (~/.claude/CLAUDE.md) For

• Personal coding preferences (tabs vs spaces, quote style)
• Universal tool preferences (Bun over npm, rg over find)
• Cross-project conventions you always follow
• Personal workflow shortcuts

Example:

# Global Preferences

## Code Style
- Use single quotes for strings
- Prefer for-loops over forEach
- Use Bun instead of npm

## Tools
- Use ripgrep (rg) for searching, not grep
- Prefer Edit over Write for modifications

Use Project Memory (./CLAUDE.md or ./.claude/CLAUDE.md) For

• Project-specific tech stack (React, Bun, Drizzle, etc.)
• Build and test commands
• Architecture overview
• Team conventions
• File structure explanations

Example:

# Project: E-Commerce API

## Tech Stack
- Runtime: Bun
- Framework: Hono
- Database: PostgreSQL with Drizzle ORM
- Testing: Bun test

## Commands
- `bun dev` - Start development server
- `bun test` - Run all tests
- `bun db:migrate` - Run database migrations

## Architecture
- `/src/routes` - API route handlers
- `/src/services` - Business logic
- `/src/db` - Database schema and queries

Use Rules (./.claude/rules/*.md) For

• File-type-specific instructions (TypeScript, React, SQL)
• Conditional guidance based on file paths
• Modular memory that loads only when relevant
• Team standards that apply to specific areas

Example:

.claude/rules/
  react-components.md     # Globs: src/components/**/*.tsx
  api-routes.md           # Globs: src/routes/**/*.ts
  database.md             # Globs: src/db/**/*.ts, *.sql
  tests.md                # Globs: **/*.test.ts, **/*.spec.ts

CLAUDE.md Structure

A well-structured CLAUDE.md file includes:

# Project Name

Brief description (1-2 sentences).

## Commands
- `bun install` - Install dependencies
- `bun dev` - Start development
- `bun test` - Run tests
- `bun build` - Build for production

## Tech Stack
- Runtime/Framework
- Database
- Key libraries

## Architecture
Brief overview of project structure.

## Code Style
Project-specific conventions.

## Important Notes
Critical information Claude should always know.

For detailed CLAUDE.md guidance, see CLAUDE-MD.md.

Rules Directory

The .claude/rules/ directory contains modular memory files that load conditionally.

Rule File Anatomy

---
globs: ["src/components/**/*.tsx", "src/ui/**/*.tsx"]
description: React component conventions for this project
alwaysApply: false
---

# React Components

Follow these patterns for React components...

Glob Matching

• Exact match: src/utils.ts
• Directory: src/components/**/*
• Extension: **/*.tsx
• Multiple: ["*.ts", "*.tsx"]

For complete rules documentation, see RULES.md.

Best Practices

Do Include

• Commands with exact syntax
• Tech stack overview
• Key architectural decisions
• Non-obvious conventions
• Error-prone areas

Do NOT Include

• Code that's easily discoverable (read the files instead)
• Verbose documentation (link instead)
• Information that changes frequently
• Full API documentation

Keep Memory Focused

## Good - Actionable and Specific

- Use Drizzle ORM for database queries
- Run `bun test` before committing
- Components go in `src/components/{feature}/`

## Avoid - Vague or Obvious

- Write clean code
- Test your changes
- Follow best practices

Reference, Don't Duplicate

## Good - Reference External Docs

See API documentation at `docs/api.md`.
Architecture diagrams in `docs/architecture/`.

## Avoid - Duplicating Content

[Pasting entire API documentation here]

Memory Strategies

Project Onboarding

When starting with a new project:

1. Create minimal CLAUDE.md with commands and tech stack
2. Add rules for the main file types you work with
3. Expand gradually as you discover project quirks
4. Update regularly when conventions change

Team Conventions

For team projects:

1. Commit CLAUDE.md and .claude/rules/ to version control
2. Keep personal preferences in ~/.claude/CLAUDE.md
3. Document decisions in rules files, not code comments
4. Review memory files during onboarding

Cross-Session Continuity

To maintain context across sessions:

1. Session hooks can inject recent context at start
2. Weave framework captures learnings for future sessions
3. Project memory persists architectural decisions
4. Rules files encode learned patterns

For advanced memory strategies, see STRATEGIES.md.

Common Patterns

Monorepo Pattern

project/
  CLAUDE.md                    # Shared conventions
  .claude/
    rules/
      frontend.md              # Globs: apps/web/**/*
      backend.md               # Globs: apps/api/**/*
      packages.md              # Globs: packages/**/*
  apps/
    web/
      CLAUDE.md                # Web-specific context
    api/
      CLAUDE.md                # API-specific context

Feature Flag Pattern

# .claude/rules/feature-flags.md
---
globs: ["src/**/*.ts", "src/**/*.tsx"]
---

## Feature Flags

Active flags:
- `ENABLE_NEW_CHECKOUT` - New checkout flow (enabled in staging)
- `DARK_MODE` - Dark mode support (enabled everywhere)

Check flags with: `useFeatureFlag('FLAG_NAME')`

Migration Pattern

# .claude/rules/migrations.md
---
globs: ["src/db/migrations/**/*.ts"]
---

## Database Migrations

1. Generate: `bun db:generate`
2. Run: `bun db:migrate`
3. Rollback: `bun db:rollback`

Naming: `NNNN_description.ts`
Always include down migration.

Reference Files

Validation Checklist

Before finalizing memory setup:

• Global preferences in ~/.claude/CLAUDE.md
• Project context in ./CLAUDE.md or ./.claude/CLAUDE.md
• Modular rules for file-specific guidance
• Commands section with exact syntax
• Tech stack clearly documented
• No duplicated documentation
• Rules have appropriate glob patterns
• Memory files committed to version control

Common Mistakes