memory-bank

记忆库

一种自适应记忆系统，让 Claude Code 能在不同会话间持久保留智能上下文，同时减少 token 浪费，让会话时长延长 3-5 倍。它不是一个扁平文件，而是一种分层架构，能够压缩、分支、比较差异、自我修复，并且只加载重要内容。

---

核心架构

记忆库分为三层：

┌─────────────────────────────────────────────┐
│  Layer 2: GLOBAL MEMORY                     │
│  ~/.claude/GLOBAL-MEMORY.md                 │
│  Cross-project patterns, user preferences,  │
│  reusable decisions. Permanent.             │
├─────────────────────────────────────────────┤
│  Layer 1: PROJECT MEMORY                    │
│  ./MEMORY.md (+ branch overlays)            │
│  Architecture, decisions, active work.      │
│  Lives as long as the project.              │
├─────────────────────────────────────────────┤
│  Layer 0: SESSION CONTEXT                   │
│  In-conversation only.                      │
│  Current task focus, scratch notes.         │
│  Dies when session ends (persisted to L1).  │
└─────────────────────────────────────────────┘

第 0 层（会话） — 临时层。跟踪你当前正在做的事。 会话结束时会自动刷新到第 1 层。

第 1 层（项目） — 主要记忆文件。跟踪项目状态、 决策、正在进行的工作和阻碍。感知分支：每个 git 分支都可以有 自己的叠加层，与基础记忆合并。

第 2 层（全局） — 跨项目知识。你的编码偏好、 工具选择和惯用模式。存放在 ~/.claude/GLOBAL-MEMORY.md。 会话开始时与第 1 层一起加载。

完整的架构详情请参阅 references/memory-layers.md。

---

何时激活

触发条件	操作
会话开始，且存在 MEMORY.md	完整加载流程
"remember this"、"don't forget"	会话中途更新
"wrap up"、"save progress"、"done for now"	完整会话写入
"pick up where we left off"、"what were we doing"	加载并总结
"switch to [branch]"、"context for [feature]"	感知分支加载
"memory health"、"is memory stale"	健康检查
"hand off"、"onboard someone"	生成交接文档
"compress memory"、"clean up memory"	执行压缩
"rebuild memory"	恢复模式
"save state"、"continue this later"	会话续接协议
"context budget"、"how much context left"	上下文预算检查
"running out of context"、"session is long"	紧急保存并生成续接文件

---

工作流

1. 会话开始 — 加载流程

在执行任何其他操作之前，按以下流程执行：

Step 1: Detect memory files
  └─ Check for MEMORY.md in project root
  └─ Check for ~/.claude/GLOBAL-MEMORY.md
  └─ Check for MEMORY-ARCHIVE.md (has history been archived?)

Step 2: Detect git context
  └─ Current branch name
  └─ Check for .memory/branches/<branch>.md overlay
  └─ Days since last session (from "Last updated" field)

Step 3: Session diff (if git available)
  └─ Commits since last memory update
  └─ Files changed since last session
  └─ Any conflicts between memory and current code state

Step 4: Health check
  └─ Score memory freshness (see Health Scoring below)
  └─ Flag stale entries
  └─ Flag referenced files that no longer exist

Step 5: Context-aware greeting
  └─ Summarize where we left off (2-3 sentences, specific)
  └─ Report any drift detected (code changed, memory stale)
  └─ State the next immediate action
  └─ Ask: "Ready to continue, or has the plan changed?"

问候示例（记忆新鲜，分支相同）：

"欢迎回来！上次会话中，你完成了 Stripe webhook 处理程序 src/api/webhooks/stripe.ts，接下来准备编写集成测试。 handlePaymentSuccess() 函数已完成，但 handleRefund() 还是存根。 之后新增了 3 个提交——都是你的，没有意外情况。 准备好继续编写集成测试了吗？"

问候示例（记忆过时，已切换分支）：

"欢迎回来！你的记忆来自 5 天前的 main 分支，但你现在在 feature/user-profiles 分支上。我找到了一个 3 天前的分支叠加层， 其中记录了头像上传的相关上下文。不过，记忆中提到的 src/components/Avatar.tsx 已重命名为 ProfileImage.tsx。要不要我 在继续之前先用当前状态更新记忆？"

