# 经验记忆（Task Memory）

经验记忆是 JiuwenSwarm 的内建任务经验系统，使 Agent 能够从历史任务中检索、记录和沉淀经验教训，从而在后续任务中避免重复错误、复用有效方案。

---

## 启用与配置

在 `config/config.yaml` 中配置：

```yaml
task_memory:
  enabled: true                          # 总开关
  retrieval_algo: ACE                    # 检索算法：ACE | ReasoningBank | ReMe
  summary_algo: ACE                      # 摘要算法：ACE | ReasoningBank | ReMe
  llm_model: ${TASK_MEMORY_LLM_MODEL}    # 使用的 LLM 模型（留空则用主模型）
  embedding_model: ${TASK_MEMORY_EMBED_MODEL}
  api_key: ${TASK_MEMORY_API_KEY}
  api_base: ${TASK_MEMORY_API_BASE}
```

`enabled: true` 后 Agent 将获得以下三个工具。

---

## 工具说明

### experience_retrieve

根据查询检索相关的历史经验。

| 参数 | 类型 | 说明 |
|------|------|------|
| `query` | string | 描述当前任务或问题，系统据此匹配最相关的经验 |

返回 `memory_string`（可读文本）和 `retrieved_memory`（结构化列表）。

**建议在每次任务开始时调用**，检查是否有可复用的经验。

### experience_learn

记录当前任务中发现的关键规律、规则或洞见，并整合到经验库中。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `params.content` | string | 是 | 要记录的经验内容 |
| `params.section` | string | 否 | 分类标签，默认 `general` |
| `params.when_to_use` | string | 否 | 何时应该使用此经验 |
| `params.title` | string | 否 | 经验标题 |
| `params.description` | string | 否 | 详细描述 |
| `params.query` | string | 否 | 关联查询 |
| `params.label` | string | 否 | 自定义标签 |
| `params.tools_used` | list | 否 | 工具调用结果列表，如 `[{"tool": "web_search", "status": "success"}]` |

**建议在最终回复前调用一次**。记录失败的工具调用尤其有价值。

### experience_clear

清除所有存储的经验数据。

> ⚠️ 仅在用户明确要求清除时调用，调用前需确认。

---

## 存储机制

经验数据持久化在 `workspace/agent/task-data.json`。即使外接经验服务不可用，本地持久化数据仍然可用（返回 `persisted_only` 状态）。

当外接服务正常时，检索结果会合并本地持久化数据和服务端数据。

---

## 检索算法

| 算法 | 说明 |
|------|------|
| **ACE** | 默认算法，基于嵌入相似度的经验检索 |
| **ReasoningBank** | 推理增强型检索，适合复杂推理链路 |
| **ReMe** | 反思型检索，侧重于从错误中学习 |

---

## 环境变量

| 变量 | 说明 |
|------|------|
| `TASK_MEMORY_LLM_MODEL` | 经验记忆专用的 LLM 模型名 |
| `TASK_MEMORY_EMBED_MODEL` | 经验记忆专用的 Embedding 模型 |
| `TASK_MEMORY_API_KEY` | 经验记忆 API 密钥 |
| `TASK_MEMORY_API_BASE` | 经验记忆 API 地址 |

---

## 详见

- [记忆系统](记忆.md) — 内建记忆与外接记忆概述
- [配置信息](配置信息.md) — `task_memory` 段的完整配置字段