AgentbaseDocs
文档目录

记忆 API

Agent 记忆的完整数据面:记忆写入(直接或模型辅助抽取)、检索与召回、知识治理(上下文/蒸馏/反馈/观察)、技能与经验库、用户画像、导入导出、共享与运维观测。记忆串行写入、失败按有界策略重试:模型辅助抽取默认异步排队,重试去重用 Idempotency-Key。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope:memories.read、memories.write、memories.delete、memories.share、memories.export;批量端点 POST /memory/memories/batch 按操作类型要求三者并集。可见性 scope(记录级):private / strict_private / user / group / project;列表与召回支持 accessMode(owned 仅本人 / accessible 授权可见并集)。

端点清单

方法 + 路径用途
POST /memory/memories创建记忆(直接或 infer 抽取)
GET /memory/memories列出记忆
GET /memory/memories/{memoryId}获取记忆
PATCH /memory/memories/{memoryId}更新记忆(CAS 版本)
DELETE /memory/memories/{memoryId}删除(遗忘)单条
DELETE /memory/memories有界批量遗忘
POST /memory/memories/batch批量创建/删除/检索组合操作
GET /memory/jobs/{jobId}查询异步写入任务
GET /memory/memories/{memoryId}/sources记忆证据源列表
POST /memory/memories/search记忆检索
POST /memory/memories/recall召回(注入用)
GET /memory/memories/skills / POST /memory/memories/skills/search技能列表/语义检索
GET /memory/memories/skills/{knowledgeId} / .../sources技能详情/证据源
GET /memory/memories/experiences / POST /memory/memories/experiences/search经验列表/语义检索
GET /memory/memories/experiences/{knowledgeId} / .../sources经验详情/证据源
GET /memory/memories/contexts治理上下文列表
GET /memory/memories/contexts/{contextId}上下文详情
POST /memory/memories/contexts/runs调度 Dreaming 运行
GET /memory/memories/contexts/statusDreaming 状态
POST /memory/memories/contexts/{contextId}/confirm确认 shadow 上下文
POST /memory/memories/contexts/{contextId}/rebuild重建上下文
POST /memory/memories/contexts/{contextId}/rollback回滚活跃上下文
GET /memory/memories/distillations蒸馏任务列表
POST /memory/memories/distillations提交蒸馏
GET /memory/memories/distillations/{distillationId}蒸馏详情
POST /memory/memories/distillations/{distillationId}/replay重放蒸馏
PATCH /memory/memories/knowledge/{knowledgeId}更新托管知识状态
DELETE /memory/memories/knowledge/{knowledgeId}标记遗忘知识
POST /memory/memories/feedback召回反馈
POST /memory/memories/observations记录知识观察结果
GET /memory/memories/users/{userId}/profile读取用户画像
DELETE /memory/memories/users/{userId}/profile删除画像
POST /memory/memories/users/{userId}/profile/extractions增量/替换画像抽取
POST /memory/memories/users/{userId}/profile/rebuild全量重建画像
GET /memory/memories/users/{userId}/profile/sources画像证据源
POST /memory/memories/imports导入记忆
GET /memory/memories/imports/{importId}导入任务详情
POST /memory/memories/exports创建导出任务
GET /memory/memories/exports/{exportId}导出任务详情
GET /memory/memories/export同步导出
`GETPOST /memory/memories/{memoryId}/shares、DELETE .../shares/{shareId}`记忆共享管理
POST /memory/memories/projections/rebuild投影重建(有界 pass)
GET /memory/memories/projections/verification投影恢复校验
GET /memory/memories/stats / quality / timeline / sessions统计/质量/时间线/会话
GET /memory/audits请求审计

请求与响应

以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:

示例上下文:示例沿用早餐店经营场景——用户 user-123 与代理 agent_support 的日常经营记忆。

记忆写入与基础 CRUD

POST /v1/memory/memories

SDK:Memory.create · scope:memories.write

创建一条记忆:直接写入,或 infer=true 时交给模型做事实抽取、派生与跨类型去重。

输入:

参数位置类型必填默认/枚举说明
contentbodystring否兼容纯文本内容;未传 messages 时必填。
messagesbodyobject[]否类型化 role/content 消息数组,作为证据源保留;与 content 同时传入时 messages 是事实抽取的权威输入(仅 user 角色参与抽取)。
userIdbodystring是目标用户 ID。
agentIdbodystring否归属代理 ID(可选);会话上下文历史只匹配相同 agentId(含空值)。
runIdbodystring否归属运行 ID(可选);不作为 sessionId 的回退值。
sessionIdbodystring否最长 128 字符会话 ID(2.7.0 新增,appbase PR 542/552/553):所有合法 scope 都可接受的来源归因字段;仅当 infer=true 且 scope 为 user / group / project 时加载同会话有界历史,private / strict_private 永不做历史补水。语义细则见本端点响应示例后的说明。
scopebodystring是枚举:private / strict_private / user / group / project可见性 scope;strict_private 不参与授权可见并集(仅所有者可见)。
sensitivitybodystring否枚举:normal / confidential / restricted / secret内容分级;secret 内容会被拒绝入库——敏感值必须走 Secret/变量。
handlingPolicybodystring否枚举:standard / no_embedding / no_model处理限制:no_embedding 不做向量化、no_model 不做任何模型处理(要求 infer=false)。
memoryTypebodystring是记忆类型;infer=true 时对话原文保留为证据、派生记录归类 long_term。
recordKindbodystring是枚举:conversation / fact / action记录类型:conversation(对话)/ fact(事实)/ action(动作);infer=true 时对话输入派生 fact。
metadatabodyobject否自由元数据对象。
inferbodyboolean否启用模型辅助抽取与跨类型去重,默认 true;会结合检索候选执行 ADD/UPDATE/DELETE/NOOP 推理。
reRememberbodyboolean否为已遗忘内容显式重建证据。
asyncbodyboolean否入队异步处理并立即返回;缺省随 infer(即默认异步入队)。

输出:

200,返回宽类型写入结果(console SDK 类型 MemoryWriteResponse):同步成功含 memory 记录;异步入队返回任务引用,用 GET /memory/jobs/{jobId} 轮询。串行写入、失败有界重试;Idempotency-Key 头或 idempotencyKey 参数用于重试去重。

字段类型说明
statusstring写入结果状态(如 ok)。
modestring处理路径:simple 直写 / inferred 模型抽取。
sourceIdstring证据源 ID,用于 provenance 追溯与 dedup 判断。
jobIdstring异步任务 ID;async=true 或 infer=true 时返回。
memoryobject同步落库时的记忆记录(含 memoryId、version)。
actionsobject[]infer=true 时模型执行的推理动作列表。
retryableboolean失败时是否可重试。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "我习惯每天早上十一点查看早餐店经营简报"
      }
    ],
    "userId": "user-123",
    "agentId": "agent_support",
    "runId": "run_20260914_01",
    "scope": "user",
    "sensitivity": "normal",
    "handlingPolicy": "standard",
    "memoryType": "conversation",
    "recordKind": "conversation",
    "metadata": {
      "topic": "早餐店经营"
    },
    "infer": true,
    "reRemember": false,
    "async": false
  }'

响应示例:

{
  "status": "ok",
  "mode": "inferred",
  "sourceId": "src_71f0c2",
  "jobId": "job_3f8a12c9",
  "memory": {
    "memoryId": "mem_7c1d94aa",
    "userId": "user-123",
    "scope": "user",
    "memoryType": "conversation",
    "recordKind": "fact",
    "version": 1
  },
  "actions": [
    {
      "action": "ADD",
      "targetType": "fact",
      "confidence": 0.92
    }
  ],
  "retryable": false
}

**sessionId 与会话上下文推断(2.7.0)**:infer=true 且 scope 为 user / group / project 时,服务加载同会话有界历史辅助指代消解——窗口最多含当前 source 之前最近 12 个较早 source turn,受约 4096 tokens 固定预算约束,只取未过期且仍允许模型处理的 conversation source;查询按项目、Memory 子存储、userId、agentId(含空值)、sessionId、scope、sensitivity、handlingPolicy 围栏,group 另要求相同 groupId 且当前身份仍属该组,不满足任一条件的历史不进入模型输入。private / strict_private 有意禁用历史补水(仍保存本轮 sessionId);infer=false 或未传 sessionId 也不加载。顶层 sessionId 为空时兼容回退读取 metadata.sessionId / metadata.session_id(顶层非空始终优先,runId 不参与回退)。推断任务在模型调用前固定本次历史 source 集合:重试只重读该集合、不吸收稍后新增的会话消息;任一历史 source 因删除/过期/治理变化失效时任务失败关闭,而不是换用其他历史。历史消息只用于本轮推断,不会复制进当前 source 正文。

GET /v1/memory/memories

SDK:Memory.list · scope:memories.read

