内容
Vectr
> **为 AI 代码编辑器提供语义持久工作内存。**
[
[](LICENSE)
[
[](#14-mcp版本 1.0.0 · 最后更新 -07-08 · [更新日志](CHANGE)
Vectr 为 AI 代码编辑器提供了两样东西：**语义代码库搜索** 和 **持久工作内存** —— 两者都通过零配置提供。
你的 AI 编辑器会忘记一切r 不会。
问题
每次 AI器开始一个任务时，它都会重新读取昨天读取的相同文件。对于不熟悉的代码库，它会运行 ripgrep，读取整个文件以寻找正确的函数，并用噪音填满其上下文窗口。在长时间的会话中，它会在第 1 轮和第 40 轮之间丢失发现的结果。在不同会话之间，它从零Vectr 打破发现的循环： **一个索引** → 在 <20ms 内代码库进行语
- **一次调用** → 以 <50ms 的速度从任何先获取结构
- **存compact`** → 笔持久化到磁盘在上下文中
测量，而不是假设： `vectr` 检索 存储的笔记，成本360 个代币 182 文件的仓库中，使用 grep 重新导出事实，成本约为,060 个代币，跨越 6 次 —— **约 7 倍的代币，6 倍的工具调用**，在 50ms 内（字符/4 标记化；完整分解见 [测量成本，诚measured-costs-h)）。在 任务的 CP冲刺中，的 Read+Bash召回规则减少39% 的整体重新发现，范围从 **0%** 不取决于模型对代码（0%是模型已经可以从训练中导航的任务 - 参见 [当 vectr 受损](#when-vectr-can-hurt)）。
笔记被持久化到磁盘，而不是保存在会话中 —— 它们在上同样存`/compact` 和新的会话。
**不需要 API 密钥。** 本地运行。
基准 - CPython 内部冲刺（6 个任务，2 个代理）
基准模拟了在不熟悉的 C 代码库（CPython 内部）上进行一周的功能工作。一个研究会话使用 `vectr_remember` 存储发现结果；六个独立的实现会话各自开启冷启动并调用 `vectr_recall`。
**仅实施会话 - 6 个任务合并：**
| 指标 | 原始 | Vectr | 增量 |
|---|---|---|---|
| 成本 | $2.50 | $1.97 | **-21%** |
| 墙上时间 | 17.6 分钟 | 13.5 分钟 | **-24%** |
| 回合 | 123 | 94 | **-24%** |
| 读取 + Bash 调用 | 102 | 62 | **-39%** |
**每个任务的重新发现（读取+Bash 在首次写入之前）：**
| 任务 | 原始 | Vectr | 增量 |
|---|---|---|---|
| `debug_gc_finalizer` | 16 | 6 | -62% |
| `feature_dict_pop_last` | 13 | 3 | -77% |
| `cross_session_set_cartesian` | 23 | 9 | -61% |
| `debug_descriptor_priority` | 6 | 0% |
| `cross_session_bytes_find_all` | 13 | 2 | -85% |
| `cross_session_list_rotate` | 21 | 16 | -24% |
**研究与实施成本分解：
研究阶段（一次性支付以建立笔记）vectr 成本更高（+94%），因为它通过 `vectr_remember` 存储了丰富的代码存根和函数签名。实施阶段（每个任务重复）成本 `vectr_recall` 替换了文件。研究开销在约 8 个任务的重用笔记后收支平衡。
| 阶段 | 原始 | Vectr | 原因 |
|---|---|---|---|
|1 次会话） |.36 |63 | Vect笔记 - 更多 |
| 实现 次会话，重复） | $2.50 | $1.97 | 笔记替换重新发现 |
| 总冲刺 | $3.86 | $4.60 | 逆转为净收益，约 后 |
早期 Camel（Java856 个文件运行：**-58% 实现成本 ·% 实现工具调用39% 墙上时间。**
完整[`benchmarks/`](benchmarks/)
---
## 测量成本
每次调用代币成本（中位数 Python 仓库，4 标记
| 工具 |代币 | 范围---|---:|---|
| `vectr_search`2,320 |,437–3 (n=8| `vectr` | ~192 | — |
| `vectr | ~720 || `vectr` （索引层） | ~180 | —，坦率地说：对于小型、已经仓库上的单个有指向的查找，grep 更便宜 — vectr 在 5事实任务上的中为 **+60代币** — 更 `vectr_search往返需要 7–3.6 秒，而 grep 约为 ~28 毫秒。Vectr 在每次调用的成本上不占优势；它在工具调用次数（一次往返而不是多次）、答案完整性（整个符号返回，而不是部分文件读取）和工作内存中的所有内容上占优势 —— 开头部分的 5.7 倍退款随着您每个任务而累积。
附带条件：自动驱逐/幅随工具骑行也会 - 始终重新获取页脚 27 代币，轻微提示约 ，升级的操作幅（仅在代币阈值保存的情况下交叉时约 480 到约 535 代币缩放，然后趋于平稳。
**何时生效：** 不大型代码库执行的工作（在中，在 `/compact`或在新），以及具有许多回合的长时间会话。**不生效：**完全了解的代码的一 — 直接使用吧。
---
##
**本地（推荐）**
```bash.14 - ~/.vectr-envvectr-envactivate # Windowsr-env/Scripts/activate
pip install gitgithub.comnanil/vect /path/to/project
vectr**需要 Python14+。：
- macOS：`brew install python@3.14`
- Ubuntu/Debian：`sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.14 python3.14-venv`
-[python.org/downloads](https://www.python.org`vectr start` 立即返回。索引在后台运行 — 运行 `vectr status` 以检查进度。在第一次运行时，嵌入模型会下载一次（约 440 MB）。重新启动您的 AI 代码编辑器一次，以获取新的 MCP 配置。
**Docker（CI/服务器）**
```bash
git clone https://github.comnanil/vectr
cd vectr
docker-compose up api
```
8765。会自动写入 IDE 配置文件 — 使用本地安装进行集成。
---
## 连接 AI 代码编辑`vectr start自动为您编辑器编写 MCP 配置。重新器一次。
| 编辑 配置 | 状态---|
| Claude 自动 — `.claude`，指南会话钩子（内存在会话开始时自动注入，每个提示和文件读取/编辑之前） | **** |
| Cursor | 自动 — `.cursor.json` | | VS CodeHub Copilot | 自动 — `.vscode/mcp.json` | 实验性 |
| Windsurf | 手动 — 见下文 | 实验性 |
| Cline | 手动 — 见下文 | 实验性 |
| Continue | 手动 — 见下文 | 实验性 |
| Codex CLI | — | 计划中（v1 后） |
"已 表示已端地验证了完整的集成（配置、子）。"" 表示编写并尚未经过相同的。"计划中"不支持。
<detailssummary>手动设置</summaryClaude — `.claude`：
```json
{ "mcpServers "vectr": { "type": " "url": "localhost:8765" } } }
** — `.cursor/mcp.json`：
{ "mcpServers": { "vectr": { "url": "http://localhost:8765/mcp" } }**VS CodeHub Copilot.99+vscode/m`：
```json "servers": { "vectr": { "type": "http", "http://8765/mcp } }
```
indsurf** —codeium/windsurf/mcp_settings.json`：
```json
{cpServers":vectr": {Url": "http:8765/m } } }
```
**Continue.dev** —/config.json`：
{ "mcpServers": [{ "namevectr",": { "type": "http", "urlhttp://localhost:8765/mcp" }```
</details## 工作原理
1. **AST 感知** — tree-s每个文件，并在函数/类/方法边界分。逻辑中。
2. **代码嵌入** —anite/-embedding-english （本地，，可覆盖）查询映射到（“JWT 验证 `verify_jwt）。BM25 处理的符号名称。
3. **混合搜索 矢量相似 BM25 组合，根据代码库特征加大型熟悉语义重；文档齐全25 重）。
4符号图** —，导入链和 HTTP 路由（Flask/FastAPI/Express/Spring）被提取和存储。`vectr` 使用 5退策略：精确 后缀 → 同模块 → 唯一名称 → 导入链 → 模糊（编辑距离 ≤ 2）。
5. **工作内存** — `vectr_remember` 将结构化笔记存储到 SQLite + ChromaDB。`vectr_recall` 对笔记进行语义搜索 — 不是 SQL LIKE — 因此多词查询始终能找到相关上下文。
6. **MCP 协议** — 14 种工具通过 HTTP 提供任何与 MCP 兼容的 AI 代码编辑器都无需插件即可连接。
---
## 14 个 MCP 工具
`vectr start` 在您的 workspace 中写入一个 `CLAUDE.md`，包含此表格和用法指南 — 代码编辑器知道在不需要提示的情况下调用。
**搜索 — 从索引中
| | 工具 |
---|
| 您知道或行为，而不是名称 | `vectr_search")` |
|一个符号名称文件 | `ocate("SymbolName")` — 退策略，可caller_file` |
| 您需要一个符号者/被调用 `vectr_trace("symbol_name")` 您需要一个架构 | `vect()` |
| 您综合的地图摘要 | `vectr_map_save(summary)` |
| 您有运行时调用数据 | `vectr_ingest_traces([{ callee}])` |
| 您需要/笔记数量 | `vectr_status()`内存工具** —会话存储和
| 情况 | 工具 |
|---|---|
| 来自先前会话的笔记存在 |r_recall(query)` — 语义，而不是子字符串匹配；两层（默认情况下具有清晰索引，展开一个带有 `note_id=N` 的笔记或detail='full'` 的所有正文） |
| 您发现了值得保留的东西 | `vectr_remember(content, tags, priority, kind, title)` — `kind` 控制注入：`directive` 无条件每次会话触发，`task` 携带当前工作状态，`gotcha` 在其文件被触摸时重新出现，` （默认）是相关性排名的，`reference` 是一个指针；`title` 在索引输出中标记笔记；`agent` 将其归因于一个子代理/编排器 |
| 上下文正在填满 | `vectr_evict_hint()` — 确定 vectr 可以重新检索的带有确切的重新获取 ID |
| 较早显示的块已离开您的上下文 | `vectr_fetch(ids=[...])` — 确定性，按 ID 原样重新获取；不搜索，不重新读取文件；如果索引本身存储了上限块，则会发出截断警告 |
| 长期会话结束，希望进行检查点 | `vectr_snapshot("label")` |
| 查找先点 | `_snapshot_list()` |
| 在大型重构后笔记已过时 | `vectr_forget(note_id=N)` 每个笔记，或 `vectr_forget(all=true)` 清除所有笔记 |
工作区范围的笔记同时作为多代理工作流的共享总线：编排器及其子代理都读取和写入相同的笔记存储，因此子代理可以在完成之前使用 `vectr_remember(..., agent="coder-2")` 调用其发现结果，然后编排器会回忆它们，而不是重新读取子代理的整个转录。`agent` 参数从不被推断 —式属性 `vectr_re 索引标记出现。
在具有会话钩子的编辑器上（请参阅矩阵](#-your-ai-code-editor了解哪些编辑器），回忆会自动注入 — 指令和高优先级任务在会话开始时，语义回忆由每个提示键入，文件锚定难题在读取或编辑文件之前 — 并通过 `vectr status`Hook injections`可观察性。
CLI 参考
```bash
vectr start 为当前目录 + 守护进程
vectr start / # 位置工作区：目录或-workspace 文件r start --path/api #工作区（，多根）
vectr start --memory-only仅工作内存钩子 -索引，无监视器
vectr status 索引块计数，笔记计数
vectr status # 所有正在实例
vectr stop /project/api # 停止一个实例（与启动相同的位置）
vectr stop --path /project/api # 停止一个实例（等效 --path 形式）
vectr stop --all # 停止所有实例
vectr index --path . # 在不重新启动守护进程的情况下重新索引
vectr fetch src/auth.py:10-42 # 通过确切 ID 原样重新获取块
vectr init --path . # 编写 CLAUDE.md + MCP 配置而不启动
vectr init --exclude vendor # 从索引中排除目录
vectr forget --path . # 删除所有工作内存笔记
```
---
## 排除路径
在项目根目录中创建 `.vectrignore`（与 `.gitignore` 语法相同）：
```
vendor/
node_modules/
*.pb.go
dist/
```
或在初始化时传递 `--exclude`：
```bash
vectr init --exclude vendor --exclude dist
```
排除项同时适用于初始索引遍历 **和** 活动文件监视器，因此将目录添加到 `.vectrignore`正在运行的实例重新索引它。下一次索引还会 **修剪** 已存储的块以获取现在被排除（或删除）的文件 — 您不必从头开始重建。如果您曾经需要完全重建（例如，在更改嵌入模型后），请强制执行：
```bash
vectr index --path . --force # 忽略增量缓存，重新嵌入所有内容
```
---
## 支持的语言
| 语言 | 分块 | 符号图 |
|---|---|---|
| Python | AST（函数，类） | ✓ |
| JavaScript | AST（函数，类，箭头函数） | ✓ |
| TypeScript | AST | ✓ |
| Go | AST | ✓ |
| Rust | AST | ✓ |
| Java | AST | ✓ |
| C | AST | ✓ |
| C++ | AST | ✓ |
| Zig | AST | ✓ |
| 其他语言 | 200 行窗口，50 行重叠 | — |
HTTP 路由（Flask/FastAPI 装饰器，Express `app.get()`，Spring `@GetMapping`）被提取为符号，可以通过 `vectr_locate("GET /api/users")` 进行搜索。
---
## 成本
| | 成本 |
|---|---|
| 嵌入模型 | $0.00 — 一次 ~440 MB 下载，缓存在 `~/.cache/v/` |
| 重新索引（10，） | CPU 分钟；后续运行 <（修改时间缓存） |
|更改的文件的增量重新索引 0.5 秒 |
| vectr_search / vectr_recall | $0.00 — 仅本地---
## 安全
Vectr v用于 **个人机器上的独立开发。
- MCP 服务器仅绑定127.0.0.1 不可从其他主机访问
- CORS 限制为 localhost 源
- 每个工作区都有自己的隔离 DB 目录，端口和进程
- v1 API 密钥身份验证 — 任何本地进程都可以查询
- 索笔记在 `~/.cache/v/` 中本地持久化
多用户，身份验证和静止加密超出了 v1 的范围。
---
## 当 vectr 受损时
**代码库更改后的过时笔记** — 笔记在写入时存储文件路径。在大规模重构后，`vectr_recall` 将用 `[STALE]` 标记已更改的引用文件。请在执行前重新验证，删除过时笔记 `vectr_forget(note_id=N)`，或使用 `vectr_forget(all=true)` 清除所有笔记。
**在熟悉的 API 上过度检索** — 如果模型已经通过训练从框架中深入了解（React 钩子，Django ORM），vectr 的研究开销可能会超过节省。基准测试显示 `debug_descriptor_priority` 任务的改进为 0% — 该任务中模型的训练知识足以在无需笔记的情况下导航。
---
## 构建
Python 3.14 · FastAPI · sentence-transformers · tree-sitter · ChromaDB · BM25 · Docker
## 作者
Swapnanil Saha · [swapnanilsaha.com](https://swapnanilsaha.com)
