# 织忆 v2 — LLM 驱动的自优化系统

> 版本：v2.0.0-draft
> 状态：待评审
> 基于：v1.0.0-stable

---

## 1. 背景与目标

### 1.1 现状问题

v1 版本中，织忆各个模块（distill、consolidate、recall）各自为政，没有全局感知和自主优化能力：

```
commit → distill（被动，一次一条）
     ↓
consolidate（定时，固定流程，不感知状态）
     ↓
质量回溯（采样20条，不闭环）
     ↓
recall（独立系统）
```

**核心矛盾**：LLM 没有被用来管理织忆，参数全靠手设，异常靠牧尘发现。

### 1.2 升级目标

1. **LLM 全局巡检** — 主动发现全流程堵点和异常
2. **参数自动调优** — 基于指标自动调整，无需手设
3. **Hermes 监督汇报** — 我执行操作，牧尘知情，重大决策上报
4. **可回滚** — 任何时候可切回 v1.0.0-stable

### 1.3 设计原则

| 原则 | 说明 |
|---|---|
| 成本优先 | 无异常不调用 LLM，用指标驱动触发 |
| 我执行 | LLM 发现/建议，我执行操作，不让它直连数据 |
| 可观测 | 每次决策记录 JSONL + git commit |
| 轻量触发 | 规则引擎处理常见情况，LLM 只处理复杂因果 |

---

## 2. 系统架构

### 2.1 角色分工

```
┌─────────────────────────────────────────────────────┐
│  织忆 v2 独立部署包（可部署在其他机器）               │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │  LLM Agent（独立运行，不依赖 Hermes）         │   │
│  │  ├─ 自己的 cronjob（每 60 分钟自检）          │   │
│  │  ├─ 规则引擎：自动调参                       │   │
│  │  ├─ LLM 巡检：复杂因果自主决策               │   │
│  │  └─ 自主调用织忆 API 执行操作                │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  决策日志 → git commit → 飞书通知牧尘              │
└─────────────────────────────────────────────────────┘
          ↓（飞书通知，仅重大决策）
┌─────────────────────────────────────────────────────┐
│  Hermes（可选，不参与运行）                         │
│  ├─ 旁听重大决策（飞书收到通知）                    │
│  └─ 牧尘可通过 Hermes 转发指令给 LLM Agent          │
└─────────────────────────────────────────────────────┘
```

### 2.2 独立性设计

LLM Agent 脱离 Hermes 独立运行的关键点：
- 自己的定时器（systemd timer 或 cronjob）
- 自己持有织忆 API 地址和认证
- 自己管理 LLM API（可独立配置模型和端点）
- 飞书机器人直接通知牧尘，不经过 Hermes 中转
- 部署时只需修改配置文件，无需改动 Hermes

### 2.3 与 v1 的关系

- v1 的各个 API 和逻辑保持不变，作为执行层
- v2 在 v1 之上加了一层"调度 + 巡检"逻辑
- v2 的调度器用 cronjob 实现，调用 v1 的已有 API

---

## 3. 触发机制

### 3.1 指标驱动（非定时）

每 60 分钟读取一次状态（现有 cronjob `织忆状态看板`），判断是否触发巡检：

| 触发条件 | 说明 |
|---|---|
| recall 命中率连续 2 次下降 | 需要巡检 recall 质量 |
| gap_detected 堆积 > 5 条未处理 | 需要巡检 recall gap |
| distill 队列积压 > 20 条 | 需要巡检 distill 瓶颈 |
| consolidate 质量分 < 0.6 | 需要巡检聚类/质量回溯 |
| 冲突堆积 > 3 条 | 需要巡检冲突处理 |
| 规则引擎连续 3 次调参无效 | 需要 LLM 分析复杂因果 |

**无异常时完全不调用 LLM**，不花额外费用。

### 3.2 手动触发

牧尘可以随时说"巡检织忆"，我会立即执行一次完整巡检。

---

## 4. 参数自动调优

### 4.1 参数列表

| 参数 | 位置 | 默认值 | 正常范围 | 调整粒度 |
|---|---|---|---|---|
| `dbscan_epsilon` | consolidate | 0.5 | 0.3–1.5 | ±0.1 |
| `dbscan_min_points` | consolidate | 3 | 2–10 | ±1 |
| `decay_rate` | tuning.go | 0.015 | 0.005–0.05 | 乘/除 1.2 |
| `gap_threshold` | tuning.go | 3 | 1–10 | ±1 |
| `consolidate_after` | tuning.go | 50 | 20–200 | ±10 |
| `prune_threshold` | consolidation_pipe.go | 0.15 | 0.05–0.5 | ±0.05 |

