evermind-ai--everos/docs/configuration.md

Configuration

EverOS uses a two-file TOML configuration system with environment variable overrides for container deployments.

Quick Start

# 1. Generate config files in the default root (~/.everos/)
everos init

# 2. Edit the config — fill in API keys
$EDITOR ~/.everos/everos.toml

# 3. Start the server
everos server start

Configuration Files

everos.toml — Application Settings

Located at <root>/everos.toml. Controls all application behavior: API bind address, LLM/embedding/rerank provider credentials, SQLite pragmas, search strategy, memorize mode, and clustering tunables.

Generated by everos init from the shipped config/default.toml template. Changes require a server restart.

ome.toml — Strategy Configuration

Located at <root>/ome.toml. Controls the Offline Memory Engine (OME) strategy scheduling: which strategies are enabled, cron expressions, gate thresholds, and retry limits.

Generated by everos init from the shipped config/default_ome.toml template. Changes are hot-reloaded within ~2 seconds — no server restart needed.

Source Priority

Settings are resolved in this order (later wins):

1. config/default.toml — shipped defaults (lowest priority)
2. <root>/everos.toml — user configuration (optional)
3. EVEROS_* environment variables — container/CI overrides
4. Programmatic init args (highest priority; internal use)

Memory Root Resolution

The memory root directory is resolved from three sources (first wins):

Source	Example
--root CLI flag	everos server start --root /data/everos
EVEROS_ROOT env var	export EVEROS_ROOT=/data/everos
Default	~/.everos

All CLI commands that interact with storage accept --root:

everos server start --root /data/everos
everos cascade status --root /data/everos
everos config show --root /data/everos
everos init --root /data/everos

Configuration Reference

[memory]

Field	Type	Default	Description
timezone	string	"UTC"	Effective timezone for date buckets and timestamps. Validated against zoneinfo.ZoneInfo.

[api]

Field	Type	Default	Description
host	string	"127.0.0.1"	HTTP server bind address.
port	int	8000	HTTP server bind port (1–65535).

[sqlite]

Field	Type	Default	Description
journal_mode	string	"WAL"	PRAGMA journal_mode. Options: WAL, DELETE, MEMORY, OFF, TRUNCATE, PERSIST.
synchronous	string	"NORMAL"	PRAGMA synchronous. Options: FULL, NORMAL, OFF, EXTRA.
foreign_keys	bool	true	PRAGMA foreign_keys.
temp_store	string	"MEMORY"	PRAGMA temp_store. Options: DEFAULT, FILE, MEMORY.
busy_timeout_ms	int	5000	PRAGMA busy_timeout in milliseconds.
journal_size_limit_bytes	int	67108864	PRAGMA journal_size_limit (~64 MB).
cache_size_kb	int	2048	PRAGMA cache_size in KB (per connection).

[lancedb]

Field	Type	Default	Description
read_consistency_seconds	float | null	null	Read consistency interval. null = no check, 0 = strict, >0 = eventual.
index_cache_size_bytes	int	16777216	Upper bound on LanceDB index cache (16 MB default).

[llm]

Field	Type	Default	Required	Description
model	string	"gpt-4.1-mini"	No	LLM model identifier.
api_key	string	—	Yes	API key for the LLM provider.
base_url	string	—	No	Custom endpoint URL (OpenAI-compatible).

[multimodal]

Field	Type	Default	Required	Description
model	string	"google/gemini-3-flash-preview"	No	Multimodal parsing model.
api_key	string	—	Yes	API key.
base_url	string	—	No	Custom endpoint URL.
max_concurrency	int	4	No	Max parallel parsing requests.
file_uri_allow_dirs	list[string]	[]	No	Allowlisted base dirs for file:// URIs. Empty = allow any readable file.
file_uri_max_bytes	int	52428800	No	Max size (bytes) of a file:// asset; larger files are rejected.

[embedding]

Field	Type	Default	Required	Description
model	string	—	Yes	Embedding model identifier.
api_key	string	—	Yes	API key.
base_url	string	—	Yes	Embedding endpoint URL.
timeout_seconds	float	30.0	No	Request timeout.
max_retries	int	3	No	Retry count on failure.
batch_size	int	10	No	Texts per batch request.
max_concurrent	int	5	No	Max parallel batch requests.

[rerank]

Field	Type	Default	Required	Description
provider	string	"deepinfra"	No	Rerank provider: deepinfra or vllm.
model	string	—	Yes	Reranker model identifier.
api_key	string	—	Yes	API key.
base_url	string	—	Yes	Rerank endpoint URL.
timeout_seconds	float	30.0	No	Request timeout.
max_retries	int	3	No	Retry count on failure.
batch_size	int	10	No	Documents per batch.
max_concurrent	int	5	No	Max parallel batch requests.

[boundary_detection]

Field	Type	Default	Description
hard_token_limit	int	65536	Max tokens before forced boundary.
hard_msg_limit	int	500	Max messages before forced boundary.

[memorize]

Field	Type	Default	Description
mode	string	"agent"	Conversation mode: chat (user-memory only) or agent (user + agent memory). Requires restart.
session_lock_timeout_seconds	float	360.0	Max wall-clock per memorize() invocation.

[clustering]

Field	Type	Default	Description
threshold	float	0.65	Cosine similarity threshold for clustering (0–1).
time_window_days	float	7.0	Max age gap between cluster members.

[knowledge]

Field	Type	Default	Description
max_upload_bytes	int	52428800	Max bytes for an uploaded knowledge document (50 MiB). Oversized uploads are rejected with HTTP 422 before parsing.

[knowledge.search]

Field	Type	Default	Description
recall_n	int	200	Initial recall pool size.
rerank_n	int	50	Candidates sent to reranker.
mass_top_m	int	50	Top-M for mass scoring.
lambda	float	0.1	Interpolation weight.
top_k_cap	int	100	Hard cap on returned results.

Troubleshooting

Use everos config show to inspect the effective configuration:

everos config show
everos config show --root /data/everos

This prints:

• The resolved root directory
• Which config files were found
• All settings sections with their effective values
• API keys are masked in output

Advanced: Container Deployment

In containerized environments, skip everos init and use environment variables directly:

ENV EVEROS_ROOT=/data/everos
ENV EVEROS_LLM__API_KEY=sk-...
ENV EVEROS_LLM__MODEL=gpt-4o
ENV EVEROS_EMBEDDING__MODEL=text-embedding-3-large
ENV EVEROS_EMBEDDING__API_KEY=sk-...
ENV EVEROS_EMBEDDING__BASE_URL=https://api.openai.com/v1
ENV EVEROS_API__HOST=0.0.0.0
ENV EVEROS_API__PORT=8000

Environment variable naming convention:

EVEROS_<SECTION>__<KEY>

• Section and key are uppercased
• Double underscore (__) separates section from key
• Nested sections use additional __ separators

Examples:

TOML	Environment Variable
[llm] api_key = "sk-..."	EVEROS_LLM__API_KEY=sk-...
[sqlite] busy_timeout_ms = 10000	EVEROS_SQLITE__BUSY_TIMEOUT_MS=10000
[memory] timezone = "Asia/Tokyo"	EVEROS_MEMORY__TIMEZONE=Asia/Tokyo