Claude 持久化记忆系统初始化

为任意项目初始化 Claude 持久化记忆系统（v3.0 搜索引擎模型）。自动扫描项目结构、技术栈、代码规范，生成完整的记忆文件和 CLAUDE.md 指令。

Security Scan

The skill's declared purpose (building a local Claude persistent memory for a codebase) matches its instructions and requirements: it scans repository files and writes structured memory files under .claude/, and it does not request external credentials or install anything.

Purpose & Capability

Name and description claim to initialize a Claude persistent memory system. The SKILL.md contains detailed, project-scanning steps and file-generation rules that directly implement that purpose. It does not request unrelated credentials or external services.

Instruction Scope

The instructions instruct the agent to run repository-scanning shell commands (find, grep, wc, head, etc.), parse many typical language config files, and create multiple files inside a .claude/memory directory. This is consistent with the stated purpose, but the skill assumes the agent can run standard Unix utilities and has permission to read the repository and write the .claude/ directory. The SKILL.md does not instruct any network exfiltration, reading of unrelated system paths, or access to secrets outside the project, but it will read project files which may themselves contain sensitive data—users should review generated outputs before committing.

Install Mechanism

No install spec and no code files (instruction-only). This is the lowest-risk install mechanism. The skill does not download or write external code at install time.

Credentials

The skill declares no required environment variables, credentials, or config paths. Its operations are limited to scanning the project tree and creating files under .claude/, which is proportionate to the stated goal.

Persistence & Privilege

always:false and user-invocable:true (normal). The skill writes persistent files into the project's .claude/memory directory; this is expected for a memory-initializer but is a persistent change to the repository's working tree. The skill does not request system-wide privileges or modify other skills' configuration.

Assessment

This skill will scan your repository (config files and source files) and create a .claude/memory/ directory with multiple JSON/MD files it generates. Before using it: 1) ensure you run it in a copy or branch if you are concerned about accidental overwrites (it refuses to overwrite .claude/memory unless --force is used); 2) review the generated files before committing (they may include project-specific details or inadvertently capture sensitive config snippets); 3) confirm the runtime environment has standard shell tools (find/grep/wc/head) and permissions to read the repo and write .claude/; 4) consider adding .claude/ to .gitignore if you do not want these memory artifacts committed; 5) if you expect secrets in the repo, audit potential outputs first or run the skill in an isolated environment. Overall the skill is coherent with its stated purpose and does not request unrelated credentials or network access, but exercise normal caution about storing and sharing repository contents.

🧠 Claude 持久化记忆系统初始化 Skill

记忆系统 v3.0 — "搜索引擎"模型：启动只读摘要，详情按需检索

核心理念: Claude 不需要"记住一切"，只需要"知道去哪找"。

参数处理

用户输入参数: $ARGUMENTS

解析参数:

• --force: 覆盖已有的记忆文件（默认跳过已存在的文件）
• --minimal: 只创建核心文件（SUMMARY.md, architecture.json, conventions.json, semantic-index.json, changelog.json）
• --lang zh: 注释和描述使用中文（默认）
• --lang en: 注释和描述使用英文

如果 .claude/memory/SUMMARY.md 已存在且没有 --force 参数，停止执行并提示用户:

⚠️ 记忆系统已存在。使用 --force 覆盖，或手动删除 .claude/memory/ 目录后重试。

---

Step 1: 扫描项目

1.1 项目结构扫描

Glob "**/{package.json,tsconfig.json,Cargo.toml,go.mod,pyproject.toml,setup.py,requirements.txt,pom.xml,build.gradle,Gemfile,composer.json,CMakeLists.txt,Makefile,.csproj,pubspec.yaml,mix.exs,deno.json}" (忽略 node_modules、vendor、target、dist、build、.git)

读取找到的配置文件，提取:

• 项目名称（优先: package.json name > Cargo.toml name > go.mod module > 目录名）
• 技术栈（语言、框架、构建工具、运行时）
• 依赖列表（核心依赖，不含 devDependencies 细节）
• 脚本/命令（build/test/dev/start）
• 是否为 monorepo（workspaces / 多个子 package.json）

1.2 目录布局

