Moon is configured through command-line flags and an optional Redis-style configuration file (moon.conf). Precedence is CLI flags → conf file → built-in defaults. Pass the conf file as the first argument (moon /etc/moon/moon.conf) or via --config; validate it without starting using --check-config. The flags below can all be set in either place.
Most deployments should run the defaults as-is: --shards 1 gives the best
per-op latency for low-concurrency and non-pipelined traffic (a cross-shard hop
costs ~10µs), keeps every key co-located (no {hash-tag} planning), and — with
--appendonly yes + --wal-kv-log auto — writes each KV record to disk exactly
once (the AOF). Reach for more shards only with 8+ concurrent connections or
deep pipelines (measured 1.3–2.5× Redis at 8–64 conns on 4 shards), and see
Tuning for --io-busy-poll-us (a p=1 latency win on dedicated
cores that now auto-gates on shared ones, so it's safe on any host — or use
--profile standalone to fold it in).
Enable append-only file persistence (yes/no) — Moon is durable by default
--appendfsync
everysec
AOF fsync policy: always, everysec, or no
--aof-fsync-timeout-ms
2000
Max time a write may block awaiting durability (fsync ack under always, writer-queue backpressure under everysec) before it fails loudly instead of parking the connection. 0 = unbounded
--wal-kv-log
auto
KV command logging into the per-shard WAL. auto: skipped while the AOF is the recovery authority (--appendonly yes) and no CDC subscriber is attached — halves write volume at --shards >= 2; re-engages automatically when a CDC subscriber attaches. on: always log (pre-0.6 behavior; needed for PITR or full CDC history alongside AOF). off: never log KV records
--appendfilename
appendonly.aof
AOF filename
--save
(none)
RDB auto-save rules (e.g., "3600 1 300 100")
--dbfilename
dump.rdb
RDB snapshot filename
--dir
(user data dir)
Directory for persistence files. Default auto-resolves per platform: Linux $XDG_DATA_HOME/moon (or ~/.local/share/moon), macOS ~/Library/Application Support/moon, Windows %LOCALAPPDATA%\moon — created on first run. Pre-v0.2.0 data in the startup directory keeps being used (with a warning). Pass any path (e.g. --dir .) to override
mlock vector code pages into RAM: enable or disable
--segment-cold-after
86400
Seconds after last access before WARM segment becomes COLD candidate
--segment-cold-min-qps
0.1
Minimum QPS threshold; segments below this are COLD candidates
--vec-diskann-beam-width
8
DiskANN beam width for disk-resident vector search
--vec-diskann-cache-levels
3
HNSW upper levels cached in memory for DiskANN hybrid search
--vector-ef-runtime
0 (auto)
Default EF_RUNTIME for indexes created without one (10-4096; 0 = per-query auto heuristic). Per-index FT.CONFIG SET <idx> EF_RUNTIME overrides at runtime
--vector-rerank-mult
4
Default RERANK_MULT for new indexes: exact-rerank depth, top mult×k beam candidates re-scored with true f16 distances (1-64). Per-index FT.CONFIG overrides
--vector-exact-beam
off
Default EXACT_BEAM for new indexes: HNSW beam navigates exact f16 sidecar distances (recall ≈ graph-limited; QPS cost grows with dimension). Per-index FT.CONFIG overrides