# A_Memorix 配置参考 (v2.0.0)

本文档对应当前仓库代码（`__version__ = 2.0.0`、`SCHEMA_VERSION = 9`）。

说明：

- 本文只覆盖 **当前运行时实际读取** 的配置键。
- 默认配置文件路径为 `config/a_memorix.toml`。
- 旧版 `/query`、`/memory`、`/visualize` 命令体系相关配置，不再作为主路径说明。
- 未配置的键会回退到代码默认值。
- 长期记忆控制台已可视化高频常用字段；未展示的长尾高级项仍然有效，请通过“源码模式 / 原始 TOML”编辑。

## 常用完整配置

```toml
[plugin]
enabled = true

[storage]
data_dir = "data/a-memorix"

[embedding]
model_name = "auto"
dimension = 1024
batch_size = 32
max_concurrent = 5
enable_cache = false
quantization_type = "int8"

[embedding.fallback]
enabled = true
probe_interval_seconds = 180
allow_metadata_only_write = true

[embedding.paragraph_vector_backfill]
enabled = true
interval_seconds = 60
batch_size = 64
max_retry = 5

[retrieval]
top_k_paragraphs = 20
top_k_relations = 10
top_k_final = 10
alpha = 0.5
enable_ppr = true
ppr_alpha = 0.85
ppr_timeout_seconds = 1.5
ppr_concurrency_limit = 4
enable_parallel = true

[retrieval.sparse]
enabled = true
backend = "fts5"
mode = "auto"
tokenizer_mode = "jieba"
candidate_k = 80
relation_candidate_k = 60

[threshold]
min_threshold = 0.3
max_threshold = 0.95
percentile = 75.0
min_results = 3
enable_auto_adjust = true

[filter]
enabled = true
mode = "blacklist"
chats = []

[episode]
enabled = true
generation_enabled = true
pending_batch_size = 20
pending_max_retry = 3
max_paragraphs_per_call = 20
max_chars_per_call = 6000
source_time_window_hours = 24
segmentation_model = "auto"

[person_profile]
enabled = true
refresh_interval_minutes = 30
active_window_hours = 72
max_refresh_per_cycle = 50
top_k_evidence = 12

[memory]
enabled = true
half_life_hours = 24.0
prune_threshold = 0.1
freeze_duration_hours = 24.0

[advanced]
enable_auto_save = true
auto_save_interval_minutes = 5
debug = false

[web.import]
enabled = true
max_queue_size = 20
max_files_per_task = 200
max_file_size_mb = 20
max_paste_chars = 200000
default_file_concurrency = 2
default_chunk_concurrency = 4

[web.tuning]
enabled = true
max_queue_size = 8
poll_interval_ms = 1200
default_intensity = "standard"
default_objective = "precision_priority"
default_top_k_eval = 20
default_sample_size = 24
```

### 可视化与原始 TOML 的分工

- 长期记忆控制台：适合修改高频项，例如 embedding、检索、Episode、人物画像、导入与调优的常用开关。
- 原始 TOML：适合复制整份配置、批量调整参数，或修改未在可视化表单中展示的高级项。
- raw-only 高级项仍包括：`retrieval.fusion.*`、`retrieval.search.relation_intent.*`、`retrieval.search.graph_recall.*`、`retrieval.aggregate.*`、`memory.orphan.*`、`advanced.extraction_model`、`web.import.llm_retry.*`、`web.import.path_aliases`、`web.import.convert.*`、`web.tuning.llm_retry.*`、`web.tuning.eval_query_timeout_seconds`。

## 1. 存储与嵌入

### `storage`

- `storage.data_dir` (当前配置模板默认 `data/a-memorix`)
: 数据目录。相对路径按 MaiBot 仓库根目录解析。

补充说明：

- 部分离线脚本若未显式覆盖路径，会回退到 `A_memorix.paths.default_data_dir()`（当前为 `data/plugins/a-dawn.a-memorix`）。
- 建议在运维侧统一目录策略，避免“控制台写入目录”和“脚本处理目录”不一致。

### `embedding`

