Copy

Forward Memory Store 相关接口共用的三个对象结构。层级关系：Memory Store → Memory → Memory Version。

层级	ID 前缀	说明
Memory Store	`memstore_`	记忆库容器，本身不存内容，可挂载到 `(identity, template)`。
Memory	`mem_`	库内一条记忆，由相对 `path` 标识，承载实际 `content`。
Memory Version	`memver_`	每次创建、更新、删除 memory 时自动生成的版本快照，不可修改。

Memory Store 对象

{
  "id": "memstore_00mc7mukn7lkxr454tjd",
  "type": "memory_store",
  "name": "project-alpha-memory",
  "description": "Alpha 项目的 Agent 知识库",
  "status": "active",
  "entry_count": 12,
  "total_size": 4096,
  "metadata": {
    "team": "backend",
    "created_by": "forward"
  },
  "system_managed": false,
  "identity_id": null,
  "created_at": "2026-08-14T10:00:00Z",
  "updated_at": "2026-08-14T10:00:00Z",
  "archived_at": null,
  "binding_info": {
    "identity_template_count": 1
  }
}

字段	类型	说明
`id`	string	Memory Store ID，前缀 `memstore_`。
`type`	string	固定为 `memory_store`。
`name`	string	Store 展示名。
`description`	string	Store 描述。
`status`	string	`active` 或 `archived`。
`entry_count`	integer	Store 中的 memory 条目数量。
`total_size`	integer	所有 memory 内容的总字节数。
`metadata`	object	元数据。始终包含服务端注入的 `created_by=forward`。
`system_managed`	boolean	`true` 表示系统在 Session 创建时为 `(identity, template)` 自动配的默认库；用户显式创建的为 `false`。
`identity_id`	string/null	系统默认库指向所属 identity；用户创建的库为 `null`。
`created_at`	string	创建时间，RFC 3339 格式。
`updated_at`	string	最后更新时间，RFC 3339 格式。
`archived_at`	string/null	归档时间，未归档为 `null`。
`binding_info.identity_template_count`	integer	当前挂载该 Store 的 `(identity, template)` 数量。归档和删除会检查该值。

Store metadata 约束

约束	值
最大键数	15
键长度	1..64 字符
值类型	必须为字符串
值长度	≤512 字符
保留键	`created_by` 由服务端注入为 `"forward"`；调用方传入返回 `400`

上游硬上限为 16 键，Forward 在写入侧注入 created_by 占用一个键位，因此调用方可用 15 键。

Memory 对象

{
  "id": "mem_00mc7mvag5u68kkfvxhy",
  "type": "memory",
  "memory_store_id": "memstore_00mc7mukn7lkxr454tjd",
  "path": "decisions/arch-choice.md",
  "content": "# 架构决策\n\n选择微服务架构。",
  "content_size_bytes": 99,
  "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a",
  "metadata": {
    "owner": "backend-team"
  },
  "created_at": "2026-08-14T10:00:00Z",
  "updated_at": "2026-08-14T10:00:00Z"
}

字段	类型	说明
`id`	string	Memory ID，前缀 `mem_`。
`type`	string	固定为 `memory`。
`memory_store_id`	string	所属 Memory Store ID。
`path`	string	库内相对路径，大小写敏感。
`content`	string/null	内容明文（UTF-8）。仅单条查询、创建、更新接口返回；列表接口不返回该字段。
`content_size_bytes`	integer	内容字节数。
`content_sha256`	string	内容的 SHA-256，可用于乐观并发控制。
`metadata`	object	元数据。
`created_at`	string	创建时间，RFC 3339 格式。
`updated_at`	string	最后更新时间，RFC 3339 格式。

path 规则

