Back to Details

memory-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Memory Manager

内存管理器

Manage the full Claude Code memory hierarchy across three layers. Produces well-organised, correctly-placed memory files that follow size guidelines and progressive disclosure.
管理跨三个层级的完整Claude Code内存体系。生成结构清晰、存放位置正确且符合大小规范与渐进式披露原则的内存文件。

Three Memory Layers

三个内存层级

LayerLocationPurposeManaged by this skill
CLAUDE.md hierarchy
./CLAUDE.md
, subdirs, parent dirs		Project context, commands, architecture, rulesYes
Rules topic files
.claude/rules/*.md
Correction rules, patterns, technical factsYes
Auto-memory
~/.claude/projects/*/memory/MEMORY.md
Session-specific patternsNo (Claude manages automatically)
层级位置用途是否由本skill管理
CLAUDE.md体系
./CLAUDE.md
、子目录、父目录		项目上下文、命令、架构、规则是
规则主题文件
.claude/rules/*.md
修正规则、模式、技术事实是
自动内存
~/.claude/projects/*/memory/MEMORY.md
会话特定模式否（由Claude自动管理）

Operating Modes

操作模式

Mode 1: Session Capture

模式1：会话捕获

When: End of session, "capture learnings", "update CLAUDE.md with what we learned"
  1. Review the conversation for discoveries worth preserving:
    • Commands that worked (or didn't)
    • Gotchas and workarounds found
    • Architecture decisions made
    • Configuration quirks discovered
    • Patterns that would help future sessions
  2. Categorise each discovery using the placement decision tree below
  3. Draft all changes as diffs in a single batch
  4. Present the batch — apply after a single yes/no confirmation
Keep it concise: one line per concept. No verbose explanations, no generic advice.
触发场景：会话结束时、执行"capture learnings"、"update CLAUDE.md with what we learned"
  1. 回顾对话内容，筛选值得保留的发现：
    • 生效（或失效）的命令
    • 发现的陷阱与解决方案
    • 已确定的架构决策
    • 发现的配置特殊点
    • 对未来会话有帮助的模式
  2. 使用下方的存放决策树对每个发现进行分类
  3. 将所有修改以diff形式批量草拟
  4. 展示批量修改内容，在单次确认同意后应用
注意简洁性：每个概念仅用一行描述。避免冗长解释，不要通用建议。

Mode 2: Full Audit

模式2：完整审计

When: "audit memory", "check project docs", periodic maintenance, working in a neglected project
  1. Run the audit script:
    bash
    python3 skills/memory-manager/scripts/audit_memory.py [repo-path]
  2. Review the output: sizes, quality scores, project type, missing docs, stale references
  3. Generate changes autonomously — create, update, or flag files as needed
  4. Present all changes as a single batch for approval
  5. Apply approved changes
For large repos, delegate to a sub-agent:
Task(subagent_type: "general-purpose",
  prompt: "Run python3 skills/memory-manager/scripts/audit_memory.py /path/to/repo
           and summarise the findings.")
触发场景：执行"audit memory"、"check project docs"、定期维护、处理长期未打理的项目
  1. 运行审计脚本：
    bash
    python3 skills/memory-manager/scripts/audit_memory.py [repo-path]
  2. 查看输出内容：文件大小、质量评分、项目类型、缺失文档、过时引用
  3. 自主生成修改内容——按需创建、更新或标记文件
  4. 将所有修改作为单个批量内容提交审批
  5. 应用已获批的修改
对于大型仓库，可委托给子Agent：
Task(subagent_type: "general-purpose",
  prompt: "Run python3 skills/memory-manager/scripts/audit_memory.py /path/to/repo
           and summarise the findings.")

Mode 3: Restructure

模式3：内存重构

When: "restructure memory", root CLAUDE.md over 200 lines, first-time memory setup
  1. Run full audit (Mode 2) first
  2. Split oversized files:
    • Extract topic sections from root CLAUDE.md into 
      .claude/rules/<topic>.md
    • Extract directory-specific content into sub-directory CLAUDE.md files
  3. Create missing documentation files based on project type
  4. Present the restructure plan, apply after approval
触发场景：执行"restructure memory"、根目录CLAUDE.md超过200行、首次设置内存
  1. 先执行完整审计（模式2）
  2. 拆分过大的文件：
    • 从根目录CLAUDE.md中提取主题章节到
      .claude/rules/<topic>.md
    • 将目录特定内容提取到子目录的CLAUDE.md文件中
  3. 根据项目类型创建缺失的文档文件
  4. 展示重构方案，在审批通过后应用

Placement Decision Tree

存放决策树

Would this still apply if I switched to a completely different project?
├── YES → ~/.claude/rules/<topic>.md
│         (correction rules, API patterns, coding standards)
└── NO  → Is it specific to a subdirectory?
    ├── YES → <dir>/CLAUDE.md
    │         (integrations, directory-specific gotchas)
    └── NO  → ./CLAUDE.md (project root)
              (identity, stack, commands, architecture, critical rules)
如果切换到一个完全不同的项目，这些内容是否仍然适用？
├── 是 → ~/.claude/rules/<topic>.md
│         （修正规则、API模式、编码标准）
└── 否  → 内容是否特定于某个子目录？
    ├── 是 → <dir>/CLAUDE.md
│         （集成内容、目录特定陷阱）
    └── 否  → ./CLAUDE.md（项目根目录）
              （项目标识、技术栈、命令、架构、关键规则）

Size Targets

大小规范

File TypeTargetMaximum
Root CLAUDE.md50-150 lines200
Sub-directory CLAUDE.md15-50 lines80
Rules topic file20-80 lines120
文件类型目标值最大值
根目录CLAUDE.md50-150行200
子目录CLAUDE.md15-50行80
规则主题文件20-80行120

What Belongs Where

内容存放规则

Root CLAUDE.md

根目录CLAUDE.md

  • Project name, purpose, owner
  • Tech stack summary
  • Build/deploy/test commands (copy-paste ready)
  • Directory structure overview
  • Critical "never do X" rules
  • Key integrations and secrets locations
  • 项目名称、用途、负责人
  • 技术栈摘要
  • 构建/部署/测试命令（可直接复制粘贴使用）
  • 目录结构概述
  • 关键的“禁止操作X”规则
  • 核心集成与密钥位置

Sub-directory CLAUDE.md

子目录CLAUDE.md

  • External service integrations for that component
  • Non-obvious configuration specific to this area
  • Directory-specific commands
  • Gotchas when working in this directory
Don't create when: parent covers it, directory is self-explanatory, content would be under 10 lines.
  • 该组件对应的外部服务集成内容
  • 特定于该区域的非显性配置
  • 目录专属命令
  • 在该目录工作时的注意事项
无需创建的情况：父目录已覆盖相关内容、目录内容一目了然、内容不足10行。

.claude/rules/ topic files

.claude/rules/主题文件

  • Correction rules bridging training cutoff (e.g. API changes, deprecated patterns)
  • Coding patterns and standards
  • Platform-specific formatting rules
  • Error prevention patterns
  • 弥补训练截止日期后变化的修正规则（如API变更、已废弃模式）
  • 编码模式与标准
  • 平台特定格式规则
  • 错误预防模式

What to delete

需删除的内容

  • Content Claude already knows from training
  • Verbose explanations of standard frameworks
  • Changelogs or version history (use git)
  • Duplicated content from parent CLAUDE.md files
  • "TODO" items that were never completed
  • Generic advice not specific to the project
  • Claude已通过训练掌握的内容
  • 对标准框架的冗长解释
  • 变更日志或版本历史（使用git管理）
  • 与父目录CLAUDE.md重复的内容
  • 从未完成的“TODO”项
  • 非项目专属的通用建议

Project Type Detection

项目类型检测

The audit script detects project type from file presence and suggests appropriate documentation:
IndicatorTypeSuggested Docs
wrangler.jsonc
/ 
wrangler.toml
Cloudflare WorkerARCHITECTURE.md
vite.config.*
+ 
.tsx
files		Vite/ReactARCHITECTURE.md
next.config.*
Next.jsARCHITECTURE.md
MCP patterns in 
src/index.ts
MCP ServerARCHITECTURE.md, API_ENDPOINTS.md
src/routes/
or 
src/api/
API ProjectAPI_ENDPOINTS.md, DATABASE_SCHEMA.md
Drizzle/Prisma configDatabaseDATABASE_SCHEMA.md
All projects get CLAUDE.md. Additional docs only when the project type warrants them. See references/project-types.md for full detection heuristics and doc templates.
审计脚本通过文件存在情况检测项目类型，并推荐合适的文档：
识别标识项目类型推荐文档
wrangler.jsonc
/ 
wrangler.toml
Cloudflare WorkerARCHITECTURE.md
vite.config.*
+ 
.tsx
文件		Vite/ReactARCHITECTURE.md
next.config.*
Next.jsARCHITECTURE.md
src/index.ts
中存在MCP模式		MCP ServerARCHITECTURE.md、API_ENDPOINTS.md
src/routes/
或 
src/api/
API项目API_ENDPOINTS.md、DATABASE_SCHEMA.md
存在Drizzle/Prisma配置数据库项目DATABASE_SCHEMA.md
所有项目都需要CLAUDE.md。仅当项目类型有需求时才添加额外文档。完整的检测规则与文档模板请查看references/project-types.md。

Autonomy Rules

自主操作规则

  • Just do it: Run audit, detect project type, identify gaps, draft changes
  • Brief confirmation: Apply changes (single batch yes/no, not item-by-item)
  • Ask first: Delete existing content, major restructures (moving 50+ lines), create new project docs from scratch where there's ambiguity about content
  • 直接执行：运行审计、检测项目类型、识别缺口、草拟修改内容
  • 简短确认：应用修改内容（单次批量确认是/否，无需逐项确认）
  • 先询问再操作：删除现有内容、大规模重构（移动50行以上内容）、在内容存在歧义时从零创建新的项目文档

Quality Scoring

质量评分

The audit script scores each CLAUDE.md on 6 criteria (100 points):
CriterionPointsWhat it measures
Commands/Workflows20Build, test, deploy documented
Architecture Clarity20Structure, relationships, entry points
Non-Obvious Patterns15Gotchas, quirks, warnings
Conciseness15Dense content, no filler
Currency15References valid, commands work
Actionability15Copy-paste ready, real paths
See references/quality-criteria.md for the full rubric.
审计脚本从6个维度对每个CLAUDE.md进行评分（总分100分）：
评分维度分值衡量内容
命令/工作流20构建、测试、部署流程是否已文档化
架构清晰度20结构、关联关系、入口点是否清晰
非显性模式15是否记录陷阱、特殊点与警告
简洁性15内容是否精炼、无冗余
时效性15引用是否有效、命令是否可正常执行
可操作性15是否可直接复制粘贴、路径是否真实有效
完整评分标准请查看references/quality-criteria.md。

Reference Files

参考文件

WhenRead
Scoring CLAUDE.md qualityreferences/quality-criteria.md
Detecting project type and expected docsreferences/project-types.md
Creating new CLAUDE.md or rules filesreferences/templates.md
使用场景参考文件
对CLAUDE.md进行质量评分references/quality-criteria.md
检测项目类型与所需文档references/project-types.md
创建新的CLAUDE.md或规则文件references/templates.md

Scripts

脚本说明

  • scripts/audit_memory.py
    — Scan all three layers, score quality, detect project type, flag issues 
    • python3 audit_memory.py [repo-path]
      — human-readable report
    • python3 audit_memory.py [repo-path] --json
      — structured JSON output
  • scripts/audit_memory.py
    — 扫描三个内存层级、进行质量评分、检测项目类型、标记问题 
    • python3 audit_memory.py [repo-path]
      — 生成人类可读的报告
    • python3 audit_memory.py [repo-path] --json
      — 生成结构化JSON输出