Vectr

Vectr

交付，而非存储。 一个本地守护进程，为 AI 代码编辑器提供代码库语义搜索，以及能在相关时自动呈现的工作记忆。

版本 1.12.0 · 上次更新于 2026-09-03 · 更新日志

30 秒了解

你的 AI 代码编辑器会为相同的知识付费两次。它会重新读取昨天读过的文件，重新 grep 已经找到的符号，并且在对话被压缩时丢失第 5 轮发现的确切签名。Vectr 是一个本地进程，可同时解决这两部分问题：

• 理解代码的检索。 支持 AST 的代码块、符号和调用图，以及结合语义与 BM25 的混合排序。描述某种行为，一次调用即可获取完整函数，无需反复 grep 和盲目读取三个文件。
• 主动交付的工作记忆。 只需保存一次发现。它会在 50 毫秒内原样返回；对于提供会话钩子的编辑器，它会在内容适用时自动呈现，无需 Agent 主动询问。
• 本地运行、无需密钥、零配置。 只需一次 pip install，再执行一次 vectr start。嵌入模型在你的机器上运行。不会向任何地方传输数据，也不需要 API 密钥。

pip install vectr && cd /path/to/your/project && vectr start

这就是全部设置过程。Vectr 会为你的编辑器写入 MCP 配置，然后在后台建立索引。

vectr 与其他 AI Agent 记忆工具的区别

AI Agent 的通用记忆层是一个成熟的类别，其中优秀的工具能很好地解决实际问题。Vectr 最常被拿来与这类工具比较，因此我们在这里直截了当地说明区别。左列描述的是这类工具通常共有的设计，而非某一款产品；各工具有所不同，请查看你正在考虑的那款工具。

为什么第一行最重要。 存储不是瓶颈。真正的问题在于检索需要 Agent 主动调用，而它基本不会调用。在我们的受控评估中，即使存储中预先放入了与任务直接相关的知识，Agent 在 114 轮中也执行了 0 次记忆操作。在每次配备注入机制的运行中，确定性注入都成功送达；审计日志记录的触发条件评估中，误报触发次数为零。在反复压缩的情况下，仅保留在对话中的 10 条事实，在 108 次强制压缩中的 106 次未能保留；而同样的 10 条事实从运行框架管理的存储中注入后，在 138 次紧凑恢复中全部完整送达。

完整方法与结果：Delivery, Not Storage: Cue-Anchored Working Memory as a Harness Property for Coding Agents（arXiv:2607.20972）。

成本与节省

这是实测数据，而非假设。 使用 vectr_recall 在一次工具调用中回忆 3 条已存储的笔记，耗费 360 个 token。在同一个包含 182 个文件的 Python 仓库中，用 grep 加 Read 重新推导相同的 3 条事实，则需要约 2,060 个 token 和 6 次工具调用。这意味着 token 用量约减少 5.7 倍，工具调用次数减少 6 倍，耗时不到 50 毫秒（按字符数除以 4 估算 token 数，完整明细见实测成本，坦诚公开）。

笔记持久化到磁盘，而非保存在对话中，因此无论经过 /compact 还是开启全新会话，都能继续使用。会话边界并不重要：第 5 轮保存、第 15 轮回忆，与 3 天后回忆使用的是同一套机制。

适用场景： 不熟悉或规模较大的代码库、需要恢复的工作，以及轮数较多的长会话。
不适用场景： 对你已经非常熟悉的代码进行一次性 grep。此时请改用 grep，并参阅 vectr 何时会适得其反。

基准测试

公开结果位于 benchmarks/。以下语料之所以选用，是因为它们规模大，而且模型不熟悉，仅此而已。

在大型且陌生的 C 代码库上完成六项任务的冲刺，模拟一周的功能开发工作。一次研究会话使用 vectr_remember 保存发现。六个相互隔离的实现会话均从冷启动开始，并调用 vectr_recall。

仅实现会话，合计 6 项任务：

每项任务的重新探索（首次写入前的 Read 和 Bash 调用）：

0% 这一行是真实结果，并且是有意保留的：模型仅凭训练知识就已经能处理该任务。

