Install
openclaw skills install init-memoryClaude 持久化记忆系统初始化
为任意项目初始化 Claude 持久化记忆系统（v3.0 搜索引擎模型）。自动扫描项目结构、技术栈、代码规范，生成完整的记忆文件和 CLAUDE.md 指令。
Audits
Pass🧠 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）- 其他部分按需更新
<!-- MEMORY-SYSTEM-END -->💡 设计理念：SUMMARY.md 是固定大小的"缓存"，详细数据永远保留在原文件中。 Claude 不需要"记住一切"，只需要"知道去哪找"。
### 注入逻辑
1. **如果 CLAUDE.md 不存在**:
创建新文件，内容为:
```markdown
# <项目名> — Claude 工程指令
> 记忆系统 v3.0 — "搜索引擎"模型：启动只读摘要，详情按需检索
<记忆系统指令块>
- 如果 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 规则）