Skip to content

Configuration reference

NamiDB is configured with command-line flags (server only) and environment variables (every entry point). Every server flag has an environment variable; when both are set, the flag wins.

Value formats

KindFormat
Durationhumantime: 500ms, 30s, 5m, 1h, 24h. 0s usually disables.
BytesAn exact integer number of bytes (1073741824). Suffixes like 1GB are rejected. Variables ending in _MIB take mebibytes.
Boolean flag--no-auth and --multi-tenant accept 1/0/true/false/yes/no/on/off as --flag=value or env var; a bare flag means true. Junk values are errors.
On/off variableNAMIDB_SST_CACHE, NAMIDB_NODE_CACHE: anything except 0 is on. NAMIDB_ADJACENCY, NAMIDB_FACTORIZE, NAMIDB_WCOJ: only 1/true/yes/on is on.

Who reads what

SectionServerPythonCLI / MCP
Server flags, Server-only variablesyes——
Engine variablesyesyesyes
Embedders——yes

Server flags

Core

FlagEnv varDefaultMeaning
--storeNAMIDB_STORErequiredStorage URI (Storage URIs).
--listenNAMIDB_LISTEN0.0.0.0:8080HTTP bind address.
--bolt-listenNAMIDB_BOLT_LISTENoffBolt bind address, e.g. 0.0.0.0:7687.
--tls-certNAMIDB_TLS_CERToffPEM certificate chain; with --tls-key, serves HTTPS and Bolt over TLS.
--tls-keyNAMIDB_TLS_KEYoffPEM private key.
--multi-tenantNAMIDB_MULTI_TENANTfalseServe many namespaces (Multi-tenant mode).
--default-namespaceNAMIDB_DEFAULT_NAMESPACEdefaultMulti-tenant fallback namespace when a request names none.
--max-namespacesNAMIDB_MAX_NAMESPACES100Multi-tenant: namespaces open at once (0 = unlimited).
--namespace-idle-timeoutNAMIDB_NAMESPACE_IDLE_TIMEOUT1hMulti-tenant: idle time before a namespace may be evicted.
--fence-policyNAMIDB_FENCE_POLICYstealWhen another process claims the namespace: steal reopens and takes it back; yield stays degraded.

Authentication

FlagEnv varDefaultMeaning
--auth-tokenNAMIDB_AUTH_TOKEN—One read-write bearer token.
--auth-tokens-fileNAMIDB_AUTH_TOKENS_FILE—JSON tokens file with roles and namespace scopes; overrides --auth-token.
--auth-tokens-reload-intervalNAMIDB_AUTH_TOKENS_RELOAD_INTERVAL10sTokens-file reload period (0s disables).
--no-authNAMIDB_NO_AUTHfalseRun without authentication. Required to start when no auth source is set.
--jwt-jwks-urlNAMIDB_JWT_JWKS_URL—(feature jwt) Enables JWT validation against this JWKS.
--jwt-issuerNAMIDB_JWT_ISSUER—(jwt) Required iss.
--jwt-audienceNAMIDB_JWT_AUDIENCE—(jwt) Required aud.
--jwt-groups-claimNAMIDB_JWT_GROUPS_CLAIMgroups(jwt) Claim with the user’s groups.
--jwt-write-groupNAMIDB_JWT_WRITE_GROUP—(jwt) Group granting read-write.
--jwt-read-groupNAMIDB_JWT_READ_GROUP—(jwt) Group granting read-only.
--jwt-namespaces-claimNAMIDB_JWT_NAMESPACES_CLAIM—(jwt) Claim listing allowed namespaces.
--pdp-urlNAMIDB_PDP_URL—(feature pdp) OPA-style policy endpoint; fail-closed.

Details: Authentication.

Budgets and timeouts