列出当前调用者可见的记忆记录(不透明游标分页)。

输入:

参数位置类型必填默认/枚举说明
cursorquerystring否默认 ""上页响应 nextCursor 返回的游标。
limitqueryinteger否单页最大记忆条数。
filterqueryobject否默认 {}结构化记忆过滤对象。
queriesquerystring[]否默认 []Appbase Query 风格查询串数组。
userIdquerystring否默认 ""按目标用户过滤。
accessModequerystring否枚举:owned / accessible;默认 "owned"owned 仅本人(兼容默认)/ accessible 授权可见并集。

输出:

200,返回宽类型列表 MemoryList:memories[](memoryId、userId、content、version、scope、memoryType、recordKind、createdAt 等)+ total + nextCursor(为空串表示没有下一页)。

字段类型说明
memoriesobject[]记忆记录数组。
totalinteger可见记忆总数。
nextCursorstring下页游标;空串表示已到末页。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories?cursor=cur_9f2e&limit=10&userId=user-123" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "memories": [
    {
      "memoryId": "mem_7c1d94aa",
      "userId": "user-123",
      "agentId": "agent_support",
      "scope": "user",
      "memoryType": "long_term",
      "recordKind": "fact",
      "content": "用户习惯每天早上十一点查看早餐店经营简报",
      "version": 3,
      "sensitivity": "normal",
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-14T08:00:00.000+00:00"
    },
    {
      "memoryId": "mem_7c1d94ab",
      "userId": "user-123",
      "scope": "user",
      "memoryType": "working",
      "recordKind": "conversation",
      "content": "讨论过周末进货安排",
      "version": 1,
      "sensitivity": "normal",
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-01T08:00:00.000+00:00"
    }
  ],
  "total": 2,
  "nextCursor": ""
}

GET /v1/memory/memories/{memoryId}

SDK:Memory.get · scope:memories.read

按 ID 获取单条记忆。

输入:

参数位置类型必填默认/枚举说明
memoryIdpathstring是目标记忆 ID。

输出:

200,返回宽类型对象 MemoryResponse:memory 字段承载记忆记录(memoryId、userId、scope、memoryType、recordKind、content、version 等)。

字段类型说明
memoryobject记忆记录本体;version 为 CAS 乐观锁版本,更新时必须回传。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/mem_7c1d94aa" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "memory": {
    "memoryId": "mem_7c1d94aa",
    "userId": "user-123",
    "agentId": "agent_support",
    "runId": "run_20260914_01",
    "scope": "user",
    "memoryType": "long_term",
    "recordKind": "fact",
    "content": "用户习惯每天早上十一点查看早餐店经营简报",
    "version": 3,
    "sensitivity": "normal",
    "handlingPolicy": "standard",
    "metadata": {
      "topic": "早餐店经营"
    },
    "retentionPolicy": "default",
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-14T08:00:00.000+00:00"
  }
}

PATCH /v1/memory/memories/{memoryId}

SDK:Memory.update · scope:memories.write

按 ID 更新记忆文本/元数据,version 做 CAS 乐观锁。

输入:

参数位置类型必填默认/枚举说明
memoryIdpathstring是目标记忆 ID。
versionbodyinteger是期望的当前版本号;与服务端不一致返回并发冲突——读取最新版本后再重试,不要盲目覆盖。
contentbodystring否更新后的记忆文本。
metadatabodyobject否元数据合并补丁(与现有 metadata 深合并)。
retentionPolicybodystring否枚举:default保留策略;当前枚举仅 default。

输出:

200,返回宽类型对象 MemoryResponse(更新后的 memory,version 递增)。

调用示例:

curl -X PATCH "https://<your-endpoint>/v1/memory/memories/mem_7c1d94aa" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 3,
    "content": "用户习惯每天早上十一点查看早餐店经营简报(更新)",
    "metadata": {
      "verified": true
    },
    "retentionPolicy": "default"
  }'

响应示例:

{
  "memory": {
    "memoryId": "mem_7c1d94aa",
    "userId": "user-123",
    "scope": "user",
    "memoryType": "long_term",
    "recordKind": "fact",
    "content": "用户习惯每天早上十一点查看早餐店经营简报(更新)",
    "version": 4,
    "metadata": {
      "topic": "早餐店经营",
      "verified": true
    },
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-14T08:00:00.000+00:00"
  }
}

DELETE /v1/memory/memories/{memoryId}

SDK:Memory.delete · scope:memories.delete + memories.write

删除(遗忘)单条记忆:逻辑删除并进入后续物理压缩流程。

输入:

参数位置类型必填默认/枚举说明
memoryIdpathstring是目标记忆 ID。
reasonbodystring否遗忘原因(审计用)。
sourcebodystring否遗忘来源(审计用)。

输出:

200,返回宽类型对象:删除登记结果。遗忘是标记语义——导出默认不含已遗忘记录,reRemember=true 可为其重建证据。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/memory/memories/mem_7c1d94aa" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "用户要求删除",
    "source": "ops-console"
  }'

响应示例:

{
  "status": "ok",
  "memoryId": "mem_7c1d94aa"
}

DELETE /v1/memory/memories

SDK:Memory.deleteMany · scope:memories.delete

有界批量遗忘:单轮最多处理 limit(≤500)条,hasMore=true 时循环调用直到清完。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring否目标用户 ID。
limitbodyinteger否本轮处理上限,1–500;服务端可能处理更少,须以 hasMore 判断是否继续。
reasonbodystring否遗忘原因。
sourcebodystring否遗忘来源。

输出:

200,返回模型 Models.MemoryBulkDeleteResponse。注意:HTTP 成功不等于全清——必须检查 hasMore 与 items[] 内的 failed 条目。

字段类型说明
status*string本轮聚合结果:ok 全部成功 / partial_failed 存在失败。
processed*integer本轮处理的记忆条数。
forgotten*integer本轮成功遗忘的条数。
failed*integer本轮删除失败的条数。
hasMore*boolean为 true 时必须继续发起新一轮 deleteMany 直到清完。
items*object[]逐条删除结果。
memoryId*stringMemory record ID processed in this pass.
status*stringPer-record deletion outcome.
errorCodestringMachine-readable error code when deletion failed.
retryablebooleanWhether the failed record can be retried.
errorstringHuman-readable failure detail.

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/memory/memories" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "limit": 500,
    "reason": "合规清理",
    "source": "ops-console"
  }'

响应示例:

{
  "status": "ok",
  "processed": 2,
  "forgotten": 2,
  "failed": 0,
  "hasMore": false,
  "items": [
    {
      "memoryId": "mem_7c1d94aa",
      "status": "ok"
    },
    {
      "memoryId": "mem_7c1d94ab",
      "status": "ok"
    }
  ]
}

POST /v1/memory/memories/batch

SDK:Memory.createBatch · scope:memories.read + memories.write + memories.delete

在有界批次中混合执行 create / delete / search 操作。

输入:

参数位置类型必填默认/枚举说明
itemsbodyobject[]是有界的操作数组;每项按 operation 携带对应负载(create/delete/search 三选一)。
items.operationbodystring是枚举:create / delete / search该操作类型:create / delete / search。
items.createbodyobject否创建负载,字段同 POST /memory/memories 请求体。
items.deletebodyobject否删除负载,字段同 DELETE /memory/memories 请求体(userId/limit/reason/source)。
items.searchbodyobject否检索负载,字段同 POST /memory/memories/search 请求体。

输出:

200,返回宽类型对象:与 items 顺序对应的逐项结果(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。scope 要求 memories.read + memories.write + memories.delete 三者并集。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/batch" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "operation": "create",
        "create": {
          "userId": "user-123",
          "scope": "user",
          "memoryType": "conversation",
          "recordKind": "conversation",
          "messages": [
            {
              "role": "user",
              "content": "周末要从批发市场进一批鸡蛋"
            }
          ]
        }
      },
      {
        "operation": "search",
        "search": {
          "query": "进货安排",
          "userId": "user-123",
          "limit": 5
        }
      }
    ]
  }'

响应示例:

{
  "results": [
    {
      "index": 0,
      "operation": "create",
      "status": "ok",
      "memoryId": "mem_7c1d94ac",
      "jobId": "job_40b1aa"
    },
    {
      "index": 1,
      "operation": "search",
      "status": "ok",
      "total": 1,
      "items": [
        {
          "memoryId": "mem_7c1d94aa",
          "content": "用户习惯每天早上十一点查看早餐店经营简报",
          "score": 0.9
        }
      ]
    }
  ]
}

GET /v1/memory/jobs/{jobId}

SDK:Memory.getJob · scope:memories.write

查询异步记忆写入任务的执行状态与结果。

输入:

参数位置类型必填默认/枚举说明
jobIdpathstring是写入任务 ID(创建记忆异步响应中返回)。

输出:

