Class: PostgresVectorStore

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:73

Interface

IVectorStore

Description

Defines the contract for interacting with a specific vector database or storage backend. Implementations will wrap specific clients (e.g., Pinecone client, Weaviate client, in-memory store logic).

Implements

• IVectorStore

Constructors

Constructor

new PostgresVectorStore(config): PostgresVectorStore

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:79

Parameters

config

PostgresVectorStoreConfig

Returns

PostgresVectorStore

Methods

checkHealth()

checkHealth(): Promise<{ details?: any; isHealthy: boolean; }>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:146

IVectorStore-compliant health check.

Returns

Promise<{ details?: any; isHealthy: boolean; }>

Implementation of

IVectorStore.checkHealth

---

close()

close(): Promise<void>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:118

Close the connection pool.

Returns

Promise<void>

---

createCollection()

createCollection(name, dimension, options?): Promise<void>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:158

Create a new collection (Postgres table) with pgvector HNSW index.

Parameters

name

string

dimension

number

options?

CreateCollectionOptions

Returns

Promise<void>

Implementation of

IVectorStore.createCollection

---

delete()

delete(collectionName, ids?, options?): Promise<DeleteResult>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:533

Delete documents by ID.

Parameters

collectionName

string

ids?

string[]

options?

DeleteOptions

Returns

Promise<DeleteResult>

Implementation of

IVectorStore.delete

---

dropCollection()

dropCollection(name): Promise<void>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:214

Drop a collection table.

Parameters

name

string

Returns

Promise<void>

---

fetchByIds()

fetchByIds(collectionName, ids, options?): Promise<RetrievedVectorDocument[]>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:361

Fetch rows by primary key without similarity ranking. Used by HybridSearcher to hydrate sparse-only RRF winners — a second similarity query would return the next-K dense rows, not the specific BM25 winners, and would misattribute rows under the wrong fused-score position.

Returns an empty array for an empty id list without firing SQL. similarityScore is set to 0 as a sentinel.

Parameters

collectionName

string

ids

string[]

options?

includeMetadata?

boolean

includeTextContent?

boolean

Returns

Promise<RetrievedVectorDocument[]>

Implementation of

IVectorStore.fetchByIds

---

healthCheck()

healthCheck(): Promise<boolean>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:135

Health check — verifies connection and pgvector availability.

Returns

Promise<boolean>

True if Postgres + pgvector is reachable.

---

hybridSearch()

hybridSearch(collectionName, queryEmbedding, queryText, options?): Promise<QueryResult>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:452

Hybrid search combining pgvector ANN and tsvector BM25 in a single SQL query with Reciprocal Rank Fusion.

This runs as one query with two CTEs — no application-level fusion needed.

Parameters

collectionName

string

queryEmbedding

number[]

queryText

string

options?

QueryOptions & object

Returns

Promise<QueryResult>

Implementation of

IVectorStore.hybridSearch

---

initialize()

initialize(): Promise<void>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:92

Initialize the connection pool, ensure pgvector extension exists, and create the collections metadata table.

Returns

Promise<void>

Implementation of

IVectorStore.initialize

---

query()

query(collectionName, queryEmbedding, options?): Promise<QueryResult>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:285

Query for top-K nearest neighbors using pgvector operators. Uses HNSW index for O(log n) approximate search.

Parameters

collectionName

string

queryEmbedding

number[]

options?

QueryOptions

Returns

Promise<QueryResult>

Implementation of

IVectorStore.query

---

scanByMetadata()

scanByMetadata(collectionName, options?): Promise<MetadataScanResult>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:393

Optional: Enumerates documents using metadata-only filtering without requiring a query embedding.

Parameters

collectionName

string

options?

MetadataScanOptions

Returns

Promise<MetadataScanResult>

Implementation of

IVectorStore.scanByMetadata

---

shutdown()

shutdown(): Promise<void>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:127

Gracefully shut down the store (alias for close).

Returns

Promise<void>

Implementation of

IVectorStore.shutdown

---

upsert()

upsert(collectionName, documents, _options?): Promise<UpsertResult>

Defined in: packages/agentos/src/cognition/rag/vector_stores/PostgresVectorStore.ts:231

Upsert documents into a collection. Uses INSERT ... ON CONFLICT (id) DO UPDATE for idempotent writes.

Parameters

collectionName

string

documents

VectorDocument[]

_options?

UpsertOptions

Returns

Promise<UpsertResult>

Implementation of

IVectorStore.upsert