FlagEnv varDefaultMeaning
--query-timeoutNAMIDB_QUERY_TIMEOUT30sWall clock per read statement (HTTP and Bolt). 0s = unbounded.
--write-timeoutNAMIDB_WRITE_TIMEOUT60sWall clock per write statement. 0s = unbounded.
--query-row-capNAMIDB_QUERY_ROW_CAP1000000Rows any read operator may materialise. 0 = unlimited.
--http-request-timeoutNAMIDB_HTTP_REQUEST_TIMEOUTderivedWhole-request ceiling (408). Unset: max(120s, largest budget + 30s). 0s disables.
--writer-lock-timeoutNAMIDB_WRITER_LOCK_TIMEOUT30sWait for the writer lock before 503. 0s = unbounded.
--bolt-tx-timeoutNAMIDB_BOLT_TX_TIMEOUT30sIdle time before an open Bolt transaction is rolled back. 0s = never.
--bolt-max-message-bytesNAMIDB_BOLT_MAX_MESSAGE_BYTES67108864 (64 MiB)Largest authenticated Bolt message. Must be positive.
--slow-query-thresholdNAMIDB_SLOW_QUERY_THRESHOLD1sLog statements at or above this at WARN. 0s disables.
--memory-max-bytesNAMIDB_MEMORY_MAX_BYTES0 (off)Process RSS ceiling: bytes, or auto (90% of the cgroup limit).
--query-memory-max-bytesNAMIDB_QUERY_MEMORY_MAX_BYTESautoWorking memory of one running statement (413 query_memory_limit over it). auto is 50% of --memory-max-bytes, off when that is 0; an exact byte count also works without a ceiling; 0 disables. With a ceiling, running statements also share a pool of 75% of it (503 memory_pressure). See Memory.

Write path and maintenance

FlagEnv varDefaultMeaning
--flush-intervalNAMIDB_FLUSH_INTERVAL30sBackground flush timer. 0s disables.
--memtable-flush-bytesNAMIDB_MEMTABLE_FLUSH_BYTES67108864 (64 MiB)Flush when the memtable passes this size. 0 disables.
--memtable-stall-bytesNAMIDB_MEMTABLE_STALL_BYTES268435456 (256 MiB)Slow commits above this memtable size. 0 disables.
--group-commit-windowNAMIDB_GROUP_COMMIT_WINDOW0sCoalesce concurrent writes into one commit (try 2ms–5ms).
--compaction-intervalNAMIDB_COMPACTION_INTERVAL300sBackground compaction and sweep timer. 0s disables maintenance.
--compaction-l0-triggerNAMIDB_COMPACTION_L0_TRIGGER8Compact when a flush leaves this many L0 files in a bucket. 0 disables.
--write-stall-l0NAMIDB_WRITE_STALL_L024Slow commits above this many L0 files. 0 disables.
--write-stall-delayNAMIDB_WRITE_STALL_DELAY50msDelay per commit while stalled on L0.
--sweep-min-ageNAMIDB_SWEEP_MIN_AGE24hMinimum age before an unreferenced object is deleted.
--sweep-deleteNAMIDB_SWEEP_DELETEtruefalse = dry-run sweep.
--restore-point-retentionNAMIDB_RESTORE_POINT_RETENTION0s (off)Keep every committed version of this long (24h, 7d) restorable for a point-in-time backup (as_of). Storage grows by what the namespace writes in the window. Needs --compaction-interval above zero; the server refuses to start otherwise. See Restore points.
--backup-target-uriNAMIDB_BACKUP_TARGET_URIoffEnables the backup and restore endpoints and restricts their locations (allowlist).

Server-only variables

No flag; read once at startup.

VariableDefaultMeaning
NAMIDB_HTTP_MAX_CONCURRENCY1024In-flight HTTP requests across all routes.
NAMIDB_MAX_CONCURRENT_QUERIESCPU cores, at least 4Concurrent read statements. 0 disables the gate.
NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE0 (off)Multi-tenant: concurrent reads per namespace.
NAMIDB_MAX_CONCURRENT_SCANS4Concurrent statements whose plan contains a full scan. 0 disables.
NAMIDB_QUERY_ADMISSION_WAIT_MS5000How long a read may wait for admission before a 503.
NAMIDB_BOLT_MAX_CONNECTIONS1024Concurrent Bolt connections.
NAMIDB_BOLT_MAX_TX_LIFETIME5mMaximum life of a Bolt explicit transaction.
NAMIDB_BOLT_MEMORY_BUDGET_BYTEShalf of the memory ceiling, else 1075838976Shared budget for decoding authenticated Bolt messages.
NAMIDB_BOLT_PARTIAL_MESSAGE_TIMEOUT120sDeadline for a partially received Bolt message. 0s disables.
NAMIDB_BOLT_SERVER_AGENTNeo4j/5.13.0Server agent announced to Bolt clients.
RUST_LOGinfoLog filter, e.g. info,namidb_storage=debug.

Engine variables

