artclaw-memory

ArtClaw 记忆管理

记住用户偏好、操作历史、项目规范、踩坑经验，管理和维护 ArtClaw 的记忆系统。

---

何时读取记忆 (必须遵守)

1. 对话开始时 — 自动注入 (已实现，无需手动)

Memory Briefing 在 bridge 层自动注入到首条消息，包含团队记忆和个人记忆。

2. 反复出错时 — 主动搜索 (强制)

当同一类操作连续失败 2 次以上时，必须主动搜索记忆寻找解决方案：

from core.memory_store import get_memory_store
mm = get_memory_store()
if mm:
    # 搜索个人记忆
    hints = mm.manager.search("关键词", tag="crash", limit=3)
    hints += mm.manager.search("关键词", tag="pattern", limit=3)
    # 搜索团队记忆
    team_hints = mm.manager.search_team_memory("关键词", limit=3)

3. 高风险操作前 — 主动检查 (建议)

执行删除、批量修改、材质替换、导入导出等操作前：

check = mm.manager.check_operation(tool="工具名", action_hint="操作描述")
# 如果有 crash_rules 或 warnings，告知用户风险

---

何时写入记忆 (必须遵守)

核心原则: 只记"付出代价的经验"

• 一次性成功的操作不记录
• 多次尝试才成功的经验才值得记录

1. 多次尝试后成功 — 提炼规则 (强制)

当你经过 2 次以上尝试或修改才正确完成一个操作时，必须提炼规则并记录：

mm.manager.record(
    key="pattern:简短描述",
    value="精炼的规则（一句话说清楚问题和解法）",
    tag="pattern",
    importance=0.8,
    source="retry_learned"
)

规则质量要求:

• 一句话说清楚：什么情况 + 正确做法
• 示例: "MaterialExpressionMultiply 的 A/B 输入必须显式连接，留空会报错"
• 不要记录过程细节，只记最终结论

2. 用户纠正后 — 提炼教训 (强制)

当用户指出错误（"不对"/"错了"/"重做"等）并经过修正后，主动提炼教训：

mm.manager.record(
    key="pattern:被纠正的问题描述",
    value="正确的做法和原因",
    tag="pattern",
    importance=0.8,
    source="user_correction"
)

3. 发现反直觉行为 — 记录陷阱 (强制)

当发现 API 行为与文档/直觉不符时：

mm.manager.record(
    key="pattern:API或行为描述",
    value="实际行为和正确用法",
    tag="pattern",
    importance=0.9,
    source="gotcha"
)

4. 崩溃/严重错误 — 记录规则 (强制)

mm.manager.record_crash(
    tool="工具名",
    action="操作名",
    params_summary="参数摘要",
    error="错误信息",
    root_cause="根因分析（一句话）",
    avoidance_rule="避免规则（一句话）",
    severity="high"  # low/medium/high/critical
)

5. 用户明确说"记住" — 直接存储

mm.manager.record(
    key="合适的key",
    value="用户要记住的内容",
    tag="preference",  # 或 convention/fact
    importance=0.7
)

---

不要记录的内容

• 纯查询操作（列出 Actor、获取属性等）
• 一次性简单操作（移动物体、改个颜色）
• 已经在团队记忆中存在的规则（避免重复）