find . -maxdepth 3 -type d \
  ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' \
  ! -path '*/build/*' ! -path '*/.next/*' ! -path '*/target/*' \
  ! -path '*/vendor/*' ! -path '*/__pycache__/*' ! -path '*/.claude/*' \
  ! -path '*/.venv/*' ! -path '*/venv/*' ! -path '*/.tox/*' \
  | head -80 | sort

1.3 核心模块识别

根据项目语言类型选择合适的扫描模式:

TypeScript/JavaScript 项目:

Grep "^export (class|function|const|interface|type|enum)" --type ts,tsx,js,jsx

Python 项目:

Grep "^(class |def )" --type py

Go 项目:

Grep "^(func |type .* struct)" --type go

Rust 项目:

Grep "^(pub fn |pub struct |pub enum |pub trait )" --type rs

Java/Kotlin 项目:

Grep "^(public class|public interface|public enum|class |fun )" --type java,kt

取前 100 个结果，识别核心模块和它们的位置。

1.4 大文件识别（热点文件）

find . \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \
  -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.java' \
  -o -name '*.kt' -o -name '*.vue' -o -name '*.svelte' -o -name '*.rb' \
  -o -name '*.ex' -o -name '*.exs' -o -name '*.dart' -o -name '*.swift' \
  -o -name '*.cpp' -o -name '*.c' -o -name '*.h' \) \
  ! -path '*/node_modules/*' ! -path '*/dist/*' ! -path '*/build/*' \
  ! -path '*/target/*' ! -path '*/vendor/*' ! -path '*/.git/*' \
  -exec wc -l {} + 2>/dev/null | sort -rn | head -20

对超过 500 行的文件进行逻辑分区扫描（扫描 function/class/section 定义及其行号）。 如果项目源文件较少，可降低阈值到 300 行。

1.5 代码规范推断

读取 3-5 个核心源文件的前 50 行，推断:

• 缩进风格（tab vs space，几个空格）
• 引号风格（单引号 vs 双引号）
• 分号使用
• 命名约定（camelCase / snake_case / PascalCase）
• 导入风格和顺序
• 注释语言（中文/英文/混合）

同时检查是否存在以下配置文件: .eslintrc*, .prettierrc*, rustfmt.toml, .editorconfig, pyproject.toml [tool.black], setup.cfg [flake8], .rubocop.yml, biome.json

1.6 项目特有规则扫描

检查是否已有:

• CLAUDE.md — 已有的 Claude 指令
• .claude/ 目录 — 已有的 Claude 配置
• CONTRIBUTING.md — 贡献指南中的规范
• .github/ — CI/CD 配置中的约束

---

Step 2: 创建记忆文件

创建 .claude/memory/ 目录，然后基于 Step 1 的扫描结果创建以下文件。

重要规则:

• 所有 JSON 文件中的 $schema 字段使用实际项目名称（从配置文件推断），不要硬编码
• 所有内容必须来自实际扫描，不得使用占位模板
• JSON 使用 2 空格缩进
• 日期格式统一 YYYY-MM-DD
• 文件使用 UTF-8 编码

2.1 architecture.json — 项目架构概览

{
  "$schema": "<项目名> Architecture",
  "$version": "1.0.0",
  "$updated": "<今天日期>",
  "$description": "项目架构概览",

  "project": {
    "name": "<项目名>",
    "description": "<从配置文件推断的项目描述>",
    "monorepo": false,
    "packageManager": "<npm|yarn|pnpm|pip|cargo|go modules|...>"
  },

  "techStack": {
    "language": "<主要语言及版本>",
    "framework": "<主要框架及版本>",
    "buildTool": "<构建工具>",
    "runtime": "<运行时环境>",
    "uiLibrary": "<UI 库（如适用）>",
    "testFramework": "<测试框架>"
  },

  "packages": {
    "<包名>": {
      "path": "<路径>",
      "role": "<职责描述>",
      "entry": "<入口文件>",
      "format": "<ESM|CJS|mixed>"
    }
  },

  "mainModules": {
    "<模块名>": {
      "file": "<文件路径>",
      "lines": "<行数>",
      "role": "<职责描述>",
      "warning": "<注意事项（可选）>",
      "keyDataStructures": ["<核心数据结构>"]
    }
  },

  "keyDependencies": [
    { "name": "<包名>", "version": "<版本>", "purpose": "<用途>" }
  ]
}

monorepo 项目: packages 字段列出所有子包及其角色。 单包项目: packages 只有一个条目或省略。

2.2 conventions.json — 代码规范

{
  "$schema": "<项目名> Code Conventions",
  "$version": "1.0.0",
  "$updated": "<今天日期>",
  "$description": "代码规范和约定。新增代码必须遵守这些规范",

  "codeStyle": {
    "language": "<TypeScript (strict)|Python 3.x|Go|...>",
    "indent": "<2 spaces|4 spaces|tabs>",
    "quotes": "<single|double>",
    "semicolons": "<true|false|N/A>",
    "trailingComma": "<none|es5|all|N/A>",
    "formatter": "<Prettier|Black|gofmt|rustfmt|...>",
    "linter": "<ESLint|Ruff|golint|clippy|...>"
  },

  "namingConventions": {
    "files": { "<类型>": "<命名规则>" },
    "code": {
      "classes": "<PascalCase>",
      "interfaces": "<规则>",
      "functions": "<camelCase|snake_case>",
      "constants": "<UPPER_SNAKE_CASE>",
      "variables": "<camelCase|snake_case>"
    }
  },

  "patterns": {
    "<模式名>": {
      "description": "<描述>",
      "template": "<代码模板（可选）>",
      "steps": ["<步骤>"]
    }
  },

  "commitMessageStyle": {
    "language": "<项目注释语言>",
    "prefix": "feat:/fix:/refactor:/chore:/docs:/test:",
    "examples": ["<示例>"]
  },

  "importOrder": ["<导入分组规则>"],

  "criticalRules": [
    "<从代码和配置中推断出的关键规则>"
  ]
}

2.3 semantic-index.json — 语义索引

{
  "$schema": "<项目名> Semantic Index",
  "$version": "1.0.0",
  "$updated": "<今天日期>",
  "$description": "关键词索引——从功能域/关键词到相关文件的映射",

  "index": {
    "<关键词|别名|同义词>": {
      "description": "<功能域描述>",
      "files": [
        { "path": "<文件路径>", "sections": ["<逻辑区域>"], "lineRange": [0, 0] }
      ],
      "quickRules": ["<该领域的快速提示/规则>"]
    }
  }
}

基于 Step 1.3 的扫描结果填充。将相关的导出按功能域分组。 每个索引条目可以有多个关键词别名（用 | 分隔）。

2.4 hotspot-map.json — 热点文件分区图

{
  "$schema": "<项目名> Hotspot Map",
  "$version": "1.0.0",
  "$updated": "<今天日期>",
  "$description": "热点文件的逻辑分区图。修改大文件前先查此文件定位行号范围",

  "files": {
    "<文件名>": {
      "path": "<完整相对路径>",
      "totalLines": 0,
      "touchFrequency": 0,
      "sections": [
        {
          "name": "<逻辑分区名>",
          "lineRange": [0, 0],
          "description": "<该分区的功能描述>",
          "keySymbols": ["<重要函数/类名>"],
          "touchCount": 0,
          "subSections": []
        }
      ]
    }
  }
}

仅包含超过 500 行（小项目 300 行）的文件。每个文件最多 15 个分区。

2.5 task-context.json — 任务上下文

{
  "$schema": "<项目名> Task Context",
  "$version": "1.0.0",
  "$updated": "<今天日期>",
  "$description": "当前任务上下文。帮助 Claude 理解未完成的工作",

  "currentTasks": [],
  "recentCompleted": [],
  "pendingIssues": [],
  "completedTasks": [],
  "knownLimitations": []
}

2.6 changelog.json — 变更日志

{
  "$schema": "<项目名> Session Changelog",
  "$version": "1.0.0",
  "$updated": "<今天日期>",
  "$description": "增量变更日志。每次会话修改代码后追加记录",

  "sessions": [
    {
      "id": "SESSION-001",
      "date": "<今天日期>",
      "summary": "初始化 Claude 记忆系统",
      "changes": [
        {
          "action": "create",
          "files": [".claude/memory/*", "CLAUDE.md"],
          "reason": "建立持久化记忆系统，实现跨会话知识保持"
        }
      ],
      "decisions": ["采用 v3.0 搜索引擎模型：启动只读 SUMMARY.md，详情按需 Grep 检索"],
      "lessonsLearned": [],
      "ripples": { "description": "纯新增文件，无代码影响", "affectedModules": [], "sideEffects": [] },
      "rejectedAlternatives": []
    }
  ]
}

2.7 bugs-and-fixes.json — Bug 记录

{
  "$schema": "<项目名> Bug & Fix Registry",
  "$version": "1.0.0",
  "$updated": "<今天日期>",
  "$description": "已知 Bug 和修复记录。避免相同问题重复犯错",

  "bugs": [],
  "commonMistakes": [],
  "predictions": []
}

2.8 causality-graph.json — 因果图谱

{
  "$schema": "<项目名> Causality Graph",
  "$version": "1.0.0",
  "$updated": "<今天日期>",
  "$description": "因果图谱——记录 Bug 的完整因果链。新 Bug 出现时沿已知链反向推导",

  "chains": [],
  "chainIndex": {}
}

如果使用了 --minimal 参数，跳过: hotspot-map.json, task-context.json, bugs-and-fixes.json, causality-graph.json

2.9 SUMMARY.md（最后创建）

# <项目名> — Claude 记忆摘要

> 记忆系统 v3.0 — 本文件是固定大小的"缓存"，详细数据在各 JSON 文件中

## 🏗️ 架构速览
- **技术栈**: <语言 + 框架 + 构建工具>
- **项目结构**: <简要描述目录布局>
- **核心模块**: <列出 3-5 个最重要的模块>

## 📊 热点文件
<列出行数最多的 3-5 个文件及其行数>

## 🔄 最近 3 次变更
1. SESSION-001: 初始化 Claude 记忆系统

## 📋 当前状态
- **进行中**: 无
- **待处理**: 无

## ⚠️ 高频陷阱（Top 5）
暂无记录

## 🔍 检索指南
| 需要什么 | 怎么查 |
|----------|--------|
| 功能域→文件映射 | `Grep "关键词" .claude/memory/semantic-index.json` |
| 大文件行号定位 | `Grep "section名" .claude/memory/hotspot-map.json` |
| Bug 因果链 | `Grep "症状" .claude/memory/causality-graph.json` |
| 已知 Bug/预判 | `Grep "症状" .claude/memory/bugs-and-fixes.json` |
| 历史决策 | `Grep "功能" .claude/memory/changelog.json` |
| 代码规范 | `Read .claude/memory/conventions.json` |
| 完整架构 | `Read .claude/memory/architecture.json` |

---

Step 3: 生成/更新 CLAUDE.md

要注入的记忆系统指令块

以下内容用 <!-- MEMORY-SYSTEM-START --> 和 <!-- MEMORY-SYSTEM-END --> 标记包裹:

<!-- MEMORY-SYSTEM-START -->
## 📖 启动时只读一个文件

\```
Read .claude/memory/SUMMARY.md
\```

**不要**在启动时读取其他记忆文件。SUMMARY.md 包含架构速览、当前状态、高频陷阱和检索指南。

## 🔍 按需检索（改代码/修 Bug 前查询）

需要详情时，用 Grep/Read **精准查询**对应文件，不要全量加载：

| 场景 | 做什么 |
|------|--------|
| **改代码前** — 定位文件和行号 | `Grep "关键词" .claude/memory/semantic-index.json` |
| **改核心文件** — 查逻辑分区行号 | `Grep "section名" .claude/memory/hotspot-map.json` |
| **修 Bug 前** — 匹配已知症状 | `Grep "症状关键词" .claude/memory/causality-graph.json` |
| **修 Bug 前** — 查是否已预判 | `Grep "症状" .claude/memory/bugs-and-fixes.json` |
| **查历史决策** — 为什么这样做 | `Grep "功能关键词" .claude/memory/changelog.json` |
| **查代码规范** — 命名/风格/模式 | `Read .claude/memory/conventions.json` |
| **查完整架构** — 模块/IPC/技术栈 | `Read .claude/memory/architecture.json` |

## ⚡ 关键规则

> 以下规则从项目扫描中自动生成，请根据实际情况补充

1. **热点文件** — 修改超过 500 行的文件前，必须先 Grep semantic-index + hotspot-map 定位
2. **修 Bug** — 先 Grep causality-graph 的 chainIndex 匹配症状
3. 提交信息推荐 `feat:/fix:/refactor:/chore:` 前缀

## 🔄 任务完成后必须更新

每次完成代码修改后，按需更新以下文件（只更新涉及到的）：

### 必更新
- **changelog.json** — 在 `sessions` 数组末尾追加：
  ```json
  {
    "id": "SESSION-xxx", "date": "YYYY-MM-DD", "summary": "...",
    "changes": [{ "action": "create|modify|delete", "files": [...], "reason": "..." }],
    "decisions": [...], "lessonsLearned": [...],
    "ripples": { "description": "...", "affectedModules": [...], "sideEffects": [...] },
    "rejectedAlternatives": [{ "option": "...", "reason": "..." }]
  }

按需更新

• bugs-and-fixes.json — 修了 Bug → 追加 bugs；发现易错模式 → 追加 commonMistakes；主动扫描 → 追加 predictions
• task-context.json — 更新 currentTasks / recentCompleted（只保留最近 5 条）/ pendingIssues
• hotspot-map.json — 改了核心文件 → touchCount +1, lastModified, lineRange 偏移
• semantic-index.json — 新增功能域 → 添加索引条目
• causality-graph.json — 发现新因果链 → 追加 chains + 更新 chainIndex
• architecture.json — 架构变化（新模块/IPC/页面）→ 同步更新

最后一步：重写 SUMMARY.md

从各详细文件中提取最新信息，重写（非追加）SUMMARY.md：

• 最近 3 次变更 ← changelog.json 最后 3 条的 summary
• 当前状态 ← task-context.json 的 currentTasks + pendingIssues
• 高频陷阱 ← bugs-and-fixes.json 的 commonMistakes（Top 5）
• 其他部分按需更新

💡 设计理念：SUMMARY.md 是固定大小的"缓存"，详细数据永远保留在原文件中。 Claude 不需要"记住一切"，只需要"知道去哪找"。

<!-- MEMORY-SYSTEM-END -->

### 注入逻辑

1. **如果 CLAUDE.md 不存在**:
   创建新文件，内容为:
   ```markdown
   # <项目名> — Claude 工程指令

   > 记忆系统 v3.0 — "搜索引擎"模型：启动只读摘要，详情按需检索

   <记忆系统指令块>

2. 如果 CLAUDE.md 已存在:
   • 如果已包含 <!-- MEMORY-SYSTEM-START --> 标记，替换标记之间的内容
   • 如果不包含标记，在文件顶部第一个一级标题之后插入记忆系统指令块
   • 保留 CLAUDE.md 中的所有其他内容不变

---

Step 4: 输出完成报告

扫描创建的所有文件，统计大小，输出如下格式的报告:

✅ Claude 记忆系统初始化完成！

📁 创建的文件:
  .claude/memory/SUMMARY.md          (xxx bytes)
  .claude/memory/architecture.json   (xxx bytes)
  .claude/memory/conventions.json    (xxx bytes)
  .claude/memory/semantic-index.json (xxx bytes)
  .claude/memory/hotspot-map.json    (xxx bytes)
  .claude/memory/task-context.json   (xxx bytes)
  .claude/memory/changelog.json      (xxx bytes)
  .claude/memory/bugs-and-fixes.json (xxx bytes)
  .claude/memory/causality-graph.json(xxx bytes)
  CLAUDE.md                          (已更新/已创建)

📊 项目分析摘要:
  - 技术栈: <语言> + <框架>
  - 核心模块: <数量>个
  - 热点文件(>500行): <数量>个
  - 语义索引域: <数量>个

🧠 记忆系统设计:
  - 启动加载: ~3KB（仅 SUMMARY.md）
  - 详情存储: 按需 Grep 检索
  - 增长模型: 启动负载永远 O(1)

💡 下一步建议:
  1. 审查 architecture.json 中的模块描述是否准确
  2. 检查 conventions.json 是否符合团队规范
  3. 在 task-context.json 中添加当前进行中的任务
  4. 将 .claude/memory/ 加入版本控制（推荐）
  5. 根据项目特点补充 CLAUDE.md 中的关键规则

---

注意事项

• 所有文件使用 UTF-8 编码
• JSON 文件使用 2 空格缩进
• 日期格式统一使用 YYYY-MM-DD
• 不要在任何文件中使用占位模板——所有内容必须来自实际扫描
• 如果某个扫描步骤失败（比如没有 package.json），优雅降级，用目录名作为项目名
• 热点文件扫描如果源文件不多，可以降低阈值到 300 行
• 如果项目已有 CLAUDE.md 中的项目特有规则（如 IPC 规则、弹窗规则等），注入时保留这些规则
• 对于不同技术栈的项目，关键规则 部分应自适应生成（如 Go 项目不需要 IPC 规则）