### 4.2 规则引擎调参（无需 LLM）

规则引擎根据指标直接调整参数：

```
IF recall 命中率下降 AND noise_points > 总数 30%:
  → epsilon += 0.1

IF gap 堆积 > 5 AND gap_threshold 连续 2 次调低无效:
  → 触发 LLM 巡检

IF distill 质量分下降 AND decay_rate 最近 7 天内未调:
  → decay_rate /= 1.2

IF 修剪节点数 / 总节点数 > 20%:
  → prune_threshold += 0.05
```

### 4.3 LLM 辅助调参

规则引擎遇到复杂因果时，调用 LLM：

```
触发条件：规则引擎连续 3 次调参后指标未改善
输入：系统手册 + 当前指标快照 + 调参历史 + 异常事件
LLM 输出：
  {
    "analysis": "根因分析",
    "action": "调参 / 重蒸 / 合并 / 其他",
    "parameters": { "epsilon": 0.6 },
    "reason": "..."
  }
```

### 4.4 调参执行流程

```
规则引擎判断需要调参
     ↓
读取当前参数值
     ↓
应用调整（写入 tuning.go 或调用 API）
     ↓
记录到 llm-tuning-log.jsonl
     ↓
git commit "llm-tune: epsilon 0.5→0.6"
     ↓
下次指标采样时判断是否生效
```

---

## 5. LLM 系统手册

### 5.1 手册内容

触发 LLM 巡检时，注入以下上下文：

```
你是织忆记忆系统的巡检员，负责发现全流程的堵点和异常。

【系统架构】
- distill：记忆蒸馏，commit 时被动触发，将长对话压缩为记忆
- consolidate：记忆整合，定时（DBSCAN 聚类 + 剪枝 + 衰减校准 + 质量回溯）
- recall：记忆召回，查询时向量检索
- graph：图谱管理，实体/关系/冲突

【参数说明】
- dbscan_epsilon：聚类半径，影响聚类数量和 noise 比例
- dbscan_min_points：最小点数，影响核心点判定
- decay_rate：遗忘衰减率，值越大记忆衰减越快
- gap_threshold：recall gap 感测阈值，连续 N 次 miss 才记录
- prune_threshold：图谱剪枝权重阈值

【正常范围】
- recall 命中率 > 70%
- noise_points / 总数 < 20%
- distill 质量分 > 0.6
- gap 堆积 < 5 条
- 冲突 < 3 条堆积

【约束】
- 不要轻易触发全量重蒸，成本高
- 优先用规则调参，复杂情况才用 LLM
- 每次操作记录到 /home/muc/projects/memoryweave/ops/llm-tuning-log.jsonl

【当前状态】
{timestamp}
{metrics_snapshot}
{recent_events}
调参历史：{tuning_history}
```

### 5.2 手册存放位置

```
/home/muc/projects/memoryweave/ops/ops-manual.md
```

---

## 6. 决策日志

### 6.1 日志格式（JSONL，每行一条）

```json
{"ts":"2026-06-09T03:00:00Z","type":"parameter_tune","param":"dbscan_epsilon","old":"0.5","new":"0.6","reason":"recall命中率下降，noise>30%","trigger":"rule_engine","result":"pending","model":"minimaxai/minimax-m2.7"}
{"ts":"2026-06-09T04:00:00Z","type":"llm_inspection","trigger":"gap堆积>5","analysis":"根因是gap_threshold设置过低","actions":["gap_threshold+=1"],"model":"minimaxai/minimax-m2.7"}
```

### 6.2 文件位置

```
/home/muc/projects/memoryweave/ops/llm-tuning-log.jsonl
```

### 6.3 Git 版本化

每次有决策写入后，提交一次：

```bash
git add ops/llm-tuning-log.jsonl
git commit -m "llm-tune: epsilon 0.5→0.6 (recall下降触发)"
```

---

## 7. LLM Agent 的运行方式

### 7.1 自主 Loop（独立于 Hermes）

LLM Agent 独立运行，通过 systemd timer 每 60 分钟自检：