200,返回宽类型对象(console SDK 类型 MemoryWriteJob)。轮询方式:每 1–2 秒调用本端点,status 到 succeeded/failed 即止;failed 且 retryable=true 时修复后重发(带同一 Idempotency-Key 去重)。

字段类型说明
jobIdstring任务 ID。
statusstringqueued / running / succeeded / failed。
modestringsimple 直写 / inferred 模型抽取。
sourceIdstring证据源 ID。
attemptCount / maxAttemptsinteger已重试次数 / 最大重试次数(有界)。
errorCode / reasonstring失败码与原因。
retryableboolean失败后是否可重试。
resultobject成功时的写入结果(同创建响应)。
queueDurationMs / executionDurationMs / totalDurationMsnumber排队/执行/总耗时(毫秒)。
createdAt / startedAt / completedAtstring创建/开始/完成时间。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/jobs/job_3f8a12c9" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "jobId": "job_3f8a12c9",
  "status": "succeeded",
  "mode": "inferred",
  "sourceId": "src_71f0c2",
  "attemptCount": 1,
  "maxAttempts": 3,
  "retryable": false,
  "result": {
    "status": "ok",
    "mode": "inferred",
    "memoryId": "mem_7c1d94aa"
  },
  "queueDurationMs": 120.5,
  "executionDurationMs": 1830.2,
  "totalDurationMs": 1950.7,
  "createdAt": "2026-09-01T08:00:00.000+00:00",
  "updatedAt": "2026-09-01T08:00:00.000+00:00",
  "startedAt": "2026-09-01T08:00:00.000+00:00",
  "completedAt": "2026-09-01T08:00:02.100+00:00"
}

证据源与共享

GET /v1/memory/memories/{memoryId}/sources

SDK:Memory.listSources · scope:memories.read

列出记忆关联的不可变证据源(provenance)。

输入:

参数位置类型必填默认/枚举说明
memoryIdpathstring是目标记忆 ID。
cursorquerystring否默认 ""上页 nextCursor 游标。
limitqueryinteger否默认 25单页最大条数,默认 25。

输出:

200,返回宽类型列表(console SDK 类型 MemorySourceList):sources[] 为不可变证据源记录 + total + nextCursor。

字段类型说明
sources[].sourceIdstring证据源 ID(创建响应中的 sourceId)。
sources[].sourceTypestring证据类型(如 conversation)。
sources[].messages / contentobject / string原始证据内容。
sources[].configVersion / promptVersioninteger / string抽取时的配置/提示词版本。
total / nextCursorinteger / string总数与下页游标。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/mem_7c1d94aa/sources?cursor=cur_9f2e&limit=10" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "sources": [
    {
      "sourceId": "src_71f0c2",
      "sourceType": "conversation",
      "userId": "user-123",
      "agentId": "agent_support",
      "runId": "run_20260914_01",
      "sessionId": "sess_8842",
      "messages": [
        {
          "role": "user",
          "content": "我习惯每天早上十一点查看早餐店经营简报"
        }
      ],
      "configVersion": 7,
      "promptVersion": "extract@3",
      "retentionPolicy": "default",
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-01T08:00:00.000+00:00"
    }
  ],
  "total": 1,
  "nextCursor": ""
}

GET /v1/memory/memories/{memoryId}/shares

SDK:Memory.listShares · scope:memories.share

列出一条记忆的全部生效读授权。

输入:

参数位置类型必填默认/枚举说明
memoryIdpathstring是目标记忆 ID。

输出:

200,返回宽类型对象:该记忆的授权列表(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
shares[].shareIdstring共享授权稳定 ID(撤销时用作 {shareId})。
shares[].subjectTypestringuser / group。
shares[].subjectIdstring被授权用户或群组 ID。
shares[].expiresAtstring过期时间(RFC3339);null 为永久。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/<MEMORYID>/shares" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "shares": [
    {
      "shareId": "share_5e77b2",
      "subjectType": "user",
      "subjectId": "user-456",
      "expiresAt": "2026-12-31T00:00:00.000+00:00",
      "createdAt": "2026-09-01T08:00:00.000+00:00"
    }
  ],
  "total": 1
}

POST /v1/memory/memories/{memoryId}/shares

SDK:Memory.createShare · scope:memories.share

为用户或群组授予单条记忆的读权限。

输入:

参数位置类型必填默认/枚举说明
memoryIdpathstring是目标记忆 ID。
subjectTypebodystring是枚举:user / group被授权主体类型:user / group。
subjectIdbodystring是被授权主体 ID。
expiresAtbodystring否过期时间(RFC3339),最多未来 365 天;省略为永久授权。

输出:

200,返回宽类型对象:新授权条目(含 shareId)(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。被授权者在 accessMode=accessible 下可见该记忆。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/<MEMORYID>/shares" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "user",
    "subjectId": "user-456",
    "expiresAt": "2026-12-31T00:00:00.000+00:00"
  }'

响应示例:

{
  "shareId": "share_5e77b2",
  "subjectType": "user",
  "subjectId": "user-456",
  "expiresAt": "2026-12-31T00:00:00.000+00:00",
  "createdAt": "2026-09-01T08:00:00.000+00:00"
}

DELETE /v1/memory/memories/{memoryId}/shares/{shareId}

SDK:Memory.deleteShare · scope:memories.share

撤销一条记忆读授权。

输入:

参数位置类型必填默认/枚举说明
memoryIdpathstring是目标记忆 ID。
shareIdpathstring是要撤销的共享授权 ID。

输出:

200,返回宽类型对象:撤销登记结果(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/memory/memories/mem_7c1d94aa/shares/share_5e77b2" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "status": "ok",
  "shareId": "share_5e77b2"
}

检索与召回

POST /v1/memory/memories/search

SDK:Memory.search · scope:memories.read

混合检索记忆记录:dense / sparse / full-text / graph 路由按项目 runtime.recallFusion 配置融合。

输入:

参数位置类型必填默认/枚举说明
querybodystring是检索查询文本(必填)。
searchModebodystring否召回模式覆盖(路由级)。
retrievalbodyobject否召回路由覆盖对象;sparse=false 跳过模型生成的稀疏召回,缺省用项目设置。
userIdbodystring否按用户过滤。
agentIdbodystring否按代理过滤。
runIdbodystring否按运行过滤。
scopebodystring否按 scope 过滤。
memoryTypebodystring否按记忆类型过滤。
recordKindbodystring否按记录类型过滤。
filterbodyobject否结构化记忆过滤对象。
limitbodyinteger否最大返回条数;0 表示用项目默认。
cursorbodystring否上页 nextCursor 游标。
sortbodystring否排序模式。
memorySubStoreIdbodystring否绑定子库精确路由。
sessionIdbodystring否按会话过滤。
groupIdbodystring否群组/实体边界过滤。
accessModebodystring否枚举:owned / accessibleowned 仅本人 / accessible 授权可见并集。

输出:

200,返回宽类型检索结果(console SDK 类型 MemorySearchResult):items[] 命中记录 + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
items[].memoryIdstring命中记忆 ID。
items[].contentstring命中内容摘要。
items[].scorenumber相关度得分(融合后)。
items[].memoryType / recordKind / scopestring命中的类型与归属。
total / nextCursorinteger / string总数与下页游标。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/search" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "早餐店经营简报",
    "retrieval": {
      "sparse": true
    },
    "userId": "user-123",
    "agentId": "agent_support",
    "runId": "run_20260914_01",
    "scope": "user",
    "filter": {},
    "limit": 10,
    "memorySubStoreId": "mss_default",
    "sessionId": "sess_8842",
    "accessMode": "accessible"
  }'

响应示例:

{
  "items": [
    {
      "memoryId": "mem_7c1d94aa",
      "content": "用户习惯每天早上十一点查看早餐店经营简报",
      "memoryType": "long_term",
      "recordKind": "fact",
      "scope": "user",
      "version": 3,
      "score": 0.93
    },
    {
      "memoryId": "mem_7c1d94ac",
      "content": "用户常在午市后复盘外卖平台评分",
      "memoryType": "long_term",
      "recordKind": "fact",
      "scope": "user",
      "version": 2,
      "score": 0.81
    }
  ],
  "total": 2,
  "nextCursor": ""
}

POST /v1/memory/memories/recall

SDK:Memory.recallKnowledge · scope:memories.read

面向注入的记忆召回:在统一 token 预算内召回记忆、画像、技能与经验,返回带 injectionId 的注入结果供 feedback 归因。

输入:

参数位置类型必填默认/枚举说明
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库精确路由。
querybodystring是召回查询文本(必填)。
kindsbodystring[]否枚举:memory / profile / skill / experience要召回的知识种类:memory / profile / skill / experience。
limitbodyinteger否最大召回条数。
tokenBudgetbodyinteger否上下文 token 预算上限。
retrievalbodyobject否召回路由覆盖。
accessModebodystring否枚举:owned / accessibleowned 仅本人 / accessible 授权可见并集。

