> ## 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 Stores

Session が終了すると、Agent のコンテキストはデフォルトで失われます。Memory Stores を使うと、Agent が得た知識や出力を Session をまたいで永続化できます。次回 Agent が実行されるときに、以前の作業を「思い出す」ことができます。

## 主要な概念

| 概念           | 説明                                            |
| ------------ | --------------------------------------------- |
| Memory Store | プロジェクトまたはドメイン単位のメモリリポジトリ                      |
| Memory       | `path` で識別される単一のメモリ。各メモリは一意の `mem_...` ID を持つ |
| Version      | 作成・更新・削除のたびに生成される不変のスナップショット                  |

階層構造: **Store → Memory → Version**。

## API エンドポイント

| Method | Path                                                             | 説明                                |
| ------ | ---------------------------------------------------------------- | --------------------------------- |
| POST   | `/memory_stores`                                                 | Memory Store を作成                  |
| GET    | `/memory_stores`                                                 | Memory Store を一覧取得                |
| GET    | `/memory_stores/{id}`                                            | Memory Store を取得                  |
| POST   | `/memory_stores/{id}`                                            | Memory Store を更新                  |
| POST   | `/memory_stores/{id}/archive`                                    | Memory Store をアーカイブ               |
| DELETE | `/memory_stores/{id}`                                            | Memory Store を削除                  |
| POST   | `/memory_stores/{id}/memories`                                   | Memory を作成                        |
| GET    | `/memory_stores/{id}/memories`                                   | Memory を一覧取得                      |
| GET    | `/memory_stores/{id}/memories/{memory_id}`                       | Memory を取得（`content` を含む）         |
| POST   | `/memory_stores/{id}/memories/{memory_id}`                       | Memory を更新                        |
| DELETE | `/memory_stores/{id}/memories/{memory_id}`                       | Memory を削除                        |
| GET    | `/memory_stores/{id}/memory_versions`                            | Memory Version を一覧取得              |
| GET    | `/memory_stores/{id}/memory_versions/{memory_version_id}`        | Memory Version を取得（`content` を含む） |
| POST   | `/memory_stores/{id}/memory_versions/{memory_version_id}/redact` | Memory Version を墨消し               |

## パスのルール

Memory の `path` は相対パスである必要があります:

* 有効: `notes/meeting-2026-05-18.md`、`config.yaml`。
* 無効: `/notes/meeting.md`(`/` で始められない)、`../secrets`(`..` を含められない)。

パスはメモリをファイルシステムのように整理します。

## エンドツーエンドのフロー

### 1. Memory Store を作成

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/memory_stores \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-alpha-memory",
    "description": "Agent knowledge base for project Alpha"
  }'
```

レスポンス例:

```json theme={null}
{
  "id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4",
  "created_at": "2026-05-18T08:00:00.000Z",
  "name": "project-alpha-memory",
  "type": "memory_store",
  "updated_at": "2026-05-18T08:00:00.000Z",
  "archived_at": null,
  "description": "Agent knowledge base for project Alpha",
  "metadata": {},
  "status": "active",
  "entry_count": 0,
  "total_size": 0
}
```

### 2. Memory を作成

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/memories \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "decisions/arch-choice.md",
    "content": "# Architecture Decision\n\nChose microservices because the team is scaling and needs independent deployments."
  }'
```

<Note>
  一覧エンドポイントは `content` を返しません。内容を読み取るには単一メモリのエンドポイントを呼び出してください。
</Note>

### 3. Memory を取得

`memory_id` を指定して完全な内容(`content` を含む)を取得します:

```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/memories/mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1 \
  -H "Authorization: Bearer $QODER_PAT"
```

レスポンス:

```json theme={null}
{
  "id": "mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1",
  "type": "memory",
  "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4",
  "path": "decisions/arch-choice.md",
  "content": "# Architecture Decision\n\nChose microservices because the team is scaling and needs independent deployments.",
  "content_size_bytes": 99,
  "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a",
  "version": 1,
  "metadata": {},
  "created_at": "2026-05-18T08:00:00.000Z",
  "updated_at": "2026-05-18T08:00:00.000Z"
}
```

### 4. Memory を更新

更新は `memory_id` に対して `POST` で行います。新しいバージョンのスナップショットが自動的に生成されます。同時書き込みを防ぐには、最後に読み取った `content_sha256` を渡してください。サーバーの現在の内容と一致しなくなった場合、API は **409 Conflict** を返します:

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/memories/mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Architecture Decision v2\n\nMoved to a Modular Monolith because microservice operational costs exceeded the budget.",
    "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a"
  }'
```

リクエストフィールド:

| フィールド            | 型      | 必須  | 説明                                          |
| ---------------- | ------ | --- | ------------------------------------------- |
| `content`        | string | はい  | 新しい内容。最大 100 KB                             |
| `content_sha256` | string | いいえ | 現在の内容の期待される SHA-256(楽観的並行制御)。省略するとチェックをスキップ |
| `metadata`       | object | いいえ | 付加するメタデータ                                   |

`content_sha256` が指定され、かつサーバーと一致しない場合(同時書き込みが検出された場合)、API は **409 Conflict** を返します。メモリを再度 `GET` してから再試行してください。

### 5. Session で使用

Session の作成時に `resources[]` を通じて Memory Store を参照します:

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "environment_id": "env_xxx",
    "resources": [
      {
        "type": "memory_store",
        "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4",
        "access": "read_write",
        "instructions": "Use this memory for project context."
      }
    ]
  }'
```

Agent は Session 内でリンクされた Memory Store の読み取りと書き込みができます。

### サンドボックス内のメモリパス

メモリはサンドボックス内の `/data/.qoder/awareness/<memory.path>` にマウントされます。サンドボックス内には memory\_store や memory ID の命名階層はなく、すべてのメモリは `awareness/` の下にフラットに配置されます。Agent は memory\_store という概念を認識できず、`path` によってファイルを読み取るだけです。

## バージョン追跡

Memory に対する作成・更新・削除のたびにスナップショットが生成されます。バージョンは不変であり、完全な変更履歴を提供します。`GET /memory_stores/{id}/memory_versions`(オプションで `memory_id` で絞り込み可能)で一覧を取得し、`GET /memory_stores/{id}/memory_versions/{memory_version_id}` で単一バージョンの `content` を読み取ります。

バージョンに機密性の高い内容が含まれている場合は、[墨消し](/ja/cloud-agents/api/memory-stores/redact-version)することで、監査用のバージョンメタデータを保持したまま、保存された内容を完全に削除できます。

## 統計フィールド

| フィールド         | 説明                      |
| ------------- | ----------------------- |
| `entry_count` | Store 内の Memory の総数     |
| `total_size`  | すべての Memory 内容の合計バイトサイズ |

## FAQ

**Q: Session はいくつの Memory Store を参照できますか?** A: 複数の Store がサポートされています。必要に応じてリンクしてください。

**Q: Memory の `path` にサブディレクトリを含められますか?** A: はい。`notes/2026/05/daily.md` のようなパスがサポートされています。

**Q: Memory Store に容量制限はありますか?** A: アカウントのクォータを参照してください。通常のプロジェクトでは、制限は一般的に十分な余裕があります。

<Note>
  メモリが混ざらないように、プロジェクトごとに別々の Memory Store を作成してください。
</Note>