CodePilot - docs handover memory system v3
# 记忆系统 V3 + V3.1 — 交接文档
> 产品思考见 [docs/future/core-system-guardrails.md](../future/core-system-guardrails.md)
> 执行计划见 [docs/exec-plans/active/memory-system-v3.md](../exec-plans/active/memory-system-v3.md)
> 后续增强见 [docs/future/memory-enhancements.md](../future/memory-enhancements.md)
> 助理体验升级见 [docs/future/assistant-ux-upgrade.md](../future/assistant-ux-upgrade.md)
## 概述
V3 重写了助理工作区的记忆系统：Onboarding 从 13 题问卷改为对话式 bootstrap，Check-in 从 3 题问卷改为 HEARTBEAT_OK 心跳协议，新增渐进式文件更新让 AI 在日常对话中自主学习用户偏好。
V3.1 将记忆从 system prompt 移出改为 MCP 按需检索，新增时间衰减、Obsidian frontmatter 感知、transcript 裁剪。
## 架构变更
### 记忆检索：从"全塞"到"按需"
**V2（旧）**：所有记忆文件（memory.md + daily memories + 检索结果 + root docs）塞进 system prompt，~40K chars。
**V3.1（新）**：system prompt 只保留身份层（soul/user/claude.md，~24K chars），记忆通过 MCP 工具按需检索。
```
System Prompt 组成：
Layer 1: 身份层（soul.md + user.md + claude.md）← 始终注入
Layer 2: Session prompt + systemPromptAppend
Layer 3: 助理指令（onboarding / heartbeat / 渐进式更新）
Layer 4-6: CLI tools / Widget / Dashboard（同 V2，unchanged）
+ <memory-hint> 标签告知 AI 有哪些 daily memory 可用
+ MEMORY_SEARCH_SYSTEM_PROMPT 指引首轮必调 memory_recent
```
### Memory Search MCP（`src/lib/memory-search-mcp.ts`）
助理模式下始终注册（非 keyword-gated），提供 3 个工具：
| 工具 | 用途 |
|------|------|
| `codepilot_memory_search` | 关键词搜索 + 30 天半衰期时间衰减 + tags 过滤 + file_type 过滤 |
| `codepilot_memory_get` | 读取指定文件（path.relative 安全校验 + 3K chars 截断 + wikilink 提取） |
| `codepilot_memory_recent` | 返回最近 3 天 daily memory + 长期记忆摘要（首轮回顾用） |
注册位置：`claude-client.ts`，在 `isAssistantProject` 条件内，先于 keyword-gated MCP 注册。
### 时间衰减
`applyTemporalDecay()` 对搜索结果应用指数衰减：
- 半衰期 30 天（`LAMBDA = ln(2) / 30`）
- 日期文件（`memory/daily/YYYY-MM-DD.md`）按文件名日期衰减
- 常青文件（`memory.md`、`MEMORY.md`、`Memory.md`、无日期文件）不衰减
- 90 天前的笔记只剩 ~12.5% 原始权重
### Obsidian 感知
- `codepilot_memory_search`：`tags` 参数从 YAML frontmatter 提取（通过 workspace-indexer manifest）
- `codepilot_memory_search`：`file_type` 参数区分 daily / longterm / notes
- `codepilot_memory_get`：提取 `[[wikilinks]]` 附在结果末尾作为关联文件提示
- 文件名大小写兼容：`memory.md` / `Memory.md` / `MEMORY.md` 均支持
## Onboarding 重写
### 旧流程（V2）
13 题固定问卷 → AI 逐题提问 → 用户在聊天框打字回答 → `onboarding-complete` JSON fence → 后端 4 个并行 AI 调用生成文件
### 新流程（V3）
3 主题对话式 bootstrap → AI 自然对话（不超过 5 个问题）→ 用户说"可以了"即结束 → 同样的 fence 机制 → 4 个结构化 prompt 生成文件
**关键改进：**
- prompt 强制"不超过 5 个问题"，3 轮后主动询问是否开始设置
- 接受自由格式 JSON（不再要求 q1-q13 固定 key）
- 4 个生成 prompt 全部重写（结构化引导 + 字符限制）
- claude.md 生成时必须包含 5 个系统预设规则区块
### claude.md 系统预设规则
`initializeWorkspace()` 和 `processOnboarding()` 生成的 claude.md 包含以下固定区块：
1. **时间感知**：先 `date` 确认时间
2. **记忆规则**："记一下"保留原文、memory.md 只追加、修改身份文件须告知
3. **文档组织**：`[[双向链接]]`、`#标签`、YAML frontmatter、少文件夹多标签
4. **写作约束**：不用空泛修饰词、不用对比句式
5. **操作安全**：身份文件修改通知、不存密码
### 涉及文件
| 文件 | 改动 |
|------|------|
| `src/lib/context-assembler.ts` | `buildOnboardingInstructions()` 重写 |
| `src/lib/onboarding-processor.ts` | 4 个 prompt 重写 + 自由 JSON + schema v5 |
| `src/lib/assistant-workspace.ts` | claude.md 模板含系统预设规则 |
| `src/i18n/en.ts` / `zh.ts` | 删除 Q1-Q13 共 26 个 key |
## Heartbeat 系统
### 旧流程（V2 Check-in）
3 题固定问卷 → `checkin-complete` JSON fence → 后端 3 个并行 AI 调用（daily memory + promotion + user update）
### 新流程（V3 Heartbeat）
读 HEARTBEAT.md 检查清单 → AI 自主判断有没有事 → HEARTBEAT_OK 静默 / 有事自然说出 → AI 自主决定写哪个文件
### 触发条件
`shouldRunHeartbeat(state, config)` — 所有条件为 true 才触发：
1. `state.onboardingComplete === true`
2. `state.heartbeatEnabled === true`
3. `state.lastHeartbeatDate !== today`
4. `isWithinActiveHours(config.heartbeat?.activeHours)`
5. 无活跃 stream（用户消息优先）
6. HEARTBEAT.md 内容非空（`isHeartbeatContentEmpty()` 检测）
### HEARTBEAT_OK 协议（`src/lib/heartbeat.ts`）
`stripHeartbeatToken(raw)` 检测逻辑：
1. 解包 HTML/Markdown 包装（`<b>HEARTBEAT_OK</b>` / `**HEARTBEAT_OK**`）
2. 从首尾剥离 token（允许尾部 4 个非字母字符）
3. 剩余内容 ≤300 chars → `shouldSkip: true`（视为静默）
4. 剩余内容 >300 chars → `shouldSkip: false`（有实质内容，剥离 token 后展示）
### Heartbeat 完成后的 state 更新（`route.ts` finally 块）
严格限定为 heartbeat turn（`isHeartbeatTurn = autoTrigger && content.includes('心跳检查')`）：
- **成功 + 非空回复**：写 `lastHeartbeatDate`，清 `hookTriggeredSessionId`
- **shouldSkip（纯 OK）**：额外调 `updateMessageHeartbeatAck(msgId, true)` 标记消息
- **失败 / 空回复**：不写 `lastHeartbeatDate`，当天可重试
### Transcript 裁剪
`messages` 表新增 `is_heartbeat_ack` 列（INTEGER DEFAULT 0）。
HEARTBEAT_OK 消息被标记后：
- `getMessages(sessionId, { excludeHeartbeatAck: true })` 过滤
- `GET /api/chat/sessions/[id]/messages` 默认过滤
- Fallback history（50 条）过滤
- Bridge conversation-engine 过滤
### 去重
`state.lastHeartbeatText` + `state.lastHeartbeatSentAt`：24h 内相同内容不重复展示。
### Active Hours
`isWithinActiveHours({ start, end })` — 本地时间 HH:MM 解析，支持跨午夜（如 22:00-08:00）。
### Telegram 通知静默
auto-trigger turns（onboarding + heartbeat）的所有 5 条 Telegram 出口全部静默：
| 出口 | 位置 | 守卫 |
|------|------|------|
| `notifySessionStart` | route.ts POST handler | `if (!autoTrigger)` |
| `notifySessionComplete` | collectStreamResponse finally | `if (!opts?.suppressNotifications)` |
| `notifySessionError` | collectStreamResponse finally | `if (!opts?.suppressNotifications)` |
| `notifyGeneric` (result error) | claude-client.ts result handler | `if (!autoTrigger)` |
| `notifyGeneric` (task_notification) | claude-client.ts system msg | `if (!autoTrigger)` |
| `notifyPermissionRequest` | claude-client.ts permission | `if (!autoTrigger)` |
### 作用域边界
心跳只对助理 workspace 生效（`session.working_directory === assistant_workspace_path`）。非助理项目走定时任务系统（尚未实现）。
### 涉及文件
| 文件 | 改动 |
|------|------|
| `src/lib/heartbeat.ts` | **新建**：stripHeartbeatToken + isHeartbeatContentEmpty + isWithinActiveHours + shouldSkipDuplicate + HEARTBEAT_TEMPLATE |
| `src/lib/context-assembler.ts` | `buildHeartbeatInstructions()` + `buildProgressiveUpdateInstructions()` + `assembleHeartbeatContext()` |
| `src/lib/assistant-workspace.ts` | `shouldRunHeartbeat()` + `loadHeartbeatMd()` + HEARTBEAT.md 创建 + V4→V5 迁移 |
| `src/hooks/useAssistantTrigger.ts` | heartbeat 触发条件 + 消息文案 |
| `src/app/api/chat/route.ts` | heartbeat state 更新 + ack 标记 + Telegram 静默 |
| `src/lib/claude-client.ts` | Telegram 旁路静默（3 处） |
| `src/lib/db.ts` | `is_heartbeat_ack` 列 + `updateMessageHeartbeatAck()` + `getMessages` 过滤 |
| `src/app/api/chat/sessions/[id]/messages/route.ts` | `excludeHeartbeatAck: true` |
| `src/lib/bridge/conversation-engine.ts` | fallback history 过滤 |
## 渐进式文件更新（Phase 3）
`buildProgressiveUpdateInstructions()` 在 onboarding 完成后的日常助理对话中注入，指引 AI 自主更新 workspace 文件：
- **身份文件**（soul/user/claude.md）：修改后必须告知用户
- **记忆文件**（memory.md / daily）：可静默更新
- **判断标准**：用户明确要求→立即更新；连续表达同一偏好→写入；不确定→先不写
## State 变更（V4 → V5）
```typescript
interface AssistantWorkspaceState {
onboardingComplete: boolean;
lastHeartbeatDate: string | null; // 替代 lastCheckInDate
lastHeartbeatText?: string; // 去重
lastHeartbeatSentAt?: number; // 去重
heartbeatEnabled: boolean; // 替代 dailyCheckInEnabled
schemaVersion: number; // 5
hookTriggeredSessionId?: string;
hookTriggeredAt?: string;
// deprecated（保留兼容）
lastCheckInDate?: string | null;
dailyCheckInEnabled?: boolean;
}
```
`migrateStateV4ToV5()` 自动迁移：旧字段值复制到新字段，schema 升到 5。
## 关键约束
- `claude.md` 永不丢弃（overflow 时强制保留）
- `memory.md` 只追加不覆写
- heartbeat state 更新严格限定为 heartbeat turn（`autoTrigger && content.includes('心跳检查')`）
- heartbeat 失败/空回复不写 `lastHeartbeatDate`（当天可重试）
- auto-trigger turns 完全不发 Telegram 通知（5 条出口全部守卫）
- Memory MCP 路径校验用 `path.relative` 判断（不用 `startsWith`，兼容根目录 workspace）
- 文件名大小写兼容（memory.md / Memory.md / MEMORY.md）
- 心跳只对助理 workspace 生效，非助理项目不触发
## 质量保障改进（同期完成）
- ESLint error：48 → 0（47 个 no-explicit-any + 1 个 setState-in-effect）
- CI lint：去掉 `continue-on-error`，lint 失败阻塞 build/release
- Smoke 测试进 CI：`smoke-test` job 接入 build/release 依赖链
- E2E 断言修复：品牌 Claude → CodePilot
- 外链行为：`shell.openExternal` 打开系统浏览器
## 未实现（后续）
- **定时任务系统**：心跳目前只在打开会话时触发，定时调度需要 TaskScheduler（见 `docs/future/scheduled-tasks-and-notifications.md`）
- **Auto Flush**：压缩前自动写盘需要 SDK compaction hook（当前用渐进式更新 prompt 替代）
- **向量搜索**：当前是关键词 bigram，向量搜索需要 embedding 基础设施
- **GUI 记忆管理**：设置页可视化记忆面板
- **Onboarding Wizard**：前端组件替代 AI 对话式（见 `docs/future/assistant-ux-upgrade.md`）