--- title: "Python Embedding Adapters" description: "Python embedding adapters provide a standardized architecture for generating vector representations of text across various cloud-managed and self-hosted machine learning providers. By implementing ..." last_updated: "2026-10-11T17:37:10.25946+00:00" canonical_url: "https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/technical/llm-providers/python-embedding-adapters" ---
Relevant source files The following files were used as context for generating this wiki page: - [mem0-ts/src/oss/src/utils/factory.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/utils/factory.ts) - [mem0/embeddings/ollama.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/ollama.py) - [mem0/embeddings/aws_bedrock.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/aws_bedrock.py) - [mem0/embeddings/fastembed.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/fastembed.py) - [mem0/embeddings/gemini.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/gemini.py) - [mem0/utils/factory.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/utils/factory.py) - [mem0/embeddings/lmstudio.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/lmstudio.py) - [mem0-ts/src/oss/src/embeddings/fastembed.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/embeddings/fastembed.ts) - [mem0-ts/src/oss/src/embeddings/aws_bedrock.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/embeddings/aws_bedrock.ts) - [mem0/embeddings/vertexai.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/vertexai.py) - [mem0/llms/aws_bedrock.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/llms/aws_bedrock.py) - [mem0/embeddings/huggingface.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/huggingface.py) - [mem0-ts/src/oss/src/embeddings/vertexai.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/embeddings/vertexai.ts) - [mem0/embeddings/azure_openai.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/azure_openai.py) - [mem0/embeddings/openai.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/openai.py) - [mem0/embeddings/base.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/base.py) - [mem0/embeddings/langchain.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/langchain.py) - [mem0-ts/src/oss/src/embeddings/ollama.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/embeddings/ollama.ts) - [integrations/openclaw/cli/oss-wizard.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/integrations/openclaw/cli/oss-wizard.ts) - [mem0-ts/src/oss/src/embeddings/lmstudio.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/embeddings/lmstudio.ts) - [mem0/embeddings/together.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/together.py) - [mem0/configs/embeddings/base.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/configs/embeddings/base.py) - [mem0-ts/src/oss/src/embeddings/langchain.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/embeddings/langchain.ts) - [integrations/hermes-plugin-mem0/_backend.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/integrations/hermes-plugin-mem0/_backend.py) - [mem0/configs/embeddings/__init__.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/configs/embeddings/__init__.py) - [mem0-ts/src/oss/src/embeddings/azure.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/embeddings/azure.ts) - [mem0/configs/vector_stores/__init__.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/configs/vector_stores/__init__.py) - [mem0/vector_stores/vertex_ai_vector_search.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/vector_stores/vertex_ai_vector_search.py) - [mem0/embeddings/__init__.py](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/__init__.py) - [mem0-ts/src/oss/src/embeddings/google.ts](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0-ts/src/oss/src/embeddings/google.ts)
## Overview Python embedding adapters provide a standardized architecture for generating vector representations of text across various cloud-managed and self-hosted machine learning providers. By implementing a common abstract contract with unified `embed` and `embed_batch` signatures, the framework allows memory subsystems to generate dense vectors interchangeably regardless of the underlying model provider. The architecture abstracts provider-specific connection management, credential handling, payload formatting, and dimension configuration into modular driver implementations. This design enables seamless integration with commercial endpoints such as OpenAI, Azure OpenAI, AWS Bedrock, Google GenAI, and Vertex AI, alongside local inference runtimes like Ollama, FastEmbed, LMStudio, and Hugging Face transformer pipelines. Sources: [mem0/embeddings/base.py:7-46](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/base.py#L7-L46), [mem0/utils/factory.py:152-178](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/utils/factory.py#L152-L178) ## Abstract Embedding Base Contract ### Core Interface Definitions The Python core defines vector generation through the abstract base class `EmbeddingBase`, located in `mem0/embeddings/base.py`. This class provides initialization logic that accepts an optional `BaseEmbedderConfig` instance. If no configuration object is supplied during instantiation, it instantiates and assigns a default `BaseEmbedderConfig` instance to `self.config`. Sources: [mem0/embeddings/base.py:7-19](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/base.py#L7-L19) ```python class EmbeddingBase(ABC): """Initialized a base embedding class :param config: Embedding configuration option class, defaults to None :type config: Optional[BaseEmbedderConfig], optional """ def __init__(self, config: Optional[BaseEmbedderConfig] = None): if config is None: self.config = BaseEmbedderConfig() else: self.config = config ``` Sources: [mem0/embeddings/base.py:7-19](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/base.py#L7-L19) ### Method Signatures and Contracts Subclasses extending `EmbeddingBase` are required to implement the abstract method `embed`, which takes a text string and an optional memory action type. The `embed_batch` method provides a default implementation that iterates over a list of texts and calls `embed` sequentially for each item, though subclasses with native batch capabilities override this method for better performance. Sources: [mem0/embeddings/base.py:20-47](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/base.py#L20-L47) ```python @abstractmethod def embed(self, text, memory_action: Optional[Literal["add", "search", "update"]]): """ Get the embedding for the given text. Args: text (str): The text to embed. memory_action (optional): The type of embedding to use. Must be one of "add", "search", or "update". Defaults to None. Returns: list: The embedding vector. """ pass def embed_batch(self, texts, memory_action="add"): """Embed multiple texts. Override in subclasses for native batch support. Default implementation calls embed() sequentially for each text. Subclasses with native batch APIs (e.g., OpenAI) should override this for better performance. Args: texts: List of text strings to embed. memory_action: The action context ("add", "search", "update"). Returns: List of embedding vectors (list of floats), one per input text. """ return [self.embed(text, memory_action) for text in texts] ``` Sources: [mem0/embeddings/base.py:20-47](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/base.py#L20-L47) | Method | Parameters | Return Type | Description | | :--- | :--- | :--- | :--- | | `__init__` | `config: Optional[BaseEmbedderConfig] = None` | `None` | Initializes the embedder with a configuration object or defaults to `BaseEmbedderConfig`. | | `embed` | `text`, `memory_action: Optional[Literal["add", "search", "update"]]` | `list` | Abstract method to generate an embedding vector for a single text input. | | `embed_batch` | `texts`, `memory_action="add"` | `list` | Generates embedding vectors for multiple texts, defaulting to sequential `embed` calls. | Sources: [mem0/embeddings/base.py:14-47](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/base.py#L14-L47) ## Embedder Configuration Hierarchy ### Configuration Schema and Provider Parameters The configuration architecture for embedding adapters centers on the `BaseEmbedderConfig` abstract base class defined in `mem0/configs/embeddings/base.py`. This class provides a unified initialization schema supporting core properties, HTTP client proxies, and provider-specific parameters for OpenAI, Azure OpenAI, Ollama, Hugging Face, Vertex AI, Gemini, LM Studio, and AWS Bedrock. Sources: [mem0/configs/embeddings/base.py:1-43](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/configs/embeddings/base.py#L1-L43) | Parameter | Type | Default Value | Provider / Purpose | | :--- | :--- | :--- | :--- | | `model` | `Optional[str]` | `None` | Embedding model identifier across providers. | | `api_key` | `Optional[str]` | `None` | API key credential for authenticated requests. | | `embedding_dims` | `Optional[int]` | `None` | Target dimension count for generated vectors. | | `ollama_base_url` | `Optional[str]` | `None` | Ollama API endpoint base URL. | | `openai_base_url` | `Optional[str]` | `None` | OpenAI API endpoint base URL. | | `model_kwargs` | `Optional[dict]` | `None` | Key-value arguments for Hugging Face transformer models. | | `huggingface_base_url` | `Optional[str]` | `None` | Hugging Face base URL endpoint. | | `azure_kwargs` | `Optional[AzureConfig]` | `None` | Configuration dictionary or `AzureConfig` instance for Azure OpenAI. | | `http_client_proxies` | `Optional[Union[Dict, str]]` | `None` | Proxy server settings used to construct `self.http_client`. | | `vertex_credentials_json` | `Optional[str]` | `None` | Filesystem path to Google Vertex AI credentials JSON. | | `memory_add_embedding_type` | `Optional[str]` | `None` | Embedding type variant for memory insertion actions. | | `memory_update_embedding_type` | `Optional[str]` | `None` | Embedding type variant for memory update actions. | | `memory_search_embedding_type` | `Optional[str]` | `None` | Embedding type variant for memory search queries. | | `output_dimensionality` | `Optional[str]` | `None` | Output dimensionality constraint for Gemini models. | | `lmstudio_base_url` | `Optional[str]` | `"http://localhost:1234/v1"` | LM Studio local server endpoint base URL. | | `aws_access_key_id` | `Optional[str]` | `None` | AWS access key identifier for Bedrock authentication. | | `aws_secret_access_key` | `Optional[str]` | `None` | AWS secret access key for Bedrock authentication. | | `aws_session_token` | `Optional[str]` | `None` | AWS session token for temporary credentials. | | `aws_region` | `Optional[str]` | `None` | AWS region; falls back to environment variable `AWS_REGION` or `"us-west-2"`. | Sources: [mem0/configs/embeddings/base.py:14-43](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/configs/embeddings/base.py#L14-L43) > [!NOTE] > When `aws_region` is unassigned in the constructor call, the configuration resolver checks `os.environ.get("AWS_REGION")` before defaulting to `"us-west-2"`. Sources: [mem0/configs/embeddings/base.py:107-111](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/configs/embeddings/base.py#L107-L111) ### Initialization and Client Resolution During `BaseEmbedderConfig.__init__`, attributes are assigned directly to instance variables while specific providers instantiate auxiliary objects. `http_client_proxies` is passed directly to `build_http_client` to establish `self.http_client`, `azure_kwargs` normalizes input dictionaries into `AzureConfig` instances, and `model_kwargs` defaults to an empty dictionary if omitted. Sources: [mem0/configs/embeddings/base.py:77-111](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/configs/embeddings/base.py#L77-L111) > [!CAUTION] > Passing `azure_kwargs` as a raw dictionary requires correct nested keys matching `AzureConfig`; passing invalid keys or omitting required Azure parameters will cause instantiation failures during `AzureConfig` validation. Sources: [mem0/configs/embeddings/base.py:93-94](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/configs/embeddings/base.py#L93-L94) ## OpenAI and Azure Embedding Integrations ### OpenAIEmbedding Adapter Mechanics The `OpenAIEmbedding` adapter implements vector generation via the `OpenAI` client SDK, defaulting to the `text-embedding-3-small` model with 1536 dimensions. Configuration resolution checks `api_key` against `self.config.api_key` or `OPENAI_API_KEY`, and resolves the base URL through `self.config.openai_base_url`, `OPENAI_API_BASE`, or `OPENAI_BASE_URL`, falling back to `https://api.openai.com/v1`. If `OPENAI_API_BASE` is detected in the environment, a `DeprecationWarning` is triggered directing users to `OPENAI_BASE_URL`. Sources: [mem0/embeddings/openai.py:11-35](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/openai.py#L11-L35) > [!WARNING] > The environment variable `OPENAI_API_BASE` is deprecated as of release 0.1.80 and will be removed; configurations must migrate to `OPENAI_BASE_URL`. Sources: [mem0/embeddings/openai.py:28-33](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/openai.py#L28-L33) Dimensions are conditionally passed to the API only when `embedding_dims` is explicitly configured by the user, preventing non-Matryoshka OpenAI-compatible backends such as vLLM or Voyage from rejecting requests due to an unsupported parameter. Both single `embed` and batch `embed_batch` methods replace newline characters with spaces in input texts, set `encoding_format` to `"float"`, and chunk batch inputs into maximum sizes of 100 to respect upstream API rate limits. Responses are sorted by index to maintain correct ordering, and a `ValueError` is raised if the returned count of embedding vectors does not match the input text count. Sources: [mem0/embeddings/openai.py:16-80](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/openai.py#L16-L80) ### AzureOpenAIEmbedding Adapter and Authentication The `AzureOpenAIEmbedding` adapter configures its client using parameters retrieved from `self.config.azure_kwargs` or environment variables: `EMBEDDING_AZURE_OPENAI_API_KEY`, `EMBEDDING_AZURE_DEPLOYMENT`, `EMBEDDING_AZURE_ENDPOINT`, and `EMBEDDING_AZURE_API_VERSION`. When `api_key` is unassigned, empty, or set to the literal placeholder `"your-api-key"`, the adapter authenticates via Azure Identity using `DefaultAzureCredential` and a bearer token provider scoped to `https://cognitiveservices.azure.com/.default`. Otherwise, token providers are omitted in favor of the provided API key. Sources: [mem0/embeddings/azure_openai.py:10-42](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/azure_openai.py#L10-L42) > [!IMPORTANT] > If `api_key` is explicitly set to `"your-api-key"`, it is treated as a placeholder and automatically overridden with `DefaultAzureCredential`. Sources: [mem0/embeddings/azure_openai.py:24-30](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/azure_openai.py#L24-L30) Similar to the standard OpenAI adapter, single and batch embedding methods strip newlines by replacing them with spaces and enforce a maximum batch size of 100 texts per API call. Response items are reordered using `sorted(response.data, key=lambda x: x.index)`, and length mismatches between incoming texts and returned embeddings trigger a `ValueError`. Sources: [mem0/embeddings/azure_openai.py:44-77](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/azure_openai.py#L44-L77) ## AWS Bedrock Embedding Implementation ### Bedrock Client Initialization and Request Serialization The `AWSBedrockEmbedding` class subclasses `EmbeddingBase` and initializes an AWS Bedrock runtime client via the `boto3` library. The model defaults to `amazon.titan-embed-text-v1` if not specified in the configuration. Credentials are resolved in order of precedence: first from explicit attributes on `self.config` (`aws_access_key_id`, `aws_secret_access_key`, and `aws_session_token`), falling back to the standard environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`. The AWS region defaults to `us-west-2` when `aws_region` is unset on the configuration. Sources: [mem0/embeddings/aws_bedrock.py:16-52](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/aws_bedrock.py#L16-L52) > [!NOTE] > `AWSBedrockEmbedding` explicitly honors a session token supplied via configuration (such as temporary credentials from STS assume-role workflows), falling back to the `AWS_SESSION_TOKEN` environment variable when the configuration value is empty. Sources: [mem0/embeddings/aws_bedrock.py:37-41](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/aws_bedrock.py#L37-L41) The adapter formats request payloads differently depending on the model provider extracted from the model prefix (`self.config.model.split(".")[0]`). When the provider is `cohere`, the payload sets `input_type` to `"search_document"` and passes texts under the `texts` key. For Amazon Titan and other providers, the text is assigned to `inputText`. Furthermore, if the model identifier contains `"v2"` and `embedding_dims` is configured, the `dimensions` field is included in the request body. Sources: [mem0/embeddings/aws_bedrock.py:63-78](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/aws_bedrock.py#L63-L78) | Provider / Model Pattern | Payload Field Key | Optional Configuration Keys | | :--- | :--- | :--- | | `cohere` | `texts` | `input_type` (`"search_document"`) | | Amazon & others (default) | `inputText` | `dimensions` (Titan Text Embeddings V2 when `embedding_dims` is set) | Sources: [mem0/embeddings/aws_bedrock.py:64-77](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/aws_bedrock.py#L64-L77) ### Model Invocation and Vector Normalization Model invocation occurs via `self.client.invoke_model`, passing the serialized JSON `body`, `modelId`, and specifying both `accept` and `contentType` as `"application/json"`. The binary response body is read and decoded from JSON. Depending on the model provider, vectors are extracted from either `response_body.get("embeddings")[0]` for Cohere or `response_body.get("embedding")` for Amazon and other providers. Any invocation errors are caught and raised as a `ValueError`. Sources: [mem0/embeddings/aws_bedrock.py:81-98](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/aws_bedrock.py#L81-L98) ```python def _normalize_vector(self, embeddings): """Normalize the embedding to a unit vector.""" emb = np.array(embeddings) norm_emb = emb / np.linalg.norm(emb) return norm_emb.tolist() ``` Sources: [mem0/embeddings/aws_bedrock.py:54-58](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/aws_bedrock.py#L54-L58) ## Google Gemini and Vertex AI ### GoogleGenAIEmbedding Generation Workflow The `GoogleGenAIEmbedding` adapter interacts with Google's Generative AI API using the `google-genai` client library. The class initializes with a default model of `models/gemini-embedding-001` and sets default embedding dimensions to `768`, preferring `self.config.output_dimensionality` or `self.config.embedding_dims`. API keys are resolved by checking `self.config.api_key` before falling back to the `GOOGLE_API_KEY` environment variable. ```python class GoogleGenAIEmbedding(EmbeddingBase): def __init__(self, config: Optional[BaseEmbedderConfig] = None): super().__init__(config) self.config.model = self.config.model or "models/gemini-embedding-001" self.config.embedding_dims = self.config.embedding_dims or self.config.output_dimensionality or 768 api_key = self.config.api_key or os.getenv("GOOGLE_API_KEY") self.client = genai.Client(api_key=api_key) ``` Sources: [mem0/embeddings/gemini.py:11-20](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/gemini.py#L11-L20) When embedding single strings, `embed()` normalizes newlines by replacing `\n` characters with spaces. It constructs an `EmbedContentConfig` object specifying `output_dimensionality` and invokes `self.client.models.embed_content`, extracting vector values from `response.embeddings[0].values`. ```python def embed(self, text, memory_action: Optional[Literal["add", "search", "update"]] = None): """ Get the embedding for the given text using Google Generative AI. Args: text (str): The text to embed. memory_action (optional): The type of embedding to use. Must be one of "add", "search", or "update". Defaults to None. Returns: list: The embedding vector. """ text = text.replace("\n", " ") # Create config for embedding parameters config = types.EmbedContentConfig(output_dimensionality=self.config.embedding_dims) # Call the embed_content method with the correct parameters response = self.client.models.embed_content(model=self.config.model, contents=text, config=config) return response.embeddings[0].values ``` Sources: [mem0/embeddings/gemini.py:22-40](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/gemini.py#L22-L40) Batch embeddings are processed in chunks of up to `100` texts using `embed_batch()`. If the total number of returned embeddings fails to match the count of input texts, a `ValueError` is raised. ```python def embed_batch(self, texts, memory_action="add"): if not texts: return [] config = types.EmbedContentConfig(output_dimensionality=self.config.embedding_dims) MAX_BATCH = 100 all_embeddings = [] for i in range(0, len(texts), MAX_BATCH): chunk = [t.replace("\n", " ") for t in texts[i : i + MAX_BATCH]] response = self.client.models.embed_content(model=self.config.model, contents=chunk, config=config) all_embeddings.extend(e.values for e in response.embeddings) if len(all_embeddings) != len(texts): raise ValueError( f"Gemini embed_batch() returned {len(all_embeddings)} embeddings for {len(texts)} texts " f"using model '{self.config.model}'" ) return all_embeddings ``` Sources: [mem0/embeddings/gemini.py:41-56](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/gemini.py#L41-L56) ### VertexAIEmbedding Enterprise Endpoints The `VertexAIEmbedding` adapter provides integration with GCP Vertex AI language models, defaulting to the `gemini-embedding-001` model and an embedding dimension size of `256`. It maps memory actions to distinct task types via `self.embedding_types`: `"add"` and `"update"` map to `RETRIEVAL_DOCUMENT` (or configured override keys), while `"search"` maps to `RETRIEVAL_QUERY`. ```python class VertexAIEmbedding(EmbeddingBase): def __init__(self, config: Optional[BaseEmbedderConfig] = None): super().__init__(config) self.config.model = self.config.model or "gemini-embedding-001" self.config.embedding_dims = self.config.embedding_dims or 256 self.embedding_types = { "add": self.config.memory_add_embedding_type or "RETRIEVAL_DOCUMENT", "update": self.config.memory_update_embedding_type or "RETRIEVAL_DOCUMENT", "search": self.config.memory_search_embedding_type or "RETRIEVAL_QUERY", } ``` Sources: [mem0/embeddings/vertexai.py:11-22](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/vertexai.py#L11-L22) ```python # Set up authentication using centralized GCP authenticator # This supports multiple authentication methods while preserving environment variable support try: GCPAuthenticator.setup_vertex_ai( service_account_json=getattr(self.config, 'google_service_account_json', None), credentials_path=self.config.vertex_credentials_json, project_id=getattr(self.config, 'google_project_id', None) ) except Exception: # Fall back to original behavior for backward compatibility credentials_path = self.config.vertex_credentials_json if credentials_path: os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = credentials_path elif not os.getenv("GOOGLE_APPLICATION_CREDENTIALS"): raise ValueError( "Google application credentials JSON is not provided. Please provide a valid JSON path or set the 'GOOGLE_APPLICATION_CREDENTIALS' environment variable." ) self.model = TextEmbeddingModel.from_pretrained(self.config.model) ``` Sources: [mem0/embeddings/vertexai.py:24-43](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/vertexai.py#L24-L43) > [!NOTE] > `VertexAIEmbedding` uses a centralized `GCPAuthenticator` to configure credentials via `google_service_account_json`, `vertex_credentials_json`, or `google_project_id`, falling back to standard `GOOGLE_APPLICATION_CREDENTIALS` environment variable checks. Sources: [mem0/embeddings/vertexai.py:24-41](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/vertexai.py#L24-L41) Single and batch text inputs are wrapped in `TextEmbeddingInput` objects paired with their respective task types and processed in batch chunks of up to `250` items. Unrecognized memory actions trigger an immediate `ValueError`. ```python def embed(self, text, memory_action: Optional[Literal["add", "search", "update"]] = None): """ Get the embedding for the given text using Vertex AI. Args: text (str): The text to embed. memory_action (optional): The type of embedding to use. Must be one of "add", "search", or "update". Defaults to None. Returns: list: The embedding vector. """ embedding_type = "SEMANTIC_SIMILARITY" if memory_action is not None: if memory_action not in self.embedding_types: raise ValueError(f"Invalid memory action: {memory_action}") embedding_type = self.embedding_types[memory_action] text_input = TextEmbeddingInput(text=text, task_type=embedding_type) embeddings = self.model.get_embeddings(texts=[text_input], output_dimensionality=self.config.embedding_dims) return embeddings[0].values def embed_batch(self, texts, memory_action="add"): if not texts: return [] embedding_type = "SEMANTIC_SIMILARITY" if memory_action is not None: if memory_action not in self.embedding_types: raise ValueError(f"Invalid memory action: {memory_action}") embedding_type = self.embedding_types[memory_action] all_embeddings = [] for i in range(0, len(texts), 250): chunk = texts[i : i + 250] inputs = [TextEmbeddingInput(text=t, task_type=embedding_type) for t in chunk] results = self.model.get_embeddings(texts=inputs, output_dimensionality=self.config.embedding_dims) all_embeddings.extend(r.values for r in results) if len(all_embeddings) != len(texts): raise ValueError( f"Vertex AI embed_batch() returned {len(all_embeddings)} embeddings for {len(texts)} texts" f" using model '{self.config.model}'" ) return all_embeddings ``` Sources: [mem0/embeddings/vertexai.py:44-85](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/vertexai.py#L44-L85) ## Local and Self-Hosted Embeddings ### Ollama, FastEmbed, and LMStudio Configurations The local embedding architecture supports three distinct execution backends: `OllamaEmbedding`, `FastEmbedEmbedding`, and `LMStudioEmbedding`. Each adapter inherits from `EmbeddingBase` and configures default local model names and vector dimensions upon initialization. | Adapter Class | Default Model | Default Dimensions | Client / Library | | :--- | :--- | :--- | :--- | | `OllamaEmbedding` | `nomic-embed-text` | `512` | `ollama.Client` | | `FastEmbedEmbedding` | `thenlper/gte-large` | Dynamic (`dense_model.embedding_size`) | `fastembed.TextEmbedding` (ONNX Runtime) | | `LMStudioEmbedding` | `nomic-ai/nomic-embed-text-v1.5-GGUF/nomic-embed-text-v1.5.f16.gguf` | `1536` | `openai.OpenAI` | Sources: [mem0/embeddings/ollama.py:12-19](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/ollama.py#L12-L19), [mem0/embeddings/fastembed.py:11-20](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/fastembed.py#L11-L20), [mem0/embeddings/lmstudio.py:9-17](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/lmstudio.py#L9-L17) ### Ollama Client Integration and Model Verification The `OllamaEmbedding` adapter initializes a local client using `self.config.ollama_base_url` and verifies model availability against running instances. It normalizes model specifiers by appending `:latest` when a colon is absent from the name. ```python @staticmethod def _normalize_model_name(name: str) -> str: return name if ":" in name else f"{name}:latest" def _ensure_model_exists(self): """ Ensure the specified model exists locally. If not, pull it from Ollama. """ local_models = self.client.list()["models"] target = self._normalize_model_name(self.config.model) if not any( self._normalize_model_name(model.get("name", "")) == target or self._normalize_model_name(model.get("model", "")) == target for model in local_models ): self.client.pull(self.config.model) ``` Sources: [mem0/embeddings/ollama.py:22-38](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/ollama.py#L22-L38) > [!WARNING] > If the normalized target model is missing from the local Ollama instance list, `_ensure_model_exists()` automatically issues a blocking `self.client.pull()` call for the model. Sources: [mem0/embeddings/ollama.py:26-38](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/ollama.py#L26-L38) Single and batch text embeddings are generated by calling `self.client.embed()`. If empty lists are returned or response counts fail to match input text lengths, a `ValueError` is raised. ```python def embed(self, text, memory_action: Optional[Literal["add", "search", "update"]] = None): """ Get the embedding for the given text using Ollama. Args: text (str): The text to embed. memory_action (optional): The type of embedding to use. Must be one of "add", "search", or "update". Defaults to None. Returns: list: The embedding vector. """ response = self.client.embed(model=self.config.model, input=text) embeddings = response.get("embeddings") or [] if not embeddings: raise ValueError(f"Ollama embed() returned no embeddings for model '{self.config.model}'") return embeddings[0] def embed_batch(self, texts, memory_action="add"): """Embed multiple texts in a single Ollama API call.""" if not texts: return [] response = self.client.embed(model=self.config.model, input=texts) embeddings = response.get("embeddings") or [] if len(embeddings) != len(texts): raise ValueError(f"Ollama embed() returned {len(embeddings)} embeddings for {len(texts)} texts using model '{self.config.model}'") return embeddings ``` Sources: [mem0/embeddings/ollama.py:39-63](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/ollama.py#L39-L63) ### FastEmbed and LMStudio In-Process Vectors The `FastEmbedEmbedding` adapter executes dense vector generation via the ONNX runtime through `TextEmbedding`. It replaces newline characters with spaces in input texts before generating embedding outputs. ```python def embed(self, text, memory_action: Optional[Literal["add", "search", "update"]] = None): """ Convert the text to embeddings using FastEmbed running in the Onnx runtime Args: text (str): The text to embed. memory_action (optional): The type of embedding to use. Must be one of "add", "search", or "update". Defaults to None. Returns: list: The embedding vector. """ text = text.replace("\n", " ") embeddings = list(self.dense_model.embed(text)) return embeddings[0].tolist() ``` Sources: [mem0/embeddings/fastembed.py:21-32](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/fastembed.py#L21-L32) The `LMStudioEmbedding` adapter communicates with local LM Studio instances through an OpenAI-compatible client interface, defaulting to an `api_key` value of `"lm-studio"`. ```python def embed(self, text, memory_action: Optional[Literal["add", "search", "update"]] = None): """ Get the embedding for the given text using LM Studio. Args: text (str): The text to embed. memory_action (optional): The type of embedding to use. Must be one of "add", "search", or "update". Defaults to None. Returns: list: The embedding vector. """ text = text.replace("\n", " ") return self.client.embeddings.create(input=[text], model=self.config.model).data[0].embedding ``` Sources: [mem0/embeddings/lmstudio.py:19-30](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/lmstudio.py#L19-L30) Batch inputs in `LMStudioEmbedding` have newline characters replaced, are sorted by their response index fields, and are validated to ensure output counts match the input batch length. ```python def embed_batch(self, texts, memory_action="add"): if not texts: return [] cleaned = [t.replace("\n", " ") for t in texts] response = self.client.embeddings.create(input=cleaned, model=self.config.model) sorted_data = sorted(response.data, key=lambda x: x.index) embeddings = [item.embedding for item in sorted_data] if len(embeddings) != len(texts): raise ValueError( f"LM Studio embed_batch() returned {len(embeddings)} embeddings for {len(texts)} texts" f" using model '{self.config.model}'" ) return embeddings ``` Sources: [mem0/embeddings/lmstudio.py:31-43](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/lmstudio.py#L31-L43) ## Hugging Face and Third-Party Bridges ### Hugging Face Transformer and TEI Integration The `HuggingFaceEmbedding` adapter supports two distinct operational modes determined by the presence of a base URL: local in-process execution using `SentenceTransformer` or remote API calls via an OpenAI-compatible client wrapper pointing to a Text Embeddings Inference (TEI) endpoint. When `huggingface_base_url` is configured, the client initializes using `self.config.api_key`, the `HUGGINGFACE_API_KEY` environment variable, or falls back to a default value of `"hf"`, defaulting the model identifier to `"tei"`. Without a base URL, the adapter loads local transformer weights using `SentenceTransformer` with a default model of `"multi-qa-MiniLM-L6-cos-v1"`, automatically resolving embedding dimensions via `model.get_sentence_embedding_dimension()`. ```python class HuggingFaceEmbedding(EmbeddingBase): def __init__(self, config: Optional[BaseEmbedderConfig] = None): super().__init__(config) if self.config.huggingface_base_url: api_key = self.config.api_key or os.getenv("HUGGINGFACE_API_KEY") or "hf" self.client = OpenAI(base_url=self.config.huggingface_base_url, api_key=api_key) self.config.model = self.config.model or "tei" else: self.config.model = self.config.model or "multi-qa-MiniLM-L6-cos-v1" self.model = SentenceTransformer(self.config.model, **self.config.model_kwargs) self.config.embedding_dims = self.config.embedding_dims or self.model.get_sentence_embedding_dimension() ``` Sources: [mem0/embeddings/huggingface.py:16-30](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/huggingface.py#L16-L30) During batch embedding operations, remote TEI responses sort items by their `index` attribute to align output vectors with input sequences. Both remote and local execution branches enforce validation checks that raise a `ValueError` if the returned embedding count diverges from the input text collection length. ```python def embed_batch(self, texts, memory_action="add"): if not texts: return [] if self.config.huggingface_base_url: response = self.client.embeddings.create(input=texts, model=self.config.model, **self.config.model_kwargs) sorted_data = sorted(response.data, key=lambda x: x.index) embeddings = [item.embedding for item in sorted_data] if len(embeddings) != len(texts): raise ValueError( f"HuggingFace embed_batch() returned {len(embeddings)} embeddings for {len(texts)} texts" f" using model '{self.config.model}'" ) return embeddings else: result = self.model.encode(texts, convert_to_numpy=True).tolist() if len(result) != len(texts): raise ValueError( f"HuggingFace embed_batch() returned {len(result)} embeddings for {len(texts)} texts" f" using model '{self.config.model}'" ) return result ``` Sources: [mem0/embeddings/huggingface.py:48-68](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/huggingface.py#L48-L68) > [!WARNING] > Library loggers for `transformers`, `sentence_transformers`, and `huggingface_hub` are explicitly restricted to the `WARNING` level during module initialization to suppress excessive console output. Sources: [mem0/embeddings/huggingface.py:11-13](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/huggingface.py#L11-L13) ### Together AI Embedding Adapter The `TogetherEmbedding` adapter interfaces with Together AI to generate dense vectors through an OpenAI-compatible SDK client. It defaults to the `"intfloat/multilingual-e5-large-instruct"` model with fixed embedding dimensions of `1024`, authenticating via `self.config.api_key` or the `TOGETHER_API_KEY` environment variable. ```python class TogetherEmbedding(EmbeddingBase): def __init__(self, config: Optional[BaseEmbedderConfig] = None): super().__init__(config) self.config.model = self.config.model or "intfloat/multilingual-e5-large-instruct" api_key = self.config.api_key or os.getenv("TOGETHER_API_KEY") self.config.embedding_dims = self.config.embedding_dims or 1024 self.client = Together(api_key=api_key) ``` Sources: [mem0/embeddings/together.py:10-18](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/together.py#L10-L18) Single text queries invoke `self.client.embeddings.create()`, returning the embedding vector from the first response data object. Batch requests sort response objects by their index before extracting vectors and validating length parity against the input array. ```python def embed(self, text, memory_action: Optional[Literal["add", "search", "update"]] = None): """ Get the embedding for the given text using OpenAI. Args: text (str): The text to embed. memory_action (optional): The type of embedding to use. Must be one of "add", "search", or "update". Defaults to None. Returns: list: The embedding vector. """ return self.client.embeddings.create(model=self.config.model, input=text).data[0].embedding def embed_batch(self, texts, memory_action="add"): if not texts: return [] response = self.client.embeddings.create(model=self.config.model, input=texts) sorted_data = sorted(response.data, key=lambda x: x.index) embeddings = [item.embedding for item in sorted_data] if len(embeddings) != len(texts): raise ValueError( f"Together embed_batch() returned {len(embeddings)} embeddings for {len(texts)} texts" f" using model '{self.config.model}'" ) return embeddings ``` Sources: [mem0/embeddings/together.py:19-43](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/together.py#L19-L43) ### LangChain Wrapper Bridge The `LangchainEmbedding` adapter wraps external LangChain embedding instances to conform to the core embedding interface. Initialization verifies that `config.model` is supplied and is a valid instance of the LangChain `Embeddings` base class, storing it internally as `self.langchain_model`. ```python class LangchainEmbedding(EmbeddingBase): def __init__(self, config: Optional[BaseEmbedderConfig] = None): super().__init__(config) if self.config.model is None: raise ValueError("`model` parameter is required") if not isinstance(self.config.model, Embeddings): raise ValueError("`model` must be an instance of Embeddings") self.langchain_model = self.config.model ``` Sources: [mem0/embeddings/langchain.py:12-23](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/langchain.py#L12-L23) Embedding generation delegates directly to the underlying LangChain model instance via `embed_query`. If the LangChain library is not present in the environment, an `ImportError` is raised during module import. ```python try: from langchain.embeddings.base import Embeddings except ImportError: raise ImportError("langchain is not installed. Please install it using `pip install langchain`") ``` Sources: [mem0/embeddings/langchain.py:6-9](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/langchain.py#L6-L9), [mem0/embeddings/langchain.py:24-35](https://github.com/blade47/mem0/blob/b7ad69afda6b6ed030347c66d48a13e4de9dec08/mem0/embeddings/langchain.py#L24-L35) ## Related - [TypeScript Embedding Adapters](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/technical/llm-providers/typescript-embedding-adapters) - [Vector Store Architecture](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/technical/vector-stores/vector-store-architecture) ## Sitemap See the full [sitemap](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/llms.txt) for all pages in this wiki.