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

# 持久化记忆

Session 结束后，Agent 的上下文默认随之消失。Memory Stores 让 Agent 的学习成果和工作产出跨 Session 持久保留——下次启动时，Agent 可以“回忆”之前的内容。

## 核心概念

| 概念           | 说明                                   |
| ------------ | ------------------------------------ |
| Memory Store | 记忆仓库，按项目或领域划分                        |
| Memory       | 一条记忆，由 `path` 标识，每条有唯一的 `mem_...` ID |
| Version      | 每次创建、更新或删除时自动生成的版本快照                 |

层级关系：**Store → Memory → Version**

## API 端点一览

| 方法     | 路径                                                               | 说明                       |
| ------ | ---------------------------------------------------------------- | ------------------------ |
| 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 版本             |
| GET    | `/memory_stores/{id}/memory_versions/{memory_version_id}`        | 获取单个版本（含 `content`）      |
| POST   | `/memory_stores/{id}/memory_versions/{memory_version_id}/redact` | Redact 某个版本              |

## 路径规则

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

响应示例：

```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": {},
  "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": "# 架构决策\n\n选择微服务架构，原因：团队规模扩大，需要独立部署。"
  }'
```

<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": "# 架构决策\n\n选择微服务架构，原因：团队规模扩大，需要独立部署。",
  "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

更新使用 `POST` 方法，路径中带 `memory_id`，系统会自动生成新的版本快照。为防止并发写入，可携带上次读取到的 `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": "# 架构决策 v2\n\n改为 Modular Monolith，原因：微服务运维成本超出预算。",
    "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a"
  }'
```

请求字段：

| 字段               | 类型     | 必填 | 说明                              |
| ---------------- | ------ | -- | ------------------------------- |
| `content`        | string | 是  | 新的内容，最大 100 KB                  |
| `content_sha256` | string | 否  | 当前内容的期望 SHA-256（乐观并发控制）。省略则跳过校验 |
| `metadata`       | object | 否  | 要附加的元数据                         |

如果传入的 `content_sha256` 与服务端不一致（说明有并发写入），API 将返回 **409 Conflict**，需要先重新 GET 该 memory 再重试。

### 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."
      }
    ]
  }'
```

Session 内 Agent 可读取和写入关联的 Memory Store。

### Memory 在 sandbox 内的路径

memory\_store 绑到 session 后，每条 memory 在 sandbox 内挂在：

```
/data/.qoder/awareness/<memory.path>
```

例如 `path = "shared/note.txt"` → sandbox 路径 `/data/.qoder/awareness/shared/note.txt`。

注意：sandbox 内**没有** `memory_store` / `mem_` 这些命名层级，全部平铺到 `awareness/` 下。Agent 看不到也搜不到 memory\_store 这个概念，只能按 `path` 直接读取文件。

## 版本追踪

每次对 Memory 执行创建、更新或删除操作，系统都会自动生成一个版本快照。版本不可修改，提供完整的变更历史。用 `GET /memory_stores/{id}/memory_versions`（可用 `memory_id` 过滤）列出版本，用 `GET /memory_stores/{id}/memory_versions/{memory_version_id}` 读取单个版本的 `content`。

如果某个版本记录了敏感内容，可以 [redact](/zh/cloud-agents/api/memory-stores/redact-version) 永久移除其存储内容，同时保留版本元数据用于审计。

## 统计字段

| 字段            | 说明                 |
| ------------- | ------------------ |
| `entry_count` | Store 中的 Memory 总数 |
| `total_size`  | 所有 Memory 内容的总字节数  |

## 常见问题

**Q: 一个 Session 可以关联多少个 Memory Store？** A: 支持多个，按需关联。

**Q: Memory 的 path 可以包含子目录吗？** A: 可以，如 `notes/2026/05/daily.md`，支持多级路径。

**Q: Memory Store 有容量限制吗？** A: 具体限制请参考账户配额，通常足够一般项目使用。

<Note>
  建议为每个独立项目创建单独的 Memory Store，避免不同项目的记忆混淆。
</Note>