Environment variables reference

Environment inputs recognized by Python MemorySettings and its optional integrations. All declared child fields are listed, including settings that the current MemoryClient does not automatically consume; those limits are stated explicitly.

This page is long; jump straight to a prefix instead of scrolling:

Section Variable prefix

Loading and precedence

NAM_BACKEND, NAM_EMBEDDING, NAM_LLM

NAMS process aliases

MEMORY_API_KEY, MEMORY_ENDPOINT, MEMORY_WORKSPACE_ID

Neo4j connection

NAM_NEO4J__*

NAMS connection

NAM_NAMS__*

Embedding configuration

NAM_EMBEDDING__*

LLM configuration

NAM_LLM__*

Graph schema configuration

NAM_SCHEMA_CONFIG__*

Extraction configuration

NAM_EXTRACTION__*

Resolution configuration

NAM_RESOLUTION__*

Memory behavior

NAM_MEMORY__*

Search configuration

NAM_SEARCH__*

Geocoding configuration

NAM_GEOCODING__*

Enrichment configuration

NAM_ENRICHMENT__*

Integration limits

Declared fields the client does not apply automatically

CLI and provider environment

NEO4J_*, MCP_USER_ID, provider SDK variables

Example dotenv configuration

A complete .env example

Test harness switches

RUN_INTEGRATION_TESTS and related test-only switches

Loading and precedence

NAM_GROUP__FIELD maps to settings.group.field. Constructor values override process environment, then .env, configured file secrets, and defaults. Arrays/dictionaries use JSON. Unknown nested fields in a recognized group are validation errors. See Configuration sources.

Use lowercase true/false for booleans and quote JSON lists in a shell. Do not mix a top-level provider string with nested fields for that same provider; use a constructed provider when you need its additional options.

Variable Default Behavior

NAM_BACKEND

Unset

bolt or nams; explicit selection overrides auto-detection.

NAM_EMBEDDING

Implicit OpenAI config

Provider string, for example openai/text-embedding-3-small; resolves through from_provider.

NAM_LLM

Resolved from extraction requirements

Provider string, for example openai/gpt-4o-mini.

NAMS process aliases

These aliases are read from process environment after settings-source loading. Use the NAM_NAMS__…​ form in a dotenv file unless your application explicitly loads that file into process environment.

Alias Default Behavior

MEMORY_API_KEY

Unset

Populates an unset NAMS key. A populated key selects NAMS when backend is not pinned.

MEMORY_ENDPOINT

Unset

Overrides the default NAMS endpoint if endpoint was not explicitly set.

MEMORY_WORKSPACE_ID

Unset

Populates an unset workspace ID, sent as X-Workspace-Id. Workspace access is determined by your credentials.

 
export MEMORY_API_KEY=nams_example_replace_with_your_key
export NAM_BACKEND=nams
export NAM_NAMS__TIMEOUT=60

Neo4j connection

NAM_NEO4J__ prefix. All scalar-valued; none need JSON encoding.

Variable Default Meaning

NAM_NEO4J__URI

bolt://localhost:7687

Neo4j connection URI

NAM_NEO4J__USERNAME

neo4j

Neo4j username

NAM_NEO4J__PASSWORD

required

Neo4j password

NAM_NEO4J__DATABASE

neo4j

Neo4j database name

NAM_NEO4J__MAX_CONNECTION_POOL_SIZE

50

Maximum connection pool size

NAM_NEO4J__CONNECTION_TIMEOUT

30.0

Connection timeout in seconds

NAM_NEO4J__MAX_TRANSACTION_RETRY_TIME

30.0

Maximum transaction retry time in seconds

NAM_NEO4J__MAX_CONNECTION_LIFETIME

300

Maximum lifetime of a pooled connection in seconds

NAM_NEO4J__LIVENESS_CHECK_TIMEOUT

60

Seconds a connection can be idle before a liveness check

NAM_NEO4J__KEEP_ALIVE

true

Enable TCP keep-alive on connections

See Neo4j connection for the Python kwarg names and constraints.

