持久化记忆-Qoder CN 系列(Lingma)-阿里云帮助中心

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

核心概念

概念	说明
Memory Store	记忆仓库，按项目或领域划分
Entry	一条记忆，由 `path` 标识，每条 Entry 有唯一的 `entry_id`
Version	每次写入/更新/删除自动生成的版本快照
Redact	不可逆地遮蔽某版本内容（合规场景）

层级关系：Store → Entry → Version

API 端点一览

方法	路径	说明
POST	`/memory_stores`	创建 Memory Store
GET	`/memory_stores`	列出所有 Memory Store
GET	`/memory_stores/{id}`	获取 Memory Store 详情
DELETE	`/memory_stores/{id}`	删除 Memory Store
POST	`/memory_stores/{id}/memories`	创建 Entry
GET	`/memory_stores/{id}/memories`	列出所有 Entry
GET	`/memory_stores/{id}/memories/{entry_id}`	获取单条 Entry（含 `content`）
PUT	`/memory_stores/{id}/memories/{entry_id}`	更新 Entry（OCC）
DELETE	`/memory_stores/{id}/memories/{entry_id}`	删除 Entry
POST	`/memory_stores/{id}/versions/{version_id}/redact`	遮蔽某版本内容

路径规则

Entry 的 path 必须是相对路径：

合法：notes/meeting-2026-05-18.md、config.yaml
非法：/notes/meeting.md（不能以 / 开头）

路径用于组织记忆结构，类似文件系统。

完整流程

1. 创建 Memory Store

curl -X POST https://api.qoder.com.cn/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",
  "type": "memory_store",
  "name": "project-alpha-memory",
  "description": "Alpha 项目的 Agent 知识库",
  "status": "active",
  "entry_count": 0,
  "total_size": 0,
  "metadata": {},
  "created_at": "2026-05-18T08:00:00Z",
  "updated_at": "2026-05-18T08:00:00Z"
}

2. 创建 Entry

curl -X POST https://api.qoder.com.cn/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. 获取单条 Entry

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

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

响应示例：

{
  "content": "# 架构决策\n\n选择微服务架构，原因：团队规模扩大，需要独立部署。",
  "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a",
  "created_at": "2026-05-18T08:00:00Z",
  "id": "mem_019e5cdb9c3f71c3b6505eba937a40b5",
  "metadata": {},
  "path": "decisions/arch-choice.md",
  "size": 45,
  "store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4",
  "type": "memory",
  "updated_at": "2026-05-18T09:30:00Z",
  "version": 2
}

4. 更新 Entry

更新 Entry 必须使用 PUT 方法，路径中带 entry_id，并携带当前 version（乐观并发控制）。系统会自动生成新版本快照：

curl -X PUT https://api.qoder.com.cn/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，原因：微服务运维成本超出预算。",
    "version": 1
  }'

请求字段：

字段	类型	必填	说明
`content`	string	是	新的内容
`version`	integer	是	当前 Entry 的版本号（用于冲突检测）

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

5. 删除 Entry

通过 entry_id 删除指定 Entry：

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

删除使用 entry_id（如 mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1），不支持通过 path 查询参数删除。

6. 在 Session 中使用

创建 Session 时通过 memory_store_ids 关联：

curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "memory_store_ids": ["memstore_019e5cdb9c3f71c3b6505eba937a40b4"]
  }'

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

Memory Entry 在 sandbox 内的路径

memory_store 绑到 session 后，每个 entry 在 sandbox 内挂在：

/data/.qoder/awareness/<entry.path>

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

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

版本追踪

每次对 Entry 执行创建、更新或删除操作，系统都会自动生成一个版本快照。版本不可修改，提供完整的变更历史。

Redact（内容遮蔽）

当某个版本包含敏感信息需要永久清除时：

curl -X POST https://api.qoder.com.cn/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/versions/ver_xyz789/redact \
  -H "Authorization: Bearer $QODER_PAT"

注意：Redact 操作不可逆，遮蔽后内容无法恢复。

统计字段

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

常见问题

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

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

Q: 删除 Entry 后版本还在吗？ A: 删除操作本身会生成一个”删除”版本记录，之前的版本仍可追溯。

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

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