smart-memory

Smart Memory v2.1 是一款专为AI代理设计的上下文感知记忆系统，采用SQLite单文件数据库作为后端，实现了零配置、完全本地化的记忆管理方案。该系统最大的特色在于其双模态检索架构：Fast Mode提供基于向量相似性的快速检索，适合简单事实查询；而Focus Mode则通过多阶段策展流程（检索→排序→综合→交付），为复杂决策和多事实合成场景提供结构化上下文。

核心用法方面，用户通过npx clawhub install完成安装后，首先运行--sync命令同步记忆文件，随后可通过CLI或JavaScript API进行搜索。系统创新性地融合了FTS5关键词搜索（BM25算法）与语义向量搜索，采用70%向量权重+30%关键词权重的混合评分机制，确保既能捕捉语义相关性，又能匹配精确词条。Focus Agent在启用时会执行20+片段的广泛检索，通过加权相关性排序和来源提升，最终合成连贯的叙述性上下文。

该系统的显著优势包括：100%本地运行（基于Transformers.js的嵌入计算，无需API密钥）、单文件SQLite存储便于备份与迁移、混合搜索算法兼顾速度与准确性、以及可在Fast与Focus模式间无缝切换的灵活性。对于注重数据隐私的用户而言，所有向量计算和存储均在本地完成，彻底消除了云端泄露风险。

然而，系统也存在一定局限性。首先，来源为T3级个人开发者（getmolty），缺乏组织级背书与长期维护保障。其次，虽然主打"零配置"，但若要获得最佳性能（~10,000 chunks/sec），需手动安装sqlite-vec扩展，该组件需从GitHub Releases下载，增加了部署复杂度。此外，纯本地化架构意味着无法实现多设备同步，限制了团队协作场景的应用。性能方面，在未安装sqlite-vec的情况下，大规模数据库的检索速度会降至约100 chunks/sec。

该技能最适合以下群体：需要为AI代理构建长期记忆能力的开发者、处理敏感数据且必须本地存储的企业用户、以及需要复杂上下文检索（如项目历史回溯、决策依据综合）的知识工作者。对于仅需简单关键词搜索或云端同步记忆的场景，该系统可能过于复杂。

使用风险主要包括：npm供应链风险（依赖Transformers.js等外部包）、可选组件sqlite-vec的下载来源可靠性、以及作为个人项目可能面临的长期维护不确定性。建议用户定期备份vector-memory.db文件，并在生产环境使用前对依赖项进行安全审计。

核心用法

Smart Memory 是面向 AI Agent 的上下文感知记忆系统，采用 SQLite 单文件存储，无需外部服务即可运行。核心操作包含三类：

记忆同步：--sync 将本地记忆文件（默认 ./memory/ 目录及 ./MEMORY.md）向量化并入库
检索模式：双模式切换——Fast Mode 直接向量相似性搜索（适合快速事实查询），Focus Mode 启用多轮策展流程（适合复杂决策与多信息整合）
工具调用：通过 memory_search/memory_get/memory_mode 三个函数与 Agent 集成，返回结构化 JSON 包含置信度评分与来源溯源

技术实现上，系统结合 FTS5 关键词搜索（BM25）与 Transformers.js 本地语义嵌入，混合评分权重为 70% 向量 + 30% 关键词。可选安装 sqlite-vec 扩展可将向量检索性能从约 100 chunks/sec 提升至 10,000 chunks/sec。

显著优点

1. 零配置开箱即用：无需 API Key、无需外部数据库、无需网络连接，依赖纯本地运行
2. 混合检索质量高：BM25 解决关键词精确匹配，向量搜索捕捉语义相似，召回率优于单一方案
3. Focus Agent 策展：独有的多阶段流程（Retrieve → Rank → Synthesize），将 20+ 原始片段整理为连贯叙事，显著降低大模型处理长上下文的认知负荷
4. 隐私原生设计：100% 本地计算，记忆数据不出境，符合 GDPR/CCPA 数据最小化原则
5. 灵活模式切换：用户或 Agent 可根据查询复杂度实时切换 Fast/Focus，平衡延迟与质量

潜在局限

• 性能天花板：无 sqlite-vec 时纯 JavaScript 实现，超大规模记忆库（十万级片段）检索延迟明显增加
• 策展开销：Focus Mode 额外增加 50-100ms 处理时间，高频实时场景不适用
• 嵌入质量依赖：Transformers.js 本地模型体积与精度有限，专业领域术语可能向量化效果不佳
• 维护者风险：项目为个人开发者/社区项目（T3），长期维护与功能迭代存在不确定性

适合人群

• 注重隐私、要求数据完全本地的个人开发者与小型团队
• 使用 OpenClaw 或其他兼容框架的 Agent 构建者，需替换或增强原生记忆能力
• 需要区分「快速查找」与「深度研究」两种记忆交互场景的产品设计
• 在无网络环境（如本地开发机、离线设备）运行 AI 工作流的技术用户

常规风险

| 风险类别 | 评估 | 说明 |

|---------|------|------|

| 代码执行风险 | 极低 | 纯 Markdown 文档，无可执行代码，静态分析 0 个真实威胁 |

| 数据外泄风险 | 极低 | 无网络传输行为，可选外部链接均为可信域名（GitHub、ClawHub） |

| 供应链风险 | 低 | 当前版本零外部依赖；未来若引入可执行代码需重新评估 |

| 功能依赖风险 | 中 | 项目依赖 OpenClaw 生态，若上游协议变更可能影响兼容性 |

使用建议：适合作为开发环境或个人知识库的记忆增强工具；生产环境大规模部署前建议评估 sqlite-vec 安装与硬件资源占用。