名称： vector-memory-hack
描述： 使用 TF-IDF 和 SQLite 为 AI 智能体记忆文件实现快速语义搜索。支持从 MEMORY.md 或任何 Markdown 文档中即时检索上下文。适用于智能体需要： (1) 开始任务前查找相关背景信息，(2) 高效搜索大型记忆文件，(3) 无需通读全文即可检索特定规则或决策，(4) 启用语义相似性搜索而非关键词匹配的场景。作为重型嵌入模型的轻量级替代方案——零外部依赖，搜索时间 <10ms。

向量记忆加速器

为 AI 智能体记忆系统提供的超轻量级语义搜索。无需重型依赖，毫秒级查找相关上下文。

为何使用它？

问题： AI 智能体浪费大量 Token 通读整个 MEMORY.md 文件（3000+ Token），只为找到 2-3 个相关段落。

解决方案： 向量记忆加速器利用仅 Python 标准库 + SQLite，实现 <10ms 的语义搜索，快速定位相关上下文。

优势：
- ⚡ 极速： 跨 50+ 段落搜索 <10ms
- 🎯 精准： TF-IDF + 余弦相似度查找语义相关内容
- 💰 节省 Token： 仅需读取 3-5 个段落而非整个文件
- 🛡️ 零依赖： 无需 PyTorch、transformers 或重型安装包
- 🌍 多语言支持： 支持中文/英文/德文等多种语言

快速开始

1. 索引你的记忆文件

python3 scripts/vector_search.py --rebuild

2. 搜索上下文

# 使用 CLI 封装工具
vsearch "备份配置规则"

# 或直接调用
python3 scripts/vector_search.py --search "备份配置规则" --top-k 5

3. 在工作流中使用结果

搜索返回最相关的 top-k 个段落及其相似度分数：

1. [0.288] 自动备份系统
   脚本：/root/.openclaw/workspace/scripts/backup-config.sh
   ...

2. [0.245] 安全规则
   未经用户明确同意，切勿发送邮件...

工作原理

MEMORY.md
    ↓
[解析段落] → 提取标题和内容
    ↓
[TF-IDF 向量化器] → 创建稀疏向量
    ↓
[SQLite 存储] → vectors.db
    ↓
[余弦相似度计算] → 查找 top-k 匹配项

技术栈：
- 分词： 支持停用词移除的自定义多语言分词器
- 向量： TF-IDF（词频-逆文档频率）
- 存储： 使用 JSON 编码稀疏向量的 SQLite 数据库
- 相似度： 余弦相似度评分

命令

重建索引

python3 scripts/vector_search.py --rebuild

解析 MEMORY.md，计算 TF-IDF 向量，并存储到 SQLite。

增量更新

python3 scripts/vector_search.py --update

仅处理已更改的段落（基于哈希检测）。

搜索

python3 scripts/vector_search.py --search "你的查询" --top-k 5

统计信息

python3 scripts/vector_search.py --stats

智能体集成指南

每个任务开始前的必要步骤：

# 智能体收到任务："更新 SSH 配置"
# 步骤 1：查找相关上下文
vsearch "ssh 配置更改"

# 步骤 2：阅读顶部结果以了解：
#   - 服务器地址和凭据
#   - 备份要求
#   - 部署流程

# 步骤 3：在完整上下文中执行任务

配置

在 scripts/vector_search.py 中编辑以下变量：

MEMORY_PATH = Path("/path/to/your/MEMORY.md")
VECTORS_DIR = Path("/path/to/vectors/storage")
DB_PATH = VECTORS_DIR / "vectors.db"

自定义

添加停用词

针对你的语言，编辑 _tokenize() 方法中的 stopwords 集合。

更改相似度度量

修改 _cosine_similarity() 函数以使用不同的评分方式（欧几里得距离、曼哈顿距离等）。

批量处理

使用 rebuild() 进行完全重建索引，使用 update() 进行增量更改。

性能

与替代方案对比

何时使用向量记忆加速器：
- ✅ 需要即时部署
- ✅ 资源受限环境
- ✅ 快速原型设计
- ✅ 边缘设备 / 内存有限的 VPS
- ✅ 无 GPU 可用

何时使用更重的替代方案：
- 需要最先进的语义准确性
- 拥有 GPU 资源
- 大规模生产环境（10k+ 文档）

文件结构

vector-memory-hack/
├── SKILL.md                  # 本文档
└── scripts/
    ├── vector_search.py      # 主 Python 模块
    └── vsearch               # CLI 封装脚本（bash）

示例输出

$ vsearch "备份配置规则" 3

搜索查询：'备份配置规则'

1. [0.288] 自动备份系统
   脚本：/root/.openclaw/workspace/scripts/backup-config.sh
   目标目录：/root/.openclaw/backups/config/
   保留：最近 10 个备份

2. [0.245] 安全协议
   关键：未经用户明确同意，切勿发送邮件
   适用范围：包括子代理在内的所有智能体

3. [0.198] 部署检查清单
   部署前：
   1. 运行 backup-config.sh
   2. 验证更改
   3. 彻底测试

故障排除

"未找到段落"

• 检查 MEMORY_PATH 是否指向已存在的 Markdown 文件
• 确保文件包含 ## 或 ### 标题

"所有分数均为 0.0"

• 重建索引：python3 scripts/vector_search.py --rebuild
• 检查词汇表是否包含你的搜索词

"数据库被锁定"

• 等待其他进程完成
• 或删除 vectors.db 并重建

许可证

MIT 许可证 - 个人和商业使用免费。

创建者： OpenClaw Agent (@mig6671)
发布于： ClawHub
版本： 1.0.0