如实说明研究与实现的区别。 研究阶段只付费一次，使用 vectr 的成本更高（+94%），因为保存丰富的代码桩和签名会产生输出 token。实现阶段会对每项任务重复进行，成本更低，因为调用记忆取代了重新探索。大约复用 8 项任务的笔记后，额外开销即可打平。

此前在一个包含 5,856 个文件的 Java 语料上进行的测试显示：实现成本降低 58%、实现工具调用减少 72%、耗时缩短 39%。

如实衡量成本

每次调用的 token 成本（中位数，182 个文件的 Python 仓库，按字符数除以 4 估算 token）：

坦率地说，这种取舍是：对于小型、已经熟悉的仓库中的单次精准查找，grep 更省成本。在 5 项单事实任务中，Vectr 的 token 中位成本高出 60%，而且速度也更慢，因为一次 vectr_search 往返需要 1.7 到 3.6 秒，而 grep 约需 28ms。Vectr 并不以单次调用成本取胜。它的优势在于工具调用次数（一次往返而非多次）、答案完整度（返回整个符号，而非部分文件内容），以及工作记忆中的所有信息；在这些场景中，5.7 倍的记忆调用成本返还会随着每次恢复任务而累积。

补充说明：工具响应中附带的自动淘汰和提醒横幅也会消耗 token。始终开启的重新获取页脚约需 27 个 token，轻量提醒约需 89 个 token，而升级后的“需要采取行动”横幅（只有在未保存且同时超过块数和 token 阈值后才会触发）会从约 480 个 token 增至 535 个 token，之后趋于稳定。

快速开始

本地安装（推荐）

python3.14 -m venv ~/.vectr-env
source ~/.vectr-env/bin/activate   # Windows: ~/.vectr-env/Scripts/activate
pip install vectr
cd /path/to/your/project
vectr start

需要 Python 3.14+。 安装方式：

• macOS：brew install [email protected]
• Ubuntu/Debian：sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.14 python3.14-venv
• Windows：python.org/downloads

vectr start 会立即返回。索引会在后台运行，因此请运行 vectr status 查看进度。首次运行时，嵌入模型会下载一次（约 290 MB）。重启一次 AI 代码编辑器，以加载新的 MCP 配置。

Docker（CI 和服务端）

git clone https://github.com/swapnanil/vectr
cd vectr
docker-compose up api

会开放端口 8765。Docker 不会自动写入 IDE 配置文件，因此 IDE 集成请使用本地安装。

连接到 AI 代码编辑器

vectr start 会自动为你的编辑器写入 MCP 配置。重启编辑器一次即可。

“已验证”表示已端到端测试完整集成（配置、指导文件和钩子）。“实验性”表示已写入 MCP 配置且可以正常工作，但尚未经过相同的验证流程。

记忆能否自动传递，取决于宿主是否提供会话钩子。对于不提供会话钩子的宿主，以下所有工具仍可按需通过 MCP 使用。

{ "mcpServers": { "vectr": { "type": "http", "url": "http://localhost:8765/mcp" } } }

{ "mcpServers": { "vectr": { "url": "http://localhost:8765/mcp" } } }

{ "servers": { "vectr": { "type": "http", "url": "http://localhost:8765/mcp" } } }

{ "mcpServers": { "vectr": { "serverUrl": "http://localhost:8765/mcp" } } }

{ "mcpServers": [{ "name": "vectr", "transport": { "type": "http", "url": "http://localhost:8765/mcp" } }] }

[mcp_servers.vectr]
url = "http://localhost:8765/mcp"

Stdio 传输

上述编辑器通过 HTTP 连接（vectr start 加 POST /mcp）。对于会将服务作为子进程启动，并通过其 stdin 和 stdout 而非建立 HTTP 连接来传输 MCP 的 MCP 客户端和托管平台，请运行：

vectr mcp-stdio [WORKSPACE]

无需端口，也无需守护进程：单个前台进程以换行符分隔的 JSON-RPC 2.0 格式传输数据（stdin 和 stdout 中每行一个 JSON 对象，不带 Content-Length 标头）。initialize 和 tools/list 会立即响应，而嵌入模型加载和初始索引会在后台线程中进行。在这些操作完成前调用 tools/call，会收到友好的“仍在启动”响应，而不会一直等待。Stdout 只传输协议 JSON，所有日志都会写入 stderr。stdin 遇到 EOF 时，进程会正常退出。--memory-only 和 --search-only 的行为与 vectr start 中相同。

