提案｜网关会话记忆层（第三块知识资产）：捕获流经 WaLiAPI 的对话→蒸馏长期记忆→按需注入，与 KB/Wiki 并列

## 一、背景与痛点

WaLiAPI 作为网关，处在每个 Agent 请求的必经之路上——它看得见 Claude Code、Codex、各类客户端的**全部对话**，但今天这些对话只是孤立的请求日志：没有会话维度（`request_logs` 无 conversation_id），同一客户端的连续多轮对话串不成线，legacy `/v1/messages` 路径的响应内容甚至未归一化落库。对话流过即丢，**知识不积累**。

知识库（KB）解决「文档知识」，Wiki 解决「结构化知识」，但会话中持续产生的**经验与偏好**（用户怎么用、什么路径有效、哪些坑反复踩）是第三块知识资产，目前完全流失。社区方向已经验证：mem0（64k+ stars）、TencentDB-Agent-Memory（25k+ stars）、OpenViking 都在做 Agent 记忆，但它们都是独立服务；**WaLiAPI 作为网关天然已经在链路上，捕获会话零接入成本**——这是别的方案需要 Proxy 转发才能获得的位置优势。

与现有能力的关系：记忆层是 Wiki 设计中预留而未实现的 Chat Agent / AgentSession（Phase 4）的地基，也与 kb-upgrade-v2 的「对话历史」互补——KB 记文档，Wiki 记结构，会话记忆记「人与 Agent 协作中产生的经验」。

## 二、总体架构

```text
Agent(Claude Code/Codex/…) ──► WaLiAPI 网关 ──► 上游渠道(OpenAI/Anthropic/…)
│
┌──────────┴──────────┐
│ ① 会话捕获 │ 挂在既有日志终笔旁，
│ （日志终笔旁挂） │ 重试不计轮次、失败不阻塞
│ ② 会话线程化 │ 显式优先 + 启发式兜底
└──────────┬──────────┘
▼
③ 异步蒸馏（阈值触发：会话满 N 轮或静默 M 分钟）
经管理员可配的「蒸馏渠道」调用 LLM，ADD-only 提取
▼
④ 记忆库（SQLite + FTS5 + HNSW 既有基座，bi-temporal 失效）
▼
⑤ MCP 记忆工具（memory_search / memory_get / memory_list）
▼
Agent 主动检索 ◄──（二期展望：稳定层摘要小预算自动注入）
```

## 三、数据模型（SQL DDL）

### 3.1 会话表（P0，迁移 025）

```sql
CREATE TABLE conversations (
id TEXT PRIMARY KEY,
api_key_id TEXT NOT NULL, -- 第一隔离边界
api_key_name TEXT,
downstream_endpoint TEXT NOT NULL, -- /v1/chat/completions 等
model TEXT NOT NULL,
origin TEXT NOT NULL DEFAULT 'heuristic', -- explicit | heuristic
client_session_id TEXT, -- 显式会话标识
user_scope TEXT, -- 可选 user 子作用域（过滤器字段）
turn_count INTEGER NOT NULL DEFAULT 0,
first_request_at TEXT NOT NULL,
last_request_at TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'active', -- active|closed_timeout|closed_manual
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
CREATE INDEX idx_conversations_scope
ON conversations(api_key_id, downstream_endpoint, model, last_request_at);

-- request_logs 增列（只增不破坏，历史日志不回填）
ALTER TABLE request_logs ADD COLUMN conversation_id TEXT;
```

### 3.2 记忆表（P2）

```sql
CREATE TABLE memories (
id TEXT PRIMARY KEY,
api_key_id TEXT NOT NULL, -- 与会话同边界
user_scope TEXT, -- 可选二级过滤（mem0 式，不分库）
kind TEXT NOT NULL, -- fact | preference | episode | skill
content TEXT NOT NULL,
entities TEXT, -- JSON 数组：实体链接
embedding BLOB, -- 与 kb_chunks 同模式（BLOB+dim）
embedding_dim INTEGER,
source_conversation_id TEXT, -- 溯源到会话与轮次
source_request_seq INTEGER,
valid_from TEXT NOT NULL, -- bi-temporal：生效时间
valid_to TEXT, -- 失效时间（NULL=当前有效）
status TEXT NOT NULL DEFAULT 'active',
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
CREATE INDEX idx_memories_scope ON memories(api_key_id, user_scope, status);
```

## 四、关键设计决策

