Skip to main content

Class: HnswSidecar

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:89

Memory-specific HNSW sidecar that wraps the canonical HnswIndexSidecar.

Maintains the original constructor-based API expected by Memory facade and Brain consumers, while delegating all index operations to the shared RAG implementation.

Constructors​

Constructor​

new HnswSidecar(config): HnswSidecar

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:95

Parameters​

config​

HnswSidecarConfig

Returns​

HnswSidecar

Accessors​

isActive​

Get Signature​

get isActive(): boolean

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:109

Whether the HNSW index is currently active and queryable.

Returns​

boolean


size​

Get Signature​

get size(): number

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:114

Number of vectors currently indexed.

Returns​

number

Methods​

add()​

add(traceId, embedding, _totalCount): Promise<void>

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:146

Add a vector to the index. If below threshold, does nothing. If threshold is crossed, caller should call rebuildFromData().

Parameters​

traceId​

string

The trace ID to associate with this vector.

embedding​

number[]

The embedding vector.

_totalCount​

number

Current total trace count (unused, kept for API compat).

Returns​

Promise<void>


addMissing()​

addMissing(items): Promise<number>

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:259

Adds the vectors of traces the index lacks, as a store's open does for the traces stored after the last save, and then saves the index once, so the next load holds them. A vector of another dimension is skipped, as a rewrite skips it.

Parameters​

items​

object[]

Returns​

Promise<number>

How many vectors it added.


destroy()​

destroy(): void

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:282

Delete index files from disk and deactivate.

Returns​

void


ids()​

ids(): string[]

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:248

The ids of the traces the index holds.

Returns​

string[]


init()​

init(): Promise<void>

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:126

Initialize the sidecar. Loads existing index from disk if present. If hnswlib-node is not installed, silently stays inactive.

Returns​

Promise<void>


query()​

query(embedding, topK): HnswQueryResult[]

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:158

Query the HNSW index for top-K nearest neighbors. Returns trace IDs sorted by distance (closest first).

Parameters​

embedding​

number[]

Query vector.

topK​

number

Number of results to return.

Returns​

HnswQueryResult[]

Array of { id, distance } sorted by distance ascending.


rebuildFromData()​

rebuildFromData(data): Promise<void>

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:212

Rebuild the entire index from a set of id/embedding pairs. Called on first threshold crossing or when the index file is missing/corrupt. Filters out dimension-mismatched vectors before delegating.

Parameters​

data​

object[]

Array of { id, embedding } to index.

Returns​

Promise<void>


remove()​

remove(traceId): void

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:200

Remove a trace from the index by marking its label as deleted. HNSW doesn't support true deletion — cleaned up on rebuild.

Parameters​

traceId​

string

The trace ID to remove.

Returns​

void


rewrite()​

rewrite(data): Promise<{ vectors: number; }>

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:232

Writes the index again from the vectors given, and from nothing else: the index held in memory is dropped unsaved and the index files are removed first, so a vector that is not in data is in no file afterwards. A delete only marks a vector in the index, which keeps its numbers until the index is written again. With no vector left the files stay removed.

Vectors of another dimension than the configured one are left out, as rebuildFromData leaves them out.

Parameters​

data​

object[]

Every vector the index is to hold.

Returns​

Promise<{ vectors: number; }>

How many vectors the index holds: 0 where hnswlib-node is not installed, and then no file is written.

Throws​

When an index file cannot be removed, or when the rebuilt index did not save.


saveToDisk()​

saveToDisk(): void

Defined in: packages/agentos/src/cognition/memory/retrieval/store/HnswSidecar.ts:275

Persist index and label map to disk. Called after rebuildFromData() and periodically after adds.

Returns​

void