memory-mastery

Memory Mastery 是专为 OpenClaw 智能体设计的跨会话记忆持久化解决方案，采用独特的三层架构（L1 每日日志、L2 长期记忆、L3 向量搜索）解决 Agent 重启后上下文丢失的核心痛点。

核心用法上，用户通过 setup.sh 初始化系统后，Agent 会在每次会话开始时自动读取当日和前一日的日志文件（memory/YYYY-MM-DD.md）以及长期记忆文件（MEMORY.md）。会话过程中，Agent 实时追加记录到每日日志，重要决策则手动整理至长期记忆。每周通过 maintenance.sh 审查近期日志，将关键信息提炼到 L2 层。若启用 memory-core 插件，还可通过语义搜索（L3）快速定位历史上下文。

显著优点体现在其工程设计的严谨性：纯 Bash 脚本实现零外部依赖，避免了供应链攻击风险；自动备份机制（.backup-TIMESTAMP）确保安装过程可逆；隐私保护设计使 MEMORY.md 仅在主会话加载，避免敏感信息泄露；三层架构兼顾了记录的便捷性（L1）、知识的持久性（L2）和检索的智能性（L3）。

潜在缺点主要包括维护成本：L2 层需要人工定期整理，否则会变得陈旧冗余；长期使用的 MEMORY.md 可能膨胀影响 token 消耗；L3 向量搜索依赖外部嵌入 API（如 Voyage）产生额外成本；每日日志积累会占用磁盘空间，需要定期归档。

适合的目标群体为 OpenClaw 的重度用户，特别是需要长期跟踪复杂项目、跨多会话保持决策连贯性的开发者、研究员或知识工作者。对于重视数据隐私、希望完全掌控记忆数据的用户尤为适用。

使用风险方面，虽然脚本内置了完善的安全措施（错误处理 set -euo pipefail、操作前确认、文件备份），但仍需注意：脚本需要对工作区目录的写权限，误操作可能修改 AGENTS.md 等核心配置；备份文件长期积累可能占用磁盘空间；多用户共享工作区时，每日日志可能包含敏感信息，需配合隐私保护策略使用。

核心用法

Memory Mastery 为 OpenClaw 代理设计了一套完整的三层记忆系统，解决会话间上下文丢失的痛点。L1 每日日志采用追加式写入（memory/YYYY-MM-DD.md），记录原始会话流水；L2 长期记忆（MEMORY.md）存储经人工或智能筛选的关键洞察，仅在主会话加载以确保隐私；L3 向量搜索通过 memory-core 插件实现语义级检索。

显著优点

• 真正的持久化：突破传统代理"睡醒即失忆"的限制，项目决策、用户偏好、历史状态自动延续
• 分层 freshness 设计：原始日志与精炼知识分离，既保留完整审计链，又避免核心记忆文件膨胀
• 零依赖纯 Bash：所有脚本不依赖第三方运行时，OpenClaw 工作空间开箱即用
• 隐私优先：敏感记忆（MEMORY.md）默认隔离于共享上下文，符合企业合规要求
• 结构化维护流程：周报式维护脚本（maintenance.sh）自动提示待归档内容，降低记忆僵化风险

潜在缺点与局限性

• MEMORY.md 膨胀风险：长期项目若不执行周报维护，token 占用将线性增长
• L3 向量搜索成本：语义搜索依赖外部 Embedding API（如 Voyage），产生额外调用费用
• 手动策展负担：从 L1 到 L2 的知识提炼需人工判断或代理主动识别，无法全自动完成
• 归档冷数据管理：每日日志 30-90 天后需手动迁移至 memory/archive/，磁盘管理不善将导致碎片化

适合人群

• 需要代理记住复杂项目背景的专业开发者与知识工作者
• 跨多周/多月持续迭代同一项目的团队
• 对隐私敏感、希望敏感上下文不泄露到共享环境的用户
• 愿意投入少量维护时间换取长期上下文连续性的高阶用户

常规风险

• 过度记忆：敏感信息（密码、token）若误入日志，存在本地泄露风险（脚本虽搜索识别，但无自动脱敏）
• 备份依赖：安装脚本会自动备份现有文件，但用户若手动编辑 MEMORY.md，建议自行版本控制
• 插件兼容性：L3 功能依赖 memory-core 插件状态，插件更新或配置变更可能导致向量搜索失效

架构概览

workspace/
├── MEMORY.md              # L2: 长期精炼记忆（主会话私有）
├── memory/                # L1: 每日原始日志
│   ├── 2026-02-09.md
│   └── heartbeat-state.json
├── AGENTS.md              # 自动注入记忆规则
└── HEARTBEAT.md           # 自动注入维护任务

安全认证摘要

• 静态分析：85/100，无危险函数，纯 Bash 实现
• 动态分析：80/100，仅限本地文件操作
• 隐私合规：75/100，数据本地存储无外泄，处理用户数据需自行审计
• 网络分析：100/100，零网络请求
• 依赖审计：100/100，零第三方依赖