- `embedding.model_name` (默认 `auto`)
: embedding 模型选择。
- `embedding.dimension` (默认 `1024`)
: 唯一公开的维度控制项。A_Memorix 内部会自动映射为 provider 所需请求字段，并在运行时做真实探测与校验。
- `embedding.batch_size` (默认 `32`)
- `embedding.max_concurrent` (默认 `5`)
- `embedding.enable_cache` (默认 `false`)
- `embedding.retry` (默认 `{}`)
: embedding 调用重试策略。
- `embedding.quantization_type`
: 当前主路径仅建议 `int8`。
- `embedding.fallback.enabled` (默认 `true`)
- `embedding.fallback.probe_interval_seconds` (默认 `180`)
- `embedding.fallback.allow_metadata_only_write` (默认 `true`)
- `embedding.paragraph_vector_backfill.enabled` (默认 `true`)
- `embedding.paragraph_vector_backfill.interval_seconds` (默认 `60`)
- `embedding.paragraph_vector_backfill.batch_size` (默认 `64`)
- `embedding.paragraph_vector_backfill.max_retry` (默认 `5`)

## 2. 检索

### `retrieval` 主键

- `retrieval.top_k_paragraphs` (默认 `20`)
- `retrieval.top_k_relations` (默认 `10`)
- `retrieval.top_k_final` (默认 `10`)
- `retrieval.alpha` (默认 `0.5`)
- `retrieval.enable_ppr` (默认 `true`)
- `retrieval.ppr_alpha` (默认 `0.85`)
- `retrieval.ppr_timeout_seconds` (默认 `1.5`)
- `retrieval.ppr_concurrency_limit` (默认 `4`)
- `retrieval.enable_parallel` (默认 `true`)
- `retrieval.relation_vectorization.enabled` (默认 `false`)

### `retrieval.sparse` (`SparseBM25Config`)

常用键（默认值）：

- `enabled = true`
- `backend = "fts5"`
- `lazy_load = true`
- `mode = "auto"` (`auto`/`fallback_only`/`hybrid`)
- 运行时若 embedding 进入 degraded，会强制按 `fallback_only` 执行读路径（不改用户配置文件）
- `tokenizer_mode = "jieba"` (`jieba`/`mixed`/`char_2gram`)
- `char_ngram_n = 2`
- `candidate_k = 80`
- `relation_candidate_k = 60`
- `enable_ngram_fallback_index = true`
- `enable_relation_sparse_fallback = true`

### `retrieval.fusion` (`FusionConfig`)

- `method` (默认 `weighted_rrf`)
- `rrf_k` (默认 `60`)
- `vector_weight` (默认 `0.7`)
- `bm25_weight` (默认 `0.3`)
- `normalize_score` (默认 `true`)
- `normalize_method` (默认 `minmax`)

### `retrieval.search.relation_intent` (`RelationIntentConfig`)

- `enabled` (默认 `true`)
- `alpha_override` (默认 `0.35`)
- `relation_candidate_multiplier` (默认 `4`)
- `preserve_top_relations` (默认 `3`)
- `force_relation_sparse` (默认 `true`)
- `pair_predicate_rerank_enabled` (默认 `true`)
- `pair_predicate_limit` (默认 `3`)

### `retrieval.search.graph_recall` (`GraphRelationRecallConfig`)

- `enabled` (默认 `true`)
- `candidate_k` (默认 `24`)
- `max_hop` (默认 `1`)
- `allow_two_hop_pair` (默认 `true`)
- `max_paths` (默认 `4`)

### `retrieval.aggregate`

- `retrieval.aggregate.rrf_k`
- `retrieval.aggregate.weights`

用于聚合检索阶段混合策略；未配置时走代码默认行为。

## 3. 阈值过滤

### `threshold` (`ThresholdConfig`)

- `threshold.min_threshold` (默认 `0.3`)
- `threshold.max_threshold` (默认 `0.95`)
- `threshold.percentile` (默认 `75.0`)
- `threshold.std_multiplier` (默认 `1.5`)
- `threshold.min_results` (默认 `3`)
- `threshold.enable_auto_adjust` (默认 `true`)

## 4. 聊天过滤

### `filter`

用于 `respect_filter=true` 场景（检索和写入都支持）。

```toml
[filter]
enabled = true
mode = "blacklist" # blacklist / whitelist
chats = ["group:123", "user:456", "stream:abc"]
```

规则：

- `blacklist`：命中列表即拒绝
- `whitelist`：仅列表内允许
- 列表为空时：
  - `blacklist` => 全允许
  - `whitelist` => 全拒绝

## 5. Episode

### `episode`