约束	值
必须为相对路径	不能以 `/` 开头
最大长度	1024 字节
最大段数	58
每段长度	≤255 字节
禁止的段	空段、`.`、`..`、首尾带空白的段
禁止字符	`\`、NUL
大小写	敏感

合法：notes/meeting-2026-08-14.md、config.yaml 非法：/notes/meeting.md、a/../b、notes//x.md

content 约束

约束	值
编码	UTF-8 明文，非 base64
最大字节	100 KiB（按原始请求字节计算）
控制字符	不允许非打印控制字符（`U+0000`–`U+001F`、`U+007F`），换行 `\n`、回车 `\r`、制表 `\t` 除外

Memory metadata 约束

约束	值
最大键数	16
键长度	1..64 字符
值类型	必须为字符串
值长度	≤512 字符
保留键	无。Forward 不在条目层注入 `created_by`，该键名可作为普通键使用，值原样保存并回显

Agent 自身的记忆写入会把条目 metadata 整体替换为 {"source":"agent"}，通过本 API 设置的 metadata 可能被正常 Agent 活动清除。

Memory Version 对象

{
  "id": "memver_00mc7mw0t337kbcx5q52",
  "type": "memory_version",
  "memory_store_id": "memstore_00mc7mukn7lkxr454tjd",
  "memory_id": "mem_00mc7mvag5u68kkfvxhy",
  "path": "decisions/arch-choice.md",
  "content": "# 架构决策\n\n选择微服务架构。",
  "content_size_bytes": 99,
  "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a",
  "operation": "updated",
  "redacted": false,
  "redacted_at": null,
  "created_at": "2026-08-14T10:00:00Z"
}

字段	类型	说明
`id`	string	Memory Version ID，前缀 `memver_`。
`type`	string	固定为 `memory_version`。
`memory_store_id`	string	所属 Memory Store ID。
`memory_id`	string	所属 Memory ID。
`path`	string	该版本对应的 memory 路径。
`content`	string/null	版本内容。仅单条查询接口返回；列表接口不返回。已 redact 的版本为 `null`。
`content_size_bytes`	integer	版本内容字节数。
`content_sha256`	string	版本内容的 SHA-256。
`operation`	string	产生该版本的操作：`created`、`updated`、`deleted`。
`redacted`	boolean	是否已脱敏。
`redacted_at`	string/null	脱敏时间，未脱敏为 `null`。
`created_at`	string	版本生成时间，RFC 3339 格式。

Memory Store 挂载对象

(identity, template) 上的一条挂载记录。

{
  "memory_store_id": "memstore_00mc7mukn7lkxr454tjd",
  "identity_id": "idn_63ee28747a35cff93771c491",
  "template_id": "tmpl_eb3377fb74ad413e17b3d755",
  "access": "read_only",
  "system_managed": false,
  "name": "team-a",
  "status": "active",
  "entry_count": 12,
  "created_at": "2026-08-14T10:00:00Z"
}

字段	类型	说明
`memory_store_id`	string	挂载的 Memory Store ID。
`identity_id`	string	挂载所属 identity。
`template_id`	string	挂载所属 template。
`access`	string	`read_write` 或 `read_only`。见下方访问权限说明。
`system_managed`	boolean	`true` 表示系统自动配的默认库槽位。
`name`	string	挂载库的展示名，取自 Store 实体。best-effort：Store 不可读时为空串。
`status`	string	挂载库的状态（`active` / `archived`），取自 Store 实体。best-effort：Store 不可读时为空串。
`entry_count`	integer	挂载库的 memory 条目数，取自 Store 实体。best-effort：Store 不可读时为 `0`。
`created_at`	string	挂载建立时间，RFC 3339 格式。

访问权限与挂载上限

规则	说明
唯一可写库	系统默认库（`system_managed=true`）是唯一以 `read_write` 注入 Session 的库。
显式挂载权限	用户显式挂载的库一律 `read_only`，Agent 能读但写不进去。
挂载上限	同一 `(identity, template)` 最多挂载 10 个显式库，不含默认槽位。
列表顺序	默认库排第一，其余按挂载时间升序。

之所以强制「恰好一个可写」：多个可写库同时挂载时，上游选择写入目标的查询没有确定排序，写入落点会不可预测。

在 Session 中的可见形态

Session 创建时，Forward 会把该 (identity, template) 上所有活跃挂载注入到会话资源中。所有库的 memory 会按 path 合并成一个扁平命名空间挂载到 sandbox：

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

沙箱内没有 memory_store / mem_ 这些命名层级，Agent 只能按 path 直接读取文件。多个库中相同 path 会相互遮蔽，遮蔽顺序按挂载建立时间稳定，但不直观 —— 建议为不同库使用不同的 path 前缀。

自托管 Environment 上不加载：当 Session 运行在自托管 Environment（config.type=self_hosted）上时，Forward 不会向 Session 注入任何 memory store。挂载关系不受影响——挂载接口照常返回，库与条目仍可通过 Memory Store 相关 API 正常读写；只是 Agent 沙箱内看不到这些记忆。需要 Agent 使用记忆时，请在托管（cloud）Environment 上运行 Session。

​Memory Store 对象

​Store metadata 约束

​Memory 对象

​path 规则

​content 约束

​Memory metadata 约束

​Memory Version 对象

​Memory Store 挂载对象

​访问权限与挂载上限

​在 Session 中的可见形态