🎉 init: 小龙的工作空间

2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
@@ -0,0 +1,178 @@
+# 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