摇摇记忆系统

四层渐进式长时记忆系统，让 AI 跨会话保持上下文、沉淀知识、持续进化。 【首次使用必读】 安装后请运行初始化命令： ``` python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/init_memory.py ``` 【运行时依赖】 - python...

Security Scan

This skill is internally consistent: it implements a local four-layer memory system (create/search/promote/cleanup/summary) and optionally syncs selected content to an external IMA service when the user provides credentials — no hidden backdoors or unexplained requirements were found.

Purpose & Capability

Name/description match the actual code and instructions. The provided scripts (init_memory.py, summarize.py, promote.py, cleanup.py, sync_ima.py) implement the described local memory lifecycle and optional cloud sync to IMA. Optional env vars (IMA_OPENAPI_CLIENTID, IMA_OPENAPI_APIKEY) are coherent with the documented IMA sync feature.

Instruction Scope

Runtime instructions create and manage files under the workspace (default ~/.openclaw/workspace) and read USER.md/SOUL.md when present. The skill will read ~/.config/ima and the two IMA env vars if present. Nothing in SKILL.md or the scripts instructs the agent to read other unrelated system secrets, but the system does persist user-provided conversation content to local files (MEMORY.md, memory/*.md) and will include whatever the user allows. The scripts do not attempt to filter or redact sensitive values (passwords, API keys) that a user might accidentally tell the agent — this is a privacy risk to be aware of.

Install Mechanism

There is no download/install step embedded in the skill bundle (instruction-only with included scripts). SKILL.md suggests using 'npx clawhub install' (an external installer) which is plausible but separate from the skill package. No remote arbitrary archives or shortened URLs are used by the included code.

Credentials

No required environment variables are declared; the two IMA credentials are optional and justified solely for cloud backup/sync. The scripts only check those IMA credentials and ~/.config/ima — they do not request unrelated credentials. However, enabling sync with valid IMA credentials will transmit MEMORY.md content to the external IMA endpoint, so granting those credentials grants the skill permission to upload your stored memories to a third party.

Persistence & Privilege

The skill does not set always:true and does not alter other skills' configs. It writes/maintains its own workspace files (MEMORY.md, memory/, heartbeat-state.json). Note: enabling 'IMA automatic sync' writes flags in heartbeat-state.json and, when enabled with credentials present, will cause heartbeats/automation to send data to the IMA service — this increases the blast radius if you enable cloud sync.

Assessment

This skill appears to do what it claims (local memory management with optional cloud backup). Before installing: (1) Review and understand that it will create and maintain files in ~/.openclaw/workspace (MEMORY.md, memory/*.md) which can contain whatever the agent records. (2) Do not store secrets (passwords, API keys, tokens) in conversations you expect this skill to record — the scripts do not redact sensitive values. (3) Only configure IMA_OPENAPI_CLIENTID / IMA_OPENAPI_APIKEY or enable automatic IMA sync if you trust the IMA endpoint (https://ima.qq.com) and want your long-term memories uploaded to that service; use the --dry-run modes first to see what would be synced. (4) If you prefer local-only operation, do not enable IMA sync and keep imaEnabled false in memory/heartbeat-state.json. (5) If you have any doubt, inspect the included scripts locally and run init/promote/cleanup in dry-run mode before allowing automated heartbeats to run.

龙虾的外骨骼会随着成长不断蜕壳更新，记忆系统亦如此——定期蜕去过时的记忆，沉淀真正有价值的内容。

核心理念

记忆不是存储，而是进化。 每一次对话都是一次蜕壳的机会——丢弃琐碎，保留精华。

🚀 快速开始（3步上手）

第0步：安装

# 从 ClawHub 安装
npx clawhub@latest install yaoyao-memory

第1步：安装后初始化

复制粘贴这条命令到终端运行：

python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/init_memory.py

看到 ✅ 初始化完成！ 就成功了。

第2步：告诉 AI 记住重要内容

直接对话，AI 会自动识别重要信息：

你：记住，我喜欢简洁的代码风格
AI：✅ 已记录到 MEMORY.md：
    - #用户 喜欢简洁的代码风格

第3步：询问历史记忆

你：我之前说过什么代码风格偏好？
AI：[检索记忆] 你喜欢简洁的代码风格

就这么简单！ 其他都是自动的。

---

📖 详细说明

初始化命令详解

# 基础初始化（推荐）
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/init_memory.py

# 强制重新初始化（会覆盖已有文件）
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/init_memory.py --force

# 配置 IMA 云端备份（可选）
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/init_memory.py --ima-setup

初始化会创建：

• MEMORY.md — 长期记忆文件（重要内容存这里）
• memory/ — 中期记忆目录（日常记录存这里）
• memory/archive/ — 归档目录

日常使用

安装并初始化后，AI 会自动：

1. 记录重要内容 — 写入 memory/日期.md 或 MEMORY.md
2. 检索历史记忆 — 使用 memory_search 工具
3. 心跳维护 — 定期升级、清理记忆

手动维护命令

# 生成每日/每周摘要
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/summarize.py --type daily
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/summarize.py --type weekly

# 升级中期记忆到长期记忆
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/promote.py --days 7

# 清理过期记忆
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/cleanup.py --retention 30

# 同步到 IMA 知识库（需配置凭证）
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/sync_ima.py --type decision

四层记忆架构

┌─────────────────────────────────────────────────────────────┐
│  档案层 (Archive)                                           │
│  存储：IMA 知识库 / 外部持久化                               │
│  时长：永久                                                  │
│  内容：核心知识、重要决策、可复用经验                         │
├─────────────────────────────────────────────────────────────┤
│  长期层 (Long-term)                                         │
│  存储：MEMORY.md                                            │
│  时长：30天+                                                 │
│  内容：用户档案、重要决策、核心知识、错误教训                 │
├─────────────────────────────────────────────────────────────┤
│  中期层 (Mid-term)                                          │
│  存储：memory/YYYY-MM-DD.md                                  │
│  时长：7-30天                                                │
│  内容：日常对话、临时任务、待确认信息                         │
├─────────────────────────────────────────────────────────────┤
│  短期层 (Short-term)                                        │
│  存储：对话上下文                                            │
│  时长：当前会话                                              │
│  内容：实时交互、当前任务                                    │
└─────────────────────────────────────────────────────────────┘

记忆流向

短期 → 中期 → 长期 → 档案
  ↓       ↓       ↓       ↓
 会话   每日   每周/月   手动/自动
 结束   总结   沉淀     同步

---

核心能力

1. 记忆写入 (Write)

场景：需要记录信息时

决策树：

信息是否重要？
├─ 是 → 是否需要长期保留？
│       ├─ 是 → 写入 MEMORY.md（长期）
│       └─ 否 → 写入 memory/YYYY-MM-DD.md（中期）
└─ 否 → 不记录，保持在对话上下文

写入规则：

• MEMORY.md：用户档案、重要决策、核心知识、错误教训
• memory/YYYY-MM-DD.md：日常对话、临时任务、待确认信息

标签系统：

标签	用途
#用户	用户信息、偏好、习惯
#决策	重要决策及理由
#技术	技术决策、实现、经验
#错误	错误教训、踩坑记录
#待处理	等待执行的任务
#重要	核心记忆，不可遗忘

2. 记忆检索 (Recall)

场景：用户询问过往信息时

检索优先级：

1. 当前上下文 — 对话中已有的信息
2. 长期记忆 — MEMORY.md
3. 中期记忆 — memory/YYYY-MM-DD.md（最近7天）
4. 会话历史 — 搜索历史 session 文件

使用工具：

• 优先使用 memory_search 进行语义搜索
• 再用 memory_get 获取具体内容

3. 记忆升级 (Promote)

场景：中期记忆需要升级为长期记忆

触发条件：

• 信息被多次检索（≥3次）
• 用户明确表示"记住这个"
• 决策被反复引用
• 错误教训需要长期避免

执行方式：

# 从 memory/YYYY-MM-DD.md 提取内容
# 写入 MEMORY.md 对应章节
# 在原文件标记 [已升级]

4. 记忆清理 (Clean)

场景：定期清理过期记忆

清理规则：

层级	保留时长	清理策略
中期	7-30天	超过30天自动归档或删除
长期	30天+	每月审查，移除过时信息
档案	永久	手动管理

心跳清理： 每次心跳时检查：

1. 是否有超过30天的中期记忆文件
2. 是否有待处理事项已过期
3. 是否有冲突信息需要更新

5. 记忆同步 (Sync)

场景：将重要内容同步到 IMA 知识库

同步策略：

• 实时同步：重要决策 → IMA 决策库
• 每日同步：每日总结 → IMA 日记
• 每周同步：技术知识 → IMA 知识库

前置条件：需配置 IMA 凭证（见 ima-skill）

---

心跳维护任务

心跳时执行以下维护操作（轮换执行，不必每次全做）：

检查清单

• 中期记忆审查：检查最近7天的 memory/*.md，识别需要升级的内容
• 长期记忆更新：更新 MEMORY.md 中的用户档案、待处理事项
• 过期清理：删除超过30天的中期记忆文件
• 冲突解决：发现冲突信息时，以最新为准，标记旧信息为 [已过期]
• IMA 同步：如有重要决策或知识，同步到 IMA

状态追踪

维护 memory/heartbeat-state.json 记录上次检查时间：

{
  "lastChecks": {
    "midTermReview": "2024-01-15T00:00:00Z",
    "longTermUpdate": "2024-01-14T00:00:00Z",
    "expiredCleanup": "2024-01-10T00:00:00Z",
    "imaSync": null
  },
  "stats": {
    "totalMemories": 42,
    "promotedThisMonth": 3,
    "cleanedThisMonth": 12
  }
}

---

文件结构

workspace/
├── MEMORY.md              # 长期记忆（核心）
├── memory/
│   ├── YYYY-MM-DD.md      # 中期记忆（每日）
│   ├── heartbeat-state.json  # 心跳状态
│   └── archive/           # 归档目录
├── USER.md                # 用户档案
├── SOUL.md                # AI 人设
└── HEARTBEAT.md           # 心跳检查清单

---

使用示例

记录重要决策

用户：我们决定用 PostgreSQL 而不是 MySQL
AI：已记录到 MEMORY.md：
    - 决策：使用 PostgreSQL
    - 理由：[用户提供的理由]
    - 标签：#决策 #技术

检索历史记忆

用户：我们之前讨论的那个技术方案是什么？
AI：[调用 memory_search] 
    找到 MEMORY.md 的记录：
    - 决定采用四层记忆架构...

心跳维护

[心跳触发]
AI：执行记忆维护...
    - 检查过期的 memory/*.md（已归档）
    - 发现 3 条待升级内容
    - 更新 MEMORY.md 待处理事项
    → HEARTBEAT_OK

---

🏷️ 标签速查表

标签	用途	示例
#用户	用户偏好、习惯	#用户 喜欢简洁的代码风格
#决策	重要决定及理由	#决策 采用 PostgreSQL，理由：JSON支持好
#错误	踩坑记录、教训	#错误 忘记检查编码导致乱码
#重要	核心知识、不可遗忘	#重要 API密钥存放在 ~/.config/
#待处理	待办事项	#待处理 下周准备演示材料
#技术	技术相关	#技术 使用 Redis 做缓存

使用方式：在记录内容时添加标签，AI 会自动识别并分类处理。

---

🔒 隐私规则

绝对不记录的内容

• ❌ 密码、密钥、Token
• ❌ 身份证、银行卡号
• ❌ 私密对话内容（用户明确要求不记录）
• ❌ 临时性、一次性的信息

群聊场景特殊处理

• 只展示记忆标题和摘要
• 不展示记忆正文
• 不暴露用户隐私信息

用户可控

• 用户可随时要求删除某条记忆
• 用户可要求查看所有记录的内容
• 用户可关闭自动记录功能

---

❓ 常见问题（小白必看）

Q: 我刚安装，接下来要做什么？

A: 只需要运行一条命令：

python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/init_memory.py

看到 ✅ 初始化完成！ 就可以开始用了。

Q: 怎么让 AI 记住我说的话？

A: 直接说就行，AI 会自动识别重要内容：

你：记住，我以后都用 VS Code 写代码
AI：✅ 已记录

或者明确说：

你：请记录：我们决定用 Redis 做缓存
AI：✅ 已记录到 MEMORY.md

Q: 怎么查看 AI 记了什么？

A: 两种方式：

方式1：直接问 AI

你：你记住了关于我的什么？
AI：[列出记忆内容]

方式2：查看文件

cat ~/.openclaw/workspace/MEMORY.md

Q: 怎么删除某条记忆？

A: 直接告诉 AI：

你：删除关于 XXX 的记忆
AI：✅ 已删除

或者手动编辑文件：

# 用文本编辑器打开
nano ~/.openclaw/workspace/MEMORY.md
# 删除对应行，保存退出

Q: AI 没有自动记录怎么办？

A: 检查以下几点：

1. 是否已运行初始化命令？
2. 尝试明确告诉 AI "请记录这个"
3. 检查 memory/ 目录是否存在

Q: 运行脚本报错怎么办？

A: 常见错误及解决：

错误	解决方案
No such file or directory	先运行初始化命令
Permission denied	检查文件权限
command not found: python3	确认 Python 已安装

Q: 记忆文件太大怎么办？

A: 运行清理命令（先预览，再执行）：

# 预览将要清理的内容
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/cleanup.py --dry-run

# 确认无误后执行
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/cleanup.py

Q: IMA 是什么？一定要配置吗？

A: IMA 是可选的云端备份功能。

• 不配置：记忆只存在本地，完全够用
• 配置后：重要记忆可同步到云端，跨设备访问

如果需要配置，运行：

python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/init_memory.py --ima-setup

Q: 心跳维护是什么？

A: 简单说就是 AI 定期自动整理记忆：

• 把重要的内容升级到长期记忆
• 清理过期的临时记忆
• 不需要你手动操作

Q: 如何备份记忆？

A:

• 方式1：复制文件

  cp -r ~/.openclaw/workspace/MEMORY.md ~/backup/
  cp -r ~/.openclaw/workspace/memory/ ~/backup/
  

• 方式2：同步到 IMA（需先配置）

  python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/sync_ima.py
  

---

🏷️ 标签速查表（给 AI 看的）

你不需要手动添加标签，AI 会自动识别。但如果你想明确分类，可以说：

标签	含义	示例
#用户	你的偏好	"记住，#用户 我喜欢深色主题"
#决策	重要决定	"记录，#决策 我们用 PostgreSQL"
#错误	踩坑教训	"记住，#错误 不要用 delete 删除数据库"
#重要	核心知识	"#重要 API 地址是 api.example.com"

---

🔒 隐私说明

AI 绝对不会记录

• ❌ 密码、密钥、Token
• ❌ 身份证、银行卡号
• ❌ 你明确说"不要记录"的内容

你可以随时

• 查看所有记录的内容
• 删除任意一条记忆
• 要求 AI 不再自动记录

---

🔗 IMA 云端备份（可选功能）

IMA 是什么？ 腾讯提供的云端知识库，可以把重要记忆存到云端。

一定要配置吗？ 不需要。本地存储完全够用。

什么时候需要？ 想在多个设备间同步记忆时。

配置方法

# 运行配置向导
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/init_memory.py --ima-setup

# 按提示输入凭证（从 https://ima.qq.com/agent-interface 获取）

---

📜 脚本说明

脚本	功能	什么时候用
init_memory.py	初始化	首次安装后
summarize.py	生成摘要	想看记忆总结时
cleanup.py	清理过期	记忆文件太大时
promote.py	升级记忆	一般自动执行
sync_ima.py	云端同步	配置 IMA 后

所有脚本都支持 --dry-run 预览模式，先看再执行，不怕误操作。

IMA 同步命令

# 启用 IMA 自动同步（配置凭证后）
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/sync_ima.py --enable

# 禁用 IMA 自动同步
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/sync_ima.py --disable

# 手动同步
python3 ~/.openclaw/workspace/skills/yaoyao-memory/scripts/sync_ima.py --type decision

---

⚠️ 注意事项

1. 隐私优先：群聊中 AI 不会展示你的记忆正文
2. 新覆盖旧：如果有冲突，新信息会覆盖旧信息
3. 精简原则：AI 只记录真正重要的内容
4. 定期审查：建议每月看看 MEMORY.md，清理过时信息

---

🗑️ 卸载与清理

卸载 Skill

# 从 ClawHub 卸载
npx clawhub@latest uninstall yaoyao-memory

清理记忆文件（可选）

卸载 Skill 不会自动删除记忆文件，如需清理：

# 删除记忆文件（谨慎操作！）
rm -rf ~/.openclaw/workspace/MEMORY.md
rm -rf ~/.openclaw/workspace/memory/

# 删除 IMA 配置（如有）
rm -rf ~/.config/ima/

注意：删除后记忆无法恢复，请先备份重要内容。

---

🔗 与 self-improving-agent 联动

推荐同时安装 self-improving-agent 技能，实现错误记录和持续改进：

npx clawhub@latest install self-improving-agent

联动方式

场景	yaoyao-memory	self-improving-agent
记录用户偏好	✅ MEMORY.md	-
记录重要决策	✅ MEMORY.md	-
记录错误教训	✅ MEMORY.md #错误	✅ .learnings/ERRORS.md
记录最佳实践	✅ MEMORY.md	✅ .learnings/LEARNINGS.md
跨会话记忆	✅	✅

推荐工作流

1. 错误发生时：

   • self-improving-agent 记录到 .learnings/ERRORS.md
   • yaoyao-memory 记录到 MEMORY.md #错误

2. 学习到新知识时：

   • self-improving-agent 记录到 .learnings/LEARNINGS.md
   • yaoyao-memory 记录到 MEMORY.md #学习

3. 会话开始时：

   • 读取 MEMORY.md 获取用户档案和重要决策
   • 读取 .learnings/ 获取错误教训，避免重犯

---

📝 更新日志

版本	日期	更新内容
v1.0.5	2024-04-04	新增：与 self-improving-agent 联动说明
v1.0.4	2024-04-04	新增：IMA 自动同步启用/禁用功能
v1.0.3	2024-04-04	新增：运行时依赖声明、可选凭证说明
v1.0.2	2024-04-04	新增：安装命令、卸载说明、更新日志
v1.0.1	2024-04-04	修复路径一致性，统一为 yaoyao-memory
v1.0.0	2024-04-04	首次发布