工作原理

1. 感知 AST 的分块。 tree-sitter 会解析每个文件，并在函数、类和方法的边界处分块。不会在逻辑中途切分。
2. 代码嵌入。 ibm-granite/granite-embedding-english-r2（本地运行、CPU 处理速度快、可覆盖）会将自然语言查询映射到代码符号，因此搜索“JWT 验证”会找到 verify_jwt_token。BM25 负责处理精确的符号名称。
3. 混合搜索。 将向量相似度与 BM25 结合，并根据代码库特征分配权重。大型且不熟悉的代码库更侧重语义搜索；小型且文档完善的代码库更侧重 BM25。
4. 符号图。 提取并存储调用边、导入链和 HTTP 路由（Flask、FastAPI、Express、Spring）。vectr_locate 通过 6 种策略依次查找名称：精确匹配、后缀、同一模块、导入链、子串，然后是模糊匹配。模糊匹配结果始终会明确标示为不精确，而不会被当作可靠匹配呈现，因为自信地给出错误符号比找不到更糟。
5. 工作记忆。 vectr_remember 会将结构化笔记存储到 SQLite 和 ChromaDB。vectr_recall 会对笔记进行语义搜索，而非使用 SQL LIKE，因此多词查询仍能找到相关上下文。
6. 触发条件评估。 守护进程会在生命周期节点确定性地检查每条笔记的条件，并使用按会话记录的触发台账和注入预算，因此笔记会在适用时准确地再次出现，且在同一时间窗口内不会重复出现。
7. MCP 协议。 通过 HTTP 提供 23 个工具。任何兼容 MCP 的 AI 代码编辑器都能连接，无需插件。

23 个 MCP 工具

vectr start 会将一份包含此表的指导文件写入你的工作区，让 AI 代码编辑器知道该使用哪个工具，无需你提示。

搜索工具，用于从索引中检索代码：

记忆工具，用于跨会话存储和回忆信息：

触发器：交付层

这些 kind 值带有合理的默认设置。笔记也可以在 vectr_remember 上声明显式的逐笔记 triggers：

同一条目内的条件以 AND 组合，不同条目之间以 OR 组合。每次触发都会附带一行说明，指出匹配了哪个触发条件。注入内容受预算限制（每轮硬性上限，由所有界面共同消耗），并会按笔记 ID 在一轮内的所有界面去重，同时标明来源，因此未经审核的自动捕获笔记绝不会被呈现得像是你设定的常驻规则。笔记不会被部分截断：它会完整呈现为索引级别的一行，否则就不会呈现。

工作区范围的笔记还可作为多 Agent 工作流的共享总线。编排器及其子 Agent 都读取和写入同一个笔记存储，因此子 Agent 可以在结束前调用 vectr_remember(..., agent="coder-2") 保存发现，编排器随后即可检索这些内容，而不必重新阅读子 Agent 的完整对话记录。agent 参数绝不会通过推断获得。它是显式归属信息，并会作为标签显示在 vectr_recall 的索引输出中。

CLI 参考

vectr start                           # index + start daemon for current dir
vectr start /project/api              # positional workspace: a directory or .code-workspace file
vectr start --path /project/api       # specific workspace (repeatable, multi-root)
vectr start --memory-only             # working memory + hooks only, no code index, no watcher
vectr status                          # index health, chunk count, notes count
vectr status --all                    # all running instances
vectr stop /project/api               # stop one instance (same positional as start)
vectr stop --path /project/api        # stop one instance (equivalent --path form)
vectr stop --all                      # stop all instances
vectr index --path .                  # re-index without restarting daemon
vectr fetch src/auth.py:10-42         # re-fetch a chunk by exact id, verbatim
vectr resume                          # most recent task note, latest snapshot, open gotchas
vectr init --path .                   # write guidance file + MCP config without starting
vectr init --exclude vendor           # exclude directories from indexing
vectr forget --path .                 # delete all working-memory notes
vectr memory export                   # render the working-memory store as a greppable, git-diffable markdown file (default MEMORY.md)
vectr memory export --path notes.md   # write the export to a specific file
vectr memory export --disable         # stop the auto-refresh that keeps the export file in sync
vectr memory edit                     # open the working-memory store in your $EDITOR, one block per note
vectr memory import                   # bring existing on-disk memory files into the working-memory store (see below)
vectr memory import --path NOTES.md   # import a specific file instead of the default discovery list
vectr memory import --dry-run         # preview what would be created (kind, title, source file, line range), change nothing
vectr cache prune                     # remove empty per-workspace cache dirs (live instances skipped)
vectr cache prune --dry-run           # preview what would be removed, delete nothing
vectr proxy                           # experimental: localhost API proxy (see below)
vectr mcp-stdio                       # foreground stdio MCP transport, no port or daemon (see above)

