持久化记忆

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

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 知识库"
  }'

响应示例：

{
  "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

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选择微服务架构，原因：团队规模扩大，需要独立部署。"
  }'

列表接口不返回 content 字段，需要调用单条获取接口才能读取内容。

​

3. 获取单条 Memory

通过 memory_id 获取完整内容（包括 content 字段）：

curl https://api.qoder.com/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/memories/mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1 \
  -H "Authorization: Bearer $QODER_PAT"

响应示例：

{
  "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：

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：

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 永久移除其存储内容，同时保留版本元数据用于审计。

​

统计字段

字段	说明
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: 具体限制请参考账户配额，通常足够一般项目使用。

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