Read by the server, the Python client, the CLI and the MCP server. Most are sampled the first time the engine needs them, so set them before the process starts. The server validates the byte-valued cache variables at startup and refuses malformed values.

Caches

VariableDefaultMeaning
NAMIDB_CACHE_MAX_BYTES1073741824 (1 GiB)Process-wide ceiling for all shared caches. 0 disables them.
NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTESproportionalExact reservation inside the ceiling for decoded vector / full-text bodies. 0 disables that pool.
NAMIDB_SST_CACHEonData-file body and decoded caches (0 = off).
NAMIDB_NODE_CACHEonCross-query node-view cache (0 = off).
NAMIDB_ADJACENCYoffIn-RAM adjacency (CSR) cache; holds whole edge types in memory.
NAMIDB_SNAPSHOT_NODE_CACHE_MAX_BYTESmin(1 MiB, ceiling / 64)Per-query node-view cache. 0 disables.
NAMIDB_SNAPSHOT_ROW_GROUP_CACHE_MAX_BYTESmin(1 MiB, ceiling / 64)Per-query decoded row groups (at most two).
NAMIDB_SNAPSHOT_EDGE_READER_CACHE_MAX_BYTESmin(1 MiB, ceiling / 64)Per-query edge reader metadata (at most 32 files).
NAMIDB_SNAPSHOT_NODE_PROPERTY_READER_CACHE_MAX_BYTESmin(1 MiB, ceiling / 64)Per-query property reader metadata.
NAMIDB_SST_CACHE_BUDGET_MIB256Relative request for data-file bodies.
NAMIDB_DECODED_NODE_RG_CACHE_BUDGET_MIB256Relative request for decoded node row groups.
NAMIDB_PROPERTY_SIDECAR_CACHE_BUDGET_MIB512Relative request for property index side-cars.
NAMIDB_SST_METADATA_CACHE_BUDGET_MIB64Relative request for file metadata.
NAMIDB_EDGE_STREAM_CACHE_BUDGET_MIB256Relative request for edge property streams.
NAMIDB_EDGE_READER_CACHE_BUDGET_MIB256Relative request for edge readers.
NAMIDB_BLOOM_FILTER_CACHE_BUDGET_MIB64Relative request for bloom filters.
NAMIDB_TEXT_INDEX_CACHE_BUDGET_MIB512Relative request for full-text bodies (with text-index).
NAMIDB_VECTOR_INDEX_CACHE_BUDGET_MIB512Relative request for vector bodies (with vector-index).
NAMIDB_CACHE_PATH_REGISTRY_BUDGET_MIB32Relative request for path / admission metadata.
NAMIDB_NODE_CACHE_BUDGET_MIB256Relative request for the node-view cache.
NAMIDB_ADJACENCY_BUDGET_MIB512Relative request for the adjacency cache, when enabled.

The _MIB requests are scaled down proportionally when they add up to more than NAMIDB_CACHE_MAX_BYTES. See Memory and caches.

Range cache

VariableDefaultMeaning
NAMIDB_RAM_PAGE_CACHE_MAX_BYTES67108864 requested, scaledRAM page cache for byte ranges, carved out of the ceiling. 0 disables.
NAMIDB_NVME_CACHE_PATHoffDirectory of the persistent cache tier.
NAMIDB_NVME_CACHE_MAX_BYTES—Exact NVMe tier capacity; required with the path.
NAMIDB_RANGE_CACHE_NAMESPACEmemory-only; required with NVMeStable deployment + bucket identity mixed into cache keys.
NAMIDB_RANGE_CACHE_PAGE_BYTES262144 (256 KiB)Page size of range reads.
NAMIDB_RANGE_CACHE_MAX_ENTRY_BYTES4194304 (4 MiB)Largest cached range.
NAMIDB_NVME_CACHE_BLOCK_BYTES16777216 (16 MiB)NVMe eviction block; the device needs at least eight.
NAMIDB_NVME_CACHE_WRITE_BUFFER_BYTES¼ of the RAM tier, ≤ 16 MiBSize of each NVMe write buffer.

Spool and index builds

