# Supermemory 插件学习报告 vs 小龙记忆系统对比

> 学习对象：github.com/supermemoryai/openclaw-supermemory
> 学习日期：2026-06-02
> 镜像：git666.u7f.cn/sawz/openclaw-supermemory

---

## 一、项目总览

| 维度 | 内容 |
|------|------|
| 用途 | 给 OpenClaw Agent 提供云端长期记忆：Auto-Recall + Auto-Capture + 用户画像 |
| 核心能力 | 回忆注入、自动捕获、画像构建、多容器隔离、语义搜索 |
| 技术栈 | TypeScript ESM、Sinclair TypeBox、esbuild、Supermemory SDK |
| 文件规模 | 17 源文件，核心源码 < 30KB |
| 协议 | MIT |

---

## 二、核心调用链

```
用户消息
  → isInteractiveTrigger() 过滤心跳/cron
  → before_prompt_build → getProfile(query)
      ├── static profile (长期偏好)
      ├── dynamic context (近期动态)
      └── searchResults (语义相似记忆)
  → formatContext → XML 块注入 prependContext
  → AI 生成回复
  → agent_end → getLastTurn()
      ├── stripInboundMetadata (剥离元数据)
      ├── filter injected context (移除 <supermemory-context>)
      ├── filter short texts (< 10字)
      └── addMemory → 云端异步处理
```

---

## 三、核心模块

### 1. 插件入口 (index.ts)
- **优雅降级**：无 API Key → 只注册 CLI stub，不崩溃
- **新旧 API 兼容**：registerMemoryCapability / registerMemoryRuntime 双路径
- **工具双注册**：supermemory_search + supermemory-search 兼容命名

### 2. Auto-Recall (hooks/recall.ts)
- **分层频率**：static profile 低频注入（新会话 + 每50轮），search 每轮查询
- **静默指令**："Do not proactively bring up memories" 避免突兀
- **记忆使用计数**：[Supermemory: X memories loaded, Y used]

### 3. Auto-Capture (hooks/capture.ts)
- **只取最后一轮**：getLastTurn() 避免重复
- **三层过滤**：元数据 → 注入上下文 → 短文本
- **session 关联**：customId = buildDocumentId(sessionKey)

### 4. 配置系统 (config.ts)
- **白名单校验**：未知 key 直接抛异常
- **环境变量插值**：${SUPERMEMORY_API_KEY}
- **Schema 驱动 UI**：configSchema 同时用于校验 + 自动生成配置表单

### 5. CLI 命令 (commands/cli.ts)
- **交互式向导**：readline 逐项问答，有默认值
- **安全确认**：wipe 需输入 "yes"

### 6. 内容处理 (memory.ts)
- **元数据剥离**：sentinel 模式识别 provider 注入前缀
- **内容分类**：preference / decision / entity / fact / other
- **实体上下文模板**：指导 Supermemory 提取规则

---

## 四、小龙 🐉 vs Supermemory 🔌 — 全面对比

### 4.1 架构对比

| 维度 | 小龙（本地文件系统） | Supermemory（云端 API） |
|------|---------------------|------------------------|
| 存储 | MEMORY.md + vault.md + daily/ | Supermemory Cloud（PostgreSQL + 向量DB） |
| 检索 | memory_search（语义，需 API Key）/ memory_get（精确） | 全语义搜索，自动嵌入 |
| 写入 | 手动写文件 | 自动捕获 + AI Tool 写入 |
| 画像 | 手动维护 USER.md | 自动提取 static + dynamic |
| 配置 | 文件级约定 | Schema 驱动 + GUI + CLI |
| 部署 | 零依赖 | 需要 API Key + 网络 |
| 费用 | 免费 | Pro 付费 |
| 延迟 | < 1ms | ~50ms API 调用 |

### 4.2 能力对比

