Vector stores

A vector store keeps documents, embeddings, and metadata and searches them by similarity. Choose the embedding model and dimensions together with the store. Conversation StorageDriver records and durable task stores serve different purposes. Start with the local example below. It proves indexing/search plumbing without credentials; it does not measure semantic retrieval quality.

VectorStore interface

This selected interface matches the public operations; use vector APIs for complete declarations:

import type { ContentPart, VectorDocument, VectorSearchOptions, VectorSearchResult } from "@agentium/core";

interface VectorStore {
  initialize(): Promise<void>;
  upsert(collection: string, doc: VectorDocument): Promise<void>;
  upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
  search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
  get(collection: string, id: string): Promise<VectorDocument | null>;
  delete(collection: string, id: string): Promise<void>;
  dropCollection(collection: string): Promise<void>;
  close(): Promise<void>;
}

Types

Type	Selected fields
`VectorDocument`	`id`, `content`, optional `embedding`, `parts`, `metadata`
`VectorSearchOptions`	`topK`, `minScore`, `filter`, optional `rerank` and `rerankMultiplier`
`VectorSearchResult`	`id`, `content`, `score`, optional `metadata`

Multimodal parts require an embedding provider that implements that input. Backends persist text, vectors, and metadata; retain media references in metadata when needed. Filter behavior is adapter-specific; do not treat a metadata filter as caller authorization.

Implementations comparison

Store	Optional client	Infrastructure	Persistence
InMemoryVectorStore	None for local fixtures	Current process	Lost on process exit
PgVectorStore	`pg`	PostgreSQL with the vector extension	Database
QdrantVectorStore	`@qdrant/js-client-rest`	Qdrant service	Service
MongoDBVectorStore	`mongodb`	MongoDB; Atlas index for server-side vector search	Database

Call initialize() for a consistent lifecycle even where it is a no-op. Creating an embedding provider can require another optional client, such as openai or @google/genai.

InMemoryVectorStore

Use an ESM TypeScript project ("type": "module" in package.json) on a supported Node version.

npm install @agentium/core@4.0.0
npm install --save-dev tsx typescript @types/node

Save as retrieve.ts:

import { HashEmbedding, InMemoryVectorStore } from "@agentium/core";

const store = new InMemoryVectorStore(new HashEmbedding());
try {
  await store.initialize();
  await store.upsertBatch("policies", [
    { id: "delivery", content: "Delivery takes three to five business days." },
    { id: "refund", content: "Refunds return to the original payment method." },
  ]);
  const hits = await store.search("policies", "delivery business days", { topK: 1 });
  console.log(hits[0]?.id);
} finally {
  await store.close();
}

npx tsx retrieve.ts

Expect delivery. HashEmbedding hashes tokens locally; replace it with a measured semantic embedder before evaluating real retrieval quality. The constructor accepts an optional EmbeddingProvider, not a dimension number.

PgVectorStore

Install pg@8. The PostgreSQL server needs its vector extension available, and initialization requests CREATE EXTENSION IF NOT EXISTS vector. The adapter formats vectors itself; the separate pgvector npm package is not required by its implementation. This host factory returns a store; the caller initializes it, uses it, and closes it after consumers finish:

import { PgVectorStore, type EmbeddingProvider } from "@agentium/core";

export function createPostgresVectors(connectionString: string, embedder: EmbeddingProvider) {
  return new PgVectorStore({ connectionString, dimensions: embedder.dimensions }, embedder);
}

Collections become sanitized table names. Each collection is created on first upsert with a vector column and HNSW index. The configuration fields are connectionString and optional dimensions; there is no tableName option. Dimension defaults come from the embedder, then 1536 when no embedder is supplied. Existing collections are not automatically migrated when the embedding model changes.

QdrantVectorStore

Install @qdrant/js-client-rest and run or provision a Qdrant service. This is another host factory:

import { QdrantVectorStore, type EmbeddingProvider } from "@agentium/core";

export function createQdrantVectors(url: string, embedder: EmbeddingProvider, apiKey?: string) {
  return new QdrantVectorStore({ url, apiKey, dimensions: embedder.dimensions }, embedder);
}

Supported configuration includes url (default http://localhost:6333), apiKey, dimensions, and checkCompatibility. initialize() is a no-op; a missing collection is created on first upsert. Collection names are arguments to store operations, not a collectionName constructor field. Match existing collection dimensions to your embedder.

MongoDBVectorStore

Install mongodb@6. For Atlas vector search, create the named index for the stored embedding field with matching dimensions. This factory configures the client; initialize() connects it:

import { MongoDBVectorStore, type EmbeddingProvider } from "@agentium/core";

export function createMongoVectors(uri: string, embedder: EmbeddingProvider) {
  return new MongoDBVectorStore({
    uri,
    dbName: "agentium_vectors",
    indexName: "vector_index",
  }, embedder);
}

The v4 constructor accepts uri, optional dbName, and optional indexName. It has no dimensions or collectionName field. Configure Atlas index dimensions on the service and pass collection names to upsert()/search(). The adapter tries Atlas search and can fall back to fetching documents for local similarity on recognized unsupported-search errors. Local fallback has different scaling characteristics; validate the mode used by your deployment instead of assuming every query uses a server-side index.

EmbeddingProvider

With an embedder, a text document/query is embedded automatically. Without one, supply numeric vectors for both documents and queries. This complete local example supplies two-dimensional vectors directly:

import { InMemoryVectorStore } from "@agentium/core";

const store = new InMemoryVectorStore();
try {
  await store.initialize();
  await store.upsert("demo", { id: "one", content: "Example vector", embedding: [1, 0] });
  const hits = await store.search("demo", [1, 0], { topK: 1 });
  console.log(hits[0]?.id); // one
} finally {
  await store.close();
}

A supplied embedding bypasses automatic embedding for that document. A string query still needs an embedder. Keep model, dimensions, document/query formatting, and normalization consistent; re-index a collection when that contract changes.

Connect retrieval to an Agent

Pass the store to KnowledgeBase, add documents, and expose kb.asTool() or explicitly insert retrieved results into the Agent’s context. Merely constructing a knowledge base does not give an Agent access to it. Continue with the retrieval tutorial for the full evidence → answer path and embeddings for model choices.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

VectorStore interface

Types

Implementations comparison

InMemoryVectorStore

PgVectorStore

QdrantVectorStore

MongoDBVectorStore

EmbeddingProvider

Connect retrieval to an Agent

​VectorStore interface

​Types

​Implementations comparison

​InMemoryVectorStore

​PgVectorStore

​QdrantVectorStore

​MongoDBVectorStore

​EmbeddingProvider

​Connect retrieval to an Agent

VectorStore interface

Types

Implementations comparison

InMemoryVectorStore

PgVectorStore

QdrantVectorStore

MongoDBVectorStore

EmbeddingProvider

Connect retrieval to an Agent