> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorose.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure the current Memorose runtime, including `llm`, `storage`, `worker`, `raft`, and environment overrides.

# Configuration

Memorose reads runtime configuration from `config.toml`, `MEMOROSE__*` environment overrides, and a small set of legacy environment variables.

The current runtime config is defined by `AppConfig` in `crates/memorose-common/src/config.rs`. That is the source of truth for what the server actually reads.

## Main files

* `config.toml`: runtime configuration file loaded by the server
* `.env`: local environment variables loaded by helper scripts such as `./scripts/start_cluster.sh`
* `.env.example`: example provider keys and common environment overrides
* `crates/memorose-common/src/config.rs`: current runtime config schema and defaults

## Current top-level config sections

The current server config is organized around:

```toml theme={null}
[llm]
[storage]
[raft]
[worker]
[sharding]
[reranker]
```

Notes:

* `sharding` is optional.
* `reranker` is optional and defaults to the built-in weighted reranker.
* Treat `config.example.toml` and `config.toml.example` as examples; `crates/memorose-common/src/config.rs` remains the canonical schema.

## Minimal working example

```toml theme={null}
[llm]
provider = "Gemini"
model = "gemini-2.0-flash"
embedding_model = "text-embedding-004"

[storage]
root_dir = "./data/node-1"
index_commit_interval_ms = 5000

[raft]
node_id = 1
raft_addr = "127.0.0.1:5001"
heartbeat_interval_ms = 500
election_timeout_min_ms = 1500
election_timeout_max_ms = 3000
snapshot_logs = 1000000
auto_initialize = true

[worker]
llm_concurrency = 5
decay_interval_secs = 60
prune_threshold = 0.1
consolidation_interval_ms = 1000
community_interval_ms = 1000
insight_interval_ms = 30000
enable_auto_planner = true
enable_task_reflection = true
auto_link_similarity_threshold = 0.6
tick_interval_ms = 100

[reranker]
type = "weighted"
```

## Reranker modes

Reranking is a server-side runtime setting. SDK clients do not choose the reranker mode per request.

| Mode       | Config                | Behavior                                                                                                                                                 |
| ---------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Weighted   | `type = "weighted"`   | Default local reranker. Combines vector similarity, importance, and recency.                                                                             |
| Arbitrator | `type = "arbitrator"` | Uses the configured LLM provider to dynamically choose only genuinely relevant candidates. It can return fewer than the requested limit, including zero. |
| HTTP       | `type = "http"`       | Calls an external reranker endpoint such as Jina or a custom service.                                                                                    |

### Arbitrator mode

`arbitrator` reuses the main `[llm]` provider, API key, base URL, and embedding settings. If `reranker.model` is set, it overrides only the generation model used by the arbitrator.

```toml theme={null}
[reranker]
type = "arbitrator"
provider = "gemini"
model = "gemini-3.1-flash-lite-preview"
max_candidates = 32
fallback_to_weighted = true
include_metadata = true
```

Important fields:

* `model`: optional generation model override for arbitrator mode. If omitted, Memorose uses `[llm].model`.
* `max_candidates`: maximum number of retrieval candidates sent to the model for arbitration. This is not a fixed result count.
* `fallback_to_weighted`: falls back to weighted reranking if the arbitrator cannot be built or fails at runtime.
* `include_metadata`: includes fields such as importance, level, user, org, domain, and namespace in the arbitrator prompt.

For Docker, enable arbitrator mode with environment variables:

```bash theme={null}
-e MEMOROSE__RERANKER__TYPE="arbitrator" \
-e MEMOROSE__RERANKER__MODEL="gemini-3.1-flash-lite-preview" \
-e MEMOROSE__RERANKER__MAX_CANDIDATES="32" \
-e MEMOROSE__RERANKER__FALLBACK_TO_WEIGHTED="true"
```

### HTTP reranker mode

HTTP mode is for external plugins. `top_n` applies only to HTTP mode.

```toml theme={null}
[reranker]
type = "http"
provider = "jina"
endpoint = "https://api.jina.ai/v1/rerank"
model = "jina-reranker-v2-base-multilingual"
top_n = 20
timeout_secs = 10
fallback_to_weighted = true
include_metadata = true

[reranker.headers]
Authorization = "Bearer your-reranker-api-key"
```

## Environment variables

There are two supported patterns:

### 1. Nested runtime overrides via `MEMOROSE__`

Use `MEMOROSE__SECTION__KEY=value` to override nested config fields.

```bash theme={null}
MEMOROSE__WORKER__CONSOLIDATION_INTERVAL_MS=1000
MEMOROSE__WORKER__LLM_CONCURRENCY=5
MEMOROSE__WORKER__AUTO_LINK_SIMILARITY_THRESHOLD=0.6
MEMOROSE__RAFT__AUTO_INITIALIZE=true
MEMOROSE__RERANKER__TYPE=arbitrator
MEMOROSE__RERANKER__MODEL=gemini-3.1-flash-lite-preview
MEMOROSE__RERANKER__MAX_CANDIDATES=32
```

### 2. Legacy direct overrides

The server still reads these directly:

```bash theme={null}
GOOGLE_API_KEY=your_google_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
LLM_MODEL=gemini-2.0-flash
EMBEDDING_MODEL=text-embedding-004
NODE_ID=1
RAFT_ADDR=127.0.0.1:5001
```

Operational helpers also use:

```bash theme={null}
DASHBOARD_ADMIN_PASSWORD=change-me
```

Important:

* `LLM_PROVIDER` appears in `.env.example`, but the current server config loader does not directly map that variable into `llm.provider`.
* If you want to switch provider through env only, prefer `MEMOROSE__LLM__PROVIDER=OpenAI` or `MEMOROSE__LLM__PROVIDER=Gemini`.

## What each section controls

* `[llm]`: provider, API endpoint, model names, embedding settings, optional STT settings
* `[storage]`: root data directory and index commit / recent-overlay behavior
* `[raft]`: node identity, raft address, election timing, snapshots, bootstrap behavior
* `[worker]`: consolidation cadence, forgetting, insight generation, task reflection, and auto-link tuning
* `[sharding]`: multi-shard deployment settings and physical node mapping
* `[reranker]`: weighted reranking, internal arbitrator mode, or external HTTP reranker

## Guidance

* Treat `crates/memorose-common/src/config.rs` as the canonical schema.
* Treat `.env.example` as an example convenience file, not as a complete description of all runtime behavior.
* Be careful with older docs or examples that refer to `[server]`, `[database]`, `[consolidation]`, `[forgetting]`, `[graph]`, `/health`, or `/api/v1/*`; those do not represent the current server config and API surface.