Configuration Reference

Lunaris is configured along four axes:

1. Cargo feature flags — chosen at build time; decide which embedder / reranker / extractor / verifier backends are compiled in.
2. Environment variables (LUNARIS_*) — read at runtime, mostly when Lunaris::open resolves the default pipeline. CLI flags on the lunaris-server binary override the matching env var (12-factor; see CONTEXT.md D-26).
3. Builder / pipeline toggles — programmatic switches on the Lunaris handle (graph pipeline on/off, verifier on/off, per-scope enablement).
4. The storage URL scheme — moon://… is the only one 0.7.0 accepts.

Defaults are tuned for “a Moon you run, a local embedder, graph and verifier off” — the safe production floor. Turn things on deliberately.

1. Cargo feature flags

lunaris (umbrella crate)

v0.6 llama.cpp-only cutover. The candle inference stack (native, embedder-gguf, reranker-gguf, verify-small, verify-large, cpu-accelerate, cpu-mkl, cuda-fa2) is deleted. llamacpp is the only local embed/rerank runtime and is on by default; it needs cmake + a C++ toolchain. See docs/decisions/2026-07-10-llamacpp-only-cutover.md (the cutover ADR) and docs/migration/0.5-to-0.6-llamacpp-only.md (the migration guide).

default = ["llamacpp"]. CPU is the default device; device selection is a runtime probe, overridden by LUNARIS_DEVICE=cpu (the kill-switch that forces zero GPU layers even on an accelerated build). Extractor and verifier are remote-only — LUNARIS_EXTRACT_PROVIDER / LUNARIS_VERIFY_PROVIDER (anthropic|openai|gemini|minimax|openai-compat) or a caller-supplied with_extractor / with_verifier impl; unset resolves to NoopExtractor/NoopVerifier. For a pure-Rust, no-C++-toolchain build (Tier-0, small devices): default-features = false → NoopEmbedder/NoopReranker. (The umbrella also forwards moon-it / pg-it integration features to the storage crates.)

lunaris-llamacpp

The only local embed/rerank runtime. LlamaCppEmbedder and LlamaCppReranker load their GGUF eagerly and raise/log a WARN + NoopEmbedder/NoopReranker fallback on a missing or corrupt artifact — there is no auto-download; the MCP server stages GGUFs lazily on first recall, other deployments download them out-of-band and verify against the canonical SHA-256s printed by cargo run -p lunaris-bench --bin stage-models -- --help.

lunaris-extract

With no feature/provider active, NoopExtractor is the fallback (applies() == false). Provider selection at runtime is via LUNARIS_EXTRACT_PROVIDER.

lunaris-verify

The candle-based verify-small (Gemma-3-270M) / verify-large (Gemma-3-27B) tiers from RFC 0006 were deleted in the v0.6 llama.cpp-only cutover — the verifier is remote-only (LUNARIS_VERIFY_PROVIDER) or NoopVerifier, with no in-process model tier.

Integration-test features (never default)

lunaris-recipes / lunaris-storage-moon: moon-it. (pg-it was removed in 0.7.0 with the Postgres backend.) lunaris-conformance: chaos-it. lunaris-bench: budget-it.

Excluded from cargo test --workspace: lunaris-py and lunaris-ts are cdylibs and fail to link under the workspace test runner. Test them with maturin + pytest / napi build + vitest, or via scripts/sdk-real-evidence.sh.

2. Environment variables

All variables below are read by Lunaris::open (or the lunaris-server binary) unless noted. Boolean variables accept 1, true, on (case- insensitive) for “enabled”; anything else (or unset) is “disabled”.

Backend / pipeline selection

The production recall pipeline (GA-1)

Every production surface builds ONE canonical recall root, lunaris_retrieve::production_root(k, graph_enabled):

• graph-OFF: Vector("chunks",k) ∧ BM25("chunks",k) → fuse_rrf(60) → top(k)
• graph-ON: the same chunks legs fused with the fact legs (Navigate("entities",k, fallback "facts") ∧ BM25("facts",k)), then top(k)

