名称： smart-memory
描述： 为 AI 代理提供上下文感知记忆，具备双重检索模式——快速向量搜索或经过策划的 Focus Agent 合成。SQLite 后端，零配置，本地嵌入。

Smart Memory v2.1 - Focus Agent 版

OpenClaw 记忆系统的即插即用替代品，提供更优的搜索质量，并可通过 Focus Agent 实现可选的策划式检索。

特性

• 混合搜索：结合 FTS5 关键词搜索 (BM25) 与语义向量搜索
• Focus Agent：针对复杂查询进行多轮策划（检索 → 排序 → 合成）
• 双重模式：快速（直接）模式或 Focus（策划）模式——可随时切换
• SQLite 后端：单文件数据库，无需外部服务
• 100% 本地化：使用 Transformers.js 在本地运行嵌入（无需 API 密钥）
• 自动优化：在可用时使用 sqlite-vec 进行原生向量操作
• 零配置：安装后立即可用

安装

npx clawhub install smart-memory

或从 ClawHub 安装：https://clawhub.ai/BluePointDigital/smart-memory

快速开始

1. 同步记忆

node smart-memory/smart_memory.js --sync

2. 搜索（快速模式 - 默认）

node smart-memory/smart_memory.js --search "James values principles"

3. 启用 Focus 模式（策划式检索）

node smart-memory/smart_memory.js --focus
node smart-memory/smart_memory.js --search "complex decision about project direction"

4. 禁用 Focus 模式

node smart-memory/smart_memory.js --unfocus

搜索模式

快速模式（默认）

直接向量相似性搜索。适用于：
- 简单查询
- 快速事实检索
- 日常查询

node smart-memory/smart_memory.js --search "git remote"

Focus 模式（策划式）

通过 Focus Agent 进行多轮策划。适用于：
- 复杂决策
- 多事实合成
- 规划与策略
- 方案比较

node smart-memory/smart_memory.js --focus
node smart-memory/smart_memory.js --search "What did we decide about BluePointDigital architecture?"

Focus 模式工作原理：
1. 检索 20+ 个文本块（广泛撒网）
2. 排序 基于加权相关性（向量 + 术语匹配 + 来源权重）
3. 合成 为连贯的叙述
4. 交付 带有置信度分数的结构化上下文

工作原理

混合搜索算法

1. FTS5 查找精确的关键词匹配（BM25 排序）
2. 向量搜索 查找语义匹配（余弦相似度）
3. 合并结果 使用加权评分：
   • 70% 向量分数 + 30% 关键词分数
   • 同时捕捉“你的意图”和“精确词条”

Focus Agent 策划

启用后，搜索会经过额外处理：

查询："What did we decide about BluePointDigital?"

┌─────────────────┐
│  检索 20+ 个   │  ← 向量相似性
│    文本块      │
└────────┬────────┘
         ▼
┌─────────────────┐
│    加权排序     │  ← 术语匹配
│                 │    来源权重
│                 │    时效性权重
└────────┬────────┘
         ▼
┌─────────────────┐
│   选择 Top 5    │  ← 阈值过滤
└────────┬────────┘
         ▼
┌─────────────────┐
│    合成叙述     │  ← 按来源分组
│                 │    提取关键事实
└────────┬────────┘
         ▼
    附带置信度的结构化输出

工具

memory_search

memory_search({
    query: "deployment configuration",
    maxResults: 5
})

返回（快速模式）：

{
    "query": "deployment configuration",
    "mode": "fast",
    "results": [
        {
            "path": "MEMORY.md",
            "from": 42,
            "lines": 8,
            "score": 0.89,
            "snippet": "..."
        }
    ]
}

返回（Focus 模式）：

{
    "query": "deployment configuration",
    "mode": "focus",
    "confidence": 0.87,
    "sources": ["MEMORY.md", "memory/2026-02-05.md"],
    "synthesis": "关于 \"deployment configuration\" 的相关上下文：\n\n来自 MEMORY.md：\n  • Docker 设置使用 docker-compose...\n  • 生产部署在 AWS...\n\n来自 memory/2026-02-05.md：\n  • 决定改用 Railway...",
    "facts": [
        {
            "content": "Docker 设置使用 docker-compose...",
            "source": "MEMORY.md",
            "lines": "42-50",
            "confidence": 0.89
        }
    ]
}

memory_get

memory_get({
    path: "MEMORY.md",
    from: 42,
    lines: 10
})

memory_mode（Focus 切换）

memory_mode('focus')    // 启用策划式检索
memory_mode('fast')     // 禁用策划式检索
memory_mode()           // 获取当前模式状态

CLI 命令

# 同步记忆文件
node smart_memory.js --sync

# 搜索（使用当前模式）
node smart_memory.js --search "query" [--max-results N]

# 搜索并覆盖模式
node smart_memory.js --search "query" --focus
node smart_memory.js --search "query" --fast

# 切换模式
node smart_memory.js --focus      # 启用 Focus 模式
node smart_memory.js --unfocus    # 禁用 Focus 模式
node smart_memory.js --fast       # 同 --unfocus

# 检查状态
node smart_memory.js --status     # 数据库统计 + 当前模式
node smart_memory.js --mode       # 当前模式详情

# 仅使用 Focus Agent
node focus_agent.js --search "query"
node focus_agent.js --suggest "query"  # 检查是否推荐使用 Focus 模式

# 模式管理
node memory_mode.js focus
node memory_mode.js unfocus
node memory_mode.js status

性能

何时使用 Focus 模式

在以下情况使用 --focus 或启用 Focus 模式：
- 查询涉及多个相关概念
- 需要合成上下文，而非原始文本块
- 需要理解关系的决策制定
- 总结项目历史
- 比较不同文件中提到的方案

在以下情况不要使用 Focus 模式：
- 快速事实查找（电话号码、命令语法）
- 需要精确文本匹配
- 延迟比上下文质量更重要时

安装：sqlite-vec（可选）

为获得最佳性能，请安装 sqlite-vec：

# macOS
brew install sqlite-vec

# Ubuntu/Debian
# 从 https://github.com/asg017/sqlite-vec/releases 下载
# 将 vec0.so 放入 ~/.local/lib/ 或 /usr/local/lib/

未安装时：仍可正常工作，只是在大型数据库上速度较慢。

文件结构

smart-memory/
├── smart_memory.js      # 主 CLI
├── focus_agent.js       # 策划式检索引擎
├── memory_mode.js       # 模式切换命令
├── memory.js            # OpenClaw 包装器
├── db.js                # SQLite 层
├── search.js            # 混合搜索
├── chunker.js           # 基于令牌的分块
├── embed.js             # Transformers.js 嵌入
└── vector-memory.db     # SQLite 数据库（自动创建）

环境变量

MEMORY_DIR=/path/to/memory        # 默认：./memory
MEMORY_FILE=/path/to/MEMORY.md    # 默认：./MEMORY.md
MEMORY_DB_PATH=/path/to/db.sqlite # 默认：./vector-memory.db

版本对比：v1 vs v2 vs v2.1

许可证

MIT