输出:

200,返回宽类型注入结果:injectionId(feedback 归因凭据)+ 按预算裁剪的 items[](响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
injectionIdstring本次注入 ID;POST .../feedback 以此归因。
items[].knowledgeIdstring命中知识 ID(记忆/技能/经验)。
items[].kindstringmemory / profile / skill / experience。
items[].contentstring注入用正文。
items[].scorenumber相关度得分。
totalinteger命中总数。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/recall" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "query": "用户每天什么时候查看经营简报?",
    "kinds": [
      "memory",
      "profile",
      "skill",
      "experience"
    ],
    "limit": 10,
    "tokenBudget": 2000,
    "retrieval": {},
    "accessMode": "owned"
  }'

响应示例:

{
  "injectionId": "inj_2ab901",
  "items": [
    {
      "knowledgeId": "mem_7c1d94aa",
      "kind": "memory",
      "content": "用户习惯每天早上十一点查看早餐店经营简报",
      "score": 0.93
    },
    {
      "knowledgeId": "knw_skill_01",
      "kind": "skill",
      "content": "生成经营简报时先汇总昨日流水与库存消耗",
      "score": 0.88
    }
  ],
  "total": 2,
  "tokenBudget": 2000
}

技能(Skill)

GET /v1/memory/memories/skills

SDK:Memory.listSkills · scope:memories.read

列出处于活跃验证状态的技能(Skill)。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope,默认 user。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话过滤。
runIdquerystring否默认 ""来源运行过滤。
memorySubStoreIdquerystring否默认 ""绑定子库。
cursorquerystring否默认 ""上页游标。
limitqueryinteger否单页最大条数。

输出:

200,返回宽类型列表:skills[] + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
skills[].knowledgeIdstring技能稳定 ID(详情/来源/feedback 用)。
skills[].title / contentstring技能标题与正文。
skills[].statusstring治理状态(如 user-active)。
skills[].revisioninteger当前修订号。
total / nextCursorinteger / string总数与下页游标。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/skills?scope=user&userId=user-123&cursor=cur_9f2e&limit=20" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "skills": [
    {
      "knowledgeId": "knw_skill_01",
      "title": "经营简报生成",
      "status": "user-active",
      "revision": 4,
      "content": "生成经营简报时先汇总昨日流水与库存消耗,再输出异常项。",
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-14T08:00:00.000+00:00"
    }
  ],
  "total": 1,
  "nextCursor": ""
}

POST /v1/memory/memories/skills/search

SDK:Memory.searchSkills · scope:memories.read

按语义检索活跃验证的技能。

输入:

参数位置类型必填默认/枚举说明
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
querybodystring是语义检索查询(必填)。
cursorbodystring否上页游标。
limitbodyinteger否单页最大条数。
retrievalbodyobject否召回路由覆盖。

输出:

200,返回宽类型检索结果:items[](含 score)+ total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/skills/search" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "query": "生成经营简报",
    "limit": 5,
    "retrieval": {}
  }'

响应示例:

{
  "items": [
    {
      "knowledgeId": "knw_skill_01",
      "title": "经营简报生成",
      "status": "user-active",
      "revision": 4,
      "content": "生成经营简报时先汇总昨日流水与库存消耗,再输出异常项。",
      "score": 0.9
    }
  ],
  "total": 1,
  "nextCursor": ""
}

GET /v1/memory/memories/skills/{knowledgeId}

SDK:Memory.getSkill · scope:memories.read

按 ID 获取单个技能详情。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
knowledgeIdpathstring是技能知识 ID。

输出:

200,返回宽类型对象:技能详情(含 revision、status、正文与统计)(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/skills/knw_skill_01?scope=user&userId=user-123" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "skill": {
    "knowledgeId": "knw_skill_01",
    "title": "经营简报生成",
    "status": "user-active",
    "revision": 4,
    "validationStatus": "verified",
    "content": "生成经营简报时先汇总昨日流水与库存消耗,再输出异常项。",
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-14T08:00:00.000+00:00"
  }
}

GET /v1/memory/memories/skills/{knowledgeId}/sources

SDK:Memory.listSkillSources · scope:memories.read

列出技能关联的不可变证据源。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
knowledgeIdpathstring是技能知识 ID。
cursorquerystring否默认 ""上页游标。
limitqueryinteger否默认 25单页最大条数,默认 25。

输出:

200,返回宽类型列表(类型 MemorySourceList):sources[] + total + nextCursor,条目结构同记忆证据源。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/skills/knw_skill_01/sources?scope=user&userId=user-123&cursor=cur_9f2e&limit=10" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "sources": [
    {
      "sourceId": "src_71f0c2",
      "sourceType": "conversation",
      "userId": "user-123",
      "messages": [
        {
          "role": "user",
          "content": "把每天简报的生成步骤固定下来"
        }
      ],
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-01T08:00:00.000+00:00"
    }
  ],
  "total": 1,
  "nextCursor": ""
}

经验(Experience)

GET /v1/memory/memories/experiences

SDK:Memory.listExperiences · scope:memories.read

列出处于活跃验证状态的经验(Experience)。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope,默认 user。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
cursorquerystring否默认 ""上页游标。
limitqueryinteger否单页最大条数。

输出:

200,返回宽类型列表:experiences[] + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
experiences[].knowledgeIdstring经验稳定 ID。
experiences[].title / contentstring经验标题与正文。
experiences[].status / revisionstring / integer治理状态与修订号。
total / nextCursorinteger / string总数与下页游标。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/experiences?scope=user&userId=user-123&cursor=cur_9f2e&limit=20" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "experiences": [
    {
      "knowledgeId": "knw_exp_01",
      "title": "周末进货节奏",
      "status": "user-active",
      "revision": 2,
      "content": "周六客流是平日两倍,鸡蛋与鲜奶备货量按 2.2 倍计算。",
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-14T08:00:00.000+00:00"
    }
  ],
  "total": 1,
  "nextCursor": ""
}

POST /v1/memory/memories/experiences/search

SDK:Memory.searchExperiences · scope:memories.read

按语义检索活跃验证的经验。

输入:

参数位置类型必填默认/枚举说明
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
querybodystring是语义检索查询(必填)。
cursorbodystring否上页游标。
limitbodyinteger否单页最大条数。
retrievalbodyobject否召回路由覆盖。

输出:

200,返回宽类型检索结果:items[](含 score)+ total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/experiences/search" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "query": "周末备货要注意什么",
    "limit": 5,
    "retrieval": {}
  }'

响应示例:

{
  "items": [
    {
      "knowledgeId": "knw_exp_01",
      "title": "周末进货节奏",
      "status": "user-active",
      "revision": 2,
      "content": "周六客流是平日两倍,鸡蛋与鲜奶备货量按 2.2 倍计算。",
      "score": 0.89
    }
  ],
  "total": 1,
  "nextCursor": ""
}

GET /v1/memory/memories/experiences/{knowledgeId}

SDK:Memory.getExperience · scope:memories.read

按 ID 获取单个经验详情。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
knowledgeIdpathstring是经验知识 ID。

输出:

200,返回宽类型对象:经验详情(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/experiences/knw_exp_01?scope=user&userId=user-123" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "experience": {
    "knowledgeId": "knw_exp_01",
    "title": "周末进货节奏",
    "status": "user-active",
    "revision": 2,
    "validationStatus": "verified",
    "content": "周六客流是平日两倍,鸡蛋与鲜奶备货量按 2.2 倍计算。",
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-14T08:00:00.000+00:00"
  }
}

GET /v1/memory/memories/experiences/{knowledgeId}/sources

SDK:Memory.listExperienceSources · scope:memories.read

列出经验关联的不可变证据源。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
knowledgeIdpathstring是经验知识 ID。
cursorquerystring否默认 ""上页游标。
limitqueryinteger否默认 25单页最大条数,默认 25。

输出:

200,返回宽类型列表(类型 MemorySourceList),条目结构同记忆证据源。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/experiences/knw_exp_01/sources?scope=user&userId=user-123&cursor=cur_9f2e&limit=10" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "sources": [
    {
      "sourceId": "src_72a1d3",
      "sourceType": "conversation",
      "userId": "user-123",
      "content": "上周六卖断货了,鸡蛋下午三点就没了",
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-01T08:00:00.000+00:00"
    }
  ],
  "total": 1,
  "nextCursor": ""
}

治理上下文(Contexts / Dreaming)

GET /v1/memory/memories/contexts

SDK:Memory.listContexts · scope:memories.read

