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 永久

记忆归属

会话启动流程

⚠️ 跨设备场景：用户可能从不同设备（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 {新文件路径}

升级标记

向量搜索

# 首次：生成向量库
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