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

> 创建一个新的 Memory Store。

`POST /api/v1/cloud/memory_stores`

创建一个 Memory Store，并返回 [Memory Store 对象](/zh/cloud-agents/api/memory-stores/schemas#memory-store-对象)。

## 请求头

| 头部              | 必选 | 说明                 |
| --------------- | -- | ------------------ |
| `Authorization` | 是  | `Bearer <PAT>`     |
| `Content-Type`  | 是  | `application/json` |

## 请求体

| 字段            | 类型     | 必选 | 说明                                                    |
| ------------- | ------ | -- | ----------------------------------------------------- |
| `name`        | string | 是  | Store 名称，1–255 字符，不含控制字符                              |
| `description` | string | 否  | 自由文本描述，最长 1024 字符。Store 被关联时会写入 Agent 的 system prompt |
| `metadata`    | object | 否  | 自定义键值元数据。最多 16 对；key 1–64 字符；value 最长 512 字符          |

## 示例请求

```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": "Alpha 项目的 Agent 知识库",
    "metadata": {"team": "backend"}
  }'
```

## 示例响应

```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": "Alpha 项目的 Agent 知识库",
  "metadata": {"team": "backend"},
  "status": "active",
  "entry_count": 0,
  "total_size": 0
}
```

## 错误码

| HTTP | type                    | 触发条件                         |
| ---- | ----------------------- | ---------------------------- |
| 400  | `invalid_request_error` | `name` 缺失或非法，或 `metadata` 非法 |
| 401  | `authentication_error`  | 缺少或无效的认证令牌                   |

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