Configuration reference

Python configuration types, defaults, constraints, and integration limits. The field tables are on the four subpages listed under On this subsystem; each lists both the Python kwarg and its NAM_GROUP__FIELD environment variable. See Environment variables for prefix rules, nesting, and env-only facts, and Backend capabilities for data scope.

On this subsystem

MemorySettings

Import configuration classes from neo4j_agent_memory.config.settings; MemorySettings, BoltSettings, and NamsSettings are also available from neo4j_agent_memory.

BoltSettings pins backend="bolt"; NamsSettings pins backend="nams". MemorySettings resolves an unset backend to NAMS when a NAMS key is populated, otherwise bolt. Explicit backend selection takes precedence. NAMS is a continuously shipped service; /v1 is its REST protocol prefix, not a service release number.

Field Accepted value Default / behavior

backend

bolt, nams, or None

Auto-resolved when unset.

neo4j

Neo4jConfig or dictionary

Local bolt URI, neo4j user/database, empty password.

nams

NamsConfig or dictionary

Hosted endpoint and transport defaults; see NAMS connection.

embedding

Provider string, EmbeddingProvider instance, legacy EmbeddingConfig or dictionary

Implicit OpenAI embedding configuration. None is rejected.

llm

Provider string, LLMProvider instance, legacy LLMConfig/dictionary, or None

Implicitly supplies LLMConfig when the selected extraction needs an LLM. Explicit None is validated against extraction settings.

schema_config

SchemaConfig or dictionary

POLE+O settings. On bolt it also selects the ontology the client extracts and validates against, and the validation mode.

extraction

ExtractionConfig or dictionary

Multi-stage pipeline with all three stages enabled.

resolution

ResolutionConfig or dictionary

Composite resolution. On bolt, extracted mentions are resolved against stored entities while a message is stored (resolve_on_ingest=True), and the same thresholds band long_term.add_entity deduplication.

memory

MemoryConfig or dictionary

Declared memory behavior values; see Memory behavior.

search

SearchConfig or dictionary

Declared search values; see Search configuration.

geocoding

GeocodingConfig or dictionary

Disabled.

enrichment

EnrichmentConfig or dictionary

Disabled.

MemorySettings.from_dict(config) is equivalent to passing the dictionary as keyword arguments. The field is schema_config, not schema. All child config models reject unknown fields, as does direct MemorySettings construction.

The ontology is resolved once per connection from MemoryClient(ontology=…​), schema_config and the active stored ontology version; see Ontology precedence for the order and Graph schema configuration for the fields.

Provider shapes and no-LLM operation

The runnable examples use Aura connection values exported by the Aura connection setup. The Default columns in the field tables on the subpages describe the SDK defaults, not these values.

Provider strings resolve immediately through from_provider. Pass a constructed provider for constructor-specific options such as API base URL, timeout, or custom dimensions. Explicit legacy EmbeddingConfig/LLMConfig inputs still work in 0.7.0 and emit DeprecationWarning; prefer provider strings/instances for new code. The warning’s historical removal date does not describe current availability.

import os
from neo4j_agent_memory import BoltSettings
from neo4j_agent_memory.config.settings import ExtractionConfig

settings = BoltSettings(
    neo4j={
        "uri": os.environ["NEO4J_URI"],
        "username": os.environ["NEO4J_USERNAME"],
        "password": os.environ["NEO4J_PASSWORD"],
        "database": os.getenv("NEO4J_DATABASE", "neo4j"),
    },
    embedding="openai/text-embedding-3-small",
    llm="openai/gpt-4o-mini",
)
# No LLM calls: also disable the pipeline's LLM fallback.
local_settings = BoltSettings(
    neo4j={
        "uri": os.environ["NEO4J_URI"],
        "username": os.environ["NEO4J_USERNAME"],
        "password": os.environ["NEO4J_PASSWORD"],
        "database": os.getenv("NEO4J_DATABASE", "neo4j"),
    },
    embedding="BAAI/bge-small-en-v1.5",
    llm=None,
    extraction=ExtractionConfig(extractor_type="gliner", enable_llm_fallback=False),
)

The examples require their corresponding provider extras; local models may download on first use. llm=None with extractor_type="llm", or a pipeline with enable_llm_fallback=True, raises a validation error. To disable extraction entirely use extractor_type="none".

Sources and precedence

From highest to lowest: explicit constructor values, process environment variables, filtered .env values, configured file-secret sources, then defaults. .env is read from the current directory; pass _env_file="path/to/file" to select another file or _env_file=None to disable dotenv loading. It is not a YAML configuration loader.

NAM_ variables use __ for nested fields. JSON represents arrays and dictionaries. Unrelated top-level dotenv keys are filtered; misspelled nested keys in a recognized group still fail validation. A variable that is not a settings field does not create a new feature.

MEMORY_API_KEY, MEMORY_ENDPOINT, and MEMORY_WORKSPACE_ID are additional process-environment aliases resolved after settings sources. They populate an unset NAMS API key/workspace and an endpoint not explicitly set on NamsConfig. They are not loaded from a dotenv file by that alias resolver. Use NAM_NAMS__…​ in .env or explicitly load process environment aliases in your application.

import os
from neo4j_agent_memory import BoltSettings

os.environ["NAM_NEO4J__URI"] = "neo4j+s://<environment-instance-id>.databases.neo4j.io"
settings = BoltSettings(neo4j={
    "uri": "neo4j+s://<explicit-instance-id>.databases.neo4j.io",
    "username": os.environ["NEO4J_USERNAME"],
    "password": os.environ["NEO4J_PASSWORD"],
    "database": os.getenv("NEO4J_DATABASE", "neo4j"),
})
assert settings.neo4j.uri == "neo4j+s://<explicit-instance-id>.databases.neo4j.io"

See also