核心用法
MemClaw Maintenance 技能专注于 MemClaw 记忆插件的基础设施管理，与面向日常使用的 memclaw 技能形成明确分工。本技能覆盖四大核心场景：
1. 安装部署：通过 OpenClaw 插件系统安装 @memclaw/memclaw，配置 LLM 与 Embedding API 密钥，启用插件并禁用原生 memorySearch
2. AGENTS.md 升级：关键步骤——替换旧版 Memory 模块，植入 MemClaw 专用指令集，确保 Agent 在会话启动时自动加载 L0/L1 记忆层，并在交互中调用 cortex_add_memory、cortex_search 等新工具
3. 数据迁移：可选执行 cortex_migrate，将既有 OpenClaw 原生记忆（MEMORY.md 等）转换为 MemClaw 的三层架构（L0 摘要/L1 概览/L2 完整记录）
4. 运维监控：通过 cortex_maintenance 执行索引重建、向量清理等维护操作，检查 Qdrant（6333/6334）与 cortex-mem-service（8085）健康状态
---
显著优点
| 维度 | 优势说明 |
|------|---------|
| **架构先进性** | 采用 Cortex Memory 三层分层设计，L0 摘要（~100 tokens）快速加载，L1 概览（~2000 tokens）提供上下文，L2 完整记录支持深度检索，实现记忆粒度与成本的精准平衡 |
| **检索效率** | 基于 Qdrant 向量数据库的语义搜索，相比原生关键词匹配，召回率与相关性显著提升 |
| **Token 经济性** | 分层加载机制避免每次会话全量记忆注入，大幅降低 LLM 调用成本 |
| **本地优先** | 记忆数据完全本地存储（macOS/Windows/Linux 标准用户目录），无云端同步，满足隐私敏感场景 |
| **开源可控** | 完整代码开源于 GitHub，API 密钥采用 OpenClaw 敏感字段机制加密存储，不向第三方传输 |
| **运维自动化** | 内置 `cortex_maintenance` 支持定时 Cron 任务，自动处理索引优化与数据清理 |
---
潜在缺点与局限性
1. 部署复杂度较高：需同时配置 LLM 和 Embedding 双端 API，涉及 JSON 配置编辑、端口冲突排查、服务健康检查，技术门槛高于原生方案
2. AGENTS.md 强依赖：若未正确更新指令模板，Agent 将回退至 legacy memory，导致 MemClaw 形同虚设——这是最常见的配置失败点
3. 资源占用：本地运行 Qdrant 与 cortex-mem-service 需持续占用内存与端口（6333/6334/8085），低配置设备可能影响性能
4. 迁移一次性风险：cortex_migrate 虽备份原文件，但复杂历史记忆的格式转换可能存在边缘 case 丢失
5. 生态绑定：深度耦合 OpenClaw 插件架构，难以迁移至其他 Agent 框架
---
适合的目标群体
- OpenClaw 重度用户：日均会话量大、记忆积累丰富，原生记忆检索精度与成本已构成瓶颈
- 隐私优先场景：医疗、法律、企业内网等禁止云端记忆同步的合规环境
- 多项目/多角色工作者：需要 Agent 长期维持跨会话的用户画像与上下文连续性
- 具备技术运维能力：能独立处理 API 配置、端口调试、JSON 编辑的用户或团队
---
使用风险说明
| 风险类型 | 具体描述 | 缓解建议 |
|---------|---------|---------|
| **配置泄漏风险** | `openclaw.json` 包含明文 API 密钥，误提交至版本控制或公开分享将导致密钥泄露 | 启用 OpenClaw `sensitive` 标志，将配置纳入 `.gitignore`，定期轮换密钥 |
| **服务可用性风险** | Qdrant 或 cortex-mem-service 未启动/端口冲突时，记忆功能完全失效 | 建立健康检查脚本，监控 `localhost:6333` 与 `:8085/health`，设置自动重启 |
| **数据一致性风险** | 不当的 `cortex_maintenance` 操作（如误删索引）可能导致记忆不可恢复 | 始终先执行 `dryRun: true` 验证，定期备份 `~/Library/Application Support/memclaw` 等数据目录 |
| **版本兼容性风险** | OpenClaw 或 MemClaw 插件升级可能引入配置格式变更 | 升级前查阅 Release Note，保留配置备份，分环境验证后再生产部署 |
| **迁移回滚风险** | 迁移后若需回退原生记忆，需手动还原备份文件 | 迁移前确认备份完整性，记录原 `memory/` 目录状态 |
总体而言，MemClaw Maintenance 是一套专业级的记忆基础设施方案，适合追求极致效率与隐私可控的技术型用户，但需投入相应的学习与运维成本。