Memory Manager

---

name: memory-manager description: OpenClaw专用三层AI记忆管理系统。管理临时记忆(L1)/长期记忆(L2)/永久记忆(L3)，支持向量语义搜索、自动压缩、OpenClaw用户身份识别和跨设备同步。 version: 3.5.0 license: MIT allowed-tools: Read,Write,Bash,Glob,Grep environment: - OPENAI_API_KEY: 可选，OpenAI API密钥（用于向量嵌入） - SILICONFLOW_API_KEY: 可选，硅基流动API密钥（国内推荐） - ZHIPU_API_KEY: 可选，智谱AI API密钥 - EMBED_BACKEND: 必需，指定后端（openai/siliconflow/zhipu） - GITHUB_TOKEN: 可选，用于GitHub同步 - MM_UID: 可选，指定用户ID - MM_BASE_DIR: 可选，记忆仓库路径 metadata: { "openclaw": { "emoji": "🧠", "requires": {"bins": ["python", "git"]}, "environment_variables": ["EMBED_BACKEND"], "optional_environment_variables": ["OPENAI_API_KEY", "SILICONFLOW_API_KEY", "ZHIPU_API_KEY", "GITHUB_TOKEN", "MM_UID", "MM_BASE_DIR"], "security_note": "该技能会读取users/目录下所有用户的profile.md文件以实现多用户识别，修改shell RC文件以持久化配置，使用curl|bash方式安装需谨慎", "data_scope": "会访问多用户私有文件、执行git操作、修改环境变量和配置文件", "install": [ { "id": "openclaw-workspace", "kind": "script", "script": "install.sh", "args": ["-p", "$HOME/.openclaw/memory"], "label": "安装到 OpenClaw workspace (会修改shell配置文件)" } ], "integration": "OpenClaw 记忆后端", "auto_enable": true } } read_when: - OpenClaw 会话开始时 - 用户询问历史记忆时 - 需要上下文理解时 - 记录重要信息时 - 总结近期工作时

---

Memory Manager — 三层记忆 + 向量搜索 + 关联记忆（v3.5）

> [!IMPORTANT] > AI 必须遵守：MEMORY_STYLE_GUIDE.md 中定义的记忆文件规范。 > 任何写入记忆系统的操作，都必须遵循该规范。

> [!TIP] > OpenClaw 用户：请参考 README.md 中的「OpenClaw 集成安装」章节。

OpenClaw 专用安装

# 方法1: 通过 OpenClaw skill 管理器安装
（推荐）OpenClaw 会自动处理依赖和配置
方法2: 手动安装到 OpenClaw workspace
cd ~/.openclaw/workspace/skills/
git clone https://github.com/Pupper0601/memory-manager.git
cd memory-manager
安装依赖
pip install -r requirements.txt
配置 OpenClaw 记忆系统
mm onboard --openclaw
方法3: 一键安装脚本
curl -fsSL https://raw.githubusercontent.com/Pupper0601/memory-manager/main/install.sh | bash -s -- -p "$HOME/.openclaw/memory"

多用户架构

memory-repo/
├── shared/              # 公共记忆
│   ├── daily/           # 公共临时（当天）
│   ├── weekly/          # 公共周报（本周）
│   └── permanent/      # 公共永久
└── users/{uid}/        # 私人记忆
    ├── daily/           # L1 临时
    ├── weekly/          # L2 长期
    ├── archive/         # 归档
    └── permanent/       # L3 永久

记忆归属

