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
Kind
Format
Duration
humantime: 500ms, 30s, 5m, 1h, 24h. 0s usually disables.
Bytes
An 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 variable
NAMIDB_SST_CACHE, NAMIDB_NODE_CACHE: anything except 0 is on. NAMIDB_ADJACENCY, NAMIDB_FACTORIZE, NAMIDB_WCOJ: only 1/true/yes/on is on.
Wait for the writer lock before 503. 0s = unbounded.
--bolt-tx-timeout
NAMIDB_BOLT_TX_TIMEOUT
30s
Idle time before an open Bolt transaction is rolled back. 0s = never.
--bolt-max-message-bytes
NAMIDB_BOLT_MAX_MESSAGE_BYTES
67108864 (64 MiB)
Largest authenticated Bolt message. Must be positive.
--slow-query-threshold
NAMIDB_SLOW_QUERY_THRESHOLD
1s
Log statements at or above this at WARN. 0s disables.
--memory-max-bytes
NAMIDB_MEMORY_MAX_BYTES
0 (off)
Process RSS ceiling: bytes, or auto (90% of the cgroup limit).
--query-memory-max-bytes
NAMIDB_QUERY_MEMORY_MAX_BYTES
auto
Working 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
Flag
Env var
Default
Meaning
--flush-interval
NAMIDB_FLUSH_INTERVAL
30s
Background flush timer. 0s disables.
--memtable-flush-bytes
NAMIDB_MEMTABLE_FLUSH_BYTES
67108864 (64 MiB)
Flush when the memtable passes this size. 0 disables.
--memtable-stall-bytes
NAMIDB_MEMTABLE_STALL_BYTES
268435456 (256 MiB)
Slow commits above this memtable size. 0 disables.
--group-commit-window
NAMIDB_GROUP_COMMIT_WINDOW
0s
Coalesce concurrent writes into one commit (try 2ms–5ms).
--compaction-interval
NAMIDB_COMPACTION_INTERVAL
300s
Background compaction and sweep timer. 0s disables maintenance.
--compaction-l0-trigger
NAMIDB_COMPACTION_L0_TRIGGER
8
Compact when a flush leaves this many L0 files in a bucket. 0 disables.
--write-stall-l0
NAMIDB_WRITE_STALL_L0
24
Slow commits above this many L0 files. 0 disables.
--write-stall-delay
NAMIDB_WRITE_STALL_DELAY
50ms
Delay per commit while stalled on L0.
--sweep-min-age
NAMIDB_SWEEP_MIN_AGE
24h
Minimum age before an unreferenced object is deleted.
--sweep-delete
NAMIDB_SWEEP_DELETE
true
false = dry-run sweep.
--restore-point-retention
NAMIDB_RESTORE_POINT_RETENTION
0s (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-uri
NAMIDB_BACKUP_TARGET_URI
off
Enables the backup and restore endpoints and restricts their locations (allowlist).
Server-only variables
No flag; read once at startup.
Variable
Default
Meaning
NAMIDB_HTTP_MAX_CONCURRENCY
1024
In-flight HTTP requests across all routes.
NAMIDB_MAX_CONCURRENT_QUERIES
CPU cores, at least 4
Concurrent read statements. 0 disables the gate.
NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE
0 (off)
Multi-tenant: concurrent reads per namespace.
NAMIDB_MAX_CONCURRENT_SCANS
4
Concurrent statements whose plan contains a full scan. 0 disables.
NAMIDB_QUERY_ADMISSION_WAIT_MS
5000
How long a read may wait for admission before a 503.
NAMIDB_BOLT_MAX_CONNECTIONS
1024
Concurrent Bolt connections.
NAMIDB_BOLT_MAX_TX_LIFETIME
5m
Maximum life of a Bolt explicit transaction.
NAMIDB_BOLT_MEMORY_BUDGET_BYTES
half of the memory ceiling, else 1075838976
Shared budget for decoding authenticated Bolt messages.
NAMIDB_BOLT_PARTIAL_MESSAGE_TIMEOUT
120s
Deadline for a partially received Bolt message. 0s disables.
NAMIDB_BOLT_SERVER_AGENT
Neo4j/5.13.0
Server agent announced to Bolt clients.
RUST_LOG
info
Log 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
Variable
Default
Meaning
NAMIDB_CACHE_MAX_BYTES
1073741824 (1 GiB)
Process-wide ceiling for all shared caches. 0 disables them.
NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTES
proportional
Exact reservation inside the ceiling for decoded vector / full-text bodies. 0 disables that pool.
NAMIDB_SST_CACHE
on
Data-file body and decoded caches (0 = off).
NAMIDB_NODE_CACHE
on
Cross-query node-view cache (0 = off).
NAMIDB_ADJACENCY
off
In-RAM adjacency (CSR) cache; holds whole edge types in memory.
NAMIDB_SNAPSHOT_NODE_CACHE_MAX_BYTES
min(1 MiB, ceiling / 64)
Per-query node-view cache. 0 disables.
NAMIDB_SNAPSHOT_ROW_GROUP_CACHE_MAX_BYTES
min(1 MiB, ceiling / 64)
Per-query decoded row groups (at most two).
NAMIDB_SNAPSHOT_EDGE_READER_CACHE_MAX_BYTES
min(1 MiB, ceiling / 64)
Per-query edge reader metadata (at most 32 files).
Alias used for index builds when NAMIDB_INDEX_BUILD_SPOOL_DIR is unset.
NAMIDB_INDEX_BUILD_MEMORY_BYTES
256 MiB (full rebuild), 64 MiB (per-flush delta)
Index builder memory; one value overrides both.
NAMIDB_SIDECAR_SORT_MEMORY_BYTES
8388608 (8 MiB, min 64 KiB)
Sort buffer per unique / equality / label side-car builder.
NAMIDB_NODE_PROPERTY_SORT_MEMORY_BYTES
8388608 (8 MiB)
Sort buffer for node property pages.
NAMIDB_FLUSH_BUILD_GATE_TIMEOUT_SECS
600
How long a flush waits for the process-wide build slot before failing (and being retried).
Search
Variable
Default
Meaning
NAMIDB_SEARCH_WORKSPACE_MAX_BYTES
268435456 (256 MiB)
Shared transient search memory.
NAMIDB_SEARCH_MAX_RESULT_BYTES
67108864 (64 MiB)
Cap for unbounded (no k) full-text results.
NAMIDB_BM25_MAX_DOCUMENT_BYTES
1048576 (1 MiB)
Largest document in exact BM25 scoring.
NAMIDB_VECTOR_FILTER_ID_CANDIDATE_CAP
8192
Side-car ids used when a vector index cannot apply a filter. 0 disables.
NAMIDB_HYBRID_TEXT_FILTER_CANDIDATE_CAP
65536
BM25 candidates hydrated for a filtered hybrid search before the exact fallback.
NAMIDB_SEARCH_LSM_MAX_SEGMENTS
8 (2–32)
Live segments per search index.
NAMIDB_SEARCH_LSM_COMPACT_SEGMENTS
max(MAX − 2, 2)
Deltas consolidated per routine pass.
NAMIDB_SEARCH_LSM_BASE_COMPACT_BYTES
8589934592 (8 GiB)
Delta bytes that trigger a base rebuild.
NAMIDB_SEARCH_LSM_BASE_STALE_PERCENT
800
Delta mutations (% of corpus) that trigger a base rebuild.
NAMIDB_SEARCH_LSM_FORCE_BASE_COMPACTION
false
One-shot base rebuild when delta debt exists.
NAMIDB_VECTOR_PAGE_ROWS
512
Vectors per index page at build time.
NAMIDB_VECTOR_BRANCH_FACTOR
8
Branching of the vector index routing tree.
NAMIDB_VECTOR_PAGE_ZSTD_LEVEL
3
Compression 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
Variable
Default
Meaning
NAMIDB_COMPACTION_BASE_BYTES
8388608 (8 MiB)
Level-1 size budget.
NAMIDB_COMPACTION_LEVEL_RATIO
10 (min 2)
Size ratio between levels.
NAMIDB_COMPACTION_MERGE_CHUNK_ROWS
16384
Rows per output chunk in the compaction merge.
NAMIDB_NODE_SST_ROW_GROUP_ROWS
131072
Rows per Parquet row group in node data files.
NAMIDB_MEMTABLE_SNAPSHOT_EVERY
0 (off)
Write a memtable snapshot every N commits (speeds up WAL replay on open).
NAMIDB_CORRELATED_WRITE_CHUNK_ROWS
128 (max 1024)
Rows per chunk for UNWIND … MATCH … SET point updates.
NAMIDB_LEGACY_PROPERTY_INDEX_MAX_BYTES
unset: written, uncapped
Older-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_BYTES
0 (unlimited)
Cap per relationship record in the exact relationship side-car; crossing a positive cap fails the build.
NAMIDB_EDGE_POINT_MAX_SST_BYTES
0 (unlimited)
Cap per exact relationship side-car; same rule.
NAMIDB_EDGE_DECODE_MAX_BYTES
67108864 (64 MiB)
Largest adjacency block decoded at once in older edge files.
NAMIDB_EDGE_IN_MEMORY_FINISH_MAX_BYTES
67108864 (64 MiB)
Cap for helper APIs that build an edge file in memory (not used by flush or compaction).
NAMIDB_NODE_PROPERTY_PAGE_TARGET_BYTES
1048576 (1 MiB)
Target size of a property page.
NAMIDB_NODE_PROPERTY_MAX_VALUE_BYTES
67108864 (64 MiB)
Largest property value.
NAMIDB_NODE_PROPERTY_MAX_PAGE_BYTES
68157440 (65 MiB)
Largest decoded property page.
NAMIDB_NODE_PROPERTY_MAX_CATALOG_BYTES
16777216 (16 MiB)
Largest property catalog per file.
NAMIDB_NODE_PROPERTY_MAX_PROPERTIES
65536
Distinct property names per file.
NAMIDB_NODE_PROPERTY_MAX_VALUE_DEPTH
32
Nesting depth of a value.
NAMIDB_NODE_PROPERTY_MAX_VALUE_ELEMENTS
1000000
Elements in one value.
NAMIDB_NODE_PROPERTY_MAX_NAME_BYTES
1024
Length of a property name.
NAMIDB_NODE_PROPERTY_MAX_INDEX_QUERY_BYTES
16777216 (16 MiB)
Largest index probe read for one property query.
NAMIDB_NODE_PROPERTY_MAX_QUERY_ROWS
1000000
Rows one property index query may return.
Query execution
Variable
Default
Meaning
NAMIDB_BATCH_LOOKUP_CHUNK
8192
Node ids resolved per batched lookup pass.
NAMIDB_EXPAND_TARGET_VIEW_BUDGET
250000
Endpoint views prefetched per expansion hop before falling back to per-edge reads.
NAMIDB_NUMERIC_RANGE_MAX_CANDIDATES
65536
Candidate ceiling for index-served numeric ranges. 0 disables that route.
1 prints per-stage profile counters to stderr after each query.
Object stores
Variable
Default
Meaning
NAMIDB_STORE_REQUEST_TIMEOUT
client default (30 s)
Per-request timeout (30s, 500ms, or seconds).
NAMIDB_STORE_RETRY_TIMEOUT
client default (180 s)
Total retry time per operation.
NAMIDB_STORE_MAX_RETRIES
client default
Retries per operation.
NAMIDB_LOCAL_ETAG_PIN
off
1/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.
Variable
Default
Meaning
NAMIDB_EMBEDDER
local
remote switches to a remote provider.
NAMIDB_EMBED_PROVIDER
openai
openai, voyage, cohere, gemini, jina.
NAMIDB_EMBED_MODEL
per provider
Model name.
NAMIDB_EMBED_DIM
1024
Output dimension.
NAMIDB_EMBED_API_KEY
provider variable
API key; falls back to OPENAI_API_KEY, VOYAGE_API_KEY, CO_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY, JINA_API_KEY.