NAMS connection

NAM_NAMS__ prefix. NAM_NAMS__HEADERS is a JSON object, for example NAM_NAMS__HEADERS='{"X-Trace-Id": "abc"}'.

Variable Default Meaning

NAM_NAMS__ENDPOINT

https://memory.neo4jlabs.com/v1

Base URL

NAM_NAMS__API_KEY

unset

NAMS API key (nams_…​); an unset value may be populated from MEMORY_API_KEY

NAM_NAMS__WORKSPACE_ID

unset

Sent as X-Workspace-Id when set

NAM_NAMS__TIMEOUT

30.0

HTTP request timeout in seconds

NAM_NAMS__MAX_RETRIES

3

Max retry attempts for 429/5xx/network errors

NAM_NAMS__RETRY_BACKOFF_SECONDS

0.5

Base exponential backoff between retries

NAM_NAMS__HEADERS

{}

Extra HTTP headers added to every request

NAM_NAMS__VALIDATE_ON_CONNECT

true

Probe an authenticated connection when connecting

NAM_NAMS__TRANSPORT_MODE

auto

auto, rest, or bridge wire-protocol override

See NAMS connection for the full field table.

Embedding configuration

NAM_EMBEDDING__ prefix, legacy nested-provider settings — provider strings/instances use adapter-specific configuration instead (see Adapters). All fields are scalar-valued.

Variable Default Meaning

NAM_EMBEDDING__PROVIDER

openai

Embedding provider to use

NAM_EMBEDDING__MODEL

text-embedding-3-small

Embedding model name

NAM_EMBEDDING__DIMENSIONS

1536

Embedding dimensions

NAM_EMBEDDING__API_KEY

unset

API key for embedding provider

NAM_EMBEDDING__BATCH_SIZE

100

Batch size for embeddings

NAM_EMBEDDING__DEVICE

cpu

Device for sentence transformers (cpu/cuda)

NAM_EMBEDDING__PROJECT_ID

unset

GCP project ID for Vertex AI

NAM_EMBEDDING__LOCATION

us-central1

GCP region for Vertex AI

NAM_EMBEDDING__TASK_TYPE

RETRIEVAL_DOCUMENT

Vertex AI task type

NAM_EMBEDDING__OUTPUT_DIMENSIONALITY

unset (768 for Vertex AI)

Vertex AI output dimensionality

NAM_EMBEDDING__AWS_REGION

unset

AWS region for Bedrock

NAM_EMBEDDING__AWS_PROFILE

unset

AWS credentials profile name

See Embedding configuration for the full field table.

LLM configuration

NAM_LLM__ prefix, legacy nested-provider settings — provider strings/instances use adapter-specific configuration instead. All fields are scalar-valued.

Variable Default Meaning

NAM_LLM__PROVIDER

openai

LLM provider to use

NAM_LLM__MODEL

gpt-4o-mini

LLM model name

NAM_LLM__API_KEY

unset

API key for LLM provider

NAM_LLM__TEMPERATURE

0.0

LLM temperature — not automatically applied by MemoryClient

NAM_LLM__MAX_TOKENS

4096

Maximum tokens for LLM — not automatically applied by MemoryClient

See LLM configuration for the full field table and the temperature / max_tokens integration limit.

Graph schema configuration

NAM_SCHEMA_CONFIG__ prefix. NAM_SCHEMA_CONFIG__ENTITY_TYPES is a JSON array, for example NAM_SCHEMA_CONFIG__ENTITY_TYPES='["PERSON", "ORGANIZATION"]'. On bolt these fields select the ontology the client extracts and validates against, resolved once per connection.

Variable Default Meaning

NAM_SCHEMA_CONFIG__MODEL

poleo

Schema model (poleo, legacy, custom); custom with ENTITY_TYPES builds an ad-hoc ontology

NAM_SCHEMA_CONFIG__ENTITY_TYPES

unset

Custom entity types (overrides model default when model=custom)

NAM_SCHEMA_CONFIG__ENABLE_SUBTYPES

true

