vectorsearch

Name: vectorsearch
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords记忆与知识02 周前更新

代码仓库

关于 vectorsearch

vectorsearch 是面向 Agent 的轻量记忆工具，提供 CLI 和 MCP 服务，可将文本存入 Qdrant 并按相似度检索。它用确定性的本地哈希嵌入替代外部嵌入服务，匹配基于令牌重叠，而非模型级语义嵌入。

主要功能

01存储文本及可选元数据
02按相似度查找条目
03通过 REST API 使用 Qdrant
04自动创建缺失的集合
05确定性的本地文本嵌入

适用场景

01保存笔记供 Agent 后续查询
02从存储文本中检索部署信息
03无需嵌入服务进行离线文本检索

MCP 相关

其 stdio MCP 服务提供 `qdrant-store` 和 `qdrant-find` 工具，用于向 Qdrant 写入信息并检索相关条目。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-vectorsearch": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/vectorsearch"
      ]
    }
  }
}

启动命令npx -y @reneturcios/vectorsearch

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/vectorsearch0.1.0stdio

ocighcr.io/cloudcorprecords/vectorsearch:0.1.0stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
metadata	object	否	与存储的信息关联并保存到 point payload 中的可选元数据。
information	string	是	要存储在 Qdrant 数据库中的文本信息。
collection_name	string	否	用于存储信息的 Qdrant 集合名称（可选）；默认使用已配置的集合。

详细介绍

vectorsearch

vectorsearch 是供 Agent 使用的小型记忆库：现在存储一条信息，之后再用自然语言查询找回。它仅保留两种操作——存储和查找，并通过 REST API 使用 Qdrant 向量数据库。

设置 QDRANT_URL 以连接非默认服务（默认使用 http://localhost:6333）。调用未指定集合时，使用的集合由 COLLECTION_NAME 决定，默认值为 documents。向尚不存在的集合存储内容时，会先创建该集合，并将维度设为此工具使用的嵌入维度，距离类型设为余弦距离。

安装

npx @reneturcios/vectorsearch find "how do we deploy the staging app"

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/vectorsearch

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

# Store something (optionally into a named collection)
vectorsearch store "the staging deploy runs from the release branch" --collection notes

# Ask for it back
vectorsearch find "staging deploy" --collection notes

# Start the MCP server
vectorsearch mcp

vectorsearch --version

退出代码：成功时为 0，服务调用失败时为 1（错误信息中包含 HTTP 状态码），用法错误时为 2。

MCP 服务

同一个可执行程序提供这两种用法。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/vectorsearch mcp

MCP 客户端配置：

{
  "mcpServers": {
    "vectorsearch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/vectorsearch", "mcp"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "COLLECTION_NAME": "documents"
      }
    }
  }
}

工具

工具	必填	可选	用途
`qdrant-store`	`information`（字符串）	`metadata`（对象）、`collection_name`（字符串）	在 Qdrant 数据库中存储信息。文本和所有元数据都会成为点的载荷。
`qdrant-find`	`query`（字符串）	`collection_name`（字符串）	从 Qdrant 数据库中检索相关信息。返回最接近的已存储条目及其载荷和分数。

关于嵌入

参考设计将 Qdrant 与外部嵌入模型搭配使用。此重建版本刻意不调用任何外部嵌入服务。相反，它使用基于哈希的确定性函数在本地嵌入文本：相同文本始终会生成相同的单位向量，共享词元的文本彼此更接近，因此存储和查找的行为保持一致，且完全离线。需要明确其权衡：这是基于词元重叠相似度的本地回退方案，并非模型级语义嵌入。之后若要换成真正的嵌入服务提供方，只需更改执行器的向量函数，工具、架构和存储结构都保持不变。

点 ID 同样具有确定性，由文本（以及存在时的元数据）哈希生成，因此重新存储相同信息时会更新同一个点，而不会堆积重复项。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fakes only, no live service
npm run dev     # run the CLI from source via tsx

分发、默认集合解析和错误传播均通过虚拟执行器进行测试；Qdrant REST 执行器则通过会记录请求的虚拟 fetch 进行测试（确保集合存在／不存在时创建集合、点的 upsert 结构、搜索映射）。