导入现有记忆

vectr memory export 和 vectr memory edit 分别是单向导出路径和签出／签入路径。vectr memory import 则是单向导入路径：无需手动重新录入，即可将磁盘上已有的记忆导入工作记忆存储。这为已经写下记忆的新用户提供了入门途径。

发现。 如果不指定 --path，导入器会遍历工作区根目录中一组固定的默认候选文件：MEMORY.md、CLAUDE.md、AGENTS.md、.cursorrules 和 .github/copilot-instructions.md。传入 --path（可重复指定）即可指向其他文件或目录；目录会递归遍历其中的 *.md 和 *.mdc 文件。不存在的文件会被报告，但不会导致报错，因为大多数工作区都不会包含所有默认文件。

粒度。 一个源文件既不会作为一条笔记，也不会按每行拆分成一条笔记。它会在 Markdown 标题边界（^#{1,6}\s+）处分割，方式与人们浏览 MEMORY.md 时相同。没有标题的文件会成为一条笔记。围栏代码块和 HTML 注释块中的标题会被跳过，因此代码示例或导出文件的头部注释不会成为章节边界。通过 `` 标头检测到由 vectr memory export 导出的文件后，会使用 vectr memory edit 的同一套块语法进行解析，将每个原始块还原为一条笔记，并沿用其声明的 kind、priority、tags 和 provenance。

试运行。 --dry-run 会准确打印将要创建的内容（种类、标题、源文件、源行范围、来源），且不做任何更改。记忆是用户难以重建的资源，因此应优先进行试运行：

vectr memory import --dry-run
# + [finding/auto] 'Project conventions'  (MEMORY.md:12-34)
# + [operational/agent] 'Test runner'  (CLAUDE.md:5-9)
# DRY RUN: would create 2 note(s), skip 0 already-imported, ...

幂等性。 每条导入的笔记都会带有 src:、src-sha: 和 src-lines: 这组三个标签。对未更改的源文件重新运行 vectr memory import 时，会识别这些标签，不会创建任何新笔记。如果编辑源文件中的某个章节，其正文哈希将与已存储的哈希不匹配，因此会成为一条新笔记，而旧笔记会保持不变，因为在用户不知情的情况下悄悄删除先前导入的内容，正是设计在导出侧要防范的无声丢失。

来源。 导入的笔记带有源文件标签（imported 和 src:FILENAME，其中 FILENAME 是源文件的基本名称），因此，在列出带有 imported 的笔记时，用户会知道“这条内容来自文件，而不是本次会话中的观察”。笔记的 provenance 默认为 auto，因为机器捕获且未经审阅判断的事实本来就带有此类别；对于解析器而言，手写的 MEMORY.md 在结构上与生成器的输出无法区分。例外范围狭窄，且依据结构而非语义判断：正文包含命令式规则标记（固定关键词集合 MUST、MUST NOT、NEVER、ALWAYS、DO NOT、DON'T、REQUIRED、FORBIDDEN）的笔记会被归类为 kind="directive"，并将 provenance 升级为 agent。这是因为 remember() 在写入时会进行 auto + directive 防护：未经审阅的常驻规则自相矛盾，而导入的规则恰好属于这种情况。升级为 agent 是对 auto 的最小偏离，刚好足以通过防护；用户审阅后可通过 vectr_promote 进一步提升。

排除路径

