Configure an Embedding Provider

The complete reference for wiring an embedding provider into MemorySettings.embedding.

For the big-picture choice between providers see Bring Your Own Model. Embedding adapters share the EmbeddingProvider Protocol; the same wiring patterns apply across cloud APIs and local models.

This page configures client-side embedding on the bolt backend. On NAMS, embedding runs server-side — the workspace’s embedding model and vector dimension are fixed when the database is provisioned (currently Amazon Titan Text v2 at 1024 dimensions by default, or OpenAI text-embedding-3-small at 1536 where configured). MemorySettings.embedding is therefore ignored on NAMS. See Bolt vs NAMS.

Set via a provider string

from neo4j_agent_memory import MemorySettings

settings = MemorySettings(
    neo4j={"password": "p"},
    embedding="openai/text-embedding-3-small",
)

The factory looks up the model in neo4j_agent_memory.llm.defaults.EMBEDDING_DIMENSIONS to populate dimensions automatically. For unknown models, pass an explicit instance with dimensions=N (see below).

Set via an explicit Provider instance

from neo4j_agent_memory import MemorySettings
from neo4j_agent_memory.llm.adapters.openai import OpenAIEmbeddingProvider

settings = MemorySettings(
    neo4j={"password": "p"},
    embedding=OpenAIEmbeddingProvider(
        "openai/text-embedding-3-large",
        dimensions=1024,    # request smaller output (OpenAI dimension reduction)
        batch_size=200,
    ),
)

Use local sentence-transformers

No API key needed; embeddings stay on your machine.

from neo4j_agent_memory import MemorySettings

settings = MemorySettings(
    neo4j={"password": "p"},
    embedding="BAAI/bge-small-en-v1.5",      # 384 dims
)

Install: pip install neo4j-agent-memory[sentence-transformers]. First call downloads the model (~50-500 MB depending on choice). Subsequent calls hit the local cache.

Tune the device:

from neo4j_agent_memory.llm.adapters.sentence_transformers import (
    SentenceTransformersProvider,
)

embedder = SentenceTransformersProvider(
    "BAAI/bge-large-en-v1.5",
    device="cuda",   # or "mps" on Apple Silicon
)

Use a custom / unknown model

For embedding models not in the defaults table, you must pass dimensions= explicitly. Otherwise the adapter raises a clear error:

from neo4j_agent_memory.llm.adapters.openai import OpenAIEmbeddingProvider

# Will raise:
#   ValueError: Could not determine dimensions for embedding model
#   'openai/my-unreleased-model'. Pass dimensions=N explicitly or use a
#   model in the defaults table.
embedder = OpenAIEmbeddingProvider("openai/my-unreleased-model")

# Correct:
embedder = OpenAIEmbeddingProvider("openai/my-unreleased-model", dimensions=2048)

Sentence-transformers is the one exception: when the model is not in the defaults table, the adapter introspects model.get_sentence_embedding_dimension() on first embed() call, at the cost of a one-time model-download delay.

Use AWS Bedrock embeddings

from neo4j_agent_memory import MemorySettings
from neo4j_agent_memory.llm.adapters.bedrock import BedrockEmbeddingProvider

settings = MemorySettings(
    neo4j={"password": "p"},
    embedding=BedrockEmbeddingProvider(
        "bedrock/amazon.titan-embed-text-v2:0",
        aws_region="us-east-1",
        aws_profile="my-aws-profile",    # optional
    ),
)

The adapter delegates to the existing BedrockEmbedder and reads the standard boto3 credential chain.

Use Vertex AI embeddings

from neo4j_agent_memory import MemorySettings
from neo4j_agent_memory.llm.adapters.vertex_ai import VertexAIEmbeddingProvider

settings = MemorySettings(
    neo4j={"password": "p"},
    embedding=VertexAIEmbeddingProvider(
        "vertex_ai/gemini-embedding-001",
        project_id="my-gcp-project",
        location="us-central1",
        dimensions=768,
    ),
)

gemini-embedding-001 is the current Vertex AI embedding model; text-embedding-004 and the textembedding-gecko* family were retired by Google and now raise an error naming the replacement. The underlying VertexAIEmbedder truncates to 768 dimensions by default (the model emits 3072 natively) so that vector indexes created against the previous default keep working — pass dimensions= here to match whatever you configure there. See the Vertex AI model table for the trade-off.

Vertex AI as a chat provider routes through LiteLLM (no native LLM adapter). Embeddings are native because the existing Vertex AI embedder predates the Protocol and is well-tested.

Configure via the MCP CLI

neo4j-agent-memory mcp serve \
  --password mypw \
  --embedding BAAI/bge-small-en-v1.5 \
  --embedding-dimensions 384      # override for unknown models

Or env var:

export NAM_EMBEDDING=BAAI/bge-small-en-v1.5
neo4j-agent-memory mcp serve --password mypw

Verify dimensions at runtime

from neo4j_agent_memory.llm import from_provider

embedder = from_provider("BAAI/bge-small-en-v1.5", kind="embedding")
assert embedder.dimensions == 384

# The vector should match
vector = await embedder.embed_one("test sentence")
assert len(vector) == 384

Migrate between embedding models

MemoryClient.connect() raises EmbeddingDimensionMismatchError if you change embedding model and existing vector indexes have a different size. The error lists every offending index and points at the migration runbook.

See Migrate Embedding Model for the three remediation options (rebuild, revert, re-embed in place).

Related