Smart Memory

核心用法

Smart Memory 是面向 AI 代理的上下文记忆系统，采用 SQLite 单文件架构，无需外部服务即可运行。核心功能围绕两种检索模式展开：

Fast Mode（快速模式）：默认启用，直接执行向量相似度搜索，适合快速事实查询、简单查找场景。支持混合搜索算法——FTS5 关键词匹配（BM25 排名）与语义向量搜索加权融合（70% 向量 + 30% 关键词）。

Focus Mode（策展模式）：通过多轮处理提供高质量上下文，执行流程为「广域检索 20+ 块 → 加权排序（向量 + 词匹配 + 来源/时效加权）→ 合成叙事 → 输出结构化结果带置信度」。适用于复杂决策、多事实综合、规划策略、历史总结等场景。

工具层面提供 memory_search（双模态检索）、memory_get（精确获取片段）、memory_mode（模式切换）三类接口，CLI 支持完整的同步、搜索、模式管理命令。

显著优点

• 零配置开箱即用：无需 API 密钥，Transformers.js 本地运行嵌入，SQLite 单文件即装即跑
• 混合搜索质量高：BM25 精确匹配与语义向量互补，显著优于纯向量方案
• 双模态灵活切换：Fast 满足速度敏感场景，Focus 满足质量敏感场景，实时 toggle
• 性能可扩展：原生 sqlite-vec 支持时向量检索达 ~10,000 chunks/sec，无插件时仍保持 ~100 chunks/sec 可用水平
• 完全离线隐私：所有嵌入与数据本地处理，无云端传输

潜在局限

• Focus Mode 增加 50-100ms 延迟，高频快速查询场景需权衡
• 依赖 Transformers.js 的首次加载与模型下载，冷启动存在初始化成本
• 复杂查询的策展质量取决于底层分块（chunking）策略，长文档语义切割可能产生边界误差
• 无多用户隔离机制，单文件架构更适合个人/单代理场景

适合人群

• 需要为 Claude/LLM 代理配置持久化记忆的开发者
• 重视数据隐私、拒绝云端记忆服务的用户
• 处理大量项目文档、需要历史上下文追踪的知识工作者
• 对检索质量有分层需求（快速查找 vs 深度决策支持）的高级用户

常规风险

• 数据持久化风险：SQLite 单文件虽便捷，但需定期备份防止损坏丢失
• 模式误用风险：Focus Mode 用于简单查询会造成不必要延迟，Fast Mode 用于复杂决策可能遗漏关键关联
• 嵌入模型局限性：本地模型（likely all-MiniLM 级别）语义理解弱于 OpenAI 等 API 方案，专业术语/多语言场景存在漂移
• 版本兼容性：作为 OpenClaw 生态组件，与上游框架版本绑定需关注更新

Smart Memory v2.1 综合评估

核心用法

Smart Memory 是专为 AI Agent 设计的上下文感知记忆系统，作为 OpenClaw 记忆模块的即插即用替代品。其核心架构采用 SQLite 单文件数据库，结合 FTS5 关键词搜索（BM25） 与 语义向量搜索 的混合检索算法，实现 70% 向量相似度 + 30% 关键词匹配的加权评分。

系统提供两种检索模式：

• Fast 模式（默认）：直接向量相似度搜索，适用于快速事实查找、命令语法查询等场景，延迟极低
• Focus 模式：启用多轮智能精筛——先检索 20+ 候选片段，经加权重排序（向量分+词匹配+来源加权+时效加权），再聚合成连贯叙事输出，带置信度评分

技术亮点包括 100% 本地嵌入（Transformers.js，无需 API Key）、零配置开箱即用、可选 sqlite-vec 原生加速（10,000 chunks/秒 vs 纯 JS 100 chunks/秒）。

显著优点

1. 混合搜索质量：BM25 + 向量双引擎，既捕获语义关联又保证精确词匹配，解决纯向量搜索的"同义词遗漏"和纯关键词的"语义鸿沟"问题
2. Focus Agent 差异化：多轮 curation 流程（retrieve→rank→synthesize）显著提升复杂决策场景下的上下文质量，支持跨文件事实关联与选项对比
3. 部署极简性：单 SQLite 文件、无外部服务依赖、无网络调用，符合边缘计算和隐私敏感场景需求
4. 性能弹性：sqlite-vec 扩展下可达生产级向量库性能，降级方案仍保持功能完整
5. 透明可控：置信度评分、来源追溯、模式热切换，用户对检索过程有清晰认知

潜在局限

1. 规模边界：虽然声明"无限"存储，但纯 JS 回退模式下大库性能（~100 chunks/秒）可能限制实时交互体验；sqlite-vec 为可选依赖，非强制捆绑
2. Focus 模式开销：+50-100ms 延迟在复杂查询可接受，但高频简单查询不建议启用
3. 嵌入模型锁定：依赖 @xenova/transformers 特定版本，模型更新需手动跟进，无云端嵌入 API 的灵活选型
4. 安装脚本风险：curl|bash 安装方式存在供应链中间人攻击理论风险（虽已通过 GitHub 来源+完整性校验缓解）

适合人群

• 本地优先、隐私敏感型 AI Agent 开发者
• 需要记忆能力的 OpenClaw / MCP 工具链用户
• 复杂决策场景（项目复盘、方案对比、规划制定）的智能体构建者
• 边缘部署或无网络环境的专业用户

常规风险

• 供应链安全：建议优先采用 git clone 而非 curl|bash 安装，启用 package-lock.json 锁定依赖
• 输入注入：当前已实现 FTS5 查询转义，但建议生产环境追加查询长度限制与路径遍历检查
• 依赖维护：需持续跟踪 @xenova/transformers 安全更新

---

认证结论：安全报告（CLS-2026-0702-SM-7A3F）显示 S 级优秀评级，六维扫描（静态分析、动态行为、依赖审计、网络分析、隐私合规、威胁情报）全数通过，T2 可信来源认证。唯一低风险项为安装脚本的 curl 管道模式，已标记为可控风险。