Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Agentic patterns

Quiver ships an MCP server (quiver mcp) that speaks JSON-RPC 2.0 over stdio, so any MCP-capable LLM agent (an IDE assistant or a custom agent) can use Quiver as a tool: build a knowledge base, retrieve from it, and curate it, all without bespoke glue. This guide covers the agent-facing surface and a typical loop.

Connect

Point your MCP client at the binary. Encryption-at-rest is on by default, so the agent’s memory is sealed on disk:

// e.g. an MCP client config
{
  "mcpServers": {
    "quiver": {
      "command": "quiver",
      "args": ["mcp", "--data-dir", "/var/lib/quiver"],
      "env": { "QUIVER_ENCRYPTION_KEY": "<64-hex>" }
    }
  }
}

Tools the agent gets

ToolWhat it does
list_collectionsEnumerate collections
collection_infoInspect one collection’s shape — dim, metric, index, filterable fields, multivector, encryption, count
database_statsA whole-database overview in one call — collection count, total points, a per-collection summary, and snapshot status (manifest_version, disk_bytes)
create_collectionCreate one (dim, metric, index, filterable, multivector, vector_encryption)
delete_collectionDrop an entire collection and all its points (reports whether it existed)
snapshotTake a consistent online backup of the whole database into a server-local directory (ADR-0050)
upsertInsert/replace a point (id, vector, payload)
searchk-NN with an optional payload filter
fetchList points by filter without ranking
getFetch one point by id
deleteDelete a point by id
upsert_document / search_multi_vector / delete_documentMulti-vector (ColBERT) late-interaction documents
upsert_text / search_textStore/query by text — Quiver embeds it server-side (needs a provider; run quiver mcp --config quiver.toml)

All calls go through the same authorized op layer and cost limits (ADR-0040) as REST/gRPC, so an agent cannot exceed the server’s guardrails.

A typical agent loop

A research assistant maintaining its own long-term memory:

  1. list_collections → does a research collection exist? If not, create_collection("research", dim=…, metric="cosine", filterable=[{path:"topic",field_type:"keyword"}]).
  2. As it reads sources, the agent embeds passages (with its own model) and upserts them with {topic, url, added} payloads.
  3. To answer a question, it embeds the query and searches with a filter (e.g. topic = "vector-db"), then grounds its answer in the returned text.
  4. It deletes stale entries or fetches a topic to review what it knows.

Because Quiver is model-agnostic, the agent owns the embedding step — pass the float vectors it produces. The server stores, filters, and ranks.

Or let Quiver do the embedding: configure an [embedding.<collection>] provider (ADR-0047/0058), launch quiver mcp --config quiver.toml, and the agent can use upsert_text / search_text to store and query by text directly — no client-side model. search_text(rerank=true) additionally reranks in one call when a [rerank.<collection>] provider is set.

Tips

  • Declare filterable fields up front so the agent can scope retrieval (per-user, per-topic, per-recency) — the pre-filter is exact.
  • Scope the agent’s API key (RBAC, security overview) to just its collection prefix, so a tool call can’t touch other data.
  • Use client_side vector encryption (client-side vectors) if the agent’s host should not be able to read the stored vectors — the agent fetches and ranks locally.
  • For paragraph-grained memory, store documents as token sets and use search_multi_vector (multi-vector).