Skip to content

configuration.md

Latest commit

 

History

History
274 lines (204 loc) · 9.76 KB

configuration.md

File metadata and controls

274 lines (204 loc) · 9.76 KB
Raw

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

Provider endpoints

Any OpenAI-protocol chat-completions endpoint works. Two aggregators cover the shipped model slugs without rewriting them:

Provider base_url Notes
aimlapi.com https://api.aimlapi.com/v1 Same vendor/model slug convention, so [llm] and [multimodal] defaults work unchanged.
OpenRouter https://openrouter.ai/api/v1 Historical default.

Both openai/gpt-4.1-mini and google/gemini-3-flash-preview were called live against aimlapi.com and answered, including the structured-output (response_format) path the extractors use.

Known limitation — multimodal against aimlapi.com. The image content parts EverOS sends carry image_url.detail = null, which aimlapi.com rejects with HTTP 400 (messages.0.content / invalid_union) where OpenAI and OpenRouter accept it. Text-only calls to [multimodal] are fine; keep [multimodal] on a provider that tolerates the null field until either side changes.

[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