Vector Store Architecture

Overview

The vector store architecture provides a polymorphic data persistence and similarity retrieval layer that unifies disparate Cloud Vector Backends, Database Vector Stores, and Embedded Vector Stores under a shared abstract interface VectorStoreBase. By abstracting vector indexing, Approximate Nearest Neighbor (ANN) search, full-text keyword matching, and metadata filtering across engines such as Qdrant, Milvus, MongoDB, PostgreSQL, and LangChain, the system insulates higher-level memory management logic from vendor-specific driver idiosyncrasies and client query dialects.

Sources: mem0/vector_stores/base.py:4-26, mem0-ts/src/oss/src/vector_stores/base.ts:3-33, mem0-ts/src/oss/src/utils/factory.ts:154-214

Dual-runtime vector store contract abstractions

Python Abstract Base Class Surface

The Python implementation defines VectorStoreBase as an abstract base class inheriting from ABC, establishing strict structural requirements across all concrete vector store implementations mem0/vector_stores/base.py:1-4. It enforces mandatory abstract methods for lifecycle operations, vector mutations, metadata storage, and collection management mem0/vector_stores/base.py:5-67.

Sources: mem0/vector_stores/base.py:1-67

Sources: mem0/vector_stores/base.py:5-66

Base methods with default implementations provide optional capabilities: keyword_search executes BM25 full-text queries and returns None unless overridden, while search_batch processes multiple queries sequentially via search unless a provider supplies native batch execution mem0/vector_stores/base.py:68-100.

Sources: mem0/vector_stores/base.py:68-100

TypeScript Interface Contract

The TypeScript client SDK exposes an asynchronous VectorStore interface defining equivalent persistence and retrieval primitives mapped to Promise-based signatures mem0-ts/src/oss/src/vector_stores/base.ts:3-33.

Copyexport interface VectorStore {
  insert(
    vectors: number[][],
    ids: string[],
    payloads: Record<string, any>[],
  ): Promise<void>;
  search(
    query: number[],
    topK?: number,
    filters?: SearchFilters,
  ): Promise<VectorStoreResult[]>;
  keywordSearch?(
    query: string,
    topK?: number,
    filters?: SearchFilters,
  ): Promise<VectorStoreResult[] | null>;
  get(vectorId: string): Promise<VectorStoreResult | null>;
  update(
    vectorId: string,
    vector: number[],
    payload: Record<string, any>,
  ): Promise<void>;
  delete(vectorId: string): Promise<void>;
  deleteCol(): Promise<void>;
  list(
    filters?: SearchFilters,
    topK?: number,
  ): Promise<[VectorStoreResult[], number]>;
  getUserId(): Promise<string>;
  setUserId(userId: string): Promise<void>;
  initialize(): Promise<void>;

Sources: mem0-ts/src/oss/src/vector_stores/base.ts:3-33

Factory instantiation and runtime resolution

VectorStoreFactory Provider Mapping

The VectorStoreFactory class resolves runtime configuration strings into concrete vector store instances via a case-insensitive switch statement over the provider identifier mem0-ts/src/oss/src/utils/factory.ts:154-214.

Sources: mem0-ts/src/oss/src/utils/factory.ts:154-214

Sources: mem0-ts/src/oss/src/utils/factory.ts:154-214

Normalized payload and result structures

Document Schema and Payload Serialization

The document representation layer standardizes how vector entries map to backend fields mem0/vector_stores/azure_ai_search.py:164-170. In backends such as AzureAISearch, metadata payloads are serialized into JSON strings alongside explicit filterable dimensions like user_id, run_id, and agent_id extracted directly from the payload dictionary mem0/vector_stores/azure_ai_search.py:137-147, mem0/vector_stores/azure_ai_search.py:164-170.

Sources: mem0/vector_stores/azure_ai_search.py:137-170

Copyclass OutputData(BaseModel):
    id: Optional[str]
    score: Optional[float]
    payload: Optional[dict]
 

Sources: mem0/vector_stores/azure_ai_search.py:37-41

Distance-to-Similarity Conversion Rules

All Python implementations of VectorStoreBase must return normalized similarity scores within the range [0, 1], where higher values indicate greater similarity mem0/vector_stores/base.py:19-20. When a backend natively uses distance metrics, the score must be converted according to explicit mathematical transformations before returning mem0/vector_stores/base.py:21-25.

Sources: mem0/vector_stores/base.py:19-25

Sources: mem0/vector_stores/base.py:21-25

Query filter DSL translation strategies

Filter Expression Generation

Vector store backends translate incoming SearchFilters dictionaries into native query language expressions mem0-ts/src/oss/src/vector_stores/milvus.ts:245-259, mem0/vector_stores/azure_ai_search.py:195-213. In the TypeScript Milvus provider, metadata keys are assembled into string literal comparisons formatted as (metadata["${key}"] == "${escaped}") for strings, or (metadata["${key}"] == ${value}) for numbers and booleans, joined by and mem0-ts/src/oss/src/vector_stores/milvus.ts:248-258.

Sources: mem0-ts/src/oss/src/vector_stores/milvus.ts:245-259

Copy    if (typeof value === "string") {
      // Escape backslashes before quotes so a value can't break out of the
      // string literal (order matters, exactly as in the Python provider).
      const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
      operands.push(`(metadata["${key}"] == "${escaped}")`);
    } else if (typeof value === "number" || typeof value === "boolean") {
      operands.push(`(metadata["${key}"] == ${value})`);
    } else {
      throw new Error(
        `Filter value for ${JSON.stringify(key)} must be a string, number, or boolean, got ${typeof value}`,
      );
    }
  }
  return operands.length > 0 ? operands.join(" and ") : undefined;
}