在项目根目录中创建 .vectrignore（语法与 .gitignore 相同）：

vendor/
node_modules/
*.pb.go
dist/

或者在初始化时传入 --exclude：

vectr init --exclude vendor --exclude dist

排除规则既适用于初始索引遍历，也适用于实时文件监视器，因此将目录添加到 .vectrignore 后，正在运行的实例也会停止为其重新建立索引。下一次索引还会清理因文件现已被排除或已删除而留存的分块，因此无需从头重建。如果需要彻底重建，例如更改嵌入模型后，请强制执行：

vectr index --path . --force      # ignore the incremental cache, re-embed everything

支持的语言

HTTP 路由（Flask 和 FastAPI 装饰器、Express app.get()、Spring @GetMapping）会作为符号提取，并可通过 vectr_locate("GET /api/users") 搜索。

成本

安全性

默认设置保持不变，核心原则依然是：供个人设备上的独立开发者使用，本地运行、无需 API 密钥、零配置。开箱即用时，守护进程仅绑定到 127.0.0.1，CORS 仅允许 localhost 来源，每个工作区都有各自隔离的数据库目录、端口和进程（POSIX 系统上权限为仅所有者可访问的 0700），索引和笔记保存在本地 ~/.cache/vectr/ 中。

以下功能均为可选启用。不启用任何功能，就不会有任何变化。

