Skip to main content

​
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: 
[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

[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.
ModeConfigBehavior
Weightedtype = "weighted"Default local reranker. Combines vector similarity, importance, and recency.
Arbitratortype = "arbitrator"Uses the configured LLM provider to dynamically choose only genuinely relevant candidates. It can return fewer than the requested limit, including zero.
HTTPtype = "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. 
[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: 
-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. 
[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. 
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: 
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: 
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.