Whether to track entity subtypes — not automatically applied by MemoryClient

NAM_SCHEMA_CONFIG__STRICT_TYPES

false

Selects strict validation when no validation mode is set or stored

NAM_SCHEMA_CONFIG__CUSTOM_SCHEMA_PATH

unset

Schema file (.json/.yaml) holding an EntitySchemaConfig or an ontology document; consulted after ONTOLOGY_PATH

NAM_SCHEMA_CONFIG__ONTOLOGY_PATH

unset

Ontology document (.json/.yaml), for example /etc/ontology.yaml

NAM_SCHEMA_CONFIG__USE_ACTIVE_ONTOLOGY

true

Adopt the ontology version activated in the database

NAM_SCHEMA_CONFIG__ONTOLOGY_TEMPLATE

poleo

Built-in template used as the final fallback

NAM_SCHEMA_CONFIG__VALIDATION_MODE

unset

permissive or strict enforcement on the write paths

NAM_SCHEMA_CONFIG__BACKFILL_RELATION_TYPES

true

Allow the one-time RELATED_TO type backfill on connect

See Graph schema configuration for the full field table, the ontology precedence, and the remaining integration limit.

Extraction configuration

NAM_EXTRACTION__ prefix. NAM_EXTRACTION__ENTITY_TYPES is a JSON array. The GLINER_* names keep their spelling but configure GLiNER2.5 (the gliner2 extra). There are no batch or streaming fields in this settings group — those are method arguments, not environment variables; GLINER_MAX_WORDS and GLINER_CHUNK_OVERLAP only window long input inside the GLiNER2.5 stage.

Variable Default Meaning

NAM_EXTRACTION__EXTRACTOR_TYPE

pipeline

Type of entity extractor (llm/gliner/spacy/pipeline/none)

NAM_EXTRACTION__ENABLE_SPACY

true

Enable spaCy in extraction pipeline

NAM_EXTRACTION__ENABLE_GLINER

true

Enable the GLiNER2.5 stage in the extraction pipeline

NAM_EXTRACTION__ENABLE_LLM_FALLBACK

true

Enable LLM as fallback in pipeline

NAM_EXTRACTION__MERGE_STRATEGY

confidence

Strategy for merging results from multiple extractors

NAM_EXTRACTION__FALLBACK_ON_EMPTY

true

Continue to next stage if current stage returns no results

NAM_EXTRACTION__SPACY_MODEL

en_core_web_sm

spaCy model name

NAM_EXTRACTION__SPACY_CONFIDENCE

0.85

Default confidence score for spaCy extractions

NAM_EXTRACTION__GLINER_MODEL

fastino/gliner2.5-base-v1

GLiNER2.5 checkpoint (small-v1, base-v1, or multi-v1); GLiNER v1 ids are rejected when the extractor is built

NAM_EXTRACTION__GLINER_THRESHOLD

0.5

GLiNER2.5 entity confidence threshold

NAM_EXTRACTION__GLINER_RELATION_THRESHOLD

unset

Confidence floor for decoded relations

NAM_EXTRACTION__GLINER_DEVICE

cpu

Device for the GLiNER2.5 model (cpu/cuda/mps)

NAM_EXTRACTION__GLINER_SCHEMA

unset

Built-in domain template (poleo, podcast, news, scientific, business, entertainment, medical, legal); replaces the resolved ontology for GLiNER2.5

NAM_EXTRACTION__GLINER_MAX_WORDS

384

Longest input decoded in one pass; longer text is windowed

NAM_EXTRACTION__GLINER_CHUNK_OVERLAP

64

Word overlap between windows

NAM_EXTRACTION__GLINER_OVERLAP_POLICY

unset

Span-overlap policy for the attribute pass (flat/nested/allow/longest)

NAM_EXTRACTION__GLINER_EXTRACT_ATTRIBUTES

false

Run the opt-in attribute pass for the ontology’s enum properties

NAM_EXTRACTION__GLINER_QUANTIZE

false

Load the GLiNER2.5 weights in fp16