VariableDefaultMeaning
NAMIDB_SPOOL_DIR/var/tmp (Unix), /var/tmp/namidb-spool (image); Python file://: <root>/.namidb-spoolDisk scratch for flush and compaction.
NAMIDB_INDEX_BUILD_SPOOL_DIRcompaction spool, then NAMIDB_SPOOL_DIRDisk scratch for vector / full-text builds.
NAMIDB_COMPACTION_SPOOL_DIR—Alias used for index builds when NAMIDB_INDEX_BUILD_SPOOL_DIR is unset.
NAMIDB_INDEX_BUILD_MEMORY_BYTES256 MiB (full rebuild), 64 MiB (per-flush delta)Index builder memory; one value overrides both.
NAMIDB_SIDECAR_SORT_MEMORY_BYTES8388608 (8 MiB, min 64 KiB)Sort buffer per unique / equality / label side-car builder.
NAMIDB_NODE_PROPERTY_SORT_MEMORY_BYTES8388608 (8 MiB)Sort buffer for node property pages.
NAMIDB_FLUSH_BUILD_GATE_TIMEOUT_SECS600How long a flush waits for the process-wide build slot before failing (and being retried).
VariableDefaultMeaning
NAMIDB_SEARCH_WORKSPACE_MAX_BYTES268435456 (256 MiB)Shared transient search memory.
NAMIDB_SEARCH_MAX_RESULT_BYTES67108864 (64 MiB)Cap for unbounded (no k) full-text results.
NAMIDB_BM25_MAX_DOCUMENT_BYTES1048576 (1 MiB)Largest document in exact BM25 scoring.
NAMIDB_VECTOR_FILTER_ID_CANDIDATE_CAP8192Side-car ids used when a vector index cannot apply a filter. 0 disables.
NAMIDB_HYBRID_TEXT_FILTER_CANDIDATE_CAP65536BM25 candidates hydrated for a filtered hybrid search before the exact fallback.
NAMIDB_SEARCH_LSM_MAX_SEGMENTS8 (2–32)Live segments per search index.
NAMIDB_SEARCH_LSM_COMPACT_SEGMENTSmax(MAX − 2, 2)Deltas consolidated per routine pass.
NAMIDB_SEARCH_LSM_BASE_COMPACT_BYTES8589934592 (8 GiB)Delta bytes that trigger a base rebuild.
NAMIDB_SEARCH_LSM_BASE_STALE_PERCENT800Delta mutations (% of corpus) that trigger a base rebuild.
NAMIDB_SEARCH_LSM_FORCE_BASE_COMPACTIONfalseOne-shot base rebuild when delta debt exists.
NAMIDB_VECTOR_PAGE_ROWS512Vectors per index page at build time.
NAMIDB_VECTOR_BRANCH_FACTOR8Branching of the vector index routing tree.
NAMIDB_VECTOR_PAGE_ZSTD_LEVEL3Compression level of vector pages.

Filter postings inside a vector index are limited to a fixed 4,096 distinct values per property (not configurable); their build spills to the index spool under NAMIDB_INDEX_BUILD_MEMORY_BYTES.

Write path, compaction and data files

VariableDefaultMeaning
NAMIDB_COMPACTION_BASE_BYTES8388608 (8 MiB)Level-1 size budget.
NAMIDB_COMPACTION_LEVEL_RATIO10 (min 2)Size ratio between levels.
NAMIDB_COMPACTION_MERGE_CHUNK_ROWS16384Rows per output chunk in the compaction merge.
NAMIDB_NODE_SST_ROW_GROUP_ROWS131072Rows per Parquet row group in node data files.
NAMIDB_MEMTABLE_SNAPSHOT_EVERY0 (off)Write a memtable snapshot every N commits (speeds up WAL replay on open).
NAMIDB_CORRELATED_WRITE_CHUNK_ROWS128 (max 1024)Rows per chunk for UNWIND … MATCH … SET point updates.
NAMIDB_LEGACY_PROPERTY_INDEX_MAX_BYTESunset: written, uncappedOlder-format property side-car, kept for rolling back to pre-paged readers. 0 stops writing it; a positive value caps it (beyond the cap only the current format is written).
NAMIDB_EDGE_POINT_MAX_ENTRY_BYTES0 (unlimited)Cap per relationship record in the exact relationship side-car; crossing a positive cap fails the build.
NAMIDB_EDGE_POINT_MAX_SST_BYTES0 (unlimited)Cap per exact relationship side-car; same rule.
NAMIDB_EDGE_DECODE_MAX_BYTES67108864 (64 MiB)Largest adjacency block decoded at once in older edge files.
NAMIDB_EDGE_IN_MEMORY_FINISH_MAX_BYTES67108864 (64 MiB)Cap for helper APIs that build an edge file in memory (not used by flush or compaction).
NAMIDB_NODE_PROPERTY_PAGE_TARGET_BYTES1048576 (1 MiB)Target size of a property page.
NAMIDB_NODE_PROPERTY_MAX_VALUE_BYTES67108864 (64 MiB)Largest property value.
NAMIDB_NODE_PROPERTY_MAX_PAGE_BYTES68157440 (65 MiB)Largest decoded property page.
NAMIDB_NODE_PROPERTY_MAX_CATALOG_BYTES16777216 (16 MiB)Largest property catalog per file.
NAMIDB_NODE_PROPERTY_MAX_PROPERTIES65536Distinct property names per file.
NAMIDB_NODE_PROPERTY_MAX_VALUE_DEPTH32Nesting depth of a value.
NAMIDB_NODE_PROPERTY_MAX_VALUE_ELEMENTS1000000Elements in one value.
NAMIDB_NODE_PROPERTY_MAX_NAME_BYTES1024Length of a property name.
NAMIDB_NODE_PROPERTY_MAX_INDEX_QUERY_BYTES16777216 (16 MiB)Largest index probe read for one property query.
NAMIDB_NODE_PROPERTY_MAX_QUERY_ROWS1000000Rows one property index query may return.