1. **会话归组——显式优先 + 启发式兜底**：`X-WaLi-Session` 头 > 请求体 `user`（chat）/ `metadata.user_id`（messages）字段 > 启发式（api_key + 下游端点 + 模型三元组，距上次请求 30 分钟内续接、否则新开）。归组是纯函数 + 真值表测试；默认参数（窗口、头名）集中定义可调。
2. **记忆提取——ADD-only，不做 LLM 合并**（mem0 2026 新算法先例）：只增不改，记忆失效靠 bi-temporal 时间戳（graphiti 思想）而非 UPDATE/DELETE 决策，避免合并误删、实现简单可解释。
3. **触发与成本——阈值异步 + 可配蒸馏渠道**：会话满 N 轮（默认 8）或静默 M 分钟（默认 30）后异步批量蒸馏；蒸馏 LLM 走管理员可配的专用渠道配置（默认复用网关现有选路），额度与模型可控可审计；embedding 链路不可用时降级为 BM25-only 检索兜底。
4. **作用域——api_key 主边界 + 可选 user 子作用域**：api_key 硬隔离；user 存在时作为过滤器字段（不分库），与归组规则天然衔接。
5. **暴露——MCP 按需拉取先行**：先交付 `memory_search / memory_get / memory_list` 工具（TencentDB 按需调用先例），Agent 主动检索，零请求路径风险；**自动注入列为二期展望**（稳定层摘要小预算尾部追加、可开关可审计）。
6. **鉴权前置**：当前 `/mcp`、`/api/kb`、`/api/wiki` 尚无鉴权（api_key 体系只覆盖 `/v1/*`）——记忆经 MCP 暴露前必须补上。可先出独立小 PR 修复，或并入 P3，请维护者定夺。
7. **安全与留存**：记忆内容复用既有 request_body 脱敏管道；retention 默认 90 天可配。

## 五、分期方案（按工程能力增量切分，每期一个可独立合入的 PR）

分期依据只有两条：**依赖顺序**（每期建立在前一期交付之上）与**可独立合入性**（每期自成完整价值、互不阻塞主线）。

| 分期 | 主题 | 交付物 | 依赖 | 尺寸 |
|---|---|---|---|---|
| P0 | 会话数据模型与捕获 | conversations 表、request_logs.conversation_id、归组纯函数+真值表、legacy messages 响应归一化、重试去重 | 无 | 小（**规格与测试设计已备好，可立即出 PR**） |
| P1 | 记忆提取管道 | 阈值触发、蒸馏渠道配置项、ADD-only 提取、BM25-only 降级链 | P0 | 中 |
| P2 | 记忆存储与混合检索 | memories 表、bi-temporal 失效、接入既有 hybrid_search（向量+FTS5） | P1 | 中 |
| P3 | MCP 记忆工具与鉴权前置 | memory_* 工具、`/mcp` 与 `/api/*` 鉴权 | P2 | 中 |
| P4 | 前端面板与可观测 | 记忆库可浏览、检索/注入审计、会话列表页 | P3 | 中 |

二期展望：自动注入双轨（稳定层摘要注入 + 事实层按需）、历史日志会话回填、多租户体系。

## 六、协同与开放问题

- **与现有路线的关系**：记忆层是 kb-upgrade-v2「对话历史」与 Wiki Phase 4 Chat Agent（AgentSession）的地基，不重复、不推翻任何现有模块；KB/Wiki/MCP 全部复用。
- **开放问题（请拍板）**：1) 30 分钟窗口 / `X-WaLi-Session` 头名等默认值是否合适；2) 鉴权修复先出独立 PR 还是并入 P3；3) 蒸馏渠道默认策略（复用选路 vs 强制显式配置）；4) memories 与 kb 的 embedding 模型配置是共用还是独立配置。
- **许可声明**：仅借鉴设计思想——mem0（Apache-2.0）、TencentDB-Agent-Memory（MIT）、OpenViking（AGPLv3，**零代码引用**）；所有实现为原创 Rust 代码，落库 WaLiAPI 既有 SQLite+FTS5+HNSW 基座。
- 我可以先从 **P0** 开始出 PR（完整规格、测试用例与迁移脚本已备好），您审阅方向后即可动手。

For the P0 scope, start by reviewing the existing request-logging path and legacy /v1/messages response handling, then read the proposed migration 025 and session-grouping truth-table tests. Done means conversations are captured with request_logs.conversation_id, retries do not add turns, legacy responses are normalized, and the specified tests pass.

Written by the indexing model from the issue text.