Skip to main content

ADR-010: LanceDB for Vector Storage

Date: 2026-06-02
Status: Accepted

Context

Agentic RAG (retrieval-augmented generation) requires a vector store for embedding
and retrieving documents. The v2 TypeScript runtime (ADR-008) needs one that:

  • Runs embedded (no external server to provision or operate)
  • Works in Node.js without native-module build issues
  • Supports metadata filtering alongside vector search
  • Has zero infrastructure cost for adopters

External managed services (Pinecone, Weaviate Cloud) were ruled out immediately,
they require accounts, API keys, and ongoing cost. The choice is between embedded
options that ship inside the npm package.

Decision

LanceDB is the default vector store, implemented in src/memory/VectorStore.ts.
It is embedded, file-based (persists to .agenthood/memory/), and has a Node.js
package that does not require native compilation on common platforms.

Alternatives Considered

OptionProsConsWhy Rejected
PineconeManaged; scalableExternal service; paid; requires API keyFails the zero-infrastructure requirement
Weaviate (embedded)Feature-rich; GraphQL APIHeavy; complex setup for embedded modeOverkill for v2 scope
hnswlib-nodePure HNSW; lightweightNo metadata filtering; manual persistenceMissing filtering capability
chromadb (embedded)Python-native; popularPython dependency; poor Node.js embedded storyConflicts with ADR-008 TS-only decision
LanceDB (chosen)Embedded; Node.js native; metadata filtering; Apache Arrow columnar formatYounger ecosystem; fewer integrations-

Consequences

Easier:

  • No infrastructure required: vector data persists to a local directory
  • Metadata filtering is native, enabling hybrid keyword + semantic search
  • Single npm dependency; no Python runtime needed (consistent with ADR-008)

Harder:

  • LanceDB Node.js bindings are in earlier maturity than the Python client
  • Arrow columnar format is unfamiliar to most TypeScript contributors
  • Distributed / multi-node scenarios require migrating to an external store

Scope:
LanceDB handles the default VectorStore implementation. IVectorStore abstraction
allows adopters to swap to Pinecone, Weaviate, or any other provider via config.

References