NAM_EXTRACTION__GLINER_COMPILE

false

Run the GLiNER2.5 weights through torch.compile

NAM_EXTRACTION__LLM_MODEL

gpt-4o-mini

LLM model for extraction

NAM_EXTRACTION__ENTITY_TYPES

["PERSON", "ORGANIZATION", "LOCATION", "EVENT", "OBJECT"]

Entity types for the LLM extractor (POLE+O by default)

NAM_EXTRACTION__EXTRACT_RELATIONS

true

Whether to extract relations

NAM_EXTRACTION__EXTRACT_PREFERENCES

true

Whether to extract preferences

NAM_EXTRACTION__CONFIDENCE_THRESHOLD

0.5

Floor applied to the merged result of EXTRACTOR_TYPE=pipeline

See Extraction configuration for the full field table.

Resolution configuration

NAM_RESOLUTION__ prefix. All scalar-valued. NAM_RESOLUTION__EMBEDDING_THRESHOLD and NAM_RESOLUTION__MATCH_SAME_TYPE_ONLY are not valid fields; the semantic threshold field is NAM_RESOLUTION__SEMANTIC_THRESHOLD. Deduplication thresholds live here too: AUTO_MERGE_THRESHOLD and REVIEW_THRESHOLD band both message ingestion and long_term.add_entity.

Variable Default Meaning

NAM_RESOLUTION__STRATEGY

composite

Resolution strategy (exact/fuzzy/semantic/composite/none); composite builds OntologyResolver on bolt

NAM_RESOLUTION__EXACT_THRESHOLD

1.0

Exact match threshold

NAM_RESOLUTION__FUZZY_THRESHOLD

0.85

Fuzzy match threshold

NAM_RESOLUTION__SEMANTIC_THRESHOLD

0.8

Semantic match threshold

NAM_RESOLUTION__FUZZY_SCORER

token_sort_ratio

Fuzzy matching scorer — not forwarded by MemoryClient

NAM_RESOLUTION__RESOLVE_ON_INGEST

true

Resolve extracted mentions while storing a message; the single opt-out for ingest-time resolution

NAM_RESOLUTION__AUTO_MERGE_THRESHOLD

0.90

Merge a mention onto the match at or above this score

NAM_RESOLUTION__REVIEW_THRESHOLD

0.85

Store the mention plus a pending SAME_AS edge at or above this score; must not exceed AUTO_MERGE_THRESHOLD

NAM_RESOLUTION__CANDIDATE_LIMIT

12

Blocking candidates per mention and per bucket

NAM_RESOLUTION__USE_ALIAS_GAZETTEER

true

Use the ontology’s aliases as blocking keys and as a 1.0 match rule

NAM_RESOLUTION__USE_EMBEDDING_BLOCKING

true

Also block via the entity vector index (needs an embedder)

NAM_RESOLUTION__CONTEXT_WINDOW_CHARS

90

Half-width of the mention context window used in scoring

NAM_RESOLUTION__SCOPE

global

global or user; user restricts candidates to entities the tenant has mentioned

See Resolution configuration for the full field table.

Memory behavior

NAM_MEMORY__ prefix. All fields are scalar-valued.

Variable Default Meaning

NAM_MEMORY__DEFAULT_CONVERSATION_LIMIT

50

Default conversation message limit — not automatically applied by MemoryClient

NAM_MEMORY__MESSAGE_EMBEDDING_ENABLED

true

Enable message embeddings — not automatically applied by MemoryClient

NAM_MEMORY__PREFERENCE_CONFIDENCE_THRESHOLD

0.7

Preference confidence threshold — not automatically applied by MemoryClient

NAM_MEMORY__FACT_DEDUPLICATION_ENABLED

true

Enable fact deduplication — not automatically applied by MemoryClient

NAM_MEMORY__TRACE_EMBEDDING_ENABLED

true

Enable reasoning trace embeddings — not automatically applied by MemoryClient

NAM_MEMORY__TOOL_STATS_ENABLED

true

Enable tool usage statistics — not automatically applied by MemoryClient

