> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 记忆整理

Memory Store 中的记忆会随着使用不断积累，可能出现重复、过时或遗漏的问题。Dreams 提供异步的记忆整理能力——系统会启动一个专用 Agent，回顾近期会话，对 Memory Store 进行合并、删减和补充。

## 核心概念

| 概念               | 说明                                         |
| ---------------- | ------------------------------------------ |
| Dream            | 一次异步记忆整理任务                                 |
| 输入 Memory Store  | 整理的数据源，**不会被修改**                           |
| 输出 Memory Store  | 系统自动克隆的副本，整理结果写入此处                         |
| Dreaming Session | Dream 运行时创建的内部 Session，不会出现在普通 Session 列表中 |

## 工作流程

```
POST /api/v1/cloud/dreams
    ↓
克隆输入 Memory Store → 生成独立的输出副本
    ↓
创建 Dreaming Session（内置 Memory Consolidation Agent）
    ↓
Agent 执行：读取近期会话 → 合并/删除/补充记忆
    ↓
Dream 完成 → outputs 中返回整理后的 Memory Store ID
```

## API 端点一览

| 方法   | 路径                     | 说明           |
| ---- | ---------------------- | ------------ |
| POST | `/dreams`              | 创建 Dream     |
| GET  | `/dreams`              | 列出 Dreams    |
| GET  | `/dreams/{id}`         | 获取 Dream 详情  |
| POST | `/dreams/{id}/cancel`  | 取消运行中的 Dream |
| POST | `/dreams/{id}/archive` | 归档已完成的 Dream |

## 快速开始

### 1. 触发一次记忆整理

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/cloud/dreams' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      { "type": "memory_store", "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4" }
    ]
  }'
```

### 2. 查询进度

```bash theme={null}
curl -s 'https://api.qoder.com/api/v1/cloud/dreams/drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9' \
  -H "Authorization: Bearer $QODER_PAT"
```

### 3. 查看结果

Dream 完成后，`outputs` 字段中包含整理后的 Memory Store ID：

```json theme={null}
{
  "status": "completed",
  "outputs": [
    { "type": "memory_store", "memory_store_id": "memstore_019e86b4b10578059435632bb357c5ed", "files_touched": ["preferences.md", "project/arch.md"] }
  ]
}
```

## 可选参数

| 参数                          | 说明                                     |
| --------------------------- | -------------------------------------- |
| `model`                     | 选择整理使用的模型：`auto`（默认）、`lite`、`ultimate` |
| `instructions`              | 自定义指令（如"重点关注 Python 项目约定"），最长 4096 字符  |
| `inputs[].type: "sessions"` | 指定重点回顾的 Session ID 列表（最多 100 个）        |

## 安全设计

* **Copy-on-Write**：输入 Memory Store 永不被修改，所有写入发生在克隆副本上
* **最小权限**：Dreaming Agent 仅可使用 `memory`、`session_list`、`session_read` 三个工具，无法执行代码或访问网络
* **Single-flight**：每个用户同一时间只能有一个活跃 Dream（状态为 pending 或 running），重复创建返回 409

## 常见问题

**Q: Dream 会修改我原来的 Memory Store 吗？**

A: 不会。Dream 始终在克隆副本上操作，原始 Memory Store 完全不受影响。

**Q: Dream 需要多长时间？**

A: 通常 1-5 分钟，取决于 Memory Store 大小和需要回顾的会话数量。