| 内容 | 归属 | 路径 | |------|------|------| | 个人当天任务/进展 | 私人L1 | users/{uid}/daily/YYYY-MM-DD.md | | 个人本周计划/总结 | 私人L2 | users/{uid}/weekly/YYYY-WNN.md | | 个人经验/偏好/决策 | 私人L3 | users/{uid}/permanent/*.md | | 团队当天进展 | 公共临时 | shared/daily/YYYY-MM-DD.md | | 团队本周摘要 | 公共周报 | shared/weekly/YYYY-WNN.md | | 项目/技术/决策 | 公共L3 | shared/permanent/*.md | | 行为习惯 | 私人 | users/{uid}/HABITS.md |

会话启动流程

> ⚠️ 跨设备场景：用户可能从不同设备（WorkBuddy / 企微 / 飞书 / Web）发起会话，AI 必须通过以下步骤自动解析 uid，不能假设用户 ID。

1. 自动解析 uid（按优先级）：
   ① 检查 users/ 目录下的子目录列表（git pull 后可见）
      - 若只有 1 个用户目录 → 直接使用该 uid
      - 若有多个 → 读取每个 users/{uid}/profile.md 的 uid 字段
      - 根据对话上下文（用户名/签名/问候）匹配最可能的 uid
   ② 读取 .current_user 文件（本地设备快速路径）
   ③ 环境变量 MEMORY_USER_ID
   ④ 都没有 → 询问用户："请问你是哪位？（输入你的用户ID）"
2. git pull → 同步最新记忆（确保拿到最新 profile.md 等文件）
3. ⚠️ 版本检查（必做）：
   - 读取记忆仓库根目录的 SKILL_VERSION.md
   - 提取 required_skill_version 字段
   - 与本 SKILL.md 顶部的 version 字段对比
   - 若本地版本 < required_skill_version：
     ⛔ 立即提示用户：
     "⚠️ memory-manager skill 需要更新！
      当前版本: {local_version}，要求版本: {required_version}
      请运行：git -C ~/.workbuddy/skills/memory-manager pull
      或查看 Release：https://github.com/Pupper0601/memory-manager/releases"
   - 版本满足则静默继续
4. 读取 users/{uid}/profile.md → 确认身份
5. 读取当天 L1 文件（如存在）
6. 读取 users/{uid}/HABITS.md
7. 读取 shared/permanent/（如上下文相关）
8. 如有搜索需求 → 使用 memory_search.py

uid 自动解析脚本

import os
def resolve_uid(repo_dir: str) -> str:
    """跨设备自动解析当前用户 uid"""
    
    # 方式 1：读取本地 .current_user（本设备快速路径）
    current_user_file = os.path.join(repo_dir, ".current_user")
    if os.path.exists(current_user_file):
        with open(current_user_file) as f:
            uid = f.read().strip()
        if uid:
            return uid
    
    # 方式 2：扫描 users/ 目录下的 profile.md（跨设备路径）
    users_dir = os.path.join(repo_dir, "users")
    if os.path.exists(users_dir):
        candidates = []
        for name in os.listdir(users_dir):
            profile = os.path.join(users_dir, name, "profile.md")
            if os.path.exists(profile):
                candidates.append(name)
        if len(candidates) == 1:
            return candidates[0]   # 单用户直接返回
        # 多用户 → 返回列表让 AI 选择
        return f"[多用户: {', '.join(candidates)}]"
    
    # 方式 3：环境变量
    return os.environ.get("MEMORY_USER_ID", "")

写入规则

> ⚠️ 严格遵守 MEMORY_STYLE_GUIDE.md 规范！

命名规范：{类型前缀}_{简短描述}_{日期}.md，如 idea_autosave_v2_20260404.md

必须字段：type, created, updated, tags, scope, importance

Frontmatter：每个记忆文件开头必须有完整的 YAML frontmatter

内容模板：使用规范中定义的模板（idea/dec/learn/daily）

文件大小：单个文件不超过 10KB

禁止内容：禁止记录密码、密钥、Token、他人隐私信息

公共记忆：写入 shared/permanent/ + git pull + push

私人记忆：写入 users/{uid}/ + git add + commit + push

压缩触发：L1 >150行 / L2 >200行 / L3 >300行 → python scripts/memory_compress.py --uid {uid} --upgrade

写入前自检

# 写入前运行检查
mm lint --path {新文件路径}

升级标记

| 标记 | 动作 | |------|------| | [IMPORTANT] | 升级到 L2 | | [PERMANENT] / [升级L3] | 升级到 L3 | | [HABIT] | 提取到 HABITS.md |

向量搜索

# 首次：生成向量库
mm embed --rebuild
语义搜索（直接输入搜索内容）
mm search "我上周做了什么"
搜索公共记忆
mm search "团队进展" --shared
关键词 fallback（无 API 依赖）
mm search "memory" --keyword-only
调整语义权重（默认 0.6）
0.8 = 纯语义相似度，0.3 = 重要性优先
python scripts/memory_search.py --uid pupper --query "重要决策" --semantic-weight 0.3
查看向量库统计
mm stats
重建 LanceDB HNSW 索引（加速搜索 100x）
python scripts/memory_search.py --uid pupper --rebuild-index
显示缓存统计
python scripts/memory_search.py --uid pupper --cache-stats

> 性能优化：安装 LanceDB 可获得 100x 搜索加速：pip install lancedb

快捷命令

"记住这个" → mm log "内容"

"同步记忆" → git pull + push

"查找记忆 [词]" → mm search "[词]"

"记忆报告" → mm insight

"AI 总结" → mm insight --weekly

"生成向量" → mm embed

AI 洞察

# 综合洞察
mm insight
每日洞察
mm insight --daily
每周洞察
mm insight --weekly

> 💡 推荐：使用 memory-agent skill，无需命令，开口即搜。

核心原则

1. 身份优先：操作前确认 uid，公私绝不混写 2. 同步为先：写入前 pull，写入后立即 push 3. 冲突保守：公共冲突不覆盖，标记待人工处理 4. 向量优先：搜索优先向量语义，关键词作 fallback

---

完整文档见 reference.md