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).

[index]

The derived vector/BM25 index is rebuildable; Markdown remains the source of truth regardless of backend.

Field	Type	Default	Description
backend	string	"lancedb"	Index implementation: lancedb or milvus.

[milvus]

Used only when index.backend = "milvus". Install the optional client with pip install "everos[milvus]". EverOS supports a remote Milvus Server or Zilliz Cloud endpoint; a Milvus Lite filesystem path is rejected.

Field	Type	Default	Description
uri	string	""	Milvus Server or Zilliz Cloud URI.
token	string	""	Authentication token, when required.
db_name	string	""	Optional Milvus database name.
consistency_level	string	"Session"	Milvus consistency level used by collections.
collection_prefix	string	"everos"	Prefix for the seven derived-index collections.

[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.8-flash"	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.
dim	int	1024	No	Width of the vector column in every index table. See below.
dimensions	int	—	No	Server-side truncation width, passed through to the embedding API for models that support it (Matryoshka). Independent of dim.
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	10	No	Max parallel batch requests from write paths.
query_max_concurrent	int	16	No	Separate budget for interactive query embeds, so a search is not queued behind cascade writes. Each hybrid or vector search holds one slot for one embedding call, so the sustainable search rate is about this value divided by the endpoint's per-call latency; lower it if the endpoint is rate-limited.

timeout_seconds bounds one request, and one request carries up to batch_size texts (the cascade embeds a file's changed entries in one batched call). On a slow or serialized local endpoint (CPU Ollama, a single GPU) queued batch requests can exceed the timeout: lower batch_size and max_concurrent together, or raise timeout_seconds.

Vector width (dim)

Every index table stores vectors in a fixed-width column, and dim is that width. The model has to agree with it:

• Model returns fewer dimensions than dim — startup stops. Nothing could ever be stored, so there is no useful degraded mode. Set dim to what the model returns, then run everos cascade rebuild: the tables were already created at the old width.

• Model returns more than dim — the extra dimensions are truncated on every write, and startup warns once. This is lossless only for models trained for it (Matryoshka representation learning); with any other model recall degrades, because a plain prefix of an embedding is not a valid embedding. Either match dim to the model or use a Matryoshka model.

  The shipped default is this case: Qwen/Qwen3-Embedding-4B returns 2560 dimensions and the default dim is 1024, so a default install sees this warning at every start. It is Matryoshka-trained, 1024 is one of its published truncation points, and the index compares with cosine distance, so nothing is lost. To silence it, set dimensions = 1024 so the server returns the shorter vector — but only if your endpoint accepts that parameter; some self-hosted servers reject it outright, which is why it is not the default.

• Changing dim on an existing index — startup stops. Vectors of different lengths have no distance between them, so there is nothing to migrate: everos cascade rebuild re-embeds from markdown.

• Downgrading after changing dim — an older EverOS hardcodes 1024, so it refuses to start against a wider or narrower index (schema drift: type_drift=[...]), and its cascade rebuild rebuilds at 1024 without mentioning it. Set dim back to 1024 and rebuild before downgrading, or expect to rebuild afterwards.

dimensions is a different knob: it asks the server to truncate (with re-normalisation, which is why it is preferable when the model supports it). Tables are still built at dim. If both are set and they disagree, startup warns and names both values.

The width is measured by one embedding call at startup, with a 5-second budget and no retries — it buys a single integer and sits in front of every everos command, so it does not inherit timeout_seconds × max_retries. A model that is still loading (a cold local endpoint) can miss that budget: the width check is then skipped for that start, the tables are created at dim, and /health reports embed: false until the next restart. Start the model first, or restart once it is up.

Changing the embedding model

An index remembers which model built it, and startup refuses to open one built by a different model -- distances between vectors from two models are meaningless, and the failure is otherwise silent: searches simply return nothing useful. The recovery is everos cascade rebuild, which re-embeds every entry from markdown and records the new model.

Deployments with no embedding configured (no api_key, for instance) are unaffected: nothing is probed, compared, or recorded.

[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.

[memorize.async_queue]

Bounds and behaviour of the queue behind async_mode on /add (a /flush joins it only behind its session's backlog) (see api.md).

Field	Type	Default	Description
enabled	bool	true	Off: new async_mode requests run synchronously; rows accepted while on are still delivered, and their sessions keep the ordering rule.
max_concurrency	int	4	Batches delivered at once, never two from one session: a session's batches run in arrival order, sessions run side by side. 1 serialises everything.
max_pending_per_session	int	50	Unfinished batches per session; beyond this /add and /flush answer 429.
max_pending_total	int	200	Unfinished batches across all sessions; beyond this the answer is 429.
max_payload_bytes	int	4194304	One serialised request body; beyond this the answer is 413.
scan_interval_seconds	float	5.0	Fallback sweep interval; an enqueue wakes the worker immediately.
max_attempts	int	1	Delivery attempts per batch before it is marked failed and skipped. Keep 1 unless duplicate memcells after a partial failure are acceptable: the pipeline is not atomic.
retry_backoff_seconds	float	2.0	Pause between attempts.
max_replays	int	3	A batch in flight when the process died is replayed on the next start; after this many replays without finishing it is marked failed (error_code: replays_exhausted).
row_retention_hours	float	168.0	Rows of any status are deleted this long after creation (seven days), including rows never delivered; the purge logs a warning for those. Delivered rows drop their request body at once, failed rows keep it.

[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