> ## 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 が直近の Session を見直し、Memory Store のマージ・削減・補完を行います。

## コアコンセプト

| 概念                  | 説明                                               |
| ------------------- | ------------------------------------------------ |
| Dream               | 非同期のメモリ整理ジョブ                                     |
| Input Memory Store  | データソース。**変更されません**                               |
| Output Memory Store | 自動でクローンされたコピー。整理結果はこちらに書き込まれる                    |
| Dreaming Session    | Dream 実行中に作成される内部 Session。通常の Session 一覧には表示されない |

## ワークフロー

```
POST /api/v1/cloud/dreams
    ↓
入力 Memory Store をクローン → 独立した出力コピーを生成
    ↓
Dreaming Session を作成（メモリ整理用ビルトイン Agent）
    ↓
Agent が実行: 直近の Session を読み込み → 記憶のマージ／削除／補完
    ↓
Dream 完了 → outputs に整理後の Memory Store ID が含まれる
```

## API エンドポイント一覧

| メソッド | パス                     | 説明                |
| ---- | ---------------------- | ----------------- |
| POST | `/dreams`              | Dream を作成         |
| GET  | `/dreams`              | Dream 一覧を取得       |
| 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. 結果を確認

完了後、`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 件）               |

## 安全設計

* **コピーオンライト**: 入力 Memory Store は変更されず、書き込みはすべてクローンされた出力に対して行われる
* **最小権限**: Dreaming Agent は `memory`、`session_list`、`session_read` の 3 つのツールのみ使用可能。コード実行やネットワークアクセスはできない
* **Single-flight**: 1 ユーザーあたり同時に 1 件のアクティブな Dream（pending または running）のみ。重複作成は 409 を返す

## よくある質問

**Q: Dream は元の Memory Store を変更しますか？**

A: いいえ。Dream は常にクローンされたコピー上で動作し、元の Memory Store は一切影響を受けません。

**Q: Dream はどれくらい時間がかかりますか？**

A: Memory Store のサイズと振り返る Session 数によりますが、通常 1〜5 分です。