在 RuView 工程中构建 Claude Code 跨会话记忆：claude-flow 状态持久化、会话恢复与记忆治理实战

导读

本篇文章围绕仓库 .claude/commands/automation/session-memory.md 展开，它是 RuView 仓库 .claude/ AI 辅助开发自动化层中的一份命令文档，系统说明如何在 Claude Code 多会话、多 Agent 协作场景下维护跨会话上下文：会话结束时自动持久化 Agent 状态、任务记录与性能指标，新会话启动时通过 MCP 工具或 CLI 快速恢复，并用命名空间、备份、删除等手段对记忆进行治理。读完本文后，你将掌握 claude-flow 记忆系统的完整调用面（MCP 工具签名、npx claude-flow hook 子命令、memory 子命令全套用法）、三类记忆（项目 / Agent / 性能）的划分方式，以及仓库中 auto-memory-hook.mjs、memory.js 等落地实现背后的存储与桥接原理。需要说明的是，这一机制属于本仓库的工程开发自动化工具链（与 WiFi 感知运行时业务无关），但在多 Agent 长期迭代大型工程时，它是保证"团队不遗忘、上下文不漂移"的关键基建。

命令定位：session-memory 在整个自动化命令集中的位置

.claude/commands/automation/ 目录集中存放 Claude Code / claude-flow 的自动化类命令，目录 README 中列出的命令还包括 auto-agent、smart-spawn、workflow-select 等；而 session-memory.md 专门解决"跨会话记忆"这一横切问题，与其相邻的还有 claude-flow 记忆体系的全量 CLI 手册 claude-flow-memory.md，以及会话生命周期钩子文档（如 session-end.md、overview.md、setup.md）。其写作目的（Purpose）非常明确：

在多个 Claude Code 会话之间维护上下文与经验沉淀，实现持续改进（Maintain context and learnings across Claude Code sessions for continuous improvement）。

这一目标与仓库 CHANGELOG.md 中记录的 claude-flow 守护进程（daemon）接入、多 Agent swarm 协作背景一致：工程体量大、迭代轮次多，如果每次新会话都从零开始，Agent 将反复丢失关键决策与既有模式。session-memory 命令给出的正是"结束即落盘、启动即恢复"的闭环方案。

记忆系统的三大支柱：自动持久化、会话恢复、记忆类型

会话结束时自动保存什么

命令文档定义了会话结束（session end）时自动持久化的五类信息，这是理解整套记忆模型的入口：

• Active agents and specializations —— 当前处于活动状态的 Agent 及其专长方向（例如分析、编码、评审、测试等分工），供下一会话按需召回正确的协作角色；
• Task history and patterns —— 任务历史与行为模式，包括已处理的任务、采用的编辑模式等；
• Performance metrics —— 性能指标，如瓶颈历史、Token 消耗趋势、优化效果；
• Neural network weights —— 神经网络的权重状态（在仓库语境中对应 Agent 侧的智能体学习权重或模式库快照，而非产品推理模型）；
• Knowledge base updates —— 知识库增量，即本次会话产生的、需要沉淀进长期记忆的更新。

在落地层面，仓库 .claude/settings.json 通过 Claude Code 的 SessionStart / SessionEnd 生命周期钩子把上述持久化动作接入会话边界，例如 SessionEnd 钩子会执行 .claude/helpers 下的钩子处理器，把会话状态写入记忆后端（详见下文"实现级纵深"一节）。

新会话如何恢复上下文

命令文档给出了两层恢复手段，按"优先 MCP、兜底 CLI"组织：

第一层：MCP 工具恢复（推荐，供 Agent 在对话内直接调用）

// 读取记忆中的会话状态
mcp__claude-flow__memory_usage({
  "action": "retrieve",
  "key": "session-state",
  "namespace": "sessions"
})

// 依据快照恢复整个 swarm 状态
mcp__claude-flow__context_restore({
  "snapshotId": "sess-123"
})

memory_usage 以 action 区分操作类型（retrieve / list / delete 等），namespace 用于限定命名空间；context_restore 则直接按快照 ID 整体还原会话。该调用风格与仓库 docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md 中描述的 mcp__claude-flow__* 工具命名空间约定一致——文档指出 ruflo 对外暴露了大量原生 MCP 工具，域边界工具以独立前缀并行注册，会话记忆正是该命名空间下的核心能力之一。

第二层：CLI 兜底（适合在钩子脚本、非 MCP 环境或人工操作时使用）

npx claude-flow hook session-restore --session-id "sess-123"

配合 hooks/overview.md 对 session-restore 钩子的定位——"Load previous session state（加载上一会话状态）"——可以确认：context_restore 与 session-restore 是同一恢复能力在 MCP 与 CLI 两个入口上的不同形态。恢复动作由 .claude/settings.json 的 SessionStart 钩子在每次会话启动时自动触发，路由到 .claude/helpers 下的钩子处理器执行（详见实现节）。

三类记忆的划分与用途

为让持久化内容可检索、可治理，记忆按用途划分三类，命令文档给出如下框架：

