/docs/configuration.md

# Configuration

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

## Quick Start

```bash
# 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`:

```bash
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:

```bash
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:

```dockerfile
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` |