Back to Details

auto-memory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Auto Memory Management

自动内存管理

Use persistent auto memory to retain project knowledge across Claude Code sessions. The memory directory (
~/.claude/projects/<path>/memory/
) stores a concise index file (
MEMORY.md
) and detailed topic files, creating a structured knowledge base that grows with the project.
使用持久化自动内存在Claude Code会话间保留项目知识。内存目录（
~/.claude/projects/<path>/memory/
）存储一个简洁的索引文件（
MEMORY.md
）和详细的主题文件，构建随项目发展而增长的结构化知识库。

Core Architecture

核心架构

text
~/.claude/projects/<project-path>/memory/
├── MEMORY.md          # Always loaded into system prompt (~200 lines max)
├── architecture.md    # Topic file: system architecture decisions
├── patterns.md        # Topic file: code patterns and conventions
├── debugging.md       # Topic file: debugging insights
├── workflows.md       # Topic file: development workflows
└── known-issues.md    # Topic file: bug tracking
text
~/.claude/projects/<project-path>/memory/
├── MEMORY.md          # 始终加载到system prompt中（最多约200行）
├── architecture.md    # 主题文件：系统架构决策
├── patterns.md        # 主题文件：代码模式与规范
├── debugging.md       # 主题文件：调试见解
├── workflows.md       # 主题文件：开发工作流
└── known-issues.md    # 主题文件：Bug追踪

Two-Tier Design

双层设计

  1. MEMORY.md (always in context): Concise index with key facts, quick reference tables, and links to topic files. Lines after 200 are truncated — keep it tight.
  2. Topic files (consulted as needed): Detailed reference organized by domain. No size limit, but keep each file focused on one topic.
  1. MEMORY.md（始终处于上下文）：包含关键事实、快速参考表和主题文件链接的简洁索引。超过200行的内容会被截断——请保持内容精炼。
  2. 主题文件（按需查阅）：按领域组织的详细参考资料。无大小限制，但每个文件需聚焦单一主题。

What to Save

需保存的内容

Save These

建议保存

  • Stable patterns confirmed across multiple interactions (naming conventions, file organization, coding style)
  • Architectural decisions and their rationale
  • Important file paths and project structure
  • User preferences for workflow, tools, and communication style
  • Solutions to recurring problems and debugging insights
  • Critical gotchas that cause repeated mistakes
  • Explicit user requests ("always use bun", "never auto-commit") — save immediately, no need to wait for confirmation across sessions
  • 经多次交互确认的稳定模式（命名规范、文件组织、编码风格）
  • 架构决策及其理由
  • 重要文件路径与项目结构
  • 用户对工作流、工具和沟通风格的偏好
  • 反复出现问题的解决方案与调试见解
  • 易导致重复错误的关键注意事项
  • 用户明确要求（如“始终使用bun”、“绝不自动提交”）——立即保存，无需跨会话确认

Do NOT Save

请勿保存

  • Session-specific context (current task details, in-progress work, temporary state)
  • Unverified information — verify against project docs before writing
  • Duplicates of CLAUDE.md — memory supplements project instructions, never contradicts them
  • Speculative conclusions from reading a single file
  • Rapidly changing values (exact line numbers, temporary feature flags)
  • 会话特定上下文（当前任务细节、进行中的工作、临时状态）
  • 未验证信息——写入前需对照项目文档确认
  • CLAUDE.md的重复内容——内存是对项目说明的补充，绝不与其冲突
  • 仅通过单个文件得出的推测性结论
  • 快速变化的值（精确行号、临时功能标志）

Setting Up Auto Memory

自动内存设置步骤

Step 1: Create the Memory Directory

步骤1：创建内存目录

The directory is created automatically by Claude Code, but to initialize manually:
bash
mkdir -p ~/.claude/projects/<project-path>/memory/
The 
<project-path>
typically mirrors the working directory with slashes replaced by dashes (e.g., 
/workspaces/my-app
becomes 
-workspaces-my-app
).
该目录由Claude Code自动创建，如需手动初始化：
bash
mkdir -p ~/.claude/projects/<project-path>/memory/
<project-path>
通常会将工作目录的斜杠替换为连字符（例如
/workspaces/my-app
变为
-workspaces-my-app
）。

Step 2: Create MEMORY.md

步骤2：创建MEMORY.md

Start with a minimal index and expand as patterns emerge. Include:
  • Project overview: Key architectural facts (2-3 bullet points)
  • Quick reference: Counts, paths, conventions that come up repeatedly
  • Critical gotchas: Hard-won lessons that prevent repeated mistakes
  • Topic file index: Table linking to detailed files with "when to consult" guidance
See examples/MEMORY.md for a starter template.
从最小化索引开始，随着模式出现逐步扩展。内容应包括：
  • 项目概述：关键架构事实（2-3个要点）
  • 快速参考：频繁提及的数量、路径、规范
  • 关键注意事项：避免重复犯错的经验教训
  • 主题文件索引：链接到详细文件的表格，并标注“何时查阅”的指引
可参考examples/MEMORY.md获取入门模板。

