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

> 获取当前账户下的 Memory Store 列表，支持游标分页。

`GET /api/v1/cloud/memory_stores`

获取当前账户下的 Memory Store 列表。默认不返回已归档的 Store。

## 请求头

| 头部              | 必选 | 说明             |
| --------------- | -- | -------------- |
| `Authorization` | 是  | `Bearer <PAT>` |

## 查询参数

| 参数                 | 类型      | 必选 | 说明                                                            |
| ------------------ | ------- | -- | ------------------------------------------------------------- |
| `limit`            | integer | 否  | 每页返回数量上限。默认 20，范围 1-100。超过 100 返回 `400 invalid_request_error` |
| `page`             | string  | 否  | 上一页响应返回的不透明游标 `next_page`。与 `after_id`/`before_id` 互斥         |
| `after_id`         | string  | 否  | 游标分页：返回此 ID 之后的记录。不能与 `before_id` 同时传入                        |
| `before_id`        | string  | 否  | 游标分页：返回此 ID 之前的记录。不能与 `after_id` 同时传入                         |
| `include_archived` | boolean | 否  | 设为 `true` 时包含已归档 Memory Store                                 |
| `name`             | string  | 否  | 按 Store 名称前缀搜索，不区分大小写                                         |
| `created_at[gte]`  | string  | 否  | 仅返回创建时间大于等于此 RFC 3339 时间的记录                                   |
| `created_at[lte]`  | string  | 否  | 仅返回创建时间小于等于此 RFC 3339 时间的记录                                   |

完整分页规范详见 [分页](/zh/cloud-agents/api/conventions/pagination)。

## 示例请求

```bash theme={null}
# 基本列表
curl -X GET "https://api.qoder.com/api/v1/cloud/memory_stores" \
  -H "Authorization: Bearer $QODER_PAT"

# 分页
curl -X GET "https://api.qoder.com/api/v1/cloud/memory_stores?limit=10&after_id=memstore_xxx" \
  -H "Authorization: Bearer $QODER_PAT"

# 按名称搜索并包含已归档 Store
curl -X GET "https://api.qoder.com/api/v1/cloud/memory_stores?name=docs&include_archived=true" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "memstore_019e3bb8d50674d9b082b73709c29c87",
      "created_at": "2026-05-18T15:33:49.449Z",
      "name": "doc-test-store",
      "type": "memory_store",
      "updated_at": "2026-05-18T15:33:49.449Z",
      "archived_at": null,
      "description": "测试用",
      "metadata": {},
      "status": "active",
      "entry_count": 0,
      "total_size": 0
    }
  ],
  "has_more": false,
  "first_id": "memstore_019e3bb8d50674d9b082b73709c29c87",
  "last_id": "memstore_019e3bb8d50674d9b082b73709c29c87",
  "next_page": null
}
```

## 响应字段

| 字段          | 类型             | 说明                                                                              |
| ----------- | -------------- | ------------------------------------------------------------------------------- |
| `data`      | array          | [Memory Store 对象](/zh/cloud-agents/api/memory-stores/schemas#memory-store-对象)数组 |
| `has_more`  | boolean        | 是否还有更多记录                                                                        |
| `first_id`  | string \| null | 当前页第一条记录 ID；`data` 为空时为 `null`                                                  |
| `last_id`   | string \| null | 当前页最后一条记录 ID；`data` 为空时为 `null`                                                 |
| `next_page` | string \| null | 下一页的不透明游标；没有更多记录时为 `null`                                                       |

## 分页说明

Memory Store 列表按资源 ID 倒序返回。遍历列表：

1. 首次请求设置 `limit` 获取第一页
2. 如果 `has_more` 为 `true`，将 `next_page` 作为 `page` 参数获取下一页
3. 也可使用 `after_id=<last_id>` / `before_id=<first_id>` 做基于 ID 的翻页

## 错误码

| HTTP | type                    | 触发条件                                             |
| ---- | ----------------------- | ------------------------------------------------ |
| 400  | `invalid_request_error` | `limit` 非法、时间格式非法，或同时传入 `before_id` 与 `after_id` |
| 401  | `authentication_error`  | 缺少或无效的认证令牌                                       |

完整错误信封说明详见 [错误参考](/zh/cloud-agents/api/conventions/errors)。