Embedded Vector Stores

Overview

Embedded vector stores provide zero-dependency local indexing solutions that enable developers to run semantic memory systems without configuring external database services or cloud infrastructure. By embedding lightweight vector engines directly into application runtimes, these components facilitate rapid local prototyping, offline development, and deterministic unit testing. They bridge the gap between abstract vector embedding generation and persistent local storage by abstracting away low-level file I/O, memory buffering, and similarity index construction. Sources: mem0/vector_stores/chroma.py:23-75

Across both Python and TypeScript packages, embedded stores handle vector insertions, approximate nearest neighbor (ANN) lookups, payload metadata association, and collection lifecycle management locally. For instance, implementations like Chroma support persistent file-backed directory storage through Python and TypeScript client bindings, while native in-memory stores utilize local SQLite file layers with Float32 buffer serialization. These lightweight backends interact directly with core memory orchestrators Vector Store Architecture while keeping administrative overhead minimal. Sources: mem0-ts/src/oss/src/vector_stores/chroma.ts:28-100

The following sections examine the specific architectural mechanics, client initialization sequences, data serialization patterns, and security guardrails governing embedded vector stores. By understanding these internals, developers can effectively choose between local file persistence (such as Chroma or FAISS) and zero-config embedded runtimes (such as SQLite-backed memory stores) during test-driven development and local prototyping. Sources: mem0-ts/src/oss/src/vector_stores/memory.ts:231-245

ChromaDB Integration and Client Lifecycle

The ChromaDB vector store driver provides both Python and TypeScript implementations that mirror each other to deliver seamless local persistence and server connectivity. In Python, ChromaDB extends VectorStoreBase to manage collections via chromadb.Client or chromadb.CloudClient. In TypeScript, ChromaDB implements the VectorStore interface, utilizing lazy peer loading of the chromadb package to ensure consumers who do not use Chroma are not forced to install the optional peer dependency. Sources: mem0/vector_stores/chroma.py:23-45

During initialization, if an existing client instance is omitted, the constructor configures local persistence settings (disabling anonymized telemetry by default) and defaults the local storage directory to "db" if no path is provided. It then invokes get_or_create_collection with an explicit null embedding function in TypeScript, ensuring that embeddings are pre-computed externally by mem0 prior to persistence. Sources: mem0/vector_stores/chroma.py:46-75

Sources: mem0-ts/src/oss/src/vector_stores/chroma.ts:35-100

SQLite-Backed In-Memory Vector Store

For lightweight unit testing and zero-configuration execution, the TypeScript runtime provides an in-memory vector store backed by SQLite Vector Store Architecture. This implementation ensures that developers can execute tests or lightweight applications without external daemon processes or native vector binaries. Sources: mem0-ts/src/oss/src/vector_stores/memory.ts:231-240

Vectors are serialized into binary buffers using Float32Array views mapped directly onto Node.js Buffer instances before insertion into SQLite tables. During vector similarity searches, rows are fetched and converted back into floating-point arrays to compute exact cosine similarity against the query vector. Sources: mem0-ts/src/oss/src/vector_stores/memory.ts:241-245

Copy// Example usage of SQLite-backed memory store in TypeScript
import { MemoryVectorStore } from "mem0-ts/oss";
 
const store = new MemoryVectorStore({
  collectionName: "test_memories",
  dimension: 3
});
 
await store.insert(
  [[0.1, 0.2, 0.3]],
  ["mem_1"],
  [{ data: "Hello local vector world" }]
);
 
const results = await store.search([0.1, 0.2, 0.3], 5);
console.log(results);

Sources: mem0-ts/src/oss/src/vector_stores/memory.ts:352-391

FAISS Local Indexing and Security Controls

The FAISS vector store integration (FAISS) provides high-performance local similarity search utilizing Facebook AI Similarity Search bindings. It supports distance strategies including 'euclidean', 'inner_product', and 'cosine', along with optional L2 normalization. Sources: mem0/vector_stores/faiss.py:127-146

To protect against arbitrary code execution vulnerabilities during local index deserialization, the FAISS driver implements a restricted unpickler (SafeUnpickler). This security guard strictly limits allowed pickle modules to builtins and restricts deserialized types to a strict whitelist. Sources: mem0/vector_stores/faiss.py:34-61

Output Parsing and Score Normalization

Embedded vector stores return uniform results encapsulated in structured OutputData models. Because different underlying libraries compute raw metrics differently (such as unbounded Euclidean distances versus cosine similarity), embedded stores normalize raw scores into consistent similarity metrics. Sources: mem0/vector_stores/chroma.py:17-21

For instance, both Chroma and FAISS wrappers parse raw distance outputs using an inverse distance transformation formula: score equals one divided by one plus raw distance. This guarantees that similarity scores fall within a predictable range where higher values indicate closer proximity. Sources: mem0/vector_stores/chroma.py:76-102

The execution path for output parsing across local drivers processes raw results through array flattening and metric transformation before yielding structured output entries. Sources: mem0/vector_stores/chroma.py:103-110

Sources: mem0-ts/src/oss/src/vector_stores/chroma.ts:120-144

Configuration and Initialization Parameters

Embedded vector stores accept specific configuration parameters to adjust persistence directories, dimension constraints, and distance metrics. The following table outlines key initialization arguments supported across embedded implementations: Sources: mem0/vector_stores/chroma.py:23-45

Sources: mem0/vector_stores/faiss.py:127-146

Error Handling and Graceful Fallbacks

Local embedded stores handle missing optional peer dependencies by raising informative installation instructions. For example, if chromadb or faiss packages are absent from the Python environment, import blocks catch ImportError exceptions and prompt the user to install the appropriate package via pip. Sources: mem0/vector_stores/chroma.py:6-11

Similarly, in TypeScript implementations, peer dependencies such as chromadb are loaded lazily via dynamic import() statements wrapped in peer loaders. This design choice prevents application boot failures when importing modules that do not utilize local vector backends. Sources: mem0-ts/src/oss/src/vector_stores/chroma.ts:49-61

Related

• Vector Store Architecture