> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorose.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置

> 配置当前 Memorose 运行时，包括 `llm`、`storage`、`worker`、`raft` 和环境变量覆盖。

# 配置

Memorose 从 `config.toml`、`MEMOROSE__*` 环境变量覆盖，以及少量兼容旧版本的环境变量中读取运行时配置。

当前运行时配置由 `crates/memorose-common/src/config.rs` 中的 `AppConfig` 定义。这才是服务端实际读取的权威来源。

## 主要文件

* `config.toml`：服务端加载的运行时配置文件
* `.env`：`./scripts/start_cluster.sh` 等辅助脚本会加载的本地环境变量
* `.env.example`：提供商密钥和常见环境变量覆盖示例
* `crates/memorose-common/src/config.rs`：当前运行时配置结构和默认值

## 当前顶层配置段

当前服务端配置围绕以下部分组织：

```toml theme={null}
[llm]
[storage]
[raft]
[worker]
[sharding]
[reranker]
```

说明：

* `sharding` 是可选的。
* `reranker` 是可选的，默认使用内置 weighted reranker。
* `config.example.toml` 和 `config.toml.example` 是示例文件；权威 schema 仍以 `crates/memorose-common/src/config.rs` 为准。

## 最小可用示例

```toml theme={null}
[llm]
provider = "Gemini"
model = "gemini-2.0-flash"
embedding_model = "text-embedding-004"

[storage]
root_dir = "./data/node-1"
index_commit_interval_ms = 5000

[raft]
node_id = 1
raft_addr = "127.0.0.1:5001"
heartbeat_interval_ms = 500
election_timeout_min_ms = 1500
election_timeout_max_ms = 3000
snapshot_logs = 1000000
auto_initialize = true

[worker]
llm_concurrency = 5
decay_interval_secs = 60
prune_threshold = 0.1
consolidation_interval_ms = 1000
community_interval_ms = 1000
insight_interval_ms = 30000
enable_auto_planner = true
enable_task_reflection = true
auto_link_similarity_threshold = 0.6
tick_interval_ms = 100

[reranker]
type = "weighted"
```

## Reranker 模式

Reranker 是服务端运行时配置。SDK 客户端不会在每次请求里选择 reranker 模式。

| 模式         | 配置                    | 行为                                                         |
| ---------- | --------------------- | ---------------------------------------------------------- |
| Weighted   | `type = "weighted"`   | 默认本地 reranker，组合向量相似度、重要性和新近度。                             |
| Arbitrator | `type = "arbitrator"` | 使用配置好的 LLM provider 动态选择真正相关的候选记忆，可以返回少于请求数量的结果，也可以返回 0 条。 |
| HTTP       | `type = "http"`       | 调用外部 reranker endpoint，例如 Jina 或自定义服务。                     |

### Arbitrator 模式

`arbitrator` 复用主 `[llm]` 的 provider、API key、base URL 和 embedding 设置。如果设置了 `reranker.model`，它只覆盖 arbitrator 使用的生成模型。

```toml theme={null}
[reranker]
type = "arbitrator"
provider = "gemini"
model = "gemini-3.1-flash-lite-preview"
max_candidates = 32
fallback_to_weighted = true
include_metadata = true
```

关键字段：

* `model`：可选的 arbitrator 生成模型覆盖项。不设置时使用 `[llm].model`。
* `max_candidates`：最多送给模型裁决的检索候选数量，不是固定返回条数。
* `fallback_to_weighted`：arbitrator 无法构建或运行失败时回退到 weighted reranker。
* `include_metadata`：在 arbitrator prompt 中包含 importance、level、user、org、domain、namespace 等元数据。

Docker 中可通过环境变量开启 arbitrator：

```bash theme={null}
-e MEMOROSE__RERANKER__TYPE="arbitrator" \
-e MEMOROSE__RERANKER__MODEL="gemini-3.1-flash-lite-preview" \
-e MEMOROSE__RERANKER__MAX_CANDIDATES="32" \
-e MEMOROSE__RERANKER__FALLBACK_TO_WEIGHTED="true"
```

### HTTP reranker 模式

HTTP 模式用于外部插件。`top_n` 只适用于 HTTP 模式。

```toml theme={null}
[reranker]
type = "http"
provider = "jina"
endpoint = "https://api.jina.ai/v1/rerank"
model = "jina-reranker-v2-base-multilingual"
top_n = 20
timeout_secs = 10
fallback_to_weighted = true
include_metadata = true

[reranker.headers]
Authorization = "Bearer your-reranker-api-key"
```

## 环境变量

支持两种模式：

### 1. 使用 `MEMOROSE__` 的嵌套运行时覆盖

使用 `MEMOROSE__SECTION__KEY=value` 覆盖嵌套配置字段。

```bash theme={null}
MEMOROSE__WORKER__CONSOLIDATION_INTERVAL_MS=1000
MEMOROSE__WORKER__LLM_CONCURRENCY=5
MEMOROSE__WORKER__AUTO_LINK_SIMILARITY_THRESHOLD=0.6
MEMOROSE__RAFT__AUTO_INITIALIZE=true
MEMOROSE__RERANKER__TYPE=arbitrator
MEMOROSE__RERANKER__MODEL=gemini-3.1-flash-lite-preview
MEMOROSE__RERANKER__MAX_CANDIDATES=32
```

### 2. 兼容旧版本的直接覆盖

当前服务端仍会直接读取这些变量：

```bash theme={null}
GOOGLE_API_KEY=your_google_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
LLM_MODEL=gemini-2.0-flash
EMBEDDING_MODEL=text-embedding-004
NODE_ID=1
RAFT_ADDR=127.0.0.1:5001
```

运维辅助脚本还会使用：

```bash theme={null}
DASHBOARD_ADMIN_PASSWORD=change-me
```

重要说明：

* `.env.example` 里出现了 `LLM_PROVIDER`，但当前服务端配置加载器不会直接把它映射到 `llm.provider`。
* 如果你想纯靠环境变量切换 provider，优先使用 `MEMOROSE__LLM__PROVIDER=OpenAI` 或 `MEMOROSE__LLM__PROVIDER=Gemini`。

## 各配置段控制什么

* `[llm]`：provider、API endpoint、模型名、embedding 设置、可选 STT 设置
* `[storage]`：数据根目录、索引提交与 recent overlay 行为
* `[raft]`：节点身份、raft 地址、选举时序、快照、引导行为
* `[worker]`：整合节奏、遗忘、insight 生成、任务反思、自动连边调优
* `[sharding]`：多分片部署设置和物理节点映射
* `[reranker]`：weighted reranker、内部 arbitrator 模式或外部 HTTP reranker

## 指导建议

* 把 `crates/memorose-common/src/config.rs` 视为权威 schema。
* 把 `.env.example` 视为示例 convenience file，而不是完整的运行时行为说明。
* 对提及 `[server]`、`[database]`、`[consolidation]`、`[forgetting]`、`[graph]`、`/health` 或 `/api/v1/*` 的旧示例保持警惕；它们不代表当前服务端的配置和 API。