NAM_MEMORY__MULTI_TENANT

false

Require user_identifier on the guarded bolt writes

NAM_MEMORY__WRITE_MODE

sync

sync or buffered — controls client.buffered.submit(…​)

NAM_MEMORY__MAX_PENDING

200

Maximum in-flight buffered writes

NAM_MEMORY__CONVERSATION_TTL_DAYS

unset

TTL value for archive_expired_conversations(ttl_days=…​) — not automatically applied

NAM_MEMORY__AUDIT_READ

false

Audit preference for client.consolidation.record_read_audit(…​) — not automatically applied

See Memory behavior for the full field table, including write_mode/max_pending (buffered writes) and the integration limits on the remaining fields.

Search configuration

NAM_SEARCH__ prefix. All scalar-valued; none are automatically read by the memory stores.

Variable Default Meaning

NAM_SEARCH__DEFAULT_LIMIT

10

Default search limit

NAM_SEARCH__DEFAULT_THRESHOLD

0.7

Default similarity threshold

NAM_SEARCH__HYBRID_SEARCH_ENABLED

true

Enable hybrid search

NAM_SEARCH__GRAPH_DEPTH

2

Graph traversal depth for search

See Search configuration for the full field table.

Geocoding configuration

NAM_GEOCODING__ prefix. All fields are scalar-valued.

Variable Default Meaning

NAM_GEOCODING__ENABLED

false

Enable automatic geocoding of Location entities

NAM_GEOCODING__PROVIDER

nominatim

Geocoding provider to use (nominatim/google)

NAM_GEOCODING__API_KEY

unset

API key for geocoding provider (required for Google)

NAM_GEOCODING__CACHE_RESULTS

true

Cache geocoding results to avoid repeated API calls

NAM_GEOCODING__RATE_LIMIT_PER_SECOND

1.0

Client request rate limit for the configured geocoder

NAM_GEOCODING__USER_AGENT

neo4j-agent-memory

User-Agent sent by the configured geocoder

See Geocoding configuration for the full field table.

Enrichment configuration

NAM_ENRICHMENT__ prefix. NAM_ENRICHMENT__PROVIDERS and NAM_ENRICHMENT__ENTITY_TYPES are JSON arrays, for example NAM_ENRICHMENT__PROVIDERS='["wikimedia", "diffbot"]'.

Variable Default Meaning

NAM_ENRICHMENT__ENABLED

false

Enable automatic entity enrichment

NAM_ENRICHMENT__PROVIDERS

["wikimedia"]

Enrichment providers to use, in priority order

NAM_ENRICHMENT__DIFFBOT_API_KEY

unset

API key for Diffbot Knowledge Graph

NAM_ENRICHMENT__WIKIMEDIA_RATE_LIMIT

0.5

Seconds between Wikimedia API requests

NAM_ENRICHMENT__DIFFBOT_RATE_LIMIT

0.2

Seconds between Diffbot API requests

NAM_ENRICHMENT__CACHE_RESULTS

true

Cache enrichment results to avoid repeated API calls

NAM_ENRICHMENT__CACHE_TTL_HOURS

168

Hours to cache enrichment results

NAM_ENRICHMENT__BACKGROUND_ENABLED

true

Run enrichment in background (non-blocking)

NAM_ENRICHMENT__QUEUE_MAX_SIZE

1000

Maximum enrichment queue size

NAM_ENRICHMENT__MAX_RETRIES

3

Maximum retry attempts for failed enrichments

NAM_ENRICHMENT__RETRY_DELAY_SECONDS

60.0

Delay between retry attempts

NAM_ENRICHMENT__ENTITY_TYPES

["PERSON", "ORGANIZATION", "LOCATION", "EVENT"]

Entity types to enrich (empty = all types)

NAM_ENRICHMENT__MIN_CONFIDENCE

0.7

Minimum entity confidence to trigger enrichment

NAM_ENRICHMENT__LANGUAGE

en

Preferred language for enrichment data

NAM_ENRICHMENT__USER_AGENT