Query execution

VariableDefaultMeaning
NAMIDB_BATCH_LOOKUP_CHUNK8192Node ids resolved per batched lookup pass.
NAMIDB_EXPAND_TARGET_VIEW_BUDGET250000Endpoint views prefetched per expansion hop before falling back to per-edge reads.
NAMIDB_NUMERIC_RANGE_MAX_CANDIDATES65536Candidate ceiling for index-served numeric ranges. 0 disables that route.
NAMIDB_FACTORIZEoffExperimental factorized execution.
NAMIDB_WCOJoffExperimental worst-case-optimal joins (needs NAMIDB_FACTORIZE).
NAMIDB_PROFILE_DUMPoff1 prints per-stage profile counters to stderr after each query.

Object stores

VariableDefaultMeaning
NAMIDB_STORE_REQUEST_TIMEOUTclient default (30 s)Per-request timeout (30s, 500ms, or seconds).
NAMIDB_STORE_RETRY_TIMEOUTclient default (180 s)Total retry time per operation.
NAMIDB_STORE_MAX_RETRIESclient defaultRetries per operation.
NAMIDB_LOCAL_ETAG_PINoff1/true: pin file:// reads to the file’s ETag (see Local filesystem).

Backend credentials use the standard variables of each provider (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, GOOGLE_APPLICATION_CREDENTIALS, AZURE_STORAGE_ACCOUNT_NAME, AZURE_STORAGE_ACCOUNT_KEY, …); see Storage URIs.

Embedders

Read by namidb load-vault --embed and namidb-mcp. The remote embedder needs a build with --features namidb-markdown/remote-embedder; see CLI.

VariableDefaultMeaning
NAMIDB_EMBEDDERlocalremote switches to a remote provider.
NAMIDB_EMBED_PROVIDERopenaiopenai, voyage, cohere, gemini, jina.
NAMIDB_EMBED_MODELper providerModel name.
NAMIDB_EMBED_DIM1024Output dimension.
NAMIDB_EMBED_API_KEYprovider variableAPI key; falls back to OPENAI_API_KEY, VOYAGE_API_KEY, CO_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY, JINA_API_KEY.
NAMIDB_EMBED_URLprovider defaultEndpoint override.

Official image defaults

The namidb/namidb-server image sets:

NAMIDB_LISTEN=0.0.0.0:8080
NAMIDB_SPOOL_DIR=/var/tmp/namidb-spool
NAMIDB_INDEX_BUILD_SPOOL_DIR=/var/tmp/namidb-spool
NAMIDB_SEARCH_WORKSPACE_MAX_BYTES=268435456
NAMIDB_SEARCH_MAX_RESULT_BYTES=67108864
NAMIDB_BM25_MAX_DOCUMENT_BYTES=1048576
NAMIDB_EDGE_DECODE_MAX_BYTES=67108864
RUST_LOG=info
MALLOC_ARENA_MAX=2
MALLOC_TRIM_THRESHOLD_=131072