Step 3: Create Topic Files as Needed

步骤3：按需创建主题文件

Create topic files only when a domain accumulates enough detail to warrant its own file. Common topic files:
FilePurpose
architecture.md
System design decisions, component relationships
patterns.md
Code conventions, naming, file organization
debugging.md
Solutions to recurring problems
workflows.md
Build, test, deploy procedures
known-issues.md
Bug tracking, open/fixed issues
release-process.md
Version management, release checklists
dependencies.md
Package versions, compatibility notes
See examples/topic-file.md for the recommended structure.
仅当某个领域积累了足够多的细节，值得单独成文件时再创建主题文件。常见主题文件：
文件用途
architecture.md
系统设计决策、组件关系
patterns.md
代码规范、命名规则、文件组织
debugging.md
反复出现问题的解决方案
workflows.md
构建、测试、部署流程
known-issues.md
Bug追踪、已解决/未解决问题
release-process.md
版本管理、发布检查清单
dependencies.md
包版本、兼容性说明
可参考examples/topic-file.md获取推荐结构。

Organization Principles

组织原则

Semantic Over Chronological

语义优先而非时间优先

Organize by topic, not by date. "Architecture decisions" is better than "Session notes 2026-02-15". When new information arrives, integrate it into the appropriate topic rather than appending chronologically.
按主题而非日期组织内容。“架构决策”比“2026-02-15会话笔记”更合适。当有新信息时，将其整合到对应主题中，而非按时间顺序追加。

Concise Index, Detailed Topics

简洁索引，详细主题

MEMORY.md answers "what do I need to know right now?" Topic files answer "what are all the details about X?" Keep the index scannable — use bullet points, tables, and bold for key terms.
MEMORY.md回答“我现在需要知道什么？”，主题文件回答“关于X的所有细节是什么？”。保持索引易于扫描——使用要点、表格和加粗突出关键术语。

Topic File Index Table

主题文件索引表

Always include a table in MEMORY.md linking to topic files with guidance on when to consult each:
markdown
undefined
务必在MEMORY.md中包含一个表格，链接到各主题文件并标注查阅指引：
markdown
undefined

Topic Files

主题文件

FileWhen to consult
architecture.md
Working on system design, component changes
patterns.md
Writing new code, reviewing conventions
debugging.md
Investigating bugs, error messages
undefined
文件查阅场景
architecture.md
进行系统设计、组件变更时
patterns.md
编写新代码、检查规范时
debugging.md
排查Bug、处理错误信息时
undefined

One Topic Per File

单一主题对应单一文件

Each file covers one domain. If a file grows beyond ~5,000 words or covers multiple unrelated topics, split it. A file named 
misc.md
or 
notes.md
is a sign of poor organization.
每个文件仅覆盖一个领域。若文件超过约5000字或涵盖多个不相关主题，应拆分文件。命名为
misc.md
或
notes.md
是组织不当的表现。

Maintenance

维护指南

When to Update

更新时机

  • After discovering a mistake that could recur
  • When a pattern is confirmed across 2+ interactions
  • When the user explicitly asks to remember something
  • After resolving a tricky bug worth documenting
  • When project structure changes significantly
  • 发现可能重复出现的错误后
  • 某个模式经2次以上交互确认后
  • 用户明确要求记住某些内容时
  • 解决了值得记录的复杂Bug后
  • 项目结构发生重大变化时

When to Remove or Edit

删除或编辑时机

  • When stored information becomes outdated (version bumps, removed features)
  • When a gotcha is fixed and no longer relevant
  • When the user asks to forget something
  • When MEMORY.md exceeds ~200 lines — prune or move detail to topic files
  • 存储的信息过时（版本升级、功能移除）时
  • 某个注意事项已修复不再相关时
  • 用户要求遗忘某些内容时
  • MEMORY.md超过约200行时——精简内容或将细节移至主题文件

Avoiding Drift

避免信息偏差

Periodically review memory files against the actual project state. Stale entries (wrong counts, outdated paths, fixed bugs still listed as open) erode trust in the memory system. Mark fixed issues as fixed rather than deleting them — the history of what went wrong is itself valuable.
定期对照实际项目状态检查内存文件。过时条目（错误的数量、失效的路径、仍列为未解决的已修复Bug）会降低用户对内存系统的信任。已修复的问题应标记为已修复而非删除——错误的历史本身也具有价值。

Additional Resources

额外资源

Reference Files

参考文件

For detailed patterns, anti-patterns, and advanced techniques:
  • references/patterns.md — Writing style guide, MEMORY.md structure patterns, topic file patterns, common anti-patterns
如需了解详细模式、反模式和高级技巧：
  • references/patterns.md — 写作风格指南、MEMORY.md结构模式、主题文件模式、常见反模式

Example Files

示例文件

Working examples ready to adapt:
  • examples/MEMORY.md — Starter MEMORY.md template
  • examples/topic-file.md — Topic file template with recommended structure
可直接适配的实用示例：
  • examples/MEMORY.md — MEMORY.md入门模板
  • examples/topic-file.md — 推荐结构的主题文件模板