memory-maintenance

核心用法

Memory Maintenance 是专为 OpenClaw 代理设计的智能内存管理系统，采用"审查-建议-审批-执行"的分级工作流。每日 23:00（可配置），系统自动扫描 memory// 目录下最近 7 天的会话笔记，调用 Gemini 2.5-flash 模型分析内容价值，生成结构化的 MEMORY.md 更新建议（JSON 格式）及人类可读报告（Markdown）。用户通过 --dry-run 预览、、--safe 执行安全维护（仅归档）、--all 确认后执行全部更改。系统同时监控目录健康状态，自动将 7 天以上的审查报告归档至月度桶，30 天后清理，并维护可恢复的 .trash 回收站。

显著优点

智能分层执行：独创三级执行模式（dry-run/safe/all），将风险操作与无害维护分离，既保证自动化效率又守住安全底线。成本优化设计：选用 Gemini 2.5-flash 作为主力模型，在结构化输出任务上实现速度与成本的最佳平衡，甚至提供 lite 版本应对限流。生态深度整合：原生适配 OpenClaw 的 MEMORY.md 标准结构，自动识别 Agent Identity、Infrastructure、Active Projects 等 8 大核心板块，建议精准可落地。防御性架构：强制人工审批内容修改、回收站替代永久删除、硬编码路径虽存但配合环境变量备选，体现安全优先的设计理念。

潜在缺点与局限性

硬编码路径隐患：脚本中硬编码 /Users/maxhutchinson/.openclaw/workspace，跨用户部署时需手动修正或依赖环境变量回退。语法缺陷：apply.sh 的 --all 分支存在模式匹配缺失，可能导致该选项失效。外部依赖链条长：需同时满足 OpenClaw ≥2026.2.0、Gemini CLI、jq 及有效 API Key，任一环节故障即中断服务。隐私权衡：会话内容需上传至 Google Gemini API 分析，对敏感场景存在合规顾虑。上下文窗口限制：7 天回溯期与 10 条建议上限可能遗漏长周期项目的隐性关联。

适合的目标群体

高频使用 OpenClaw 的专业用户：日均多会话、记忆目录快速膨胀的开发者与知识工作者。多项目并行管理者：需要跨会话维护 Active Projects 状态、避免重复上下文设置的产品经理与研究员。注重可审计性的团队：分级审批与完整日志输出满足企业合规要求的中小技术团队。成本敏感型 AI 采用者：愿以轻度人工复核换取显著 API 费用节约的理性用户。

使用风险

数据可用性风险：虽有回收站机制，但误配置 retention 参数或强制 --all 操作可能导致关键历史版本暂时不可访问。API 依赖风险：Gemini 服务中断或密钥失效将直接瘫痪核心审查功能，需建立本地降级预案。命令注入可能：路径变量未充分校验，极端文件名场景下存在 shell 注入攻击面。性能瓶颈：大规模 memory 目录（千级文件）的遍历与 LLM 分析可能触发超时，建议配合 cron 错峰执行。

核心用法

Memory Maintenance 是一个面向 OpenClaw 代理的自动化内存管理工具，主要解决「代理每次会话从零开始、历史笔记堆积难以检索」的痛点。其核心工作流为：每日定时扫描 memory/ 目录下的会话笔记 → 通过 Gemini 模型分析内容并生成结构化建议 → 输出人类可读的审查报告 → 经人工确认后更新 MEMORY.md → 自动归档过期文件。

使用方法灵活：支持手动触发 (openclaw skill memory-maintenance run)、命令行精细化操作 (review/apply/cleanup/status/stats)，以及安装时配置的定时任务（默认 23:00）。apply 命令提供三级安全模式：--dry-run 预览、--safe 仅应用归档等低风险操作、--all 需二次确认才执行内容修改。

显著优点

安全设计周到：内容变更强制人工审批，删除操作采用 trash 回收站机制（非永久删除），且所有文件操作限定在用户配置的 WORKSPACE 目录内。

依赖极简可控：仅依赖 gemini CLI 和 jq 两个知名工具，无 npm/pip 第三方库，供应链攻击面极小。

成本效益优秀：推荐使用 gemini-2.5-flash 系列轻量模型，处理速度快、API 成本低。

配置高度灵活：支持自定义审查周期、保留策略、归档阈值、时区等，适配不同工作节奏。

潜在缺点与局限性

来源可信度为 T3：作者 Max Hutchinson 为个人开发者，虽代码质量良好（安全评分 78/A 级），但长期维护响应速度、社区生态成熟度不及 T1/T2 级企业/组织项目。

隐私合规存在 minor gap：安全报告显示「数据访问日志」项为 warn 状态，对审计追踪要求严格的场景需额外关注。

首次配置有门槛：需自行准备 Gemini API key、安装 CLI 工具、理解 WORKSPACE 路径配置，对非技术用户不够友好。

适合人群

• 使用 OpenClaw 框架且代理会话频繁、笔记量大的开发者
• 希望减少「重复设置上下文」摩擦、提升代理长期记忆质量的技术用户
• 具备基础 shell 环境配置能力、能接受 T3 来源风险的个人或小型团队

常规风险

1. 误操作风险：虽有多层保护，但 --all 模式下若未仔细审阅建议，可能误改 MEMORY.md 重要内容。建议首次使用必走 --dry-run。

2. API 依赖与成本：依赖 Google Gemini API，虽成本低但存在服务可用性和费率变动风险；API key 泄露可能导致额度被盗用。

3. 数据保留策略误配：默认 30 天自动清理，若未及时调整可能丢失需要长期追溯的笔记。建议根据合规需求个性化配置 retention_days。