Claude Code记忆系统：四层持久化全实战

graph TB
    subgraph "Claude Code 四层记忆架构"
        L1["第一层：CLAUDE.md<br/>项目级持久指令<br/>提交到Git，团队共享"]
        L2["第二层：CLAUDE.local.md<br/>个人本地偏好<br/>不提交，仅自己可见"]
        L3["第三层：Auto Memory<br/>自动学习积累<br/>存储在 ~/.claude/"]
        L4["第四层：模块化规则<br/>.claude/rules/*.md<br/>按场景拆分指令"]
    end

    L1 --> |"会话启动时加载"| CTX["上下文窗口<br/>200K token"]
    L2 --> CTX
    L3 --> CTX
    L4 --> CTX

    CTX --> |"会话中动态管理"| TOOLS["管理工具<br/>/compact /clear /memory"]

    style L1 fill:#4A90D9,color:#fff
    style L2 fill:#7B68EE,color:#fff
    style L3 fill:#20B2AA,color:#fff
    style L4 fill:#FF8C00,color:#fff

# My Project

This is a full-stack application built with React and Node.js.
We use TypeScript for type safety. The database is PostgreSQL.
Our team follows agile methodology with two-week sprints...
（200行项目介绍）

# Project Instructions

## Tech Stack
- Frontend: React 19 + TypeScript 5.x (strict mode)
- Backend: Node.js 22 + Fastify 5.x
- Database: PostgreSQL 16 + Drizzle ORM
- Package Manager: pnpm (NOT npm or yarn)

## Code Style
- Use functional components, no class components
- Named exports only, no default exports
- File naming: kebab-case for utilities, PascalCase for components
- Error handling: use Result<T, E> pattern from `src/lib/result.ts`

## Commands
- `pnpm dev` — start dev server (port 3000)
- `pnpm test` — run all tests
- `pnpm db:push` — sync schema to database
- `pnpm lint:fix` — auto-fix linting issues

## Architecture
- `src/features/` — feature modules (each has routes/, components/, hooks/)
- `src/lib/` — shared utilities
- `src/server/` — API routes and services
- NEVER modify `src/generated/` — auto-generated by Drizzle

## Critical Rules
- ALWAYS run `pnpm test` after modifying any file in src/server/
- NEVER commit .env files
- Database migrations go in `drizzle/migrations/` with timestamp prefix

echo "CLAUDE.local.md" >> .gitignore

# Local Preferences

## Editor
- I use Neovim with lazyvim config
- When showing code snippets, prefer short form

## Language
- Respond in Chinese (中文回复)
- Code comments in English

## Workflow
- I prefer step-by-step explanations
- Show me the diff before applying changes
- Run tests after each modification

## My Common Paths
- Test data: ~/projects/test-data/
- Local config: ~/.config/myapp/

# Global Preferences

## Style
- Use Chinese for all responses
- Keep responses concise
- Code comments in English

## Git
- Never auto-commit
- Never push without asking
- Always check git status before committing

## Safety
- Never delete files without confirmation
- Never modify .env files
- Always read before editing

# 在Claude Code会话中输入
/memory

Loaded memory files:
  ~/.claude/CLAUDE.md (global user instructions)
  ./CLAUDE.md (project instructions)
  ./CLAUDE.local.md (local instructions)
  ~/.claude/memory/auto-learned.md (auto memory, 47 lessons)
  ./.claude/rules/typescript.md (rule: typescript conventions)
  ./.claude/rules/api-design.md (rule: API design patterns)

> 记住：我们的staging环境数据库密码每天自动轮换，
> 测试时用 mock-db.sh 脚本生成临时连接

> 记住：修改 src/api/ 下的文件后必须运行 
> pnpm test:integration

> 记住：不要用 axios，我们项目统一用 fetch + 
> src/lib/http.ts 的封装

~/.claude/
├── CLAUDE.md                    # 全局指令
├── memory/
│   ├── auto-learned.md          # 通用教训（主文件）
│   ├── project-patterns.md      # 项目模式
│   ├── debugging-notes.md       # 调试经验
│   └── api-conventions.md       # API约定

> /memory

（查看记忆列表）

> 清理auto memory中过时的条目：
> - 删除关于旧版本React的规则（已升级到React 19）
> - 删除已解决的调试笔记
> - 合并重复的API约定

mkdir -p .claude/rules

# TypeScript Conventions