记忆类型	覆盖内容	典型用途
Project Memory（项目记忆）	文件关系、常见编辑模式、测试方法、构建配置	让新会话立刻理解仓库结构与既有约定，避免重复踩坑
Agent Memory（Agent 记忆）	专长等级、任务成功率、优化策略、错误模式	跨会话沉淀单个 Agent 的学习曲线与行为画像
Performance Memory（性能记忆）	瓶颈历史、优化结果、Token 使用模式、效率趋势	支撑资源分配与工作流调优（对应仓库中 performance/token 相关监控命令的横向话题）

这种"项目—Agent—性能"三分法把记忆从"一张键值大表"细化为三个可独立查询、独立治理的视图，是理解后续命名空间设计（sessions / agents / project 等）的基础。

会话生命周期钩子：结束动作与恢复动作的全量参数

虽然 session-memory.md 只给出了核心调用示例，其姊妹文档 session-end.md 对"会话结束"一侧的参数做了完整展开，建议一并阅读。其选项如下：

选项	说明	默认值
--session-id, -s <id>	要结束的会话标识	—（必填）
--save-state	保存当前会话状态	true
--export-metrics	导出会话指标（时长、命令数、改动文件、Token、性能）	关闭
--generate-summary	生成会话摘要（完成工作、关键决策、待办）	关闭
--cleanup-temp	清理临时文件与缓存	关闭

典型用法组合：

# 基础结束：仅保存状态
npx claude-flow hook session-end --session-id "dev-session-2024"

# 全量持久化：状态 + 指标 + 摘要
npx claude-flow hook session-end -s "major-refactor" --save-state --export-metrics --generate-summary

# 快速收尾：不保存状态但清理临时文件
npx claude-flow hook session-end -s "quick-fix" --save-state false --cleanup-temp

session-end 钩子会在对话结束、工作会话关闭、关闭前、上下文切换等时机被自动调用，返回的 JSON 结果给出会话的"结算单"，例如 { "sessionId", "duration", "metrics": { "commandsRun", "filesModified", "tokensUsed", "tasksCompleted" }, "summaryPath", "nextSession" }。文档还交叉引用了 hook session-start（会话初始化）与 hook session-restore（会话恢复），三者共同构成完整的生命周期闭环。

记忆内容的日常管理：MCP 治理动作与手动控制

MCP 层：列出、删除、备份

命令文档给出了三个治理性 MCP 调用，与上面的 retrieve 一起构成"读写删备"四件套：

// 列出 sessions 命名空间下已存储的内容
mcp__claude-flow__memory_usage({
  "action": "list",
  "namespace": "sessions"
})

// 删除指定的会话记忆
mcp__claude-flow__memory_usage({
  "action": "delete",
  "key": "session-123",
  "namespace": "sessions"
})

// 将记忆整体备份到文件
mcp__claude-flow__memory_backup({
  "path": "./backups/memory-backup.json"
})

其中"按命名空间 + 键名精确删除"与"整体备份"两两配合，可以做到：日常只清理过期会话条目，定期把全量记忆落盘归档。

手动控制与一键停用

当不想依赖 MCP 时，命令文档提供两条直接手段：

# 查看已存储的记忆内容（人工审计）
ls .claude-flow/memory/

# 关闭记忆持久化（下次会话不写入）
export CLAUDE_FLOW_MEMORY_PERSIST=false

CLAUDE_FLOW_MEMORY_PERSIST=false 是记忆系统的总开关：置为 false 后，会话结束时的自动持久化被跳过，适用于隐私敏感或临时探索型会话。配合 MCP 层的 delete 动作，可在细粒度（单条）、粗粒度（停用）两个层面控制数据留存。

记忆后端与自动化桥接的实现级纵深

settings.json 中的 SessionStart/SessionEnd 接线

从 .claude/settings.json 的源码结构看，SessionStart 与 SessionEnd 两个生命周期钩子均被配置执行 .claude/helpers 下的钩子处理器，例如 SessionStart 调用 hook-handler.cjs session-restore 完成上一会话状态加载。也就是说，session-memory 命令描述的行为，在仓库内是有真实接线支撑的：hook-handler.cjs 的用法说明中列出了 session-restore 分支（"Restore previous session state"），并提供了 route|pre-bash|post-edit|session-restore|session-end|pre-task|post-task|stats 等多路由能力。从该处理器实现可推断，会话记忆的"存"与"取"最终收敛到若干帮助器模块，且所有记忆入口都遵循"失败不致命"原则——记忆系统任何环节出错都不应中断 Claude Code 主流程。

auto-memory-hook.mjs：AutoMemoryBridge 的双向桥接

更完整的自动记忆机制体现在 .claude/helpers/auto-memory-hook.mjs 中。它同样由 settings.json 的 SessionStart/SessionEnd 钩子调用，提供三个子命令：

node auto-memory-hook.mjs import   # SessionStart：把自动记忆文件导入后端
node auto-memory-hook.mjs sync     # SessionEnd：把洞察同步回 MEMORY.md
node auto-memory-hook.mjs status   # 查看桥接状态