```
systemd timer（每 60 分钟）:
  ├─ 读取指标（/api/v1/stats）
  ├─ 规则引擎判断
  │   └─ 可处理 → 自动调参 → 记录日志
  │   └─ 复杂因果 → 调用 LLM 巡检
  └─ LLM 巡检结果 → 执行操作 → 记录日志
     └─ 重大决策 → 飞书机器人直接通知牧尘
```

### 7.2 飞书直接通知牧尘

LLM Agent 拥有自己的飞书机器人，重大决策不经过 Hermes 直接通知牧尘：

| 决策类型 | 是否通知 |
|---|---|
| 小调参（epsilon ±0.1） | ❌ 静默 |
| 正常调参（decay_rate ±20%） | ❌ 静默 |
| 大幅调参（decay_rate ±50%以上） | ✅ 飞书通知 |
| 触发全量重蒸 | ✅ 飞书通知 |
| 连续 3 次调参无效 | ✅ 飞书通知 |
| 发现系统性问题（distill 质量持续下降） | ✅ 飞书通知 |

### 7.3 汇报格式（飞书）

```
🤖 织忆 LLM 巡检报告

时间：2026-06-09 08:00
发现问题：recall 命中率下降至 62%，连续 2 次调参无效
分析：根因是 DBSCAN epsilon 过小，导致记忆碎片化
操作：epsilon 0.5→0.7，触发 consolidate full
建议：观察 3 天，如未改善考虑扩大 rerank 范围
```

### 7.4 Hermes 的位置

Hermes 不参与 LLM Agent 的运行，只在以下场景介入：
- 牧尘通过飞书问 Hermes "织忆最近怎么了"→ Hermes 查询日志回答
- 牧尘让 Hermes "帮看看织忆的状态"→ Hermes 调用 LLM Agent 的状态 API
- LLM Agent 通知牧尘后，牧尘追问 Hermes → Hermes 解读

---

## 8. 回滚机制

### 8.1 回滚到 v1

```bash
cd /home/muc/projects/memoryweave
git checkout v1.0.0-stable
git reset --hard
systemctl --user restart zhiyid
```

### 8.2 v1.0.0-stable 内容

```
commit: fix: add clusters_found/noise_points/quality_score to consolidate API
tag: v1.0.0-stable
```

### 8.3 v2 开发分支

```
主开发分支：main（当前）
v1 稳定版：v1.0.0-stable（tag）
v2 发布后打 tag：v2.0.0-stable
```

---

## 9. 实施计划

### Phase 1：日志基础设施（v2 前置）
- 创建 `ops/llm-tuning-log.jsonl`
- 创建 `ops/ops-manual.md`
- 实现 git commit 封装

### Phase 2：LLM Agent Loop
- 实现 cronjob 驱动的自主巡检
- 实现规则引擎自动调参
- 实现 JSONL 写入 + git commit

### Phase 3：Hermes 旁听汇报
- 实现飞书重大决策上报
- 实现牧尘手动巡检入口（飞书 → Hermes → LLM Agent）

---

## 10. 待确认问题

1. **调参上限** — LLM 一次调整不超过一个参数，幅度不超过 ±50% ✅
2. **手动巡检入口** — 牧尘说"巡检织忆"→ LLM Agent 自己的飞书机器人直接响应 ✅
3. **LLM Agent 用的模型** — 和织忆共用同一个 LLM API（`LLM_ENDPOINT` / `LLM_MODEL` 环境变量）✅

---

## 11. 实施计划

### Phase 1：日志基础设施（v2 前置）
- 创建 `ops/llm-tuning-log.jsonl`
- 创建 `ops/ops-manual.md`
- 创建 `ops/llm-agent/` 目录（LLM Agent 代码）
- 实现 git commit 封装

### Phase 2：LLM Agent 独立服务
- 实现 systemd timer + service
- 实现指标读取 + 规则引擎调参
- 实现 LLM 巡检调用
- 配置独立飞书机器人

### Phase 3：部署独立运行
- 配置文件（织忆 API 地址、LLM 端点、飞书机器人）
- 部署在其他机器上验证
- 验证脱离 Hermes 自主运行

---

*文档状态：已保存，待将来需要时实现 v2*

> **状态说明**：v2 方案已完整设计，但因当前织忆运行正常、规模不大，暂不实现。先用监控报警最小闭环。
> 需要时执行：`git checkout main && cat DESIGN-v2-llm-optimizer.md`