身份验证。 设置 VECTR_API_KEY 后，所有发往 /v1/* 和 /mcp 的请求都必须携带该密钥（使用 X-Api-Key: <key> 或 Authorization: Bearer <key>，采用恒定时间比较；/v1/health 除外，该端点保持开放以供存活探测）。使用 vectr key 生成密钥。如果启动时已设置密钥，vectr 写入的编辑器 MCP 配置会自动包含该请求头。这些文件（.mcp.json、.cursor/mcp.json、.vscode/mcp.json）会以明文保存密钥，因此请将其视为机密，并避免将它们提交到共享或公开的版本控制中。

静态加密。 设置 VECTR_ENCRYPT_KEY，或将密码短语存储在操作系统密钥链中（服务名为 vectr，用户名为 encrypt-key，需要 pip install vectr[encryption]），即可使用 Fernet 和 PBKDF2 派生密钥加密笔记内容、笔记标题和快照载荷。需要说明的是：代码索引不会加密，因为搜索引擎需要可读的代码块文本和向量。请使用操作系统全盘加密来保护它。笔记标签和元数据仍以明文保存；笔记嵌入向量（笔记文本的有损投影）也会保留，以便进行语义检索，除非设置 VECTR_ENCRYPT_DISABLE_NOTE_VECTORS=1。

保留与审计。 笔记会一直保留，直到你将其删除。设置 VECTR_NOTES_TTL_DAYS，即可在启动时自动清除超过指定天数的笔记。vectr_forget(all=true) 和 vectr forget --all 会删除笔记、快照和笔记向量，因此会删除所有内容。设置 VECTR_AUDIT_LOG=<path>，即可记录索引、搜索、记忆存储和回忆事件，并在本地轮换日志（默认关闭；日志会记录查询文本，这正是其用途，且绝不会被传输）。完整策略：docs/data-handling.md。

团队模式（共享实例）。 一台中央守护进程即可为团队提供对一个仓库的服务。在服务器上运行 VECTR_API_KEY=<key> vectr start --host 0.0.0.0（绑定到非回环地址时，没有密钥将拒绝启动），然后在每个客户端上运行 vectr connect --url http://<host>:<port> --api-key <key> --label <you>，将编辑器指向该服务。工作记忆是共享的：一个 Agent 存储的笔记，所有已连接的 Agent 都可以回忆；--label 会标注笔记和审计日志行。笔记 ID 由中央存储按写入到达顺序分配，因此多个客户端并发使用时，你的笔记 ID 不会连续，而会与其他客户端的 ID 交错。写入操作返回的 Stored note #N 行是该笔记的权威引用，因此不要假设下一个 ID 也属于你。明确来说：使用同一个共享密钥意味着每个持有者都是权限相同且可信的对等方（没有角色或按用户划分的权限）；服务器运营者可以读取所有内容；搜索结果引用的是服务器上的工作副本，可能与你本地的代码树不同；vectr 使用明文 HTTP，因此如果网络不可信，请通过反向代理或隧道配置 TLS。

主动上下文（实验性，仅限 localhost）

基于拉取的回忆意味着 Agent 必须主动询问。主动上下文通过直接介入通信链路，为没有会话钩子的宿主提供确定性内容传递。此功能为实验性功能，且仅限 localhost。从 1.6.0 版本起，本地实例默认启用主动传递（proactive.enabled；设置 VECTR_PROACTIVE=0 可将其关闭）。下方的通信链路由启动时的授权决定，而非由该开关控制：启动代理并将 Agent 指向代理即表示选择启用；停止代理或取消设置基础 URL 即表示选择退出。

vectr proxy 命令会在 Agent 和模型 API 之间运行一个小型本地代理：

vectr proxy                            # starts a localhost proxy (default :8785)
export ANTHROPIC_BASE_URL=http://127.0.0.1:8785   # point your agent at it

以下是它的功能与限制，直言不讳：

• 默认透明。 它会将每个请求转发到真实 API，流式响应和工具调用也会逐字节原样通过。你的 API 密钥会原样转发，绝不会被存储或记录。
• 确定性注入。 工作区守护进程运行时，它会在最后一个提示词缓存断点之后，将匹配的工作记忆笔记附加到请求中，因此绝不会使提示词缓存失效。触发条件是相似度阈值加精确的结构匹配，而非猜测关键词；同时设有严格的每请求预算，确保只有在提示信息值得消耗这些令牌时才会注入。
• 故障时放行。 如果智能层响应缓慢或出错，请求仍会原样通过。要完全绕过代理，请取消设置基础 URL： unset ANTHROPIC_BASE_URL。代理位于请求路径上，因此如果代理不可用，请取消设置该变量，直接与 API 通信。
• 仅限独立模式和 localhost。 它会读取你的对话来计算上下文，因此拒绝绑定任何非回环地址，并且不能与团队模式同时使用。
• **关于使用非第一方基础 URL 的注意事项，**依据宿主自身的文档：除非设置 ENABLE_TOOL_SEARCH=true 且代理转发工具引用块，否则 MCP 工具搜索会被禁用；而在非 api.anthropic.com 的基础 URL 上，Remote Control 会被禁用。

全组织缓存（团队模式）。 使用中央共享实例时，vectr 可以缓存自身开销较大的产物，即语义搜索和回忆结果，并以精确身份和当前索引状态作为键，因此重新索引或笔记变更会自动使缓存失效，所有连接的开发者都能从中受益。此功能默认关闭（proactive.cache）；vectr status 会报告缓存命中率和预计节省的令牌数，以便衡量实际效果，而不是空口断言。Vectr 不会跨相似请求缓存大模型响应，只会在本地、经用户选择启用的情况下缓存字节完全相同的响应，因为错误的缓存命中会悄无声息地破坏对话。

vectr 可能带来的负面影响

代码库变动后笔记过时。 笔记会在写入时记录文件路径。进行大规模重构后，vectr_recall 会用 [STALE] 标记引用的已变更文件。采取行动前请重新核实；使用 vectr_forget(note_id=N) 删除过时笔记，或使用 vectr_forget(all=true) 清除所有笔记。

对熟知的 API 过度检索。 如果模型在训练中已深入了解某个框架，vectr 的研究开销可能超过其带来的节省。上方的基准测试准确展示了这种情况：在 debug_descriptor_priority 任务中，仅凭训练知识就足以完成导航。

架构概览过时。 通过 vectr_map_save 保存的架构护照描述的是索引时的架构。模块重命名或入口点重构后，内容可能看似可靠实则错误，因此 vectr_map 会显示过时警告，你应重新运行 vectr_map_save。

广泛回忆会消耗令牌。 不带查询调用 vectr_recall() 会返回所有内容。请传入有针对性的查询；如果不确定是否需要回忆，先检查 vectr_status()。

构建所用技术

Python 3.14 · FastAPI · sentence-transformers · tree-sitter · ChromaDB · BM25 · Docker

作者

Swapnanil Saha · swapnanilsaha.com