Per-surface deltas on top of that shared root:

Rerank is OFF by default on every surface; with it off the bge-reranker GGUF is never loaded. When enabled, the stage runs between RRF fusion and the final top(k) over the top LUNARIS_RECALL_RERANK_TOP_IN candidates. Budget seconds, not milliseconds, for it — the measured cost is p50 1301.3 ms at top_in=60 and 575.6 ms at top_in=30 (capacity §4). It is a quality stage, not a latency-class stage, and turning it on voids the 25 ms p50 recall contract.

Activation boost — on by default, and it changes ranking

Read this before you A/B anything. The boost is on by default on every surface (W1.8 — it was previously applied only on the lunaris-memory-service path, so the same query could rank differently through MCP than through /v1/recall; that divergence is gone). Any benchmark, eval, or regression comparison MUST still state which value it ran with, and both arms of an A/B must run with the same one — the prior is a real ranking input, not a tiebreaker. It is also the first thing to check when recall ordering looks inexplicable in production.

One consequence worth knowing before you read a flamegraph: with the boost on, every recall issues one activation-ledger point read per distinct hit — bounded by the hit set, never by the scope’s size, and pinned by ledger_read_cost_is_one_point_read_per_distinct_hit. Callers that never write reinforcement signals still pay those reads and get an empty ledger back; LUNARIS_ACTIVATION_BOOST=0 removes them entirely.

How much the boost is worth, and for how long. The prior is additive on a hit’s fused score, bounded by BOOST_CAP (0.30, an asymptote — not a value any real record reaches), and it decays with the age of the memory’s most recent reference. Measured for a memory referenced ten times (weighted = 30):

A memory that was never referenced gets exactly 0.0 — the ledger only ever promotes, never demotes, so an unreferenced memory keeps its raw hybrid rank.

Until the fix for F43 landed, this curve clamped negative ACT-R activation to zero, which made the prior read exactly 0.0 for any memory older than weighted² seconds — 9 seconds after a single strong reference, 15 minutes after ten. If you are reading recall traces from an older build, the boost column is expected to be zero almost everywhere; that was a defect (F43), not a tuning choice.

The llama.cpp granite-r2 embedder and bge-reranker-v2-m3 reranker are selected unconditionally when the llamacpp feature is on (default) — there is no LUNARIS_EMBEDDER_BACKEND or LUNARIS_RERANKER_BACKEND variable. Use the env vars below to change the GGUF path or (operators only) redirect the embedder to a remote Ollama endpoint.

Embedder and reranker details

Verifier / extractor providers (remote-only)

A provider that is set but fails to construct (bad URL, missing key) logs a tracing::warn! and degrades to NoopExtractor/NoopVerifier — never a silent backend swap.

Workspace-wide LLM defaults (lunaris-llm, src/config.rs) — consulted only when the per-pipeline variable (LUNARIS_EXTRACT_PROVIDER / LUNARIS_VERIFY_PROVIDER / LUNARIS_REFLECT_PROVIDER) is unset. Precedence: per-pipeline env → workspace env → TOML file → built-in default.

Precedence for a pipeline’s provider/model, highest first: the per-pipeline env var (LUNARIS_EXTRACT_PROVIDER / LUNARIS_EXTRACT_MODEL) → the workspace env var (LUNARIS_LLM_PROVIDER / LUNARIS_LLM_MODEL) → the matching section of LUNARIS_LLM_CONFIG’s TOML → the built-in fallback pair (ollama + gemma3:4b). Env always wins over the file.

Moon storage tuning (lunaris-storage-moon)

Read by the Moon adapter in any embedding process (server, MCP, SDKs).

Supervision / worker pool

Ingest + embedding batching