列出治理上下文聚合(按 scope/定位键过滤,观察 shadow → active 生命周期)。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope,默认 user。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
statusquerystring否枚举:shadow / quarantine / stale / user-active / agent-active / deprecated;默认 ""按生命周期状态过滤:shadow / quarantine / stale / user-active / agent-active / deprecated。
kindquerystring否枚举:memory_topic / memory_episode / memory_state / memory_overview;默认 ""按层级过滤:memory_topic / memory_episode / memory_state / memory_overview。
cursorquerystring否默认 ""上页游标。
limitqueryinteger否单页最大条数。

输出:

200,返回宽类型列表:contexts[] + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
contexts[].contextIdstring上下文稳定 ID(confirm/rebuild/rollback 用)。
contexts[].kindstring层级:memory_topic / memory_episode / memory_state / memory_overview。
contexts[].statusstring生命周期:shadow → user-active/agent-active,中间态 quarantine/stale,终态 deprecated。
contexts[].revisioninteger当前修订号。
total / nextCursorinteger / string总数与下页游标。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/contexts?scope=user&userId=user-123&status=shadow&cursor=cur_9f2e&limit=20" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "contexts": [
    {
      "contextId": "knw_ctx_01",
      "scope": "user",
      "userId": "user-123",
      "kind": "memory_topic",
      "status": "shadow",
      "revision": 5,
      "validationStatus": "verified",
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-14T08:00:00.000+00:00"
    }
  ],
  "total": 1,
  "nextCursor": ""
}

GET /v1/memory/memories/contexts/{contextId}

SDK:Memory.getContext · scope:memories.read

按 ID 获取单个治理上下文聚合。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
contextIdpathstring是上下文知识 ID。

输出:

200,返回宽类型对象:上下文详情(生命周期状态、修订号与正文)(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/contexts/knw_ctx_01?scope=user&userId=user-123" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "context": {
    "contextId": "knw_ctx_01",
    "scope": "user",
    "userId": "user-123",
    "kind": "memory_topic",
    "status": "shadow",
    "revision": 5,
    "validationStatus": "verified",
    "content": "用户围绕早餐店经营形成的主要话题:简报查看、进货节奏与平台复盘。",
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-14T08:00:00.000+00:00"
  }
}

POST /v1/memory/memories/contexts/runs

SDK:Memory.createContextRun · scope:memories.write

扫描变更记忆并调度 Dreaming 运行(202 异步)。

输入:

参数位置类型必填默认/枚举说明
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。

输出:

202,返回宽类型对象:调度登记结果(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。运行态用 GET .../contexts/status 查询。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/contexts/runs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default"
  }'

响应示例:

{
  "status": "scheduled",
  "scope": "user",
  "userId": "user-123"
}

GET /v1/memory/memories/contexts/status

SDK:Memory.getContextStatus · scope:memories.read

查询 Dreaming 的水位(watermark)与任务状态。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope,默认 user。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。

输出:

200,返回宽类型对象:Dreaming 运行态与水位(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
runningboolean是否有 Dreaming 运行进行中。
lastRunAtstring最近一次运行完成时间。
lastJobIdstring最近一次运行的任务 ID。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/contexts/status?scope=user&userId=user-123" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "scope": "user",
  "userId": "user-123",
  "running": false,
  "lastRunAt": "2026-09-14T08:00:00.000+00:00",
  "lastJobId": "job_50c2de"
}

POST /v1/memory/memories/contexts/{contextId}/confirm

SDK:Memory.confirmContext · scope:memories.write

把验证通过的 shadow 上下文确认为活跃(CAS 并发控制)。

输入:

参数位置类型必填默认/枚举说明
contextIdpathstring是上下文知识 ID。
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
expectedVersionbodyinteger是期望的 CAS 版本号;不匹配返回并发冲突。
reasonbodystring是有界的治理原因说明(必填,进审计)。

输出:

200,返回宽类型对象:确认后的上下文(status 变为 user-active 或 agent-active)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/contexts/knw_ctx_01/confirm" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "expectedVersion": 5,
    "reason": "人工审核通过"
  }'

响应示例:

{
  "context": {
    "contextId": "knw_ctx_01",
    "status": "user-active",
    "revision": 6
  }
}

POST /v1/memory/memories/contexts/{contextId}/rebuild

SDK:Memory.rebuildContext · scope:memories.write

把单个上下文排入重建(202 异步)。

输入:

参数位置类型必填默认/枚举说明
contextIdpathstring是上下文知识 ID。
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
reasonbodystring是有界的重建原因(必填)。

输出:

202,返回宽类型对象:重建调度登记(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。重建完成后 revision 递增、状态经 shadow 流程重新验证。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/contexts/knw_ctx_01/rebuild" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "reason": "证据源更新后重算"
  }'

响应示例:

{
  "status": "scheduled",
  "contextId": "knw_ctx_01"
}

POST /v1/memory/memories/contexts/{contextId}/rollback

SDK:Memory.rollbackContext · scope:memories.write

把活跃上下文回滚到更早的已验证修订。

输入:

参数位置类型必填默认/枚举说明
contextIdpathstring是上下文知识 ID。
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
expectedVersionbodyinteger是期望的 CAS 版本号。
targetRevisionbodyinteger是要回滚到的更早已验证修订号。
reasonbodystring是有界的治理原因(必填)。

输出:

200,返回宽类型对象:回滚后的上下文(revision 指向目标修订)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/contexts/knw_ctx_01/rollback" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "expectedVersion": 6,
    "targetRevision": 4,
    "reason": "最新修订引入事实错误"
  }'

响应示例:

{
  "context": {
    "contextId": "knw_ctx_01",
    "status": "user-active",
    "revision": 4
  }
}

蒸馏(Distillation)

GET /v1/memory/memories/distillations

SDK:Memory.listDistillations · scope:memories.read

列出蒸馏任务(可按状态过滤)。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope,默认 user。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
statusquerystring否枚举:(空,表示不限) / queued / running / succeeded / partial_failed / failed / dead;默认 ""按任务状态过滤:queued / running / succeeded / partial_failed / failed / dead。
cursorquerystring否默认 ""上页游标。
limitqueryinteger否单页最大条数。

输出:

200,返回宽类型列表:distillations[] + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
distillations[].distillationIdstring蒸馏任务 ID。
distillations[].statusstringqueued / running / succeeded / partial_failed / failed / dead。
distillations[].jobIdstring底层异步任务 ID。
total / nextCursorinteger / string总数与下页游标。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/distillations?scope=user&userId=user-123&status=succeeded&cursor=cur_9f2e&limit=20" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "distillations": [
    {
      "distillationId": "dst_60a1",
      "jobId": "job_61b2",
      "status": "succeeded",
      "queueDurationMs": 90.0,
      "executionDurationMs": 4200.0,
      "totalDurationMs": 4290.0
    }
  ],
  "total": 1,
  "nextCursor": ""
}

POST /v1/memory/memories/distillations

SDK:Memory.submitDistillation · scope:memories.write

提交有界证据做 Experience/Skill 蒸馏;mode=wait 最长等 20 秒取终态,async 立即返回。

输入:

参数位置类型必填默认/枚举说明
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
sourceIdbodystring否已持久化证据源 ID;与 sourceType 搭配,替代内联 messages/toolEvents。
sourceTypebodystring否枚举:(空,表示不限) / conversation / tool-trace / execution-log证据源类型:conversation / tool-trace / execution-log。
messagesbodyobject[]否有界的对话消息数组(与 toolEvents 二选一)。
messages.rolebodystring是枚举:system / user / assistant / tool消息角色:system / user / assistant / tool。
messages.contentbodystring是消息正文。
messages.namebodystring否工具消息的工具名(role=tool 时使用)。
toolEventsbodyobject[]否有界的工具执行事件数组(与 messages 二选一)。
toolEvents.eventIdbodystring是工具事件 ID。
toolEvents.namebodystring是工具名。
toolEvents.argumentsbodyany否工具调用参数(任意 JSON)。
toolEvents.resultbodyany否工具执行结果(status=succeeded 必填)。
toolEvents.statusbodystring是枚举:succeeded / failed执行结果:succeeded / failed;failed 时 error 必填。
toolEvents.errorbodystring否失败信息(status=failed 必填)。
modebodystring否枚举:async / waitasync 立即返回;wait 最长等待 20 秒取终态,超时返回运行中状态而非错误(改用轮询)。
idempotencyKeybodystring否幂等键(也可用 Idempotency-Key 头)。

输出:

202,返回宽类型对象:蒸馏任务登记(distillationId + status)。轮询方式:GET .../distillations/{distillationId} 至终态;dead 状态只能 replay 到新任务。

字段类型说明
distillationIdstring蒸馏任务 ID。
statusstringqueued / running / succeeded / partial_failed / failed / dead。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/distillations" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "sourceType": "",
    "messages": [
      {
        "role": "user",
        "content": "周六进了两箱鸡蛋,下午就卖完了"
      },
      {
        "role": "assistant",
        "content": "建议把周六备货量上调到平日两倍以上"
      }
    ],
    "toolEvents": [],
    "mode": "async",
    "idempotencyKey": "idem-dst-01"
  }'

