跳转到主要内容
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}/redactRedact 某个版本

​
路径规则

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"
  }'
请求字段：
字段类型必填说明
contentstring是新的内容，最大 100 KB
content_sha256string否当前内容的期望 SHA-256（乐观并发控制）。省略则跳过校验
metadataobject否要附加的元数据
如果传入的 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_countStore 中的 Memory 总数
total_size所有 Memory 内容的总字节数

​
常见问题

Q: 一个 Session 可以关联多少个 Memory Store？ A: 支持多个，按需关联。 Q: Memory 的 path 可以包含子目录吗？ A: 可以，如 notes/2026/05/daily.md，支持多级路径。 Q: Memory Store 有容量限制吗？ A: 具体限制请参考账户配额，通常足够一般项目使用。
建议为每个独立项目创建单独的 Memory Store，避免不同项目的记忆混淆。