其内部实现透露出几个关键设计：

• 存储落点：自动记忆存于 .claude-flow/data/auto-memory-store.json，通过 JsonFileBackend 实现一套 IMemoryBackend 接口（initialize/store/get/update/delete/query/search/bulkInsert/getStats/healthCheck 等），覆盖语义（semantic）、情景（episodic）、程序性（procedural）、工作（working）、缓存（cache）五类条目计数；
• 模块加载降级链：优先加载本地 v3/@claude-flow/memory/dist/index.js，其次 npm 安装的 @claude-flow/memory，再退回 CLI 内置版本——保证在不同安装形态下都能拿到 AutoMemoryBridge、LearningBridge、MemoryGraph 等类；
• 可配置的学习与图谱参数：读 .claude-flow/config.yaml 中 memory 段（含默认值兜底），其中 learningBridge 支持 sonaMode（默认 balanced）、confidenceDecayRate（默认 0.005）、accessBoostAmount（默认 0.03）、consolidationThreshold（默认 10）；memoryGraph 支持 pageRankDamping（默认 0.85）、maxNodes（默认 5000）、similarityThreshold（默认 0.8）；同步模式固定为 on-session-end；
• 同步后整理索引：SessionEnd 侧执行 syncToAutoMemory() 后还会调用 curateIndex()，以图谱感知的排序方式整理 MEMORY.md 索引，便于人读。

这与 session-memory.md 描述的"自动保存知识库更新"完全对应：Agent 在会话中产生的学习成果，经 LearningBridge 做置信度加权（带衰减与访问加成），再由 MemoryGraph 建图组织，最终以文件形式持久化。

memory.js：最简键值记忆帮助器

作为对照，.claude/helpers/memory.js 提供了一个极简键值实现，命令行接口为：

memory.js <get|set|delete|clear|keys> [key] [value]

其数据落在 .claude-flow/data/memory.json，并维护一个 _updated 时间戳用于追踪最近变更。它清晰展示了记忆系统"底层无非是结构化 JSON 存储"的本质：复杂能力（向量搜索、图谱、置信度学习）都在其上以桥接层叠加，而 memory.js 这类帮助器负责最基本的存取。从 auto-memory-hook.mjs 与 memory.js 都选择 .claude-flow/data/ 作为落盘目录可推断，.claude-flow/ 是这套自动化记忆体系约定的数据根目录（与命令文档中 ls .claude-flow/memory/ 的路径约定一致）。

命令行的全套记忆运维（进阶参考）

如需在钩子脚本或 CI 场景下做程序化运维，仓库 claude-flow-memory.md 给出了比 session-memory.md 更完整的 CLI 手册，可直接配合使用：

# 写入（默认命名空间 / 指定命名空间）
./claude-flow memory store "key" "value"
./claude-flow memory store "architecture_decisions" "microservices with API gateway" --namespace arch

# 查询（全空间 / 过滤）
./claude-flow memory query "authentication"
./claude-flow memory query "API design" --namespace arch --limit 10

# 统计
./claude-flow memory stats
./claude-flow memory stats --namespace project

# 导出 / 导入
./claude-flow memory export full-backup.json
./claude-flow memory export project-backup.json --namespace project
./claude-flow memory import backup.json

# 过期清理
./claude-flow memory cleanup --days 30
./claude-flow memory cleanup --namespace temp --days 7

文档中定义的命名空间包括：default（通用）、agents（Agent 状态）、tasks（任务信息）、sessions（会话历史，session-memory.md 的 retrieve/list/delete 示例均落在此）、swarm（多 Agent 协调）、project（项目上下文）、spec（规格）、arch（架构决策）、impl（实现记录）、test（测试结果）、debug（调试日志）。与 session-memory.md 对照可以看出：MCP 层的 namespace 参数与 CLI 层的 --namespace 选项共用同一套命名空间体系，而三类记忆（Project / Agent / Performance）正是 project、agents 与性能相关条目在这些命名空间中的聚合视图。其最佳实践也值得沿用到生产流程：命名键加组件前缀、时间敏感数据带时间戳、按命名空间归类、定期 export 备份 + cleanup 清理 + stats 监控。

收益与适用边界

命令文档总结了四类收益：上下文感知（Contextual awareness）——新会话不必重新考古；累积式学习（Cumulative learning）——经验随迭代不断叠加而非丢失；更快的任务完成（Faster task completion）——跳过重复探索阶段；个性化优化（Personalized optimization）——基于各 Agent 历史画像做针对性调优。

同时需要明确其适用边界：这套跨会话记忆属于开发侧的 Agent 自动化设施，服务于本仓库的长期多会话协作开发；它不参与 RuView WiFi 感知产品的推理与运行时链路。若要把同一模式复用到其他工程，最小闭环只需三步：参照 setup.md 以 npx claude-flow init --hooks 初始化钩子，确保 settings.json 中 SessionStart/SessionEnd 接线正确，再按 session-memory.md 的 MCP 调用面实现"结束落盘、启动恢复"，最后用备份 + 停用开关 + 命名空间清理守住数据治理底线。