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.

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/text-embedding-004",
        project_id="my-gcp-project",
        location="us-central1",
    ),
)

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