neo4j-agent-memory/1.0

User-Agent for API requests

See Enrichment configuration for the full field table.

Integration limits

The declared field inventory above is not an assertion of runtime wiring. See Configuration integration limits for provider, method-default, schema, TTL, and auditing behavior. The settings family is NAM_RESOLUTION__SEMANTIC_THRESHOLD; NAM_RESOLUTION__EMBEDDING_THRESHOLD and NAM_RESOLUTION__MATCH_SAME_TYPE_ONLY are invalid fields.

There are no NAM_DEDUPLICATION__..., NAM_OBSERVABILITY__..., or NAM_CLI__... settings groups; variables with those prefixes are ignored. Set deduplication thresholds with NAM_RESOLUTION__AUTO_MERGE_THRESHOLD and NAM_RESOLUTION__REVIEW_THRESHOLD. Batch sizes/concurrency/chunk sizes for extraction belong to method arguments, not ExtractionConfig environment fields.

CLI and provider environment

These inputs are consumed by command options or external provider adapters rather than becoming nested MemorySettings fields. Provider-specific availability depends on the installed extra.

Variable Consumer

NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD, NEO4J_DATABASE

CLI connection options (database is an MCP serve option). The Python settings family instead uses NAM_NEO4J__…​ and USERNAME.

MCP_USER_ID

MCP serve --user-id option.

NAM_LLM_API_KEY

MCP serve LLM API-key override; not a MemorySettings field.

OPENAI_API_KEY

OpenAI adapters/embedder when no explicit key is supplied.

ANTHROPIC_API_KEY

Anthropic adapter when no explicit key is supplied.

AWS_REGION, AWS_DEFAULT_REGION, AWS_PROFILE

Bedrock region/profile selection and AWS SDK configuration.

AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN

AWS SDK credential chain.

GOOGLE_APPLICATION_CREDENTIALS

Google SDK application-default credentials when using Vertex AI.

NAM_GEOCODING__API_KEY

Google geocoder key. There is no automatic GOOGLE_GEOCODING_API_KEY fallback; pass that application variable explicitly if you use it.

OPIK_API_KEY

Opik SDK credentials for the configured tracer.

OTEL_EXPORTER_OTLP_ENDPOINT

External OpenTelemetry exporter convention. The SDK tracer requires an explicit endpoint argument to create an exporter; the variable alone does not enable export.

The CLI does not automatically load .neo4j-memory.yaml. Review CLI reference for exact flags, including NAMS backend options.

Example dotenv configuration

Copy the credentials from the Aura connection setup.

This example uses the SDK’s native NAM_NEO4J__…​ fields; the tutorial’s helper explicitly maps its NEO4J_* variables to these settings. Plain NEO4J_* keys are not automatic MemorySettings aliases.

NAM_BACKEND=bolt
NAM_NEO4J__URI="neo4j+s://<instance-id>.databases.neo4j.io"
NAM_NEO4J__USERNAME=neo4j
NAM_NEO4J__PASSWORD=replace-with-your-Aura-password
NAM_NEO4J__DATABASE=neo4j
NAM_EXTRACTION__EXTRACTOR_TYPE=pipeline
NAM_EXTRACTION__ENABLE_SPACY=true
NAM_EXTRACTION__ENABLE_GLINER=true
NAM_EXTRACTION__ENABLE_LLM_FALLBACK=false
NAM_EXTRACTION__GLINER_MODEL=fastino/gliner2.5-base-v1
NAM_EXTRACTION__GLINER_SCHEMA=podcast
NAM_RESOLUTION__RESOLVE_ON_INGEST=true
NAM_ENRICHMENT__ENABLED=false
NAM_GEOCODING__ENABLED=false

Test harness switches

Test-only inputs such as RUN_INTEGRATION_TESTS, SKIP_INTEGRATION_TESTS, AUTO_START_DOCKER, and AUTO_STOP_DOCKER belong to the test harness, not the SDK configuration API. Read the relevant test fixture before relying on their parsing or defaults.

See also