vector-memory-hack

核心用法

Vector Memory Hack 是一款专为 AI Agent 设计的轻量级语义搜索技能，解决 Agent 读取大型 MEMORY.md 文件时的 Token 浪费问题。用户通过 python3 scripts/vector_search.py --rebuild 构建索引，随后使用 vsearch "查询词" 或 --search 参数执行检索，系统返回 Top-K 最相关的文档片段及相似度分数。该技能支持增量更新（--update）、统计查询（--stats），并可集成到 Agent 工作流中作为任务前置步骤，确保 Agent 在执行任务前获取精准上下文。

显著优点

极致轻量：零外部依赖，仅使用 Python 标准库（os、sqlite3、json、re、math），无需 PyTorch 或 Transformers，部署即开即用。极速响应：<10ms 搜索延迟，索引速度约 50 sections/秒，内存占用仅 ~10KB/section。Token 高效：从读取 3000+ Token 的完整文件缩减至 3-5 个相关片段，降低 90% 以上 Token 消耗。多语言支持：内置 CZ/EN/DE 等多语言分词与停用词处理。边缘友好：适用于 VPS、边缘设备等资源受限场景，无 GPU 需求。

潜在缺点与局限性

精度天花板：TF-IDF 基于词频统计，无法捕捉深层语义关系，复杂查询的准确性显著低于 sentence-transformers 或 OpenAI Embeddings 等嵌入方案。规模限制：设计目标为 1000 级文档片段，超大规模场景（10k+ 文档）性能与存储效率不及 ChromaDB 等专业向量数据库。无实时同步：依赖手动或定时触发 rebuild/update，非实时索引。定制门槛：停用词、相似度算法等需直接修改源码，缺乏配置化接口。

适合的目标群体

• 资源受限的 AI Agent 开发者：需在低配置 VPS、边缘设备或离线环境部署语义搜索
• 快速原型验证团队：追求分钟级部署，不愿等待重型依赖安装
• Token 成本敏感用户：高频调用场景下需严格控制上下文长度
• 多语言文档处理者：需支持中欧德等多语种的轻量检索方案

使用风险

数据一致性风险：增量更新依赖哈希检测，极端情况下可能遗漏变更；建议定期全量重建索引。并发访问限制：SQLite 在并发写入时可能触发 "Database locked" 错误，多 Agent 共享场景需加锁机制。路径配置风险：MEMORY_PATH 与 VECTORS_DIR 为硬编码配置，误配可能导致索引失败或数据散落。精度预期管理：用户若误将其与神经网络嵌入方案等同，可能对搜索结果相关性产生误判。