响应示例:

{
  "distillationId": "dst_60a1",
  "jobId": "job_61b2",
  "status": "queued"
}

GET /v1/memory/memories/distillations/{distillationId}

SDK:Memory.getDistillation · scope:memories.read

查询蒸馏任务状态与产出引用。

输入:

参数位置类型必填默认/枚举说明
scopequerystring否枚举:user / agent / project;默认 "user"知识归属 scope。
userIdquerystring否默认 ""目标用户 ID。
agentIdquerystring否默认 ""agent scope 定位键。
sessionIdquerystring否默认 ""来源会话。
runIdquerystring否默认 ""来源运行。
memorySubStoreIdquerystring否默认 ""绑定子库。
distillationIdpathstring是蒸馏任务 ID。

输出:

200,返回宽类型对象(console SDK 类型 MemoryDistillationResponse):distillation 含 distillationId、status、jobId 与耗时字段;产出引用(生成的 Skill/Experience ID)随任务输出返回。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/distillations/dst_60a1?scope=user&userId=user-123" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "distillation": {
    "distillationId": "dst_60a1",
    "jobId": "job_61b2",
    "status": "succeeded",
    "queueDurationMs": 90.0,
    "executionDurationMs": 4200.0,
    "totalDurationMs": 4290.0,
    "outputs": [
      {
        "kind": "skill",
        "knowledgeId": "knw_skill_01"
      }
    ]
  }
}

POST /v1/memory/memories/distillations/{distillationId}/replay

SDK:Memory.replayDistillation · scope:memories.write

对失败或部分失败的蒸馏任务重放(生成新任务,不改动原任务)。

输入:

参数位置类型必填默认/枚举说明
distillationIdpathstring是要重放的蒸馏任务 ID。
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。

输出:

200,返回宽类型对象:重放产生的新蒸馏任务引用(distillationId 不同)(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/distillations/dst_60a1/replay" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default"
  }'

响应示例:

{
  "distillationId": "dst_60a2",
  "jobId": "job_61b3",
  "status": "queued",
  "replayedFrom": "dst_60a1"
}

托管知识 / 反馈 / 观察

PATCH /v1/memory/memories/knowledge/{knowledgeId}

SDK:Memory.updateKnowledge · scope:memories.write

更新托管知识(记忆/上下文/技能/经验)的治理状态(CAS 并发控制)。

输入:

参数位置类型必填默认/枚举说明
knowledgeIdpathstring是知识 ID。
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
expectedVersionbodyinteger是期望的 CAS 版本号(必填);不匹配返回并发冲突。
statusbodystring否枚举:candidate / shadow / user-active / agent-active / quarantine / deprecated目标治理状态:candidate / shadow / user-active / agent-active / quarantine / deprecated。
validationStatusbodystring否枚举:pending / verified / conflicted / rejected目标验证状态:pending / verified / conflicted / rejected。

输出:

200,返回宽类型对象:更新后的知识状态(status / validationStatus / revision)。

调用示例:

curl -X PATCH "https://<your-endpoint>/v1/memory/memories/knowledge/knw_skill_01" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "expectedVersion": 4,
    "status": "user-active",
    "validationStatus": "verified"
  }'

响应示例:

{
  "knowledgeId": "knw_skill_01",
  "status": "user-active",
  "validationStatus": "verified",
  "revision": 5
}

DELETE /v1/memory/memories/knowledge/{knowledgeId}

SDK:Memory.forgetKnowledge · scope:memories.delete

为托管知识写入遗忘标记(逻辑遗忘,与记忆删除同语义)。

输入:

参数位置类型必填默认/枚举说明
knowledgeIdpathstring是知识 ID。
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
expectedVersionbodyinteger是期望的 CAS 版本号(必填)。
reasonbodystring否遗忘原因。
sourcebodystring否遗忘标记来源。

输出:

200,返回宽类型对象:遗忘登记结果(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/memory/memories/knowledge/knw_skill_01" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "expectedVersion": 5,
    "reason": "知识过时",
    "source": "ops-console"
  }'

响应示例:

{
  "status": "ok",
  "knowledgeId": "knw_skill_01",
  "forgotten": true
}

POST /v1/memory/memories/feedback

SDK:Memory.createKnowledgeFeedback · scope:memories.write

为一次召回的知识修订记录反馈(仅 Skill/Experience 可评,凭 injectionId 归因)。

输入:

参数位置类型必填默认/枚举说明
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
injectionIdbodystring是召回注入 ID(POST .../recall 响应返回)。
knowledgeIdbodystring是被评的 Skill/Experience 知识 ID;Memory 与画像条目不可评。
revisionbodyinteger是被评的知识修订号。
feedbackTypebodystring是枚举:positive / negative / not-relevantpositive / negative / not-relevant。
reasonCodebodystring否有界的原因代码(可选)。
idempotencyKeybodystring否幂等键(也可用 Idempotency-Key 头)。

输出:

201,返回宽类型对象:反馈登记结果(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/feedback" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "injectionId": "inj_2ab901",
    "knowledgeId": "knw_skill_01",
    "revision": 4,
    "feedbackType": "positive",
    "reasonCode": "helpful-briefing",
    "idempotencyKey": "idem-fb-01"
  }'

响应示例:

{
  "status": "ok",
  "injectionId": "inj_2ab901",
  "knowledgeId": "knw_skill_01",
  "revision": 4
}

POST /v1/memory/memories/observations

SDK:Memory.createKnowledgeObservation · scope:memories.write

为知识修订记录一次有界观察证据(工具执行结果等),供可信度推导。

输入:

参数位置类型必填默认/枚举说明
scopebodystring否枚举:user / agent / project知识归属 scope。
userIdbodystring否目标用户 ID。
agentIdbodystring否agent scope 定位键。
sessionIdbodystring否来源会话。
runIdbodystring否来源运行。
memorySubStoreIdbodystring否绑定子库。
knowledgeIdbodystring是知识 ID。
revisionbodyinteger是知识修订号。
sourceIdbodystring否证据源 ID。
injectionIdbodystring否召回注入 ID。
outcomebodystring是枚举:success / failure / not-applicable / security-violation观察结果:success / failure / not-applicable / security-violation。
verificationSourcebodystring否枚举:user / agent / tool-result已废弃:平台按认证来源推导可信来源。
toolNamebodystring否工具名。
toolVersionbodystring否工具版本。
toolSchemaVersionbodystring否工具 schema 版本。
errorFingerprintbodystring否有界的错误指纹。
evidencebodyobject是有界的观察证据对象(必填)。
weightbodyinteger否已废弃:平台按认证来源推导可信权重。
observedAtbodystring否观察时间戳。
idempotencyKeybodystring否幂等键(也可用 Idempotency-Key 头)。

输出:

201,返回宽类型对象:观察登记结果(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/observations" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user",
    "userId": "user-123",
    "agentId": "agent_support",
    "sessionId": "sess_8842",
    "runId": "run_20260914_01",
    "memorySubStoreId": "mss_default",
    "knowledgeId": "knw_skill_01",
    "revision": 4,
    "sourceId": "src_71f0c2",
    "injectionId": "inj_2ab901",
    "outcome": "success",
    "verificationSource": "user",
    "toolName": "briefing-generator",
    "toolVersion": "1.4.0",
    "toolSchemaVersion": "v2",
    "errorFingerprint": "",
    "evidence": {
      "runId": "run_20260914_01",
      "durationMs": 800
    },
    "weight": 0,
    "observedAt": "2026-09-14T08:00:00.000+00:00",
    "idempotencyKey": "idem-obs-01"
  }'

响应示例:

{
  "status": "ok",
  "knowledgeId": "knw_skill_01",
  "revision": 4,
  "outcome": "success"
}

用户画像(Profile)

GET /v1/memory/memories/users/{userId}/profile

SDK:Memory.getProfile · scope:memories.read

读取用户画像(正文或话题摘要)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是目标用户 ID。
profileTypequerystring否枚举:content / topics;默认 "content"画像类型:content(画像正文,默认)/ topics(话题摘要)。

输出:

200,返回宽类型对象:画像内容与元信息(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
userId / profileTypestring画像归属与类型。
contentstring画像正文(profileType=content)。
topicsobject[]话题摘要(profileType=topics)。
revisioninteger画像修订号。
updatedAtstring最近更新时间。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/users/user-123/profile?profileType=content" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "userId": "user-123",
  "profileType": "content",
  "content": "用户经营一家早餐店,习惯每天早上十一点查看经营简报,关注进货节奏与外卖评分。",
  "revision": 8,
  "updatedAt": "2026-09-14T08:00:00.000+00:00"
}

DELETE /v1/memory/memories/users/{userId}/profile