- Strict mode enabled (tsconfig.json > strict: true)
- Prefer `interface` over `type` for object shapes
- Use `unknown` instead of `any`, narrow with type guards
- Generic naming: T for single, K/V for key-value, TInput/TOutput for transforms
- Branded types for domain primitives (UserId, OrderId, etc.)

# Database Rules

- Using Drizzle ORM with PostgreSQL
- Schema files in `src/db/schema/`
- NEVER write raw SQL — use Drizzle query builder
- Migrations must be reversible (always include down migration)
- Use transactions for multi-table operations
- Index foreign keys automatically

# Testing Standards

- Framework: Vitest + React Testing Library
- File naming: `*.test.ts` or `*.test.tsx`
- Co-locate tests with source files
- Use `describe/it` blocks, not `test()`
- Mock external APIs with MSW (Mock Service Worker)
- Minimum coverage: 80% for src/server/, 70% for src/features/

# API Design Patterns

- RESTful endpoints under `/api/v1/`
- Use Zod for request/response validation
- Error response format: `{ error: { code: string, message: string, details?: unknown } }`
- Pagination: cursor-based for lists > 100 items
- Authentication: Bearer token in Authorization header

# 在会话中输入
/compact

/compact 保留所有架构决策和数据库schema变更，丢弃调试过程

/clear

graph LR
    A["开始会话"] --> B{"完成任务？"}
    B -->|"是"| C["结束"]
    B -->|"否，上下文>60%"| D["/compact"]
    D --> B
    B -->|"否，完全偏离"| E["/clear + 简要重述目标"]
    E --> B

    style D fill:#FF8C00,color:#fff
    style E fill:#DC143C,color:#fff

# 1. 创建项目
mkdir my-saas-app && cd my-saas-app

# 2. 初始化Git
git init

# 3. 创建目录结构
mkdir -p .claude/rules src/features src/server src/lib

# Project: MySaaS

## Tech Stack
- Next.js 15 (App Router) + TypeScript 5.x strict
- Tailwind CSS 4 + shadcn/ui components
- Drizzle ORM + PostgreSQL 16 (Neon serverless)
- Auth: Clerk
- Package manager: pnpm 9.x

## Commands
- `pnpm dev` — dev server on port 3000
- `pnpm build` — production build
- `pnpm test` — vitest unit tests
- `pnpm lint` — eslint + prettier check
- `pnpm db:push` — sync Drizzle schema to DB
- `pnpm db:studio` — open Drizzle Studio

## Architecture

## Critical Rules
- ALWAYS run `pnpm test` after modifying server/ or lib/
- NEVER modify src/db/schema without creating a migration
- ALWAYS use `cn()` utility for className merging
- Server Components by default; add 'use client' only when needed
- API errors use `errorResponse()` from `src/lib/api.ts`

# Git相关规则
cat > .claude/rules/git.md << 'EOF'
# Git Workflow

- Commit messages: conventional commits format (feat:, fix:, chore:, etc.)
- NEVER commit without running `pnpm lint` first
- NEVER push without explicit user approval
- Always check `git status` and `git diff` before staging
- Prefer creating new commits over amending
EOF

# 安全规则
cat > .claude/rules/security.md << 'EOF'
# Security Rules

- NEVER expose API keys in client-side code
- ALWAYS validate server-side inputs with Zod schemas
- Use Clerk's `auth()` for server-side auth checks
- Rate limit all API endpoints (use `src/lib/rate-limit.ts`)
- SQL injection prevention: use Drizzle parameterized queries only
EOF

# 性能规则
cat > .claude/rules/performance.md << 'EOF'
# Performance

- Use `next/dynamic` for heavy client components
- Implement loading.tsx for route-level Suspense boundaries
- Database queries: always select specific columns, never SELECT *
- Use React `use()` for data fetching in Server Components
- Cache expensive computations with `unstable_cache` from Next.js
EOF

cat > CLAUDE.local.md << 'EOF'
# Local Preferences

- Respond in Chinese
- I use Neovim + tmux, show code in terminal-friendly format
- When debugging, show me the failing test output first
- I prefer inline error handling over try/catch wrappers
EOF

echo "CLAUDE.local.md" >> .gitignore

cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences

## Language
- 默认使用中文回复，代码注释可用英文
- 回复简洁明了，避免冗长解释

## General Rules
- 不要自动commit，只在用户明确要求时执行
- 始终先读取文件再编辑
- 不要主动创建文档文件，除非明确要求
- 优先编辑现有文件而非创建新文件

