Vector Memory Hack

核心用法

Vector Memory Hack 是一款专为AI代理设计的轻量级语义搜索工具，解决传统代理读取完整MEMORY.md文件造成的token浪费问题。核心流程包括：使用--rebuild构建TF-IDF向量索引，通过--search执行余弦相似度查询，返回top-k相关段落及相似度分数。支持增量更新(--update)和统计查询(--stats)，配套CLI包装器vsearch便于集成。

显著优点

• 极致轻量：纯Python标准库+SQLite，零外部依赖，无PyTorch/Transformers负担
• 极速响应：<10ms搜索1000个向量段落，索引速度约50段/秒
• 多语言支持：内置CZ/EN/DE等多语种分词与停用词处理
• token效率：从读取3000+tokens降至仅需3-5个相关段落
• 资源友好：每段约10KB内存，适合边缘设备/VPS低内存环境

潜在局限

• 精度天花板：TF-IDF基于词频统计，无法理解深层语义（vs神经网络嵌入）
• 词汇盲区：未登录词/同义词/缩写匹配能力有限
• 规模瓶颈：文档量达万级时性能劣于专业向量数据库（ChromaDB/Milvus）
• 无动态学习：无法根据用户反馈优化排序，需手动调整停用词或相似度算法

适合人群

• 快速原型开发者：需分钟级部署语义搜索
• 资源受限场景：无GPU、低RAM的VPS/边缘设备
• token敏感型AI代理：希望大幅降低上下文读取成本
• 多语言轻量应用：需支持中欧德等语种的简单语义检索

常规风险

| 风险类型 | 说明 | 缓解建议 |

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

| 索引陈旧 | 源文件更新后未重建索引导致检索失效 | 任务前自动执行`--update`或`--rebuild` |

| 数据库锁 | 并发访问SQLite产生锁定错误 | 串行化访问或删除vectors.db重建 |

| 零分结果 | 词汇表未覆盖查询词或索引损坏 | 检查分词逻辑，定期重建索引 |

| 安全边界 | 检索结果可能包含敏感配置（如SSH密钥路径） | 对MEMORY.md实施访问控制，搜索结果过滤敏感字段 |

核心用法

Vector Memory Hack 是一款专为 AI Agent 设计的超轻量级语义搜索解决方案，用于快速检索 MEMORY.md 等文档中的相关上下文。用户通过 python3 scripts/vector_search.py --rebuild 构建索引，随后使用 vsearch "查询语句" 或 --search 参数进行检索，系统返回 Top-K 最相关的章节及其余弦相似度得分。

显著优点

• 零依赖架构：仅使用 Python 标准库（sqlite3、json、hashlib、re、math），从根本上消除供应链攻击风险
• 极致性能：<10ms 搜索延迟，索引速度约 50 章节/秒，内存占用仅 ~10KB/章节
• Token 高效：替代读取 3000+ tokens 的完整文件，只需读取 3-5 个相关章节
• 多语言支持：内置多语言分词器，支持 CZ/EN/DE 等多种语言
• 离线运行：无需网络连接、API 密钥或 GPU 资源

潜在局限

• 语义精度受限：TF-IDF 基于词频统计，无法理解深层语义关系，准确率低于神经网络嵌入模型
• 规模瓶颈：适合数百至数千章节场景，万级文档以上建议升级至 ChromaDB 等专业方案
• 无实时学习：需手动触发 --update 或 --rebuild 更新索引
• 调优门槛：停用词、分词规则需手动修改源码适配特定领域

适合人群

• 资源受限环境（VPS、边缘设备、无 GPU 服务器）
• 需要快速原型验证的开发者
• 对数据隐私敏感、拒绝外部 API 调用的场景
• 中小型 Agent 项目，记忆文件规模可控（<1000 章节）

常规风险

• 路径配置风险：默认路径依赖 OpenClaw 目录结构，自定义配置时需确保路径有效
• 索引过期：记忆文件更新后若未重建索引，搜索结果可能不准确
• 相似度得分解读：TF-IDF 得分绝对值较低（如 0.2-0.3），需依赖相对排序而非阈值判断