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

在 RuView 工程中构建 Claude Code 跨会话记忆claude-flow 状态持久化、会话恢复与记忆治理实战【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView导读本篇文章围绕仓库 .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 MemoryAgent 记忆专长等级、任务成功率、优化策略、错误模式跨会话沉淀单个 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-tempsession-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_PERSISTfalseCLAUDE_FLOW_MEMORY_PERSISTfalse是记忆系统的总开关置为 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.mjsAutoMemoryBridge 的双向桥接更完整的自动记忆机制体现在 .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默认 10memoryGraph支持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通用、agentsAgent 状态、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 调用面实现结束落盘、启动恢复最后用备份 停用开关 命名空间清理守住数据治理底线。【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考