如果不存在 MEMORY.md：

• 正常继续
• 完成第一项有意义的工作后，主动询问：“要我开始跟踪我们的 进度吗？我会创建一个记忆文件，这样下次会话就能立即继续。”

---

2. 会话中途更新

当用户说“记住这个”，或你完成重要里程碑时：

1. 读取当前的 MEMORY.md
2. 确定发生了哪些变化：
   • 做出了新决策？→ 更新 Key Decisions
   • 完成了任务？→ 从 Active Work 移到 Completed，并更新 Where We Left Off
   • 出现了新的阻碍？→ 添加到 Blockers
   • 有重要上下文？→ 添加到 Notes
3. 写入更新后的文件
4. 具体确认：“已保存——添加了 Zod 迁移决策，并将用户模型标记为已完成。”

会话中途更新时，不要重写整个文件。 只修改发生变化的部分。 这样可以保留会话开始时的上下文。

---

3. 会话结束 — 写入流程

结束会话时，执行完整的记忆写入：

Step 1: Audit the session
  └─ What was accomplished? (be specific: files, functions, lines)
  └─ What decisions were made and why?
  └─ What's blocked or unresolved?
  └─ What should happen next? (crystal clear next step)

Step 2: Compress completed work
  └─ Move finished items to Completed with one-line summaries
  └─ Remove resolved blockers
  └─ Archive stale notes

Step 3: Update memory health metadata
  └─ Update "Last updated" timestamp
  └─ Increment session counter
  └─ Update file reference table (verify paths still exist)

Step 4: Write MEMORY.md
  └─ Full overwrite with current state
  └─ Verify the file was written successfully

Step 5: Check compression threshold
  └─ If > 150 lines, suggest compression
  └─ If > 200 lines, auto-compress (see Smart Compression)

Step 6: Prompt for global memory
  └─ Any cross-project learnings worth saving to Layer 2?
  └─ New user preferences discovered?

---

MEMORY.md 模板

# Project Memory
Last updated: [DATE] | Session [N] | Branch: [BRANCH]
Memory health: [SCORE]/10

## Project Overview
[1-2 sentences. What this is, what stack, what stage.]

## Where We Left Off
- **Current task:** [specific task with file/function reference]
- **Status:** [done | in progress | blocked]
- **Next immediate step:** [so clear Claude can start without asking anything]
- **Open question:** [decision pending, if any]

## Completed
- [DATE] [one-line summary with key files touched]
- [DATE] [one-line summary]

## Active Work
- [ ] [task — specific file, function, or component]
- [ ] [task]
- [x] [recently completed, will archive on next compression]