| 能力 | 小龙 | Supermemory | 谁优 |
|------|------|-------------|------|
| **自动捕获** | ❌ 无，需手动写 daily/ | ✅ 每次对话自动捕获 | 🔌 |
| **自动召回** | ❌ 无，需手动 memory_get | ✅ 每轮自动搜索 + 注入 | 🔌 |
| **用户画像** | ⚠️ 手动 USER.md | ✅ 自动 static + dynamic | 🔌 |
| **语义搜索** | ⚠️ memory_search（依赖 embedding API，目前挂） | ✅ 内置，SOTA 基准第一 | 🔌 |
| **去重/降噪** | ⚠️ 靠我自己判断 | ✅ 自动过滤 + 短文本 + 元数据剥离 | 🔌 |
| **多容器隔离** | ❌ 无 | ✅ containerTag + 自定义容器 | 🔌 |
| **缓存友好** | ✅ MEMORY.md 瘦身到 2KB + 缓存线以上锁定 | ⚠️ 注入内容每次变→前缀变→缓存可能炸 | 🐉 |
| **透明度** | ✅ 文件可读可改 | ⚠️ 黑盒，用户看不到存了什么 | 🐉 |
| **零依赖** | ✅ 不依赖外部服务 | ❌ 依赖网络 + API | 🐉 |
| **延迟** | ✅ 无额外延迟 | ⚠️ 每轮 ~50-200ms | 🐉 |
| **离线可用** | ✅ | ❌ | 🐉 |
| **费用** | ✅ $0 | ❌ Pro 月度订阅 | 🐉 |

### 4.3 设计哲学对比

| 维度 | 小龙 | Supermemory |
|------|------|-------------|
| 核心理念 | "我知道我要记什么" | "我不知道我要记什么，你帮我" |
| 人机关系 | 工具辅助人决策 | 自动代理减轻人的负担 |
| 记忆质量 | 高（我筛选过才写） | 中（自动提取，可能漏/误） |
| 记忆数量 | 少而精 | 多而全 |
| 适用场景 | 精准工作，少量偏好 | 海量对话，长期积累 |

---

## 五、综合评价

### Supermemory 胜出的场景
- 长期大量对话 → 自动积累，人不需要操心
- 多对话 channel → 跨 session 记忆统一
- 用户画像 → 自动识别偏好、习惯、项目
- 新手用户 → 不需要手动维护记忆文件

### 小龙胜出的场景
- **缓存命中率** → 稳定前缀不动，DeepSeek 缓存不炸
- 精准关键决策 → 我判断重要才记，不是全量
- 离线/弱网 → 不依赖外部服务
- 零成本 → 不花钱
- 透明度 → 尘哥可以随时看、改、删任何记忆
- 安全 → 数据不出机器

---

## 六、最佳方案：双轨制 🐉🫧

**不是二选一，是互补：**

```
本地骨架（小龙）              云端引擎（Supermemory）
├── MEMORY.md (2KB)            ├── 自动捕获对话
├── vault.md (决策/项目)        ├── 语义搜索 + 画像
├── daily/ (日志)               ├── 跨 session 关联
├── 缓存友好 ✅                 └── 多容器隔离
└── 零依赖 ✅
        ↕                         ↕
   关键记忆 + 工程规范         海量对话 + 模式发现
```

具体分工：
- **小龙负责**：工程范式、关键决策、工具环境、时间规则 —— 缓存线上不动
- **Supermemory 负责**：日常对话的自动捕获、语义召回、用户画像 —— 上下文注入
- **互不干扰**：缓存线上的文件不动，Supermemory 的注入在缓存线以下

---

## 七、从 Supermemory 学到可迁移到小龙的能力

| 能力 | 如何迁移 |
|------|---------|
| **元数据剥离** | 写入 daily/ 前 strip 注入的前缀和 JSON 块 |
| **短文本过滤** | 对话片段 < 20 字不记录 |
| **分类标签** | vault.md 条目加 preference/decision/fact 标签 |
| **回忆计数** | 每次回复后标注用了多少条记忆 |
| **频率控制** | vault.md 不全量注入，按需 memory_get |
| **触发器过滤** | 心跳/cron 触发时不写记忆 |
| **优雅降级** | memory_search 不可用时降级到 memory_get 精确读 |

---

## 八、结论

**Supermemory 是一个成熟的记忆引擎，但我们的本地文件系统在缓存友好性、零成本、透明度上有不可替代的优势。**

最优策略是双轨：本地做骨架（缓存友好 + 关键决策），云端做血肉（自动捕获 + 语义召回）。如果只选一个，对于缓存敏感情景，小龙的本地系统更优。

> 报告生成：小龙 🐉 + 团子 🫧 · 2026-06-02