The embedder batches by token window, not by row count, and the two families of knob are independent: *_BATCH_TOKENS sizes the llama.cpp compute buffer, *_BATCH* sizes how many items the caller hands over at once.

Scope resolution

contextd — the shared local daemon

lunaris-contextd keeps one warm embedder and one Moon connection for all the short-lived hook / MCP / CLI processes on a machine. Everything below tunes how those processes find it and how long they will wait.

Codex hook-adapter budgets

scripts/lunaris-codex-hook-adapter.py is a thin shim that talks to contextd over the socket above. These are its per-phase deadlines, in milliseconds; each one degrades to “inject nothing” rather than delaying the agent.

Hook context injection

What the Claude Code / Codex hook may inject, and the latency budgets it may spend doing it. Every timeout here is a hard budget on a user-visible path — exceeding one degrades to injecting nothing, never to blocking the turn.

The LUNARIS_CODEX_* spellings (LUNARIS_CODEX_CONTEXT_MAX_CHARS, …_CONTEXT_MIN_SCORE, …_POST_TOOL_*) are legacy aliases consulted after the LUNARIS_CONTEXT_* names above. Prefer the unprefixed names; the Codex ones exist so older Codex hook configs keep working.

Recall degradation signal

Logging

There is no LUNARIS_LOG variable — the library/server filter is the standard RUST_LOG; the auxiliary binaries each have their own clap-backed filter var.

HTTP server (lunaris-server)

crates/lunaris-server/src/config.rs — every var has a matching CLI flag that takes precedence.

Plus the --metrics-disabled CLI flag, which removes the /metrics endpoint. The per-command Moon timeout the server inherits is LUNARIS_MOON_OP_TIMEOUT — a storage-layer variable, not a lunaris-server flag (see Moon storage tuning above).

Bearer-token map format (LUNARIS_TOKENS_FILE, D-07):

{
  "<opaque-bearer-token>": { "tenant": "acme",   "scopes": ["ingest", "recall", "forget"] },
  "<another-token>":       { "tenant": "globex", "scopes": ["recall"] }
}

• tenant is the partition scope for the token (typed as Scope, validated against [A-Za-z0-9_\-.]{1,128}) — and the only source of truth for it. Route handlers ignore any scope / tenant field on the request body; every public DTO carries #[serde(deny_unknown_fields)], so a body that contains such a field is rejected (HTTP 422).
• scopes is the verb-permission set — which of ingest / recall / forget this token may call. A request whose route requires a verb not in this list is 403.
• A missing or invalid token is 401.

MCP server (lunaris-mcp)

Every var has a matching CLI flag (clap) that takes precedence. Storage resolution is explicit → contextd-advertised → refuse-to-boot; see MCP Server.

(LUNARIS_MCP_LOG is in the Logging table above.)

Hooks & context injection (lunaris-hook / lunaris-contextd)

LUNARIS_DREAM_CRON and LUNARIS_DREAM_PIGGYBACK appear in the /dream skill docs as v2 stubs but are not read by any code yet — setting them does nothing today.

Bench-only variables

The LUNARIS_EVAL_* family (plus the bench harness knobs) configures the LongMemEval / PersonaMem benchmark rigs only — never a production process. They are documented next to the harnesses: scripts/bench/lme/README.md and scripts/bench/pm/README.md.

Integration-test probes (not for production)

Point these at a dedicated Moon. Never at a store you care about — the fixtures own their instance and clear it.

3. Builder / pipeline toggles (programmatic)

Each opt-in pipeline exposes a handle on Lunaris plus an env-seeded initial state:

The handles are obtained from the Lunaris value after open; see Guides → Consolidation & Verification and Guides → The Graph Pipeline.

4. Storage URL scheme

Lunaris::open(url) / lunaris::open(url) dispatch on the scheme:

There is no schema migration and no role bootstrap to run — per-scope keyspaces, FT indices, GRAPH keys, and MQ topics are created lazily on the first atomic_write per scope.

See also Operations → The Storage Backend.