SDK:Memory.deleteProfile · scope:memories.delete

删除用户画像及其派生 provenance。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是目标用户 ID。
profileTypebodystring否枚举:content / topics要删除的画像类型:content / topics。
reasonbodystring否删除原因。
sourcebodystring否删除来源。

输出:

200,返回宽类型对象:删除登记结果(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/memory/memories/users/user-123/profile" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "profileType": "content",
    "reason": "用户行使删除权",
    "source": "ops-console"
  }'

响应示例:

{
  "status": "ok",
  "userId": "user-123",
  "profileType": "content"
}

POST /v1/memory/memories/users/{userId}/profile/extractions

SDK:Memory.createProfileExtraction · scope:memories.write

从证据做画像抽取:默认增量合并,mode=replace 整体替换。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是目标用户 ID。
profileTypebodystring否枚举:content / topics画像类型:content / topics。
messagesbodyobject[]否作为证据的 role/content 消息数组(与 sourceMemoryIds 二选一)。
sourceMemoryIdsbodystring[]否作为替换证据的既有记忆 ID 数组(与 messages 二选一)。
modebodystring否枚举:incremental / replaceincremental(默认)增量更新 / replace 整体替换。

输出:

200,返回宽类型对象:抽取任务登记(含任务/画像引用)(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/users/user-123/profile/extractions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "profileType": "content",
    "messages": [
      {
        "role": "user",
        "content": "我最近开始用外卖平台接单了"
      }
    ],
    "sourceMemoryIds": [],
    "mode": "incremental"
  }'

响应示例:

{
  "userId": "user-123",
  "profileType": "content",
  "mode": "incremental",
  "jobId": "job_70d3ef",
  "status": "queued"
}

POST /v1/memory/memories/users/{userId}/profile/rebuild

SDK:Memory.createProfileRebuild · scope:memories.write

基于全部可见证据全量重建用户画像。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是目标用户 ID。
profileTypebodystring否枚举:content / topics画像类型:content / topics。

输出:

200,返回宽类型对象:重建任务登记(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。全量重建消耗较大,仅在增量抽取不足时使用。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/users/user-123/profile/rebuild" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "profileType": "content"
  }'

响应示例:

{
  "userId": "user-123",
  "profileType": "content",
  "jobId": "job_80e4fa",
  "status": "queued"
}

GET /v1/memory/memories/users/{userId}/profile/sources

SDK:Memory.listProfileSources · scope:memories.read

列出画像的证据源。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是目标用户 ID。
profileTypequerystring否枚举:content / topics;默认 "content"画像类型:content / topics。

输出:

200,返回宽类型列表(类型 MemorySourceList),条目结构同记忆证据源。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/users/user-123/profile/sources?profileType=content" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "sources": [
    {
      "sourceId": "src_71f0c2",
      "sourceType": "conversation",
      "userId": "user-123",
      "messages": [
        {
          "role": "user",
          "content": "我习惯每天早上十一点查看早餐店经营简报"
        }
      ],
      "createdAt": "2026-09-01T08:00:00.000+00:00",
      "updatedAt": "2026-09-01T08:00:00.000+00:00"
    }
  ],
  "total": 1,
  "nextCursor": ""
}

导入与导出

POST /v1/memory/memories/imports

SDK:Memory.createImport · scope:memories.write

批量导入记忆:结构化数组或原始 JSON/JSONL 串,支持只校验不写入。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是目标用户 ID。
formatbodystring否枚举:json / jsonljson / jsonl;data 时的解析格式。
databodystring否原始 JSON 或 JSONL 导入串(与 records 二选一)。
recordsbodyobject[]否结构化记忆记录数组(与 data 二选一;字段同创建记忆输入)。
dryRunbodyboolean否为 true 时只校验不写入,返回校验结果。

输出:

200,返回宽类型对象(console SDK 类型 MemoryImportJobResponse):importId + status + job。轮询方式:GET .../imports/{importId} 至任务终态。

字段类型说明
importIdstring导入任务 ID。
statusstring导入状态。
job.statusstring底层任务状态:queued / running / succeeded / failed。
job.resultobject完成后的导入统计(成功/跳过/失败计数)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/imports" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "format": "json",
    "records": [
      {
        "userId": "user-123",
        "scope": "user",
        "memoryType": "long_term",
        "recordKind": "fact",
        "content": "用户对花生过敏",
        "infer": false
      }
    ],
    "dryRun": false
  }'

响应示例:

{
  "importId": "imp_88c3",
  "status": "queued",
  "job": {
    "jobId": "job_90f5ab",
    "status": "queued",
    "mode": "simple",
    "attemptCount": 0,
    "maxAttempts": 3,
    "retryable": false,
    "queueDurationMs": null,
    "executionDurationMs": null,
    "totalDurationMs": null,
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-01T08:00:00.000+00:00"
  }
}

GET /v1/memory/memories/imports/{importId}

SDK:Memory.getImport · scope:memories.read

查询导入任务状态与逐条结果。

输入:

参数位置类型必填默认/枚举说明
importIdpathstring是导入任务 ID。

输出:

200,返回宽类型对象(类型 MemoryImportJobResponse):importId + status + job(终态含统计与失败项)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/imports/imp_88c3" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "importId": "imp_88c3",
  "status": "succeeded",
  "job": {
    "jobId": "job_90f5ab",
    "status": "succeeded",
    "mode": "simple",
    "attemptCount": 1,
    "maxAttempts": 3,
    "retryable": false,
    "result": {
      "imported": 1,
      "skipped": 0,
      "failed": 0
    },
    "queueDurationMs": 80.0,
    "executionDurationMs": 600.0,
    "totalDurationMs": 680.0,
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-01T08:00:00.000+00:00",
    "startedAt": "2026-09-01T08:00:00.000+00:00",
    "completedAt": "2026-09-01T08:00:00.000+00:00"
  }
}

POST /v1/memory/memories/exports

SDK:Memory.createExport · scope:memories.export

创建记忆导出任务(mode=sync 直接返回或 async 轮询)。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是被导出记忆的用户。
formatbodystring否枚举:json / jsonljson / jsonl。
includeForgottenbodyboolean否包含已遗忘记录——需系统级授权。
includeVectorsbodyboolean否包含向量投影——需系统级授权。
includeRawSourcesbodyboolean否包含原始证据源——需系统级授权。
modebodystring否枚举:sync / asyncsync 同步返回 / async 创建任务后轮询。

输出:

200,返回宽类型对象:mode=async 时为导出任务引用(console SDK 类型 MemoryExportJobResponse 的 job 字段);mode=sync 直接携带导出数据。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/exports" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "format": "json",
    "includeForgotten": false,
    "includeVectors": false,
    "includeRawSources": false,
    "mode": "sync"
  }'

响应示例:

{
  "job": {
    "jobId": "job_a0b7cd",
    "status": "succeeded",
    "mode": "simple",
    "attemptCount": 1,
    "maxAttempts": 3,
    "retryable": false,
    "result": {
      "exportId": "exp_51d0",
      "format": "json",
      "records": 2
    },
    "queueDurationMs": 60.0,
    "executionDurationMs": 900.0,
    "totalDurationMs": 960.0,
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-01T08:00:00.000+00:00",
    "startedAt": "2026-09-01T08:00:00.000+00:00",
    "completedAt": "2026-09-01T08:00:00.000+00:00"
  }
}

GET /v1/memory/memories/exports/{exportId}

SDK:Memory.getExportJob · scope:memories.export

查询导出任务状态与产出位置。

输入:

参数位置类型必填默认/枚举说明
exportIdpathstring是导出任务 ID。

输出:

200,返回宽类型对象(类型 MemoryExportJobResponse):job 字段承载任务状态与结果引用。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/exports/exp_51d0" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "job": {
    "jobId": "job_a0b7cd",
    "status": "succeeded",
    "mode": "simple",
    "attemptCount": 1,
    "maxAttempts": 3,
    "retryable": false,
    "result": {
      "exportId": "exp_51d0",
      "format": "json",
      "records": 2
    },
    "queueDurationMs": 60.0,
    "executionDurationMs": 900.0,
    "totalDurationMs": 960.0,
    "createdAt": "2026-09-01T08:00:00.000+00:00",
    "updatedAt": "2026-09-01T08:00:00.000+00:00",
    "startedAt": "2026-09-01T08:00:00.000+00:00",
    "completedAt": "2026-09-01T08:00:00.000+00:00"
  }
}

GET /v1/memory/memories/export

SDK:Memory.getExport · scope:memories.export

同步导出一批记忆(mode 固定 sync,直接返回数据)。

输入:

参数位置类型必填默认/枚举说明
userIdquerystring是被导出记忆的用户(必填)。
formatquerystring否枚举:json / jsonl;默认 "jsonl"json(默认示例)/ jsonl,缺省 jsonl。
modequerystring否枚举:sync;默认 "sync"固定 sync。
includeForgottenqueryboolean否默认 false包含已遗忘记录——需系统级授权。
includeVectorsqueryboolean否默认 false包含向量投影——需系统级授权。
includeRawSourcesqueryboolean否默认 false包含原始证据源——需系统级授权。

输出:

200,返回导出数据本体(format=json 为 JSON 记录数组;jsonl 为逐行记录)(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/export?userId=user-123&format=json&mode=sync&includeForgotten=false&includeVectors=false&includeRawSources=false" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "records": [
    {
      "memoryId": "mem_7c1d94aa",
      "userId": "user-123",
      "scope": "user",
      "memoryType": "long_term",
      "recordKind": "fact",
      "content": "用户习惯每天早上十一点查看早餐店经营简报",
      "version": 3,
      "createdAt": "2026-09-01T08:00:00.000+00:00"
    },
    {
      "memoryId": "mem_7c1d94ac",
      "userId": "user-123",
      "scope": "user",
      "memoryType": "long_term",
      "recordKind": "fact",
      "content": "用户常在午市后复盘外卖平台评分",
      "version": 2,
      "createdAt": "2026-09-01T08:00:00.000+00:00"
    }
  ],
  "total": 2
}

投影与运维观测

POST /v1/memory/memories/projections/rebuild

SDK:Memory.createProjectionRebuild · scope:memories.write

按路由有界重建记忆投影(检索索引),多轮推进直至完成;仅允许可信运维调用。

输入:

参数位置类型必填默认/枚举说明
routesbodystring[]是枚举:dense / sparse / graph要重建的投影路由:dense / sparse / graph(必填)。
cursorbodystring否上一轮响应返回的游标。
limitbodyinteger否本轮最多调度的记忆条数。
dryRunbodyboolean否为 true 时只检查本轮影响范围,不改变投影状态。

输出:

200,返回宽类型对象:本轮重建结果与下轮游标(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。先 dryRun=true 确认影响范围,再按 nextCursor 循环推进直到为空。

字段类型说明
scheduledinteger本轮调度的记忆条数。
nextCursorstring下一轮游标;空表示全部完成。
dryRunboolean是否为演练轮。

调用示例:

curl -X POST "https://<your-endpoint>/v1/memory/memories/projections/rebuild" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "routes": [
      "dense",
      "sparse"
    ],
    "limit": 100,
    "dryRun": false
  }'

响应示例:

{
  "scheduled": 120,
  "nextCursor": "cur_proj_00a1",
  "dryRun": false
}

GET /v1/memory/memories/projections/verification

SDK:Memory.getProjectionVerification · scope:memories.read

读取项目级记忆投影恢复校验结果(重建后的一致性检查)。

输入:

参数位置类型必填默认/枚举说明

输出:

200,返回宽类型对象:各路由的校验状态(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
generatedAtstring校验报告生成时间。
routes[].routestring投影路由:dense / sparse / graph。
routes[].statusstring校验结论(如 verified)。
routes[].laginteger该路由滞后条数。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/projections/verification" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "generatedAt": "2026-09-14T08:00:00.000+00:00",
  "routes": [
    {
      "route": "dense",
      "status": "verified",
      "lag": 0
    },
    {
      "route": "sparse",
      "status": "verified",
      "lag": 0
    }
  ]
}

GET /v1/memory/memories/stats

SDK:Memory.getStats · scope:memories.read

读取当前调用者可见的记忆统计。

输入:

参数位置类型必填默认/枚举说明

输出:

200,返回宽类型对象:记忆计数与分布统计(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/stats" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "totalMemories": 128,
  "forgotten": 6,
  "byScope": {
    "user": 100,
    "agent": 20,
    "project": 8
  },
  "byMemoryType": {
    "working": 40,
    "short_term": 50,
    "long_term": 38
  },
  "byRecordKind": {
    "conversation": 60,
    "fact": 52,
    "action": 16
  }
}

GET /v1/memory/memories/quality

SDK:Memory.getQuality · scope:memories.read

读取记忆质量报告。

输入:

参数位置类型必填默认/枚举说明

输出:

200,返回宽类型对象:质量指标汇总(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/quality" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "score": 0.86,
  "dedupRate": 0.04,
  "extractionSuccessRate": 0.97,
  "forgottenLast7d": 3,
  "generatedAt": "2026-09-14T08:00:00.000+00:00"
}

GET /v1/memory/memories/timeline

SDK:Memory.getTimeline · scope:memories.read

读取记忆活动时间线。

输入:

参数位置类型必填默认/枚举说明

输出:

200,返回宽类型对象:按时间桶聚合的写入/遗忘活动(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/timeline" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "points": [
    {
      "date": "2026-09-13",
      "created": 12,
      "forgotten": 1
    },
    {
      "date": "2026-09-14",
      "created": 9,
      "forgotten": 0
    }
  ],
  "total": 2
}

GET /v1/memory/memories/sessions

SDK:Memory.getSessions · scope:memories.read

读取记忆会话聚合。

输入:

参数位置类型必填默认/枚举说明

输出:

200,返回宽类型对象:会话列表与计数(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。

字段类型说明
sessions[].sessionIdstring会话 ID。
sessions[].memoryCountinteger该会话关联的记忆条数。
sessions[].lastActiveAtstring会话最近活跃时间。
totalinteger会话总数。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/memories/sessions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "sessions": [
    {
      "sessionId": "sess_8842",
      "memoryCount": 14,
      "lastActiveAt": "2026-09-14T08:00:00.000+00:00"
    },
    {
      "sessionId": "sess_8843",
      "memoryCount": 5,
      "lastActiveAt": "2026-09-01T08:00:00.000+00:00"
    }
  ],
  "total": 2
}

GET /v1/memory/audits

SDK:Memory.listAudits · scope:memories.read

查询项目记忆请求审计(整数偏移分页)。

输入:

参数位置类型必填默认/枚举说明
jobIdquerystring否默认 ""精确匹配的记忆任务 ID。
queryquerystring否默认 ""按请求/资源/主体/操作标识搜索。
operationquerystring否默认 ""按记忆操作名过滤(如 memory.create)。
outcomequerystring否枚举:success / failure;默认 ""按请求结果过滤:success / failure。
limitqueryinteger否默认 25最大审计条数,默认 25。
cursorqueryinteger否默认 0整数偏移游标(区别于本域其他端点的不透明游标)。

输出:

200,返回宽类型对象:审计条目列表(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。本端点用整数 cursor 偏移分页,不适合深分页,建议配合 jobId/operation 缩小范围。

字段类型说明
audits[].jobIdstring关联任务 ID。
audits[].operationstring记忆操作名。
audits[].outcomestringsuccess / failure。
audits[].createdAtstring发生时间。

调用示例:

curl -X GET "https://<your-endpoint>/v1/memory/audits?jobId=job_3f8a12c9&operation=memory.create&outcome=success&limit=25&cursor=0" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "audits": [
    {
      "jobId": "job_3f8a12c9",
      "operation": "memory.create",
      "outcome": "success",
      "createdAt": "2026-09-01T08:00:00.000+00:00"
    },
    {
      "jobId": "job_50c2de",
      "operation": "memory.contextRun",
      "outcome": "success",
      "createdAt": "2026-09-14T08:00:00.000+00:00"
    }
  ],
  "total": 2,
  "cursor": 0
}

错误与边界

与 Server SDK 的对应

service.method端点
Memory.create / list / get / update / delete / deleteMany / createBatch/memory/memories 各读写端点
Memory.getJobGET /memory/jobs/{jobId}
Memory.search / recallKnowledgePOST /memory/memories/search、POST /memory/memories/recall
Memory.listSkills / searchSkills / getSkill / listSkillSources/memory/memories/skills*
Memory.listExperiences / searchExperiences / getExperience / listExperienceSources/memory/memories/experiences*
Memory.listContexts / getContext / createContextRun / getContextStatus / confirmContext / rebuildContext / rollbackContext/memory/memories/contexts*
Memory.listDistillations / submitDistillation / getDistillation / replayDistillation/memory/memories/distillations*
Memory.updateKnowledge / forgetKnowledge / createKnowledgeFeedback / createKnowledgeObservation/memory/memories/knowledge/{knowledgeId}、.../feedback、.../observations
Memory.getProfile / deleteProfile / createProfileExtraction / createProfileRebuild / listProfileSources/memory/memories/users/{userId}/profile*
Memory.createImport / getImport / createExport / getExportJob / getExport/memory/memories/imports*、exports*、export
Memory.listShares / createShare / deleteShare / listSources/memory/memories/{memoryId}/shares*、.../sources
Memory.createProjectionRebuild / getProjectionVerification / getStats / getQuality / getTimeline / getSessions / listAudits/memory/memories/projections/*、stats、quality、timeline、sessions、/memory/audits

事实源