# 长期记忆

fkteams 内置了全局长期记忆模块，能够跨会话自动记住用户的各类信息，在后续对话中自动召回相关记忆，让助手越用越顺手。

## 工作原理

1. **自动提取**：对话过程中，系统在后台异步调用 LLM 从对话中提取六类记忆：
   - **用户偏好**（preference）：喜好、厌恶、习惯、风格倾向
   - **个人信息**（fact）：身份、背景、环境、关系等客观事实
   - **经验教训**（lesson）：踩过的坑、需要避免的做法
   - **决策结论**（decision）：确定的方案、选定的方向
   - **认知洞察**（insight）：观点、原则、价值判断
   - **操作经验**（experience）：AI 操作中遇到的问题及解决方法
2. **智能去重**：提取的记忆会与已有记忆自动去重（基于摘要包含关系和标签重叠度），相似条目会更新而非重复添加
3. **BM25 检索**：用户每次提问时，系统基于 BM25 算法从记忆库中召回最相关的条目；当条目数 ≤ 20 时直接全量注入
4. **上下文注入**：召回的记忆以结构化格式注入到 Agent 的系统提示词中

## 提取时机

记忆提取在以下场景中自动触发：

| 场景                            | 触发方式                      | 说明                                                |
| ------------------------------- | ----------------------------- | --------------------------------------------------- |
| **CLI 模式**                    | 每轮查询结束后                | 在 `defer` 中异步调用提取                           |
| **Web 模式**                    | 每次 WebSocket 聊天处理完成后 | 在 `finishChat` 中异步调用提取                      |
| **渠道模式**（QQ/微信/Discord） | 桥接消息处理完成后            | 在 bridge 的回调中异步调用提取                      |
| **CLI 退出时**                  | 程序退出前                    | 强制同步提取剩余未处理的消息（`FlushFromRecorder`） |
| **Server 停止时**               | 服务优雅退出                  | 等待所有异步提取任务完成（`Wait`）                  |

## 触发条件

并非每次对话都会触发 LLM 提取，系统有智能判断机制以节省 token 消耗：

- **最少用户消息数**：新增至少 **2 条**用户消息
- **最小内容长度**：新增消息总字符数至少 **300**
- **冷却时间**：同一会话两次提取间隔至少 **3 分钟**

## 容量管理

- **最大条目数**：500 条（超出后按命中次数和时间淘汰最不活跃的条目）
- **淘汰策略**：30 天内未被命中的条目优先被淘汰

## 存储位置

记忆数据按类型持久化在 `~/.fkteams/workspace/memory/` 目录下，每种类型对应一个 Markdown 文件（如 `preference.md`、`fact.md` 等），可直接查看和手动编辑。

## 使用说明

在配置文件 `~/.fkteams/config/config.toml` 中启用长期记忆功能：

```toml
[memory]
enabled = true
```

启用后，CLI 模式和 Web 模式均自动工作，无需额外配置。