Sources: mem0-ts/src/oss/src/vector_stores/milvus.ts:245-259

Similarly, the Python AzureAISearch vector store translates filter keys by sanitizing identifiers and evaluating data types to construct OData filter expressions mem0/vector_stores/azure_ai_search.py:192-213. String values have single quotes escaped as '', booleans are converted via lowercase string representation, and numbers are appended directly before being joined with and mem0/vector_stores/azure_ai_search.py:199-212.

Sources: mem0/vector_stores/azure_ai_search.py:192-213

Copydef _build_filter_expression(self, filters):
    filter_conditions = []
    for key, value in filters.items():
        safe_key = self._sanitize_key(key)
        if isinstance(value, str):
            safe_value = value.replace("'", "''")
            condition = f"{safe_key} eq '{safe_value}'"
        elif isinstance(value, bool):
            condition = f"{safe_key} eq {str(value).lower()}"
        elif isinstance(value, (int, float)):
            condition = f"{safe_key} eq {value}"
        else:
            raise ValueError(
                f"Filter value for {key!r} must be str, int, float, or bool, "
                f"got {type(value).__name__}"
            )
        filter_conditions.append(condition)
    filter_expression = " and ".join(filter_conditions)
    return filter_expression

Sources: mem0/vector_stores/azure_ai_search.py:195-213

Filter Translation Mapping

Sources: mem0-ts/src/oss/src/vector_stores/milvus.ts:245-259, mem0/vector_stores/azure_ai_search.py:195-213

LangChain bridge and adapter architecture

Client Validation and Embedding Fallbacks

The LangChain bridge allows external vector stores to integrate with both runtimes. In TypeScript, LangchainVectorStore validates that a provided client object implements addVectors and similaritySearchVectorWithScore mem0-ts/src/oss/src/vector_stores/langchain.ts:16-30. In Python, the Langchain class inspects the client interface to check for add_embeddings; if absent, it falls back to calling add_texts using data extracted from payloads mem0/vector_stores/langchain.py:95-103.

Sources: mem0-ts/src/oss/src/vector_stores/langchain.ts:16-30, mem0/vector_stores/langchain.py:95-103

