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
| Option | Pros | Cons | Why Rejected |
|---|---|---|---|
| Pinecone | Managed; scalable | External service; paid; requires API key | Fails the zero-infrastructure requirement |
| Weaviate (embedded) | Feature-rich; GraphQL API | Heavy; complex setup for embedded mode | Overkill for v2 scope |
hnswlib-node | Pure HNSW; lightweight | No metadata filtering; manual persistence | Missing filtering capability |
chromadb (embedded) | Python-native; popular | Python dependency; poor Node.js embedded story | Conflicts with ADR-008 TS-only decision |
| LanceDB (chosen) | Embedded; Node.js native; metadata filtering; Apache Arrow columnar format | Younger 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
- ADR-008 — TypeScript runtime this store ships with
- ADR-009 — companion LLM provider decision
- Academy: Vector Databases
src/memory/VectorStore.ts— IVectorStore interface + LanceDBStore implementation