Vectorsearch

vectorsearch

vectorsearch is a small memory for agents: store a piece of information now, then ask for it back later with a plain-language query. It keeps exactly two operations — store and find — and backs them with a Qdrant vector database over its REST API.

Set QDRANT_URL to reach a non-default service (it assumes http://localhost:6333). The collection used when a call does not name one comes from COLLECTION_NAME and defaults to documents. Storing into a collection that does not exist yet creates it first, sized to this tool's embedding dimension with cosine distance.

Install

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

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/vectorsearch

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

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

Exit codes: 0 on success, 1 when the service call fails (the error includes the HTTP status), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/vectorsearch mcp

MCP client configuration:

{

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

Tools

About the embeddings

The reference design pairs Qdrant with an external embedding model. This rebuild deliberately calls no external embedding service. Instead it embeds text locally with a deterministic hash-based function: the same text always produces the same unit vector, and texts that share tokens land near each other, which keeps store and find self-consistent and fully offline. Be clear-eyed about the trade-off: this is a local fallback with token-overlap similarity, not model-grade semantic embeddings. Swapping in a real embedding provider later only changes the executor's vector function — the tools, schemas, and storage shape stay the same.

Point ids are likewise deterministic, derived from a hash of the text (and metadata when present), so re-storing the same information updates the same point instead of piling up duplicates.

Development

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

Dispatch, default-collection resolution, and error propagation are tested against a fake executor; the Qdrant REST executor is tested against a fake fetch that records its requests (collection ensure / create-on-missing, point upsert shape, search mapping).

License

MIT — see LICENSE.