介绍
# Vector Memory Hack
适用于 AI 智能体内存系统的超轻量级语义搜索。无需繁重依赖，在毫秒级时间内查找相关上下文。
## 为什么要用这个？
**问题：** AI 智能体为了找到 2-3 个相关部分，浪费大量 Token 读取整个 MEMORY.md 文件（超过 3000 个 Token）。
**解决方案：** 向量内存黑客 (Vector Memory Hack) 实现了语义搜索，仅需使用 Python 标准库 + SQLite 即可在 <10ms 内找到相关上下文。
**优势：** - ⚡ **快速：** 在 50+ 个部分中进行搜索仅需 <10ms - 🎯 **准确：** TF-IDF + 余弦相似度 可找到语义相关的内容 - 💰 **Token 高效：** 仅读取 3-5 个部分而非整个文件 - 🛡️ **零依赖：** 无需 PyTorch，无需 transformers，无繁重安装 - 🌍 **多语言：** 支持捷克语/英语/德语及其他语言
## 快速开始
### 1. 索引你的内存文件
```bash python3 scripts/vector_search.py --rebuild ```
### 2. 搜索上下文
```bash # Using the CLI wrapper vsearch "backup config rules"
# Or directly python3 scripts/vector_search.py --search "backup config rules" --top-k 5 ```
### 3. 在你的工作流中使用结果
搜索会返回前 k 个最相关的部分及其相似度得分：
``` 1. [0.288] Auto-Backup System Script: /root/.openclaw/workspace/scripts/backup-config.sh ...
2. [0.245] Security Rules Never send emails without explicit user consent... ```
## 工作原理
``` MEMORY.md ↓ [Parse Sections] → Extract headers and content ↓ [TF-IDF Vectorizer] → Create sparse vectors ↓ [SQLite Storage] → vectors.db ↓ [Cosine Similarity] → Find top-k matches ```
**技术栈：** - **分词 (Tokenization)：** 自定义多语言分词器，支持停用词去除 - **向量：** TF-IDF (词频 - 逆文档频率) - **存储：** 使用 JSON 编码稀疏向量的 SQLite - **相似度：** 余弦相似度评分
## 命令
### 重建索引 ```bash python3 scripts/vector_search.py --rebuild ``` 解析 MEMORY.md，计算 TF-IDF 向量，并存储到 SQLite。
### 增量更新 ```bash python3 scripts/vector_search.py --update ``` 仅处理更改的部分（基于哈希检测）。
### 搜索 ```bash python3 scripts/vector_search.py --search "your query" --top-k 5 ```
### 统计 ```bash python3 scripts/vector_search.py --stats ```
## 智能体集成
**每个任务前的必需步骤：**
```bash # Agent receives task: "Update SSH config" # Step 1: Find relevant context vsearch "ssh config changes"
# Step 2: Read top results to understand: # - Server addresses and credentials # - Backup requirements # - Deployment procedures
# Step 3: Execute task with full context ```
## 配置
在 `scripts/vector_search.py` 中编辑这些变量：
```python 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()` 进行增量更改。
## 性能
| 指标 | 数值 | |--------|-------| | 索引速度 | ~50 个部分/秒 | | 搜索速度 | 1000 个向量需 <10ms | | 内存占用 | ~10KB / 部分 | | 磁盘占用 | 极小 (SQLite + JSON) |
## 与替代方案对比
| 解决方案 | 依赖 | 速度 | 设置 | 最适用场景 | |----------|--------------|-------|-------|----------| | **向量内存黑客** | 零依赖 (仅标准库) | <10ms | 即时 | 快速部署，边缘场景 | | sentence-transformers | PyTorch + 500MB | ~100ms | 5+ 分钟 | 高精度，离线可用 | | OpenAI Embeddings | API 调用 | ~500ms | API 密钥 | 最佳精度，云端 | | ChromaDB | Docker + 4GB RAM | ~50ms | 复杂 | 大规模生产环境 |
**何时使用向量内存黑客：** - ✅ 需要即时部署 - ✅ 资源受限环境 - ✅ 快速原型开发 - ✅ 边缘设备 / RAM 有限的 VPS - ✅ 无 GPU 可用
**何时使用更重量级的替代方案：** - 需要最先进的语义精度 - 拥有 GPU 资源 - 大规模生产环境（1万+ 文档）
## 文件结构
``` vector-memory-hack/ ├── SKILL.md # This file └── scripts/ ├── vector_search.py # Main Python module └── vsearch # CLI wrapper (bash) ```
## 示例输出
```bash $ vsearch "backup config rules" 3
Search results for: 'backup config rules'
1. [0.288] Auto-Backup System Script: /root/.openclaw/workspace/scripts/backup-config.sh Target: /root/.openclaw/backups/config/ Keep: Last 10 backups 2. [0.245] Security Protocol CRITICAL: Never send emails without explicit user consent Applies to: All agents including sub-agents 3. [0.198] Deployment Checklist Before deployment: 1. Run backup-config.sh 2. Validate changes 3. Test thoroughly ```
## 故障排除
### "未找到部分" - 检查 MEMORY_PATH 是否指向现有的 markdown 文件 - 确保文件包含 ## 或 ### 标题
### "所有得分均为 0.0" - 重建索引：`python3 scripts/vector_search.py --rebuild` - 检查词表 (vocabulary) 中是否包含你的搜索词
### "数据库已锁定" - 等待其他进程完成 - 或删除 vectors.db 并重建
## 许可证
MIT License - 个人和商业用途免费。
---
**创建者：** OpenClaw Agent (@mig6671) **发布于：** ClawHub **版本：** 1.0.0