## Safety
- 不要提交 secrets、credentials、.env 等敏感文件
- commit message 不要自动加版本号
EOF

# 只提交团队共享的配置
git add CLAUDE.md .claude/rules/ .gitignore
git commit -m "feat: add Claude Code memory system configuration"

# Project Memory

## Current State
- Sprint: Week 3 of 4
- Focus: Billing integration (Stripe)
- Last deployed: 2026-05-20 (v0.4.2)

## Active Threads
- [ ] Webhook handler for Stripe needs idempotency
- [ ] Dashboard charts showing stale data (cache invalidation issue)
- [x] Auth flow refactored to use Clerk's new SSR helpers

## Lessons Learned
- Drizzle `jsonb` columns need explicit type casting for PostgreSQL
- Next.js 15 `cookies()` requires `await` — non-obvious breaking change
- shadcn/ui Dialog doesn't unmount on close — memory leak in long sessions

## Decisions
- 2026-05-15: Chose Neon serverless over Supabase for Postgres (cold start acceptable for our scale)
- 2026-05-18: Decided against tRPC — REST + Zod sufficient for our 12 endpoints
- 2026-05-21: Billing will use Stripe Checkout, not Stripe Billing (simpler for MVP)

> 更新MEMORY.md：记录今天的进展和未完成的任务

graph TB
    subgraph "六层记忆架构"
        L1["Layer 1: 全局CLAUDE.md<br/>个人身份、通用偏好"]
        L2["Layer 2: 项目CLAUDE.md<br/>技术栈、命令、架构"]
        L3["Layer 3: CLAUDE.local.md<br/>个人工作流偏好"]
        L4["Layer 4: .claude/rules/<br/>模块化场景规则"]
        L5["Layer 5: MEMORY.md<br/>项目状态日志+教训"]
        L6["Layer 6: Auto Memory<br/>自动积累的教训"]
    end

    L1 --> L2 --> L3 --> L4 --> L5 --> L6

    style L5 fill:#9370DB,color:#fff
    style L6 fill:#20B2AA,color:#fff

// .claude/settings.json
{
  "hooks": {
    "SessionEnd": [
      {
        "command": "claude -p 'Review and clean up MEMORY.md. Remove resolved threads, archive old decisions older than 30 days. Keep lessons learned concise.' --allowedTools 'Edit,Read,Write'",
        "timeout": 60000
      }
    ]
  }
}

# 工作空间结构
workspace/
├── bootstrap/              # 引导仓库（记忆中心）
│   ├── CLAUDE.md           # 全局工作空间说明
│   ├── REPOS.md            # 所有仓库清单和关系
│   └── scripts/
│       └── sync-memory.sh  # 同步记忆到各仓库
├── services/
│   ├── user-service/       # 用户服务
│   │   └── CLAUDE.md
│   ├── order-service/      # 订单服务
│   │   └── CLAUDE.md
│   └── payment-service/    # 支付服务
│       └── CLAUDE.md
└── shared-libs/            # 共享库
    └── CLAUDE.md

# Repository Manifest

## Architecture

## Common Patterns
- All services: Fastify + TypeScript + Drizzle
- All APIs: REST with /api/v1/ prefix
- All use `@shared/logger` for structured logging
- Inter-service auth: JWT with shared public key

## Key People
- user-service: @alice (lead), @bob
- order-service: @charlie (lead)
- payment-service: @alice, @diana

> /memory
> 分析当前加载的所有记忆文件，估算总token消耗，
> 标记出可能过时或重复的内容

有效上下文 = 200K（总窗口）
          - CLAUDE.md tokens
          - local.md tokens
          - rules tokens（按场景加载）
          - auto memory tokens
          = 可用于实际工作的token

sequenceDiagram
    participant D as 开发者
    participant C as Claude Code
    participant G as Git Repo

    D->>C: 开始新会话
    C->>C: 加载 CLAUDE.md + rules + auto memory
    D->>C: 执行任务
    C->>C: 发现新的项目知识
    C-->>D: 建议更新 CLAUDE.md 或 rules
    D->>C: 确认更新
    C->>G: 提交更新的记忆文件
    Note over G: 团队其他成员<br/>pull后获得新知识

> 打开auto memory文件，删除关于"使用axios"的错误记录，
> 我们项目用的是fetch

# 找到auto memory文件
ls ~/.claude/memory/
# 编辑清理
vim ~/.claude/memory/auto-learned.md