docs: add CLI system docs

docs/memory/context.mdx

@@ -0,0 +1,80 @@
+---
+title: 短期记忆
+description: 对话上下文 — 消息管理、压缩策略和上下文操作
+---
+
+对话上下文是 Agent 的短期记忆，包含当前会话中的所有消息（用户输入、Agent 回复、工具调用及结果）。合理管理上下文对于 Agent 的推理质量和成本控制至关重要。
+
+## 上下文结构
+
+每一轮对话由以下消息组成：
+
+```
+用户消息 → Agent 思考 → 工具调用 → 工具结果 → ... → Agent 最终回复
+```
+
+一轮中可能包含多次工具调用（Agent 的决策步数由 `agent_max_steps` 控制），所有工具调用和结果都会保留在上下文中，直到被压缩或裁剪。
+
+## 关键配置
+
+| 参数 | 说明 | 默认值 |
+| --- | --- | --- |
+| `agent_max_context_tokens` | 上下文最大 token 预算 | `50000` |
+| `agent_max_context_turns` | 上下文最大对话轮次 | `20` |
+| `agent_max_steps` | 单轮对话最大决策步数（工具调用次数） | `15` |
+
+可通过 `config.json` 或对话中的 `/config` 命令修改。
+
+## 压缩策略
+
+当上下文超出限制时，系统会自动执行压缩以释放空间。整个过程分为多个阶段：
+
+### 1. 工具结果截断
+
+在每次决策循环开始前，系统会检查历史轮次中的工具调用结果。超过 **20000 字符** 的工具结果会被截断，仅保留首尾内容和截断说明。当前轮次的工具结果不受影响。
+
+### 2. 轮次裁剪
+
+当对话轮次超过 `agent_max_context_turns` 时：
+
+- 裁剪 **最早一半** 的完整轮次（保证工具调用链的完整性）
+- 被裁剪的消息会通过 LLM 总结后**写入当天的日级记忆文件**
+- 剩余轮次保持不变
+
+### 3. Token 预算裁剪
+
+裁剪轮次后，如果 token 数仍超出预算：
+
+- **轮次 < 5 时**：对所有轮次进行**文本压缩** — 每轮只保留第一条用户文本和最后一条 Agent 回复，去掉中间的工具调用链
+- **轮次 ≥ 5 时**：再次裁剪**前半轮次**，被丢弃内容同样写入记忆
+
+### 4. 溢出应急处理
+
+当模型 API 返回上下文溢出错误时：
+
+1. 先将当前所有消息总结写入记忆
+2. 执行激进裁剪（工具结果限制 10K 字符、用户文本限制 10K、最多保留 5 轮）
+3. 如果仍然溢出，清空整个对话上下文
+
+## 会话持久化
+
+对话消息会持久化到本地数据库，服务重启后自动恢复。恢复策略：
+
+- 恢复最近的 **`max(3, max_context_turns / 6)`** 轮对话
+- 只保留每轮的**用户文本和 Agent 最终回复**，不恢复中间工具调用链
+- 超过 **30 天**的历史会话自动清理
+
+## 操作命令
+
+在对话中可以使用以下命令管理上下文：
+
+| 命令 | 说明 |
+| --- | --- |
+| `/context` | 查看当前上下文统计（消息数、角色分布、总字符数） |
+| `/context clear` | 清空当前会话上下文 |
+| `/config agent_max_context_tokens 80000` | 调整上下文 token 预算 |
+| `/config agent_max_context_turns 30` | 调整上下文轮次上限 |
+
+<Tip>
+  清空上下文后，Agent 会"忘记"之前的对话内容。被裁剪和清空的内容如果已经写入长期记忆，仍可通过记忆检索找回。
+</Tip>

docs/memory/index.mdx

@@ -0,0 +1,58 @@
+---
+title: 长期记忆
+description: CowAgent 的长期记忆系统 — 文件持久化、自动写入与混合检索
+---
+
+长期记忆保存在工作空间文件中，跨会话持久存在。Agent 在对话中通过检索工具按需加载历史记忆，也会在上下文裁剪时自动将对话摘要写入长期记忆。
+
+## 记忆类型
+
+### 核心记忆（MEMORY.md）
+
+存储在 `~/cow/MEMORY.md` 中，包含用户的长期偏好、重要决策、关键事实等不会随时间淡化的信息。Agent 可通过工具读写此文件来维护长期知识。
+
+### 日级记忆（memory/YYYY-MM-DD.md）
+
+存储在 `~/cow/memory/` 目录下，按日期命名（如 `2026-03-08.md`），记录每天的对话摘要和关键事件。仅在首次写入时创建，避免生成空文件。
+
+## 自动写入
+
+Agent 通过以下机制自动将对话内容持久化为长期记忆：
+
+- **上下文裁剪时** — 当对话轮次或 token 超出配置上限时，裁剪最早一半的上下文，使用 LLM 将被裁剪的内容总结为关键信息写入当天记忆文件
+- **每日定时总结** — 每天 23:55 自动触发一次全量总结，防止低活跃日无记忆留存（内容无变化时自动跳过）
+- **API 上下文溢出时** — 当模型 API 返回上下文溢出错误时，紧急保存当前对话摘要
+
+所有记忆写入均在后台异步执行（LLM 总结 + 文件写入），不阻塞正常对话回复。
+
+## 记忆检索
+
+记忆系统支持混合检索模式：
+
+- **关键词检索** — 基于 FTS5 全文索引匹配历史记忆，支持 BM25 排序
+- **向量检索** — 基于 embedding 语义相似度搜索，即使表述不同也能找到相关记忆
+
+Agent 会在对话中根据需要自动触发记忆检索，将相关历史信息纳入上下文。检索结果按混合评分排序（默认向量权重 0.7、关键词权重 0.3），日级记忆会随时间衰减（半衰期 30 天），核心记忆不衰减。
+
+## 首次启动
+
+首次启动 Agent 时，Agent 会主动向用户询问关键信息，并记录至工作空间（默认 `~/cow`）中：
+
+| 文件 | 说明 |
+| --- | --- |
+| `system.md` | Agent 的系统提示词和行为设定 |
+| `user.md` | 用户身份信息和偏好 |
+| `MEMORY.md` | 核心记忆（长期） |
+| `memory/YYYY-MM-DD.md` | 日级记忆（按需创建） |
+
+<Frame>
+  <img src="https://cdn.link-ai.tech/doc/20260203000455.png" width="800" />
+</Frame>
+
+## 相关配置
+
+| 参数 | 说明 | 默认值 |
+| --- | --- | --- |
+| `agent_workspace` | 工作空间路径，记忆文件存储在此目录下 | `~/cow` |
+| `agent_max_context_tokens` | 最大上下文 token 数，超出时裁剪并总结写入记忆 | `50000` |
+| `agent_max_context_turns` | 最大上下文轮次，超出时裁剪并总结写入记忆 | `20` |