wehub-resource-sync
6c9c7fe7f3
CI / integration tests (3.13) (push) Failing after 1s
Commit lint / pull request title (push) Has been skipped
Docs / links (push) Failing after 1s
CI / unit tests (3.13) (push) Failing after 1s
CI / lint (push) Failing after 1s
CI / integration tests (push) Failing after 1s
CI / package build (push) Failing after 1s
Commit lint / commit messages (push) Failing after 1s
CI / unit tests (push) Failing after 1s
231 lines
7.9 KiB
Markdown
231 lines
7.9 KiB
Markdown
# 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` |
|