Copyconstructor(config: LangchainStoreConfig) {
  if (!config.client || typeof config.client !== "object") {
    throw new Error(
      "Langchain vector store provider requires an initialized Langchain VectorStore instance passed via the 'client' field.",
    );
  }
  // Basic checks for core methods
  if (
    typeof config.client.addVectors !== "function" ||
    typeof config.client.similaritySearchVectorWithScore !== "function"
  ) {
    throw new Error(
      "Provided Langchain 'client' does not appear to be a valid Langchain VectorStore (missing addVectors or similaritySearchVectorWithScore method).",
    );
  }

Sources: mem0-ts/src/oss/src/vector_stores/langchain.ts:16-30

Scored Search Method Resolution

The Python adapter iterates through a ranked priority list of methods to retrieve document-score pairs from diverse underlying stores mem0/vector_stores/langchain.py:27-31, mem0/vector_stores/langchain.py:114-129.

Sources: mem0/vector_stores/langchain.py:27-31, mem0/vector_stores/langchain.py:114-129

Sources: mem0/vector_stores/langchain.py:27-31, mem0/vector_stores/langchain.py:114-129

Input sanitization and injection prevention

Identifier and Payload Escaping Mechanics

Vector backends that expose query languages or dynamic shell interfaces implement strict regex validations and string escaping routines to prevent injection attacks. In Databricks, identifiers are validated against SAFE_IDENTIFIER_RE (/^[A-Za-z_][A-Za-z0-9_]{0,127}$/), and SQL values are serialized with backslashes and single quotes escaped prior to literal interpolation mem0-ts/src/oss/src/vector_stores/databricks.ts:5-154. Similarly, Milvus escapes backslashes and double quotes when constructing string filter operands mem0-ts/src/oss/src/vector_stores/milvus.ts:245-249.

Sources: mem0-ts/src/oss/src/vector_stores/databricks.ts:5-154, mem0-ts/src/oss/src/vector_stores/milvus.ts:245-249

Copyconst SAFE_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
const DEFAULT_PAGE_SIZE = 100;
const MAX_QUERY_RESULTS = 10_000;
const MAX_FULL_TEXT_RESULTS = 200;
const DEFAULT_SYNC_POLL_INTERVAL_MS = 1000;
const DEFAULT_SYNC_TIMEOUT_MS = 5 * 60 * 1000;

Sources: mem0-ts/src/oss/src/vector_stores/databricks.ts:5-10

Filter Key Sanitization and Type Enforcement

Query filter keys and values undergo rigorous validation across search integrations to reject malformed payloads before execution. Elasticsearch evaluates filter keys against SAFE_FILTER_KEY (/^[a-zA-Z_][a-zA-Z0-9_]*$/) and verifies that scalar values are restricted to strings, numbers, or booleans mem0-ts/src/oss/src/vector_stores/elasticsearch.ts:26-44. Redis tag filters explicitly escape special characters including -, |, and whitespace to prevent RediSearch operator injection mem0-ts/src/oss/src/vector_stores/redis.ts:13-24.

Sources: mem0-ts/src/oss/src/vector_stores/elasticsearch.ts:26-44, mem0-ts/src/oss/src/vector_stores/redis.ts:13-24

Copyconst SAFE_FILTER_KEY = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 
// Mirrors the Python provider's _validate_filter. Filter keys are interpolated
// into `metadata.${key}` field paths, so reject anything that is not a plain
// identifier and reject non-scalar values before they reach the query.
function validateFilter(key: string, value: unknown): void {
  if (typeof key !== "string" || !SAFE_FILTER_KEY.test(key)) {
    throw new Error(`Invalid filter key: ${JSON.stringify(key)}`);
  }

Sources: mem0-ts/src/oss/src/vector_stores/elasticsearch.ts:26-34

Related

• Cloud Vector Backends
• Database Vector Stores
• Embedded Vector Stores