- `episode.enabled` (默认 `true`)
- `episode.generation_enabled` (默认 `true`)
- `episode.pending_batch_size` (默认 `20`，部分路径默认 `12`)
- `episode.pending_max_retry` (默认 `3`)
- `episode.max_paragraphs_per_call` (默认 `20`)
- `episode.max_chars_per_call` (默认 `6000`)
- `episode.source_time_window_hours` (默认 `24`)
- `episode.segmentation_model` (默认 `auto`)
: 支持 `auto`，也支持填写 `utils/replyer/planner/tool_use` 或具体模型名。

## 6. 人物画像

### `person_profile`

- `person_profile.enabled` (默认 `true`)
- `person_profile.refresh_interval_minutes` (默认 `30`)
- `person_profile.active_window_hours` (默认 `72`)
- `person_profile.max_refresh_per_cycle` (默认 `50`)
- `person_profile.top_k_evidence` (默认 `12`)

## 7. 记忆演化与回收

### `memory`

- `memory.enabled` (默认 `true`)
- `memory.half_life_hours` (默认 `24.0`)
- `memory.base_decay_interval_hours` (默认 `1.0`)
- `memory.prune_threshold` (默认 `0.1`)
- `memory.freeze_duration_hours` (默认 `24.0`)

### `memory.orphan`

- `enable_soft_delete` (默认 `true`)
- `entity_retention_days` (默认 `7.0`)
- `paragraph_retention_days` (默认 `7.0`)
- `sweep_grace_hours` (默认 `24.0`)

## 8. 高级运行时

### `advanced`

- `advanced.enable_auto_save` (默认 `true`)
- `advanced.auto_save_interval_minutes` (默认 `5`)
- `advanced.debug` (默认 `false`)
- `advanced.extraction_model` (默认 `auto`)

## 9. 导入中心 (`web.import`)

### 开关与限流

- `web.import.enabled` (默认 `true`)
- `web.import.max_queue_size` (默认 `20`)
- `web.import.max_files_per_task` (默认 `200`)
- `web.import.max_file_size_mb` (默认 `20`)
- `web.import.max_paste_chars` (默认 `200000`)
- `web.import.default_file_concurrency` (默认 `2`)
- `web.import.default_chunk_concurrency` (默认 `4`)
- `web.import.max_file_concurrency` (默认 `6`)
- `web.import.max_chunk_concurrency` (默认 `12`)
- `web.import.poll_interval_ms` (默认 `1000`)

### 重试与路径

- `web.import.llm_retry.max_attempts` (默认 `4`)
- `web.import.llm_retry.min_wait_seconds` (默认 `3`)
- `web.import.llm_retry.max_wait_seconds` (默认 `40`)
- `web.import.llm_retry.backoff_multiplier` (默认 `3`)
- `web.import.path_aliases` (默认内置 `raw/lpmm/plugin_data`)

### 转换阶段

- `web.import.convert.enable_staging_switch` (默认 `true`)
- `web.import.convert.keep_backup_count` (默认 `3`)

## 10. 调优中心 (`web.tuning`)

- `web.tuning.enabled` (默认 `true`)
- `web.tuning.max_queue_size` (默认 `8`)
- `web.tuning.poll_interval_ms` (默认 `1200`)
- `web.tuning.eval_query_timeout_seconds` (默认 `10.0`)
- `web.tuning.default_intensity` (默认 `standard`，可选 `quick/standard/deep`)
- `web.tuning.default_objective` (默认 `precision_priority`，可选 `precision_priority/balanced/recall_priority`)
- `web.tuning.default_top_k_eval` (默认 `20`)
- `web.tuning.default_sample_size` (默认 `24`)
- `web.tuning.llm_retry.max_attempts` (默认 `3`)
- `web.tuning.llm_retry.min_wait_seconds` (默认 `2`)
- `web.tuning.llm_retry.max_wait_seconds` (默认 `20`)
- `web.tuning.llm_retry.backoff_multiplier` (默认 `2`)

## 11. 兼容性提示

- 若你从 `1.x` 升级，请优先运行：

```bash
python src/A_memorix/scripts/release_vnext_migrate.py preflight --strict
python src/A_memorix/scripts/release_vnext_migrate.py migrate --verify-after
python src/A_memorix/scripts/release_vnext_migrate.py verify --strict
```

- 启动前再执行：

```bash
python src/A_memorix/scripts/runtime_self_check.py --json
```

以避免 embedding 维度与向量库不匹配导致运行时异常。