记忆 API
Agent 记忆的完整数据面:记忆写入(直接或模型辅助抽取)、检索与召回、知识治理(上下文/蒸馏/反馈/观察)、技能与经验库、用户画像、导入导出、共享与运维观测。记忆串行写入、失败按有界策略重试:模型辅助抽取默认异步排队,重试去重用 Idempotency-Key。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1,路径前缀/memory。 - 核心资源:
memory(记忆记录,{memoryId});治理面统一使用knowledgeId(记忆/上下文/技能/经验的稳定 ID,路径段不同语义不同:/memories/knowledge/{knowledgeId}、/memories/skills/{knowledgeId}、/memories/experiences/{knowledgeId}、/memories/contexts/{contextId})。 - 分页:本域使用不透明游标
cursor+limit(非 Query 数组);审计接口用cursor(整数偏移)。
认证与权限
认证与请求头约定见 通用约定。本域 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/status | Dreaming 状态 | |
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 | 同步导出 | |
| `GET | POST /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 | 请求审计 |
请求与响应
以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:
- 认证:所有请求携带
X-Appwrite-Project: <YOUR_PROJECT_ID>与X-Appwrite-Key: <YOUR_API_KEY>;各端点 scope 见小节标注(memories.read/memories.write/memories.delete/memories.share/memories.export)。 - 分页:本域使用不透明游标
cursor+limit(响应nextCursor为空串即末页);例外:GET /memory/audits使用整数偏移cursor。 - 异步与重试:
infer=true的写入默认异步入队(用GET /memory/jobs/{jobId}轮询);串行写入、失败按有界次数重试;Idempotency-Key头或idempotencyKey参数用于重试去重。 - 可见性:列表/检索默认
accessMode=owned(仅本人),accessible返回授权可见并集;strict_private不进入并集。 - 响应 schema 说明:Server spec 将本域多数响应定义为宽类型(
any),字段语义以 console SDK 类型与端点描述为准;下文示意骨架中的动态对象(如统计、审计条目)以实际部署返回为准。
示例上下文:示例沿用早餐店经营场景——用户 user-123 与代理 agent_support 的日常经营记忆。
记忆写入与基础 CRUD
POST /v1/memory/memories
SDK:Memory.create · scope:memories.write
创建一条记忆:直接写入,或 infer=true 时交给模型做事实抽取、派生与跨类型去重。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
content | body | string | 否 | 兼容纯文本内容;未传 messages 时必填。 | |
messages | body | object[] | 否 | 类型化 role/content 消息数组,作为证据源保留;与 content 同时传入时 messages 是事实抽取的权威输入(仅 user 角色参与抽取)。 | |
userId | body | string | 是 | 目标用户 ID。 | |
agentId | body | string | 否 | 归属代理 ID(可选);会话上下文历史只匹配相同 agentId(含空值)。 | |
runId | body | string | 否 | 归属运行 ID(可选);不作为 sessionId 的回退值。 | |
sessionId | body | string | 否 | 最长 128 字符 | 会话 ID(2.7.0 新增,appbase PR 542/552/553):所有合法 scope 都可接受的来源归因字段;仅当 infer=true 且 scope 为 user / group / project 时加载同会话有界历史,private / strict_private 永不做历史补水。语义细则见本端点响应示例后的说明。 |
scope | body | string | 是 | 枚举:private / strict_private / user / group / project | 可见性 scope;strict_private 不参与授权可见并集(仅所有者可见)。 |
sensitivity | body | string | 否 | 枚举:normal / confidential / restricted / secret | 内容分级;secret 内容会被拒绝入库——敏感值必须走 Secret/变量。 |
handlingPolicy | body | string | 否 | 枚举:standard / no_embedding / no_model | 处理限制:no_embedding 不做向量化、no_model 不做任何模型处理(要求 infer=false)。 |
memoryType | body | string | 是 | 记忆类型;infer=true 时对话原文保留为证据、派生记录归类 long_term。 | |
recordKind | body | string | 是 | 枚举:conversation / fact / action | 记录类型:conversation(对话)/ fact(事实)/ action(动作);infer=true 时对话输入派生 fact。 |
metadata | body | object | 否 | 自由元数据对象。 | |
infer | body | boolean | 否 | 启用模型辅助抽取与跨类型去重,默认 true;会结合检索候选执行 ADD/UPDATE/DELETE/NOOP 推理。 | |
reRemember | body | boolean | 否 | 为已遗忘内容显式重建证据。 | |
async | body | boolean | 否 | 入队异步处理并立即返回;缺省随 infer(即默认异步入队)。 |
输出:
200,返回宽类型写入结果(console SDK 类型 MemoryWriteResponse):同步成功含 memory 记录;异步入队返回任务引用,用 GET /memory/jobs/{jobId} 轮询。串行写入、失败有界重试;Idempotency-Key 头或 idempotencyKey 参数用于重试去重。
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | 写入结果状态(如 ok)。 |
mode | string | 处理路径:simple 直写 / inferred 模型抽取。 |
sourceId | string | 证据源 ID,用于 provenance 追溯与 dedup 判断。 |
jobId | string | 异步任务 ID;async=true 或 infer=true 时返回。 |
memory | object | 同步落库时的记忆记录(含 memoryId、version)。 |
actions | object[] | infer=true 时模型执行的推理动作列表。 |
retryable | boolean | 失败时是否可重试。 |
调用示例:
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
列出当前调用者可见的记忆记录(不透明游标分页)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
cursor | query | string | 否 | 默认 "" | 上页响应 nextCursor 返回的游标。 |
limit | query | integer | 否 | 单页最大记忆条数。 | |
filter | query | object | 否 | 默认 {} | 结构化记忆过滤对象。 |
queries | query | string[] | 否 | 默认 [] | Appbase Query 风格查询串数组。 |
userId | query | string | 否 | 默认 "" | 按目标用户过滤。 |
accessMode | query | string | 否 | 枚举:owned / accessible;默认 "owned" | owned 仅本人(兼容默认)/ accessible 授权可见并集。 |
输出:
200,返回宽类型列表 MemoryList:memories[](memoryId、userId、content、version、scope、memoryType、recordKind、createdAt 等)+ total + nextCursor(为空串表示没有下一页)。
| 字段 | 类型 | 说明 |
|---|---|---|
memories | object[] | 记忆记录数组。 |
total | integer | 可见记忆总数。 |
nextCursor | string | 下页游标;空串表示已到末页。 |
调用示例:
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 获取单条记忆。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | 目标记忆 ID。 |
输出:
200,返回宽类型对象 MemoryResponse:memory 字段承载记忆记录(memoryId、userId、scope、memoryType、recordKind、content、version 等)。
| 字段 | 类型 | 说明 |
|---|---|---|
memory | object | 记忆记录本体;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 乐观锁。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | 目标记忆 ID。 | |
version | body | integer | 是 | 期望的当前版本号;与服务端不一致返回并发冲突——读取最新版本后再重试,不要盲目覆盖。 | |
content | body | string | 否 | 更新后的记忆文本。 | |
metadata | body | object | 否 | 元数据合并补丁(与现有 metadata 深合并)。 | |
retentionPolicy | body | string | 否 | 枚举: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
删除(遗忘)单条记忆:逻辑删除并进入后续物理压缩流程。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | 目标记忆 ID。 | |
reason | body | string | 否 | 遗忘原因(审计用)。 | |
source | body | string | 否 | 遗忘来源(审计用)。 |
输出:
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 时循环调用直到清完。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 否 | 目标用户 ID。 | |
limit | body | integer | 否 | 本轮处理上限,1–500;服务端可能处理更少,须以 hasMore 判断是否继续。 | |
reason | body | string | 否 | 遗忘原因。 | |
source | body | string | 否 | 遗忘来源。 |
输出:
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* | string | Memory record ID processed in this pass. |
status* | string | Per-record deletion outcome. |
errorCode | string | Machine-readable error code when deletion failed. |
retryable | boolean | Whether the failed record can be retried. |
error | string | Human-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 操作。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
items | body | object[] | 是 | 有界的操作数组;每项按 operation 携带对应负载(create/delete/search 三选一)。 | |
items.operation | body | string | 是 | 枚举:create / delete / search | 该操作类型:create / delete / search。 |
items.create | body | object | 否 | 创建负载,字段同 POST /memory/memories 请求体。 | |
items.delete | body | object | 否 | 删除负载,字段同 DELETE /memory/memories 请求体(userId/limit/reason/source)。 | |
items.search | body | object | 否 | 检索负载,字段同 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
查询异步记忆写入任务的执行状态与结果。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
jobId | path | string | 是 | 写入任务 ID(创建记忆异步响应中返回)。 |
输出:
200,返回宽类型对象(console SDK 类型 MemoryWriteJob)。轮询方式:每 1–2 秒调用本端点,status 到 succeeded/failed 即止;failed 且 retryable=true 时修复后重发(带同一 Idempotency-Key 去重)。
| 字段 | 类型 | 说明 |
|---|---|---|
jobId | string | 任务 ID。 |
status | string | queued / running / succeeded / failed。 |
mode | string | simple 直写 / inferred 模型抽取。 |
sourceId | string | 证据源 ID。 |
attemptCount / maxAttempts | integer | 已重试次数 / 最大重试次数(有界)。 |
errorCode / reason | string | 失败码与原因。 |
retryable | boolean | 失败后是否可重试。 |
result | object | 成功时的写入结果(同创建响应)。 |
queueDurationMs / executionDurationMs / totalDurationMs | number | 排队/执行/总耗时(毫秒)。 |
createdAt / startedAt / completedAt | string | 创建/开始/完成时间。 |
调用示例:
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)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | 目标记忆 ID。 | |
cursor | query | string | 否 | 默认 "" | 上页 nextCursor 游标。 |
limit | query | integer | 否 | 默认 25 | 单页最大条数,默认 25。 |
输出:
200,返回宽类型列表(console SDK 类型 MemorySourceList):sources[] 为不可变证据源记录 + total + nextCursor。
| 字段 | 类型 | 说明 |
|---|---|---|
sources[].sourceId | string | 证据源 ID(创建响应中的 sourceId)。 |
sources[].sourceType | string | 证据类型(如 conversation)。 |
sources[].messages / content | object / string | 原始证据内容。 |
sources[].configVersion / promptVersion | integer / string | 抽取时的配置/提示词版本。 |
total / nextCursor | integer / 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
列出一条记忆的全部生效读授权。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | 目标记忆 ID。 |
输出:
200,返回宽类型对象:该记忆的授权列表(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
shares[].shareId | string | 共享授权稳定 ID(撤销时用作 {shareId})。 |
shares[].subjectType | string | user / group。 |
shares[].subjectId | string | 被授权用户或群组 ID。 |
shares[].expiresAt | string | 过期时间(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
为用户或群组授予单条记忆的读权限。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | 目标记忆 ID。 | |
subjectType | body | string | 是 | 枚举:user / group | 被授权主体类型:user / group。 |
subjectId | body | string | 是 | 被授权主体 ID。 | |
expiresAt | body | string | 否 | 过期时间(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
撤销一条记忆读授权。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | 目标记忆 ID。 | |
shareId | path | string | 是 | 要撤销的共享授权 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 配置融合。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | 检索查询文本(必填)。 | |
searchMode | body | string | 否 | 召回模式覆盖(路由级)。 | |
retrieval | body | object | 否 | 召回路由覆盖对象;sparse=false 跳过模型生成的稀疏召回,缺省用项目设置。 | |
userId | body | string | 否 | 按用户过滤。 | |
agentId | body | string | 否 | 按代理过滤。 | |
runId | body | string | 否 | 按运行过滤。 | |
scope | body | string | 否 | 按 scope 过滤。 | |
memoryType | body | string | 否 | 按记忆类型过滤。 | |
recordKind | body | string | 否 | 按记录类型过滤。 | |
filter | body | object | 否 | 结构化记忆过滤对象。 | |
limit | body | integer | 否 | 最大返回条数;0 表示用项目默认。 | |
cursor | body | string | 否 | 上页 nextCursor 游标。 | |
sort | body | string | 否 | 排序模式。 | |
memorySubStoreId | body | string | 否 | 绑定子库精确路由。 | |
sessionId | body | string | 否 | 按会话过滤。 | |
groupId | body | string | 否 | 群组/实体边界过滤。 | |
accessMode | body | string | 否 | 枚举:owned / accessible | owned 仅本人 / accessible 授权可见并集。 |
输出:
200,返回宽类型检索结果(console SDK 类型 MemorySearchResult):items[] 命中记录 + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
items[].memoryId | string | 命中记忆 ID。 |
items[].content | string | 命中内容摘要。 |
items[].score | number | 相关度得分(融合后)。 |
items[].memoryType / recordKind / scope | string | 命中的类型与归属。 |
total / nextCursor | integer / 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 归因。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库精确路由。 | |
query | body | string | 是 | 召回查询文本(必填)。 | |
kinds | body | string[] | 否 | 枚举:memory / profile / skill / experience | 要召回的知识种类:memory / profile / skill / experience。 |
limit | body | integer | 否 | 最大召回条数。 | |
tokenBudget | body | integer | 否 | 上下文 token 预算上限。 | |
retrieval | body | object | 否 | 召回路由覆盖。 | |
accessMode | body | string | 否 | 枚举:owned / accessible | owned 仅本人 / accessible 授权可见并集。 |
输出:
200,返回宽类型注入结果:injectionId(feedback 归因凭据)+ 按预算裁剪的 items[](响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
injectionId | string | 本次注入 ID;POST .../feedback 以此归因。 |
items[].knowledgeId | string | 命中知识 ID(记忆/技能/经验)。 |
items[].kind | string | memory / profile / skill / experience。 |
items[].content | string | 注入用正文。 |
items[].score | number | 相关度得分。 |
total | integer | 命中总数。 |
调用示例:
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)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope,默认 user。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话过滤。 |
runId | query | string | 否 | 默认 "" | 来源运行过滤。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
cursor | query | string | 否 | 默认 "" | 上页游标。 |
limit | query | integer | 否 | 单页最大条数。 |
输出:
200,返回宽类型列表:skills[] + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
skills[].knowledgeId | string | 技能稳定 ID(详情/来源/feedback 用)。 |
skills[].title / content | string | 技能标题与正文。 |
skills[].status | string | 治理状态(如 user-active)。 |
skills[].revision | integer | 当前修订号。 |
total / nextCursor | integer / 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
按语义检索活跃验证的技能。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
query | body | string | 是 | 语义检索查询(必填)。 | |
cursor | body | string | 否 | 上页游标。 | |
limit | body | integer | 否 | 单页最大条数。 | |
retrieval | body | object | 否 | 召回路由覆盖。 |
输出:
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 获取单个技能详情。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
knowledgeId | path | string | 是 | 技能知识 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
列出技能关联的不可变证据源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
knowledgeId | path | string | 是 | 技能知识 ID。 | |
cursor | query | string | 否 | 默认 "" | 上页游标。 |
limit | query | integer | 否 | 默认 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)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope,默认 user。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
cursor | query | string | 否 | 默认 "" | 上页游标。 |
limit | query | integer | 否 | 单页最大条数。 |
输出:
200,返回宽类型列表:experiences[] + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
experiences[].knowledgeId | string | 经验稳定 ID。 |
experiences[].title / content | string | 经验标题与正文。 |
experiences[].status / revision | string / integer | 治理状态与修订号。 |
total / nextCursor | integer / 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
按语义检索活跃验证的经验。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
query | body | string | 是 | 语义检索查询(必填)。 | |
cursor | body | string | 否 | 上页游标。 | |
limit | body | integer | 否 | 单页最大条数。 | |
retrieval | body | object | 否 | 召回路由覆盖。 |
输出:
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 获取单个经验详情。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
knowledgeId | path | string | 是 | 经验知识 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
列出经验关联的不可变证据源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
knowledgeId | path | string | 是 | 经验知识 ID。 | |
cursor | query | string | 否 | 默认 "" | 上页游标。 |
limit | query | integer | 否 | 默认 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 生命周期)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope,默认 user。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
status | query | string | 否 | 枚举:shadow / quarantine / stale / user-active / agent-active / deprecated;默认 "" | 按生命周期状态过滤:shadow / quarantine / stale / user-active / agent-active / deprecated。 |
kind | query | string | 否 | 枚举:memory_topic / memory_episode / memory_state / memory_overview;默认 "" | 按层级过滤:memory_topic / memory_episode / memory_state / memory_overview。 |
cursor | query | string | 否 | 默认 "" | 上页游标。 |
limit | query | integer | 否 | 单页最大条数。 |
输出:
200,返回宽类型列表:contexts[] + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
contexts[].contextId | string | 上下文稳定 ID(confirm/rebuild/rollback 用)。 |
contexts[].kind | string | 层级:memory_topic / memory_episode / memory_state / memory_overview。 |
contexts[].status | string | 生命周期:shadow → user-active/agent-active,中间态 quarantine/stale,终态 deprecated。 |
contexts[].revision | integer | 当前修订号。 |
total / nextCursor | integer / 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 获取单个治理上下文聚合。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
contextId | path | string | 是 | 上下文知识 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 异步)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 |
输出:
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)与任务状态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope,默认 user。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
输出:
200,返回宽类型对象:Dreaming 运行态与水位(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
running | boolean | 是否有 Dreaming 运行进行中。 |
lastRunAt | string | 最近一次运行完成时间。 |
lastJobId | string | 最近一次运行的任务 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 并发控制)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
contextId | path | string | 是 | 上下文知识 ID。 | |
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
expectedVersion | body | integer | 是 | 期望的 CAS 版本号;不匹配返回并发冲突。 | |
reason | body | string | 是 | 有界的治理原因说明(必填,进审计)。 |
输出:
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 异步)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
contextId | path | string | 是 | 上下文知识 ID。 | |
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
reason | body | string | 是 | 有界的重建原因(必填)。 |
输出:
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
把活跃上下文回滚到更早的已验证修订。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
contextId | path | string | 是 | 上下文知识 ID。 | |
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
expectedVersion | body | integer | 是 | 期望的 CAS 版本号。 | |
targetRevision | body | integer | 是 | 要回滚到的更早已验证修订号。 | |
reason | body | string | 是 | 有界的治理原因(必填)。 |
输出:
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
列出蒸馏任务(可按状态过滤)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope,默认 user。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
status | query | string | 否 | 枚举:(空,表示不限) / queued / running / succeeded / partial_failed / failed / dead;默认 "" | 按任务状态过滤:queued / running / succeeded / partial_failed / failed / dead。 |
cursor | query | string | 否 | 默认 "" | 上页游标。 |
limit | query | integer | 否 | 单页最大条数。 |
输出:
200,返回宽类型列表:distillations[] + total + nextCursor(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
distillations[].distillationId | string | 蒸馏任务 ID。 |
distillations[].status | string | queued / running / succeeded / partial_failed / failed / dead。 |
distillations[].jobId | string | 底层异步任务 ID。 |
total / nextCursor | integer / 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 立即返回。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
sourceId | body | string | 否 | 已持久化证据源 ID;与 sourceType 搭配,替代内联 messages/toolEvents。 | |
sourceType | body | string | 否 | 枚举:(空,表示不限) / conversation / tool-trace / execution-log | 证据源类型:conversation / tool-trace / execution-log。 |
messages | body | object[] | 否 | 有界的对话消息数组(与 toolEvents 二选一)。 | |
messages.role | body | string | 是 | 枚举:system / user / assistant / tool | 消息角色:system / user / assistant / tool。 |
messages.content | body | string | 是 | 消息正文。 | |
messages.name | body | string | 否 | 工具消息的工具名(role=tool 时使用)。 | |
toolEvents | body | object[] | 否 | 有界的工具执行事件数组(与 messages 二选一)。 | |
toolEvents.eventId | body | string | 是 | 工具事件 ID。 | |
toolEvents.name | body | string | 是 | 工具名。 | |
toolEvents.arguments | body | any | 否 | 工具调用参数(任意 JSON)。 | |
toolEvents.result | body | any | 否 | 工具执行结果(status=succeeded 必填)。 | |
toolEvents.status | body | string | 是 | 枚举:succeeded / failed | 执行结果:succeeded / failed;failed 时 error 必填。 |
toolEvents.error | body | string | 否 | 失败信息(status=failed 必填)。 | |
mode | body | string | 否 | 枚举:async / wait | async 立即返回;wait 最长等待 20 秒取终态,超时返回运行中状态而非错误(改用轮询)。 |
idempotencyKey | body | string | 否 | 幂等键(也可用 Idempotency-Key 头)。 |
输出:
202,返回宽类型对象:蒸馏任务登记(distillationId + status)。轮询方式:GET .../distillations/{distillationId} 至终态;dead 状态只能 replay 到新任务。
| 字段 | 类型 | 说明 |
|---|---|---|
distillationId | string | 蒸馏任务 ID。 |
status | string | queued / 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
查询蒸馏任务状态与产出引用。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 枚举:user / agent / project;默认 "user" | 知识归属 scope。 |
userId | query | string | 否 | 默认 "" | 目标用户 ID。 |
agentId | query | string | 否 | 默认 "" | agent scope 定位键。 |
sessionId | query | string | 否 | 默认 "" | 来源会话。 |
runId | query | string | 否 | 默认 "" | 来源运行。 |
memorySubStoreId | query | string | 否 | 默认 "" | 绑定子库。 |
distillationId | path | string | 是 | 蒸馏任务 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
对失败或部分失败的蒸馏任务重放(生成新任务,不改动原任务)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
distillationId | path | string | 是 | 要重放的蒸馏任务 ID。 | |
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 |
输出:
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 并发控制)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeId | path | string | 是 | 知识 ID。 | |
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
expectedVersion | body | integer | 是 | 期望的 CAS 版本号(必填);不匹配返回并发冲突。 | |
status | body | string | 否 | 枚举:candidate / shadow / user-active / agent-active / quarantine / deprecated | 目标治理状态:candidate / shadow / user-active / agent-active / quarantine / deprecated。 |
validationStatus | body | string | 否 | 枚举: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
为托管知识写入遗忘标记(逻辑遗忘,与记忆删除同语义)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeId | path | string | 是 | 知识 ID。 | |
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
expectedVersion | body | integer | 是 | 期望的 CAS 版本号(必填)。 | |
reason | body | string | 否 | 遗忘原因。 | |
source | body | string | 否 | 遗忘标记来源。 |
输出:
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 归因)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
injectionId | body | string | 是 | 召回注入 ID(POST .../recall 响应返回)。 | |
knowledgeId | body | string | 是 | 被评的 Skill/Experience 知识 ID;Memory 与画像条目不可评。 | |
revision | body | integer | 是 | 被评的知识修订号。 | |
feedbackType | body | string | 是 | 枚举:positive / negative / not-relevant | positive / negative / not-relevant。 |
reasonCode | body | string | 否 | 有界的原因代码(可选)。 | |
idempotencyKey | body | string | 否 | 幂等键(也可用 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
为知识修订记录一次有界观察证据(工具执行结果等),供可信度推导。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scope | body | string | 否 | 枚举:user / agent / project | 知识归属 scope。 |
userId | body | string | 否 | 目标用户 ID。 | |
agentId | body | string | 否 | agent scope 定位键。 | |
sessionId | body | string | 否 | 来源会话。 | |
runId | body | string | 否 | 来源运行。 | |
memorySubStoreId | body | string | 否 | 绑定子库。 | |
knowledgeId | body | string | 是 | 知识 ID。 | |
revision | body | integer | 是 | 知识修订号。 | |
sourceId | body | string | 否 | 证据源 ID。 | |
injectionId | body | string | 否 | 召回注入 ID。 | |
outcome | body | string | 是 | 枚举:success / failure / not-applicable / security-violation | 观察结果:success / failure / not-applicable / security-violation。 |
verificationSource | body | string | 否 | 枚举:user / agent / tool-result | 已废弃:平台按认证来源推导可信来源。 |
toolName | body | string | 否 | 工具名。 | |
toolVersion | body | string | 否 | 工具版本。 | |
toolSchemaVersion | body | string | 否 | 工具 schema 版本。 | |
errorFingerprint | body | string | 否 | 有界的错误指纹。 | |
evidence | body | object | 是 | 有界的观察证据对象(必填)。 | |
weight | body | integer | 否 | 已废弃:平台按认证来源推导可信权重。 | |
observedAt | body | string | 否 | 观察时间戳。 | |
idempotencyKey | body | string | 否 | 幂等键(也可用 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
读取用户画像(正文或话题摘要)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 目标用户 ID。 | |
profileType | query | string | 否 | 枚举:content / topics;默认 "content" | 画像类型:content(画像正文,默认)/ topics(话题摘要)。 |
输出:
200,返回宽类型对象:画像内容与元信息(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
userId / profileType | string | 画像归属与类型。 |
content | string | 画像正文(profileType=content)。 |
topics | object[] | 话题摘要(profileType=topics)。 |
revision | integer | 画像修订号。 |
updatedAt | string | 最近更新时间。 |
调用示例:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 目标用户 ID。 | |
profileType | body | string | 否 | 枚举:content / topics | 要删除的画像类型:content / topics。 |
reason | body | string | 否 | 删除原因。 | |
source | body | string | 否 | 删除来源。 |
输出:
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 整体替换。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 目标用户 ID。 | |
profileType | body | string | 否 | 枚举:content / topics | 画像类型:content / topics。 |
messages | body | object[] | 否 | 作为证据的 role/content 消息数组(与 sourceMemoryIds 二选一)。 | |
sourceMemoryIds | body | string[] | 否 | 作为替换证据的既有记忆 ID 数组(与 messages 二选一)。 | |
mode | body | string | 否 | 枚举:incremental / replace | incremental(默认)增量更新 / 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
基于全部可见证据全量重建用户画像。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 目标用户 ID。 | |
profileType | body | string | 否 | 枚举: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
列出画像的证据源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 目标用户 ID。 | |
profileType | query | string | 否 | 枚举: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 串,支持只校验不写入。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 目标用户 ID。 | |
format | body | string | 否 | 枚举:json / jsonl | json / jsonl;data 时的解析格式。 |
data | body | string | 否 | 原始 JSON 或 JSONL 导入串(与 records 二选一)。 | |
records | body | object[] | 否 | 结构化记忆记录数组(与 data 二选一;字段同创建记忆输入)。 | |
dryRun | body | boolean | 否 | 为 true 时只校验不写入,返回校验结果。 |
输出:
200,返回宽类型对象(console SDK 类型 MemoryImportJobResponse):importId + status + job。轮询方式:GET .../imports/{importId} 至任务终态。
| 字段 | 类型 | 说明 |
|---|---|---|
importId | string | 导入任务 ID。 |
status | string | 导入状态。 |
job.status | string | 底层任务状态:queued / running / succeeded / failed。 |
job.result | object | 完成后的导入统计(成功/跳过/失败计数)。 |
调用示例:
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
查询导入任务状态与逐条结果。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
importId | path | string | 是 | 导入任务 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 轮询)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 被导出记忆的用户。 | |
format | body | string | 否 | 枚举:json / jsonl | json / jsonl。 |
includeForgotten | body | boolean | 否 | 包含已遗忘记录——需系统级授权。 | |
includeVectors | body | boolean | 否 | 包含向量投影——需系统级授权。 | |
includeRawSources | body | boolean | 否 | 包含原始证据源——需系统级授权。 | |
mode | body | string | 否 | 枚举:sync / async | sync 同步返回 / 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
查询导出任务状态与产出位置。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
exportId | path | string | 是 | 导出任务 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,直接返回数据)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | query | string | 是 | 被导出记忆的用户(必填)。 | |
format | query | string | 否 | 枚举:json / jsonl;默认 "jsonl" | json(默认示例)/ jsonl,缺省 jsonl。 |
mode | query | string | 否 | 枚举:sync;默认 "sync" | 固定 sync。 |
includeForgotten | query | boolean | 否 | 默认 false | 包含已遗忘记录——需系统级授权。 |
includeVectors | query | boolean | 否 | 默认 false | 包含向量投影——需系统级授权。 |
includeRawSources | query | boolean | 否 | 默认 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
按路由有界重建记忆投影(检索索引),多轮推进直至完成;仅允许可信运维调用。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
routes | body | string[] | 是 | 枚举:dense / sparse / graph | 要重建的投影路由:dense / sparse / graph(必填)。 |
cursor | body | string | 否 | 上一轮响应返回的游标。 | |
limit | body | integer | 否 | 本轮最多调度的记忆条数。 | |
dryRun | body | boolean | 否 | 为 true 时只检查本轮影响范围,不改变投影状态。 |
输出:
200,返回宽类型对象:本轮重建结果与下轮游标(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。先 dryRun=true 确认影响范围,再按 nextCursor 循环推进直到为空。
| 字段 | 类型 | 说明 |
|---|---|---|
scheduled | integer | 本轮调度的记忆条数。 |
nextCursor | string | 下一轮游标;空表示全部完成。 |
dryRun | boolean | 是否为演练轮。 |
调用示例:
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;以下为关键字段示意骨架,以实际返回为准)。
| 字段 | 类型 | 说明 |
|---|---|---|
generatedAt | string | 校验报告生成时间。 |
routes[].route | string | 投影路由:dense / sparse / graph。 |
routes[].status | string | 校验结论(如 verified)。 |
routes[].lag | integer | 该路由滞后条数。 |
调用示例:
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[].sessionId | string | 会话 ID。 |
sessions[].memoryCount | integer | 该会话关联的记忆条数。 |
sessions[].lastActiveAt | string | 会话最近活跃时间。 |
total | integer | 会话总数。 |
调用示例:
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
查询项目记忆请求审计(整数偏移分页)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
jobId | query | string | 否 | 默认 "" | 精确匹配的记忆任务 ID。 |
query | query | string | 否 | 默认 "" | 按请求/资源/主体/操作标识搜索。 |
operation | query | string | 否 | 默认 "" | 按记忆操作名过滤(如 memory.create)。 |
outcome | query | string | 否 | 枚举:success / failure;默认 "" | 按请求结果过滤:success / failure。 |
limit | query | integer | 否 | 默认 25 | 最大审计条数,默认 25。 |
cursor | query | integer | 否 | 默认 0 | 整数偏移游标(区别于本域其他端点的不透明游标)。 |
输出:
200,返回宽类型对象:审计条目列表(响应为宽类型 JSON 对象,spec 未固定 schema;以下为关键字段示意骨架,以实际返回为准)。本端点用整数 cursor 偏移分页,不适合深分页,建议配合 jobId/operation 缩小范围。
| 字段 | 类型 | 说明 |
|---|---|---|
audits[].jobId | string | 关联任务 ID。 |
audits[].operation | string | 记忆操作名。 |
audits[].outcome | string | success / failure。 |
audits[].createdAt | string | 发生时间。 |
调用示例:
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
}错误与边界
- 记忆不存在:
404+memory_not_found;任务不存在:404+job_not_found。 - CAS 冲突:
version/expectedVersion不匹配返回并发冲突错误——读取最新版本后重试;不要盲目覆盖。 - 可见性边界:
strict_private不参与授权可见并集(仅所有者);sensitivity=secret的内容会被拒绝入库(提示改用 Secret/变量)。 - 批量遗忘单次上限 500 条,超过时以
hasMore分次执行;遗忘是标记语义,导出默认不含,includeForgotten需系统授权。 - 模型辅助路径(
infer=true)为异步:创建响应可能是任务引用;handlingPolicy=no_model与infer=true组合返回参数错误。 - 蒸馏
mode=wait超时返回运行中状态而非错误,改用轮询;dead状态任务只能 replay 到新任务。 - feedback 仅接受 Skill/Experience 的
knowledgeId;Memory/画像条目不可评。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Memory.create / list / get / update / delete / deleteMany / createBatch | /memory/memories 各读写端点 |
Memory.getJob | GET /memory/jobs/{jobId} |
Memory.search / recallKnowledge | POST /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 |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(/memory域 54 个端点与参数枚举);v2.7.2 spec 新增POST /memory/memories的sessionId参数(v2.6.0 → v2.7.2 diff 实读确认,为 memory 段唯一参数变化)。 - 2.7.0 行为增量:appbase release-2.7.0 PR 542/552/553(bounded session context inference;
docs/features/memory/api-guide.md实读)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0Memoryservice。 - 语义深度参考:
skills/ob-agentbase/references/memory.md。