## Blockers
- [blocker with context on what's needed to unblock]

## Key Decisions
| Date | Decision | Reasoning | Affects |
|------|----------|-----------|---------|
| [DATE] | [what was decided] | [why] | [files/areas impacted] |

## Key Files
| File | Purpose | Last Modified |
|------|---------|---------------|
| [path] | [what it does] | [session N] |

## Architecture Notes
[Non-obvious design choices, data flow, system boundaries]

## Known Issues
- [issue, severity, and workaround if any]

## Session Log
| Session | Date | Summary |
|---------|------|---------|
| [N] | [DATE] | [one-line summary of what happened] |

## User Preferences
[How the user likes to work — discovered across sessions]

## External Context
[APIs, services, env setup — NO secrets, NO credentials, NEVER]

---

分支感知记忆

在多个 git 分支之间切换工作时，记忆会随之调整：

MEMORY.md                          <- Base project memory (main/trunk)
.memory/
  branches/
    feature-auth.md                <- Overlay for feature/auth branch
    feature-payments.md            <- Overlay for feature/payments branch
    bugfix-race-condition.md       <- Overlay for bugfix branch

工作原理：

1. 在会话开始时检测当前 git 分支
2. 首先加载基础 MEMORY.md
3. 检查 .memory/branches/<branch-slug>.md 中是否存在覆盖文件
4. 将覆盖文件合并到基础记忆之上（覆盖文件中的部分优先级更高）
5. 在会话结束时，将更改写回正确的层级：
   • 架构决策 → 基础 MEMORY.md（在各分支间共享）
   • 分支专属工作 → .memory/branches/<branch>.md

分支合并时：

• 当功能分支合并到 main 时，提示： "刚刚合并了 feature/auth 分支。要我将其记忆覆盖文件合并到基础 MEMORY.md，并清理分支文件吗？"

请参阅 references/branch-aware-memory.md，了解合并策略。

---

智能压缩

记忆文件会不断增长。智能压缩让它们保持实用：

自动压缩触发条件：

• MEMORY.md 超过 150 行 → 建议压缩
• MEMORY.md 超过 200 行 → 自动压缩
• 超过 5 个会话的条目 → 可归档候选项

压缩规则：

1. 超过 3 个会话的已完成任务 → 在会话日志中缩为一句话
2. 已解决的阻碍 → 完全移除
3. 过时的“当前工作”条目（3 个或更多会话没有进展）→ 提醒用户
4. 决策日志条目 → 绝不压缩（永久记录）
5. 架构说明 → 绝不压缩（永久记录）

归档： 当会话数超过 10 时，创建 MEMORY-ARCHIVE.md：

# Memory Archive
Archived sessions from Project Memory.

## Sessions 1-8 Summary
[Paragraph summary of early project work]

## Key Milestones
- Session 2: Initial project scaffolding complete
- Session 5: Auth system shipped
- Session 8: Database migration to Prisma complete

请参阅 references/smart-compression.md，了解完整的压缩算法。

---

会话差异对比

在会话开始时，检测自上次写入记忆以来发生的更改：

# Get the date from MEMORY.md "Last updated" field
# Then check what happened since

git log --oneline --since="[last-updated-date]"
git diff --stat HEAD~[commits-since]

报告格式：

"自上次会话（3 天前）以来，共有 7 次提交： 4 次由你提交，3 次由 @teammate 提交。主要更改：重构了 src/api/users.ts， package.json 新增了 2 个依赖项（zod、@tanstack/query）。 你的记忆引用了 src/api/users.ts——我会检查其内容是否仍然准确。"

冲突检测： 当会话差异显示的更改与记忆相矛盾时：

• 记忆称“使用 Express”，但 package.json 现在包含 Fastify → 标记
• 记忆引用了 src/auth/login.ts，但该文件已删除 → 标记
• 记忆称“受阻于 API 密钥”，但 .env 现在已有该密钥 → 更新

请参阅 references/session-diffing.md，了解冲突解决策略。

---

记忆健康度评分

从四个维度对记忆按 1 到 10 分评分：

维度	权重	10 分	1 分
新鲜度	30%	今天更新	超过 14 天
相关性	30%	所有引用的文件都存在	大多数文件缺失或已重命名
完整性	20%	所有部分均已填写，下一步清晰	缺少关键部分
可执行性	20%	可立即开始工作	需要询问 3 个或更多问题

在会话开始时显示：

Memory health: 8/10
  Freshness:    9/10 (updated yesterday)
  Relevance:    7/10 (2 file paths changed)
  Completeness: 8/10 (all sections present)
  Actionability: 9/10 (next step is crystal clear)

如果健康度 < 5： 启动恢复模式，或建议重建记忆。

---

恢复模式

当记忆严重过时、损坏或缺少关键上下文时：

Step 1: Scan the project
  └─ Read package.json / pyproject.toml / go.mod (detect stack)
  └─ Read README.md and CLAUDE.md (project context)
  └─ List key directories and recent files

Step 2: Read git history
  └─ Last 20 commits (who, what, when)
  └─ Current branch and recent branches
  └─ Any open/recent PRs

Step 3: Reconstruct memory
  └─ Build Project Overview from package.json + README
  └─ Build Key Files from most-modified files in git log
  └─ Build Key Decisions from commit messages and code patterns
  └─ Set "Where We Left Off" from most recent commits
  └─ Flag confidence level: "Reconstructed from code — verify with user"

Step 4: Present and confirm
  └─ Show reconstructed memory to user
  └─ Ask for corrections
  └─ Write verified MEMORY.md

---

交接协议

生成一份针对人类（而非 Claude）优化的开发者交接文档：

# Project Handoff: [Project Name]
Generated: [DATE] | By: [user] via Claude Code

## Quick Start
1. Clone: `git clone [repo]`
2. Install: `[package manager] install`
3. Setup: [env vars, database, etc.]
4. Run: `[dev command]`

## Current State
[Where the project is right now — what works, what doesn't]

## Architecture
[System diagram, key components, data flow]

## Active Work
[What's in progress, what's next, what's blocked]

## Key Decisions & Why
[Decisions that a new developer would question — with the reasoning]

## Gotchas
[Things that will bite you if you don't know about them]

## Who to Ask
[People, channels, or docs for domain-specific questions]

通过以下说法触发：“生成交接文档”“让某人熟悉这个项目”“编写交接文档”

---

上下文效率引擎

Claude Code 最常见的抱怨：会话很快就达到上下文限制。 你会把一半 Token 花在重新解释上下文上，另一半才用于实际工作。 Memory Bank 颠倒了这一比例。

Token 问题（使用 tiktoken 验证）

不使用 memory-bank 时，每次会话开始约消耗 1,200 个 Token：

Conversation overhead (4 exchanges):      ~566 tokens
  User re-explains project, stack, status
  Claude asks clarifying questions
  User answers follow-ups
  Back-and-forth until Claude understands

File reads (Claude reads 3+ files to orient): ~634 tokens
  Webhook handler:    ~344 tokens
  Checkout route:     ~257 tokens
  Stripe client:      ~33 tokens

TOTAL per session: ~1,200 tokens
TOTAL over 10 sessions: ~12,000 tokens wasted

Token 解决方案（已验证）

使用 memory-bank 时，相同的会话开始约消耗 400 个 Token：

MEMORY.md loads (compact format):  ~334 tokens
  Entire project context in one structured file
  Decisions, files, status, blockers, architecture

Claude greeting + user confirms:   ~60 tokens
  Claude already knows everything, no questions needed

File reads needed:                 0 tokens
  Memory has file purposes, no need to read source

TOTAL per session: ~394 tokens (67% reduction)
TOTAL over 10 sessions: ~3,940 tokens (saved ~8,060)

这些数字是使用 tiktoken 对我们的示例文件进行测量得出的。 实际节省量取决于项目复杂度（项目越大，节省越多）。

渐进式加载

不要将所有内容一次性塞进上下文。分层加载：

Tier 1: ALWAYS load (costs ~200 tokens)
  └─ Project Overview (1-2 sentences)
  └─ Where We Left Off (current task, status, next step)
  └─ Active Blockers

Tier 2: Load on DEMAND (costs ~300 tokens when needed)
  └─ Key Decisions (only when a decision comes up)
  └─ Key Files (only when working with files not in Tier 1)
  └─ Architecture Notes (only when touching architecture)

Tier 3: Load ONLY when asked (costs ~200 tokens when needed)
  └─ Session Log (only for velocity/history questions)
  └─ User Preferences (only on first session or when relevant)
  └─ External Context (only when working with APIs/services)

结果： 不再一次性加载 800 个 token 的记忆，而是立即加载 200 个 token，仅在确实需要时才加载其余内容。大多数会话根本用不到第 3 层。

精简编码规则

MEMORY.md 中的每一行都经过优化，以最大化每个 token 所承载的信息量：

使用结构化简写，而非散文：

BAD (38 tokens):
  "We made the decision to use Prisma as our ORM instead of Drizzle
   because it provides better TypeScript type inference and the team
   is already familiar with it from previous projects."

GOOD (14 tokens):
  | 2025-04-01 | Prisma over Drizzle | Type inference, team familiarity | All DB |

结构化数据使用表格（压缩效果好）：

BAD (scattered prose — 120 tokens for 5 files):
  The main checkout route is in src/app/api/checkout/route.ts. The Stripe
  client is configured in src/lib/stripe.ts. Cart state management is in...

GOOD (table — 60 tokens for 5 files):
  | File | Purpose |
  | src/app/api/checkout/route.ts | Stripe session creation |
  | src/lib/stripe.ts | Stripe client singleton |
  | src/stores/cart.ts | Zustand cart + persistence |

进行中的工作使用清单（便于浏览，信息密集）：

BAD (prose):
  We are currently working on the webhook handler, which is partially
  complete. We also need to write tests and haven't started yet.

GOOD (checklist):
  - [x] Stripe webhook handler — handlePaymentSuccess()
  - [ ] handleRefund() — stubbed, needs implementation
  - [ ] Integration tests for webhook endpoints

一行一条事实。不写填充词：

BAD: "The project is essentially a web application that was built for..."
GOOD: "Bakery e-commerce. Next.js 14, Prisma, Stripe. Launching April."

上下文预算跟踪

监控 token 用量，并在接近上限前发出警告：

At session start, estimate the context budget:

Available context:   ~200,000 tokens (Claude's window)
Memory load:         ~800 tokens (Tier 1 + loaded Tiers)
System prompt:       ~2,000 tokens
Remaining for work:  ~197,200 tokens

At 40% usage (~80,000 tokens consumed):
  → Suggest: "We're at 40% context. Consider compacting soon."

At 60% usage (~120,000 tokens consumed):
  → Save a session checkpoint automatically
  → Suggest: "Context at 60%. Good time to /compact or start fresh."

At 80% usage (~160,000 tokens consumed):
  → Auto-save full state to MEMORY.md
  → Alert: "Context is at 80%. Saving state now — you can continue
     in a new session with zero loss. Say 'wrap up' or keep going."

会话延续协议

当会话触及上下文上限，或用户想重新开始时：

Step 1: EMERGENCY SAVE (before context dies)
  └─ Write MEMORY.md with EVERYTHING from current session
  └─ Include exact cursor position: file, function, line number
  └─ Include any uncommitted mental model (what Claude was thinking)
  └─ Include partial work state: what's done, what's half-done, what's next

Step 2: Write CONTINUATION.md (a one-shot warm-up file)
  └─ Ultra-compact: under 50 lines, under 500 tokens
  └─ Contains ONLY what the next session needs to start immediately
  └─ Format:

  ```markdown
  # Continue: [task name]
  Resume from: `src/auth/refresh.ts:47` — writing rotateToken()
  
  ## State
  - handlePaymentSuccess(): DONE ✓
  - handleRefund(): stubbed at line 89, needs Stripe refund.created event
  - Tests: NOT STARTED
  
  ## Context
  - Stripe webhook sig verified in middleware (line 12)
  - Using stripe.webhooks.constructEvent() not manual HMAC
  - Refund handler follows same pattern as payment handler
  
  ## Immediate Next Action
  Implement handleRefund() in src/api/webhooks/stripe/route.ts:89
  using the stripe.refund.created event payload. Pattern:
  extract refund.payment_intent → find order → update status to "refunded"

第 3 步：问候并开始（下一个会话） └─ 首先读取 CONTINUATION.md（这是快速通道） └─ 仅在需要时读取 MEMORY.md 以获取完整上下文 └─ 加载后删除 CONTINUATION.md └─ 立即开始工作——无需提问，无需预热

**Trigger phrases:** "save state", "I'm running out of context",
"continue this later", "session is getting long"

### Token Savings By Feature (Verified)

| Feature | How It Saves | Measured Impact |
|---------|-------------|-----------------|
| Structured memory vs re-explaining | Compact file replaces 4+ conversation exchanges | ~566 tokens/session |
| Eliminating orientation file reads | Claude doesn't need to read source files to understand project | ~634 tokens/session |
| Compact encoding (tables > prose) | Same info, 39-42% fewer tokens than prose | 39-42% reduction in memory size |
| Session continuation protocol | CONTINUATION.md is under 200 tokens vs full re-warm-up | ~1,000 tokens on session handoff |
| Smart compression | Keeps memory under 150 lines / ~700 tokens | Prevents bloat over time |

**Verified totals (measured with tiktoken):**

| Scenario | Tokens | Turns |
|----------|--------|-------|
| Without memory-bank | ~1,200/session | 8 turns |
| With memory-bank | ~394/session | 2 turns |
| **Savings** | **~806/session (67%)** | **6 turns** |
| Over 10 sessions | **~8,060 saved** | 60 turns saved |
| Over 30 sessions | **~24,180 saved** | 180 turns saved |

### Anti-Patterns That Waste Tokens

**Never do these in memory files:**

✗ 明明表格就够，却使用冗长的散文 ✗ 在多个章节中重复相同信息 ✗ 在记忆中存储代码片段（改为引用文件:行号） ✗ 冗长描述已完成的工作（仅保留一行摘要） ✗ 保留已解决的阻碍（将其删除） ✗ 存储 README.md 或 CLAUDE.md 中已有的信息 ✗ 用记忆记录 Git 会追踪的内容（提交历史、差异、代码归属信息）

**Always do these:**

✓ 结构化数据（决策、文件、任务）使用表格 ✓ 进行中的工作使用清单 ✓ 项目概述只用一句话（而非一段话） ✓ 使用文件:行号引用，而非描述代码 ✓ 删除已解决事项（它们已留在 Git 历史中） ✓ 引用其他文件，而非重复内容

> See `references/context-efficiency.md` for the full token optimization guide.

---

## Rules for Excellent Memory

**Be surgical, not vague.**
Bad: "Working on auth"
Good: "Implementing JWT refresh token rotation in `src/auth/refresh.ts` —
`rotateToken()` is complete, needs Redis TTL logic in `src/cache/tokens.ts:47`"

**The "Next immediate step" is the single most important line.**
It should be so precise that Claude can start coding the instant a session
begins, with zero clarifying questions.

**Capture the "why" behind every decision.**
Future Claude will encounter the same trade-offs and re-litigate them
unless the reasoning is recorded.

**Never store secrets.** No API keys, passwords, tokens, or credentials.
Ever. Not even "temporarily". Reference `.env` or a secrets manager instead.

**Overwrite on session end, surgical update mid-session.**
Session end = full rewrite for consistency. Mid-session = targeted section
updates to avoid losing context.

**Keep it under 150 lines.** Compress aggressively. Stale information is
actively harmful — it misleads more than it helps.

---

## Auto-Setup via CLAUDE.md

For fully automatic memory with all features, add to project `CLAUDE.md`
(or `~/.claude/CLAUDE.md` for all projects):

```markdown
## Memory

At the start of every session:
1. Check for MEMORY.md in the project root
2. Check for ~/.claude/GLOBAL-MEMORY.md
3. Check current git branch and look for .memory/branches/<branch>.md
4. Run session diff — what changed since last memory update
5. Score memory health and flag any issues
6. Greet me with a specific summary and the next immediate step

During sessions:
- Update memory when I say "remember this" or complete a milestone
- Track key decisions with reasoning in the decision table

At session end (when I say "wrap up", "save", "done for now"):
1. Write comprehensive MEMORY.md with full current state
2. Ensure "Next immediate step" is crystal clear
3. Run compression if over 150 lines
4. Confirm what was saved

完整的集成指南请参阅 references/claude-md-integration.md。

---

参考文件

• references/memory-layers.md — 3 层记忆系统的完整架构，包括晋升规则和跨层交互
• references/branch-aware-memory.md — Git 分支集成、叠加合并和清理策略
• references/smart-compression.md — 压缩算法、归档阈值，以及绝不能压缩的内容
• references/session-diffing.md — 跨会话变更检测、冲突解决和偏差修正
• references/advanced-patterns.md — 团队工作流、进度跟踪、交接协议和企业级模式
• references/context-efficiency.md — token 优化指南、渐进式加载详情和精简编码参考
• references/claude-md-integration.md — 在所有项目中实现自动触发的完整设置指南

示例

• examples/solo-fullstack.md — Next.js 应用独立开发者的记忆示例
• examples/team-backend.md — 后端服务的团队共享记忆
• examples/monorepo.md — 单体仓库的多领域记忆
• examples/minimal.md — 用于快速原型的 5 行记忆