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，无需命令，开口即搜。
核心原则
- 身份优先：操作前确认 uid，公私绝不混写
- 同步为先：写入前 pull，写入后立即 push
- 冲突保守：公共冲突不覆盖，标记待人工处理
- 向量优先：搜索优先向量语义，关键词作 fallback
完整文档见 reference.md
