记忆 API
本页以 Agentbase 2.12.0 的项目级 Memory 服务接口为基准。第一次接入建议先完成项目与 SDK 准备,再运行完整 SDK 操作示例。
服务与资源边界
项目级记忆系统(Memory)运行于 OceanBase Shared V2 存储架构之上,面向智能客服与企业智能体提供长期事实记忆、对话推理抽取、用户画像(Profile)、上下文做梦整合(Context Dreaming)与经验/技能蒸馏(Experience & Skill Distillation)全生命周期 HTTP 接口。项目启停与 Pipeline 编排属管理面,业务读写、召回、共享、导入导出与请求审计通过本页说明的项目级 API 执行。
资源与基础路径
API 基址为当前项目提供的 https://<agentbase-host>/v1。下文路径已包含 /v1,拼接时不要重复。项目须已启用 Memory 且状态 active、数据 ready;启用与配置在 Console 完成。仅支持 Shared V2 项目,不需要创建 Memory Resource 或填写 Space ID。
所有资源标识按字符串处理。记忆使用 memoryId,技能/经验使用 knowledgeId,写入任务使用 jobId,蒸馏查询使用 distillationId;它们不能互换。
已登记 Shared V2 资源池的物理库名可以包含连字符;这一兼容能力由服务端部署提供。调用方继续使用项目 ID 与既有凭据,无需传物理库名、连接池别名或内部签名上下文。初始化或路由失败时,请管理员核对服务版本与资源池登记;不要通过修改请求字段绕过项目隔离。
认证与权限
每个业务请求携带 X-Appwrite-Project 与 X-Appwrite-Key;有 JSON 正文时使用 Content-Type: application/json。API Key 仅在可信服务端保存。通用约定见认证与访问,Memory 的 DELETE 正文与游标分页以本页为准。
读取用 memories.read,写入与写入任务查询用 memories.write,遗忘用 memories.delete,共享用 memories.share,导出用 memories.export。混合 batch 逐项检查所需权限;上下文治理和知识管理还要求管理访问能力。普通项目用户不能通过请求参数获得系统权限。
记忆 scope 为 private、strict_private、user、group、project;group 写入还需 metadata.groupId。可见范围不是 API Key scope。
经验、技能、蒸馏、统一召回、反馈与上下文使用知识归属 scope:user(默认)、agent、project。服务端显式传 userId;仅 agent 范围传 agentId,且必须提供。普通用户不能自报跨用户归属。
accessMode 默认 owned;accessible 查询已授权可见集合,strict_private 不进入授权并集。
所有写请求示例的幂等键均为演示示意。同一次逻辑写入的重试复用原键,不同操作使用不同键;若接口同时支持 idempotencyKey 参数,两处提供时必须相同。
请求与响应约定
成功响应直接返回业务对象,不使用 success/data 外层包装。HTTP 202 表示已受理,不保证业务已完成。任务 succeeded 后仍需检查 result.status 与逐项结果,partial_failed 不能当作全部成功。
列表通常使用 limit/cursor,下一页原样传回 nextCursor;审计 cursor 是整数偏移。记忆 list 也接受 SDK Query 表达式,但不能与直接参数提交互相冲突的分页条件。
SDK 列对照已发布的 agentbase-node-sdk@2.12.0。media、pipelineId 等字段仍须满足各接口的模型、权限和使用条件;请按对应方法签名传参,不要假设未声明的属性会自动发送。
端点总览
记忆系统的业务操作按职责分为:记忆 CRUD 与批量写入任务(/v1/memory/memories*、/v1/memory/jobs/{jobId})、多模态搜索与统一知识召回(/search、/recall)、技能与经验管理(/skills*、/experiences*)、上下文做梦治理(/contexts*)、经验技能蒸馏(/distillations*)、用户画像抽取(/users/{userId}/profile*)、导入导出与会话审计(/imports*、/exports*、/sessions、/audits)。
端点清单
| 方法与路径 | SDK 方法 |
|---|---|
POST /v1/memory/memories | Memory.create |
GET /v1/memory/memories | Memory.list |
GET /v1/memory/memories/{memoryId} | Memory.get |
PATCH /v1/memory/memories/{memoryId} | Memory.update |
DELETE /v1/memory/memories/{memoryId} | Memory.delete |
DELETE /v1/memory/memories | Memory.deleteMany |
POST /v1/memory/memories/batch | Memory.createBatch |
GET /v1/memory/jobs/{jobId} | Memory.getJob |
GET /v1/memory/memories/{memoryId}/sources | Memory.listSources |
GET /v1/memory/memories/{memoryId}/shares | Memory.listShares |
POST /v1/memory/memories/{memoryId}/shares | Memory.createShare |
DELETE /v1/memory/memories/{memoryId}/shares/{shareId} | Memory.deleteShare |
POST /v1/memory/memories/search | Memory.search |
POST /v1/memory/memories/recall | Memory.recallKnowledge |
GET /v1/memory/memories/skills | Memory.listSkills |
POST /v1/memory/memories/skills/search | Memory.searchSkills |
GET /v1/memory/memories/skills/{knowledgeId} | Memory.getSkill |
GET /v1/memory/memories/skills/{knowledgeId}/sources | Memory.listSkillSources |
GET /v1/memory/memories/experiences | Memory.listExperiences |
POST /v1/memory/memories/experiences/search | Memory.searchExperiences |
GET /v1/memory/memories/experiences/{knowledgeId} | Memory.getExperience |
GET /v1/memory/memories/experiences/{knowledgeId}/sources | Memory.listExperienceSources |
GET /v1/memory/memories/contexts | Memory.listContexts |
GET /v1/memory/memories/contexts/{contextId} | Memory.getContext |
POST /v1/memory/memories/contexts/runs | Memory.createContextRun |
GET /v1/memory/memories/contexts/status | Memory.getContextStatus |
POST /v1/memory/memories/contexts/{contextId}/confirm | Memory.confirmContext |
POST /v1/memory/memories/contexts/{contextId}/rebuild | Memory.rebuildContext |
POST /v1/memory/memories/contexts/{contextId}/rollback | Memory.rollbackContext |
GET /v1/memory/memories/distillations | Memory.listDistillations |
POST /v1/memory/memories/distillations | Memory.submitDistillation |
GET /v1/memory/memories/distillations/{distillationId} | Memory.getDistillation |
POST /v1/memory/memories/distillations/{distillationId}/replay | Memory.replayDistillation |
PATCH /v1/memory/memories/knowledge/{knowledgeId} | Memory.updateKnowledge |
DELETE /v1/memory/memories/knowledge/{knowledgeId} | Memory.forgetKnowledge |
POST /v1/memory/memories/feedback | Memory.createKnowledgeFeedback |
POST /v1/memory/memories/observations | Memory.createKnowledgeObservation |
GET /v1/memory/memories/users/{userId}/profile | Memory.getProfile |
DELETE /v1/memory/memories/users/{userId}/profile | Memory.deleteProfile |
POST /v1/memory/memories/users/{userId}/profile/extractions | Memory.createProfileExtraction |
POST /v1/memory/memories/users/{userId}/profile/rebuild | Memory.createProfileRebuild |
GET /v1/memory/memories/users/{userId}/profile/sources | Memory.listProfileSources |
POST /v1/memory/memories/imports | Memory.createImport |
GET /v1/memory/memories/imports/{importId} | Memory.getImport |
POST /v1/memory/memories/exports | Memory.createExport |
GET /v1/memory/memories/exports/{exportId} | Memory.getExportJob |
GET /v1/memory/memories/export | Memory.getExport |
POST /v1/memory/memories/projections/rebuild | Memory.createProjectionRebuild |
GET /v1/memory/memories/projections/verification | Memory.getProjectionVerification |
GET /v1/memory/memories/stats | Memory.getStats |
GET /v1/memory/memories/quality | Memory.getQuality |
GET /v1/memory/memories/timeline | Memory.getTimeline |
GET /v1/memory/memories/sessions | Memory.getSessions |
GET /v1/memory/audits | Memory.listAudits |
端点详解
各端点严格区分同步查询(200 OK)与异步抽取/蒸馏/重建任务(202 Accepted 返回 jobId),写操作通过 Idempotency-Key 保证重试幂等,更新与遗忘操作支持基于 expectedVersion 的乐观并发控制(CAS)。
请求与响应
以下示例展示单次操作。批量或知识治理操作执行前核对范围;DELETE 业务参数使用 JSON 正文。
POST /v1/memory/memories
SDK:Memory.create · scope:memories.write
创建一条记忆:直接写入,或 infer=true 时交给模型做事实抽取、派生与跨类型去重。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
pipelineId | body | string | 否 | 空串 | 可选已发布 Pipeline ID,省略使用对应场景默认;Node SDK 2.12.0 支持此参数。 |
content | body | string | 否 | 空串 | 正文,非空输入时最多 20,000 UTF-8 字节;与 messages/media 的组合见写入说明。 |
messages | body | array | 否 | [] | 有效消息列表,role 与非空 content 必填;消息限制见对应操作说明。 |
media | body | object | 否 | {} | 同项目 Storage 引用 {bucketId,fileId};格式、大小与权限见本页多模态说明;Node SDK 2.12.0 支持此参数。 |
userId | body | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
runId | body | string | 否 | 空串 | 归属运行 ID(可选);不作为 sessionId 的回退值。 |
sessionId | body | string | 否 | 空串 | 可选会话标识(最多 128 UTF-8 字节);infer=true 时服务端自动关联同会话最近 12 轮(12-turn context)历史上下文辅助指代消解与事实抽取;不替代权限。 |
scope | body | string | 是 | — | 可见性隔离域:strict_private(仅写入调用方与指定本人可见,不进入 accessible 共享并集)、private、user、group(须同时传 metadata.groupId)、project。 |
sensitivity | body | string | 否 | 'normal' | normal(默认)、confidential、restricted;secret 会被拒绝。 |
handlingPolicy | body | string | 否 | 'standard' | standard(默认,执行完整模型抽取与向量化)、no_embedding(仅存文本/结构化元数据,不生成向量)、no_model(纯确定性落库,要求 infer=false 且拒绝媒体输入)。 |
memoryType | body | string | 是 | — | 记忆时间衰减层级(Time-decay tiers)或业务分类:核心支持 working(工作记忆,会话级高频读写)、short_term(短期记忆,受艾宾浩斯遗忘半衰期调控)、long_term(长期记忆,高重要度事实沉淀)及业务自定义类型(如 preference)。 |
recordKind | body | string | 是 | — | 记录种类:conversation(原始对话)、fact(原子事实)或 action(执行动作);结合认知层级 L0(原始来源证据)→ L1(原子事实记忆)→ L2(上下文抽象主题)→ L3(全局领域综述)构成四层认知架构。 |
metadata | body | object | 否 | {} | 自定义元数据对象(可携带 cognitiveLayer: "L0"–"L3"、importance: 0.0–1.0 等业务标签);不能直接覆写系统遗忘或治理内部字段。 |
infer | body | boolean | 否 | true | 默认 true(经 LLM 执行事实抽取、冲突消解与 ADD/UPDATE/DELETE/NONE 决策);false 为确定性直写。 |
reRemember | body | boolean | 否 | false | 重新学习曾被遗忘(forgotten)的内容时必须显式设 reRemember: true 并携带 Idempotency-Key;创建新版本记忆而不直接复活已归档的旧来源。 |
async | body | boolean | 否 | — | 文本缺省随 infer;多模态 media: {bucketId, fileId} 始终异步处理,不能显式设 false。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
pipeline | object / null | 实际使用的流程与固定发布版本回执。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
mode | string | 本次处理方式,例如 simple/inferred。 |
sourceId | string | 不可变来源标识。 |
jobId | string | 任务标识。 |
memory | object / null | 记忆对象;包含 memoryId、version、content、归属与模型处理状态。 |
actions | array | 每项含 index、action、status、memoryId 等,action 为 ADD/UPDATE/DELETE/NONE。 |
errorCode | string | 可省略的错误分类,例如 LLM_TIMEOUT;有错误信息时返回。 |
reason | string | 本次操作或失败原因。 |
retryable | boolean | 失败是否仍可重试,不替代任务状态。 |
fallback | object / null | 受控回退信息:strategy 为字符串;errorCode、reason 为可省略的字符串。 |
idempotencyKey | string | 本次逻辑写入的幂等标识。 |
纯文本默认 infer=true、async=true;需要确定性直写时显式设置 infer=false、async=false。消息最多 100 条,单条 content 最多 10,000 UTF-8 字节,含角色/分隔符的来源文本总长最多 20,000 UTF-8 字节。group 范围写入必须带 metadata.groupId。同步结果状态为 completed、partial_failed 或 failed;推断 actions 为 ADD/UPDATE/DELETE/NONE。异步受理为 HTTP 202,返回 jobId 与 Location。
actions 每项的 errorCode、reason 也是可省略的字符串,retryable 为可省略的布尔值。错误字段仅在有相应信息时出现,不能假定成功响应带空错误对象;发生 fallback 时还应检查回退策略和逐项结果。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"userId": "user-123",
"scope": "user",
"memoryType": "preference",
"recordKind": "fact",
"content": "用户喜欢拿铁咖啡。",
"infer": false,
"async": false
}'多模态与多层级推断写入示例(infer=true、sessionId 12 轮上下文、media: {bucketId, fileId} 与 reRemember: true):
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-H "Idempotency-Key: mem-multimodal-20261022-01" \
--data '{
"userId": "user_zhangwei_001",
"sessionId": "sess_ob_sre_12turns",
"scope": "user",
"handlingPolicy": "standard",
"memoryType": "long_term",
"recordKind": "fact",
"content": "张伟负责华东生产集群 OB-Prod-East 的日常容灾演练,告警阈值倾向设置为日志盘 80%。",
"media": {
"bucketId": "agent_multimedia_bucket",
"fileId": "file_topology_arch_png"
},
"metadata": {
"cognitiveLayer": "L1",
"importance": 0.92
},
"infer": true,
"reRemember": true,
"async": true
}'
)主要字段示例(ID、正文与评分仅作示意):
{
"status": "completed",
"mode": "simple",
"memory": {
"memoryId": "mem-example",
"userId": "user-123",
"scope": "user",
"memoryType": "preference",
"recordKind": "fact",
"content": "用户喜欢拿铁咖啡。",
"version": 1
},
"actions": [
{
"index": 0,
"action": "ADD",
"status": "completed",
"memoryId": "mem-example"
}
]
}GET /v1/memory/memories
SDK:Memory.list · scope:memories.read
列出当前调用者可见的记忆记录(不透明游标分页)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
cursor | query | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | query | integer | 否 | — | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
filter | query | object | 否 | — | 结构化过滤对象,字段必须在项目允许列表内。 |
queries | query | array | 否 | [] | SDK Query 过滤表达式;不与直接参数提交互相冲突的分页条件。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
accessMode | query | string | 否 | 'owned' | owned(默认)或 accessible,后者仍受实际可见权限限制。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
memories | array | 记忆对象数组。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'userId=user-123' \
--data-urlencode 'limit=20'主要字段示例(ID、正文与评分仅作示意):
{
"memories": [
{
"memoryId": "mem-example",
"userId": "user-123",
"scope": "user",
"memoryType": "preference",
"recordKind": "fact",
"content": "用户喜欢拿铁咖啡。",
"version": 1
}
],
"total": 1,
"nextCursor": ""
}GET /v1/memory/memories/{memoryId}
SDK:Memory.get · scope:memories.read
按 ID 获取单条记忆。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | — | 目标记忆 ID。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
memory | object | 记忆对象;包含 memoryId、version、content、归属与模型处理状态。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/{memoryId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"主要字段示例(ID、正文与评分仅作示意):
{
"memory": {
"memoryId": "mem-example",
"userId": "user-123",
"scope": "user",
"memoryType": "preference",
"recordKind": "fact",
"content": "用户喜欢拿铁咖啡。",
"version": 1
}
}PATCH /v1/memory/memories/{memoryId}
SDK:Memory.update · scope:memories.write
按 ID 更新记忆文本/元数据,version 做 CAS 乐观锁。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | — | 目标记忆 ID。 |
version | body | integer | 是 | — | 最近获取的记忆版本,正整数;冲突后重新读取。 |
content | body | string | 否 | — | 更新后的非空正文,最多 20,000 UTF-8 字节。 |
metadata | body | object | 否 | {} | 自定义元数据对象;不能设置系统遗忘或治理字段。 |
retentionPolicy | body | string | 否 | — | 保留策略;当前枚举仅 default。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
memory | object | 记忆对象;包含 memoryId、version、content、归属与模型处理状态。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X PATCH "https://<agentbase-host>/v1/memory/memories/{memoryId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"version": 3,
"content": "用户习惯每天早上十一点查看早餐店经营简报(更新)",
"metadata": {
"verified": true
},
"retentionPolicy": "default"
}'主要字段示例(ID、正文与评分仅作示意):
{
"memory": {
"memoryId": "mem-example",
"userId": "user-123",
"scope": "user",
"memoryType": "preference",
"recordKind": "fact",
"content": "用户现在喜欢美式咖啡。",
"version": 2
}
}DELETE /v1/memory/memories/{memoryId}
SDK:Memory.delete · scope:memories.delete
主动删除单条记忆及其检索数据,不可撤销;仍以 status=forgotten 表示该接口的成功结果。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | — | 目标记忆 ID。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
reason | body | string | 否 | 空串 | 操作原因;上下文确认、重建、回滚时必填且非空。 |
source | body | string | 否 | 'appbase_delete' | 操作来源标记;不授予额外权限。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
memoryId | string | 记忆的完整字符串标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
返回 status=forgotten。主动删除会清除记忆记录与检索投影,来源证据和审计仍可能保留,Storage 原文件不随之删除;不受自适应归档的“永久遗忘”开关控制。相同内容的后续 create/update 可能因已遗忘保护返回 409;确需重新学习时使用 create 的 reRemember=true 和新的幂等键,创建新证据。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X DELETE "https://<agentbase-host>/v1/memory/memories/{memoryId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"reason": "用户要求删除",
"source": "ops-console"
}'主要字段示例(ID、正文与评分仅作示意):
{
"memoryId": "mem-example",
"status": "forgotten"
}DELETE /v1/memory/memories
SDK:Memory.deleteMany · scope:memories.delete
有界批量遗忘:单轮最多处理 limit(≤500)条,hasMore=true 时循环调用直到清完。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
limit | body | integer | 否 | 100 | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
reason | body | string | 否 | 空串 | 操作原因;上下文确认、重建、回滚时必填且非空。 |
source | body | string | 否 | 'appbase_delete_worker' | 操作来源标记;不授予额外权限。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
processed | integer | 本批已处理记录数量。 |
forgotten | integer | 本批成功遗忘的数量。 |
failed | integer | 失败数量,需检查逐项错误。 |
hasMore | boolean | true 时需要继续相同范围的下一批处理。 |
items | array | 逐项结果;结构见本页对应操作说明。 |
limit 默认 100、最大 500,服务可能处理更少;hasMore=true 时继续相同范围,并处理 failed 和逐项错误。避免省略 userId 执行项目范围清理。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X DELETE "https://<agentbase-host>/v1/memory/memories" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"userId": "user-123",
"limit": 500,
"reason": "合规清理",
"source": "ops-console"
}'POST /v1/memory/memories/batch
SDK:Memory.createBatch · scope:按批次各项操作授权
在有界批次中混合执行 create / delete / search 操作。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
items | body | array | 是 | [] | 有界的操作数组;每项按 operation 携带对应负载(create/delete/search 三选一)。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
items | array | 逐项结果;结构见本页对应操作说明。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
items 最多 50 条。返回 status 与 items,逐项检查 status/publicCode/retryable,不能读取不存在的 results 字段。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/batch" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"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
}
}
]
}'GET /v1/memory/jobs/{jobId}
SDK:Memory.getJob · scope:memories.write
查询异步记忆写入任务的执行状态与结果。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
jobId | path | string | 是 | — | 写入任务 ID(创建记忆异步响应中返回)。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
pipeline | object / null | 实际使用的流程与固定发布版本回执。 |
jobId | string | 任务标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
mode | string | 本次处理方式,例如 simple/inferred。 |
sourceId | string | 不可变来源标识。 |
attemptCount | integer | 已经尝试执行的次数。 |
maxAttempts | integer | 重试预算上限。 |
errorCode | string | 可省略的错误分类,例如 LLM_TIMEOUT;有错误信息时返回,重试中的任务也可能携带。 |
reason | string | 本次操作或失败原因。 |
retryable | boolean | 失败是否仍可重试,不替代任务状态。 |
result | object / null | 终态业务结果;调度 succeeded 后仍需检查 result.status。 |
createdAt | string(时间) | 创建时间。 |
updatedAt | string(时间) | 最后更新时间。 |
startedAt | string(时间) | 首次开始执行时间。 |
completedAt | string(时间) | 任务终态时间。 |
queueDurationMs | number / null | 排队耗时,尚未开始时为 null。 |
executionDurationMs | number / null | 首次开始至终态耗时,含重试退避;未结束时为 null。 |
totalDurationMs | number / null | 创建至终态耗时,未结束时为 null。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/jobs/{jobId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"主要字段示例(ID、正文与评分仅作示意):
{
"jobId": "job-example",
"status": "succeeded",
"retryable": false,
"result": {
"status": "completed",
"mode": "inferred",
"actions": [
{
"index": 0,
"action": "ADD",
"status": "completed",
"memoryId": "mem-example"
}
]
}
}失败任务的主要字段示意如下;任务与 result 的 errorCode 均为字符串。未出现的错误字段可以省略,不能按空对象读取。
{
"jobId": "job-failed-example",
"status": "failed",
"errorCode": "LLM_REQUEST_REJECTED",
"reason": "模型请求被拒绝",
"retryable": false,
"result": {
"status": "failed",
"mode": "inferred",
"errorCode": "LLM_REQUEST_REJECTED",
"reason": "模型请求被拒绝"
}
}部分失败时 result.status 为 partial_failed,检查每项 actions,不能将成功动作再次提交为新写入。以下只展示业务结果的主要字段;错误也可能只存在于失败动作,而没有顶层 errorCode:
{
"status": "partial_failed",
"mode": "inferred",
"actions": [
{ "index": 0, "action": "ADD", "status": "completed", "memoryId": "mem-example" },
{ "index": 1, "action": "NONE", "status": "failed", "errorCode": "VALIDATION_FAILED", "reason": "动作参数无效" }
]
}GET /v1/memory/memories/{memoryId}/sources
SDK:Memory.listSources · scope:memories.read
列出记忆关联的不可变证据源(provenance)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | — | 目标记忆 ID。 |
cursor | query | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | query | integer | 否 | 25 | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
sources | array | 当前可见且仍有效的来源。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/{memoryId}/sources" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'limit=20'GET /v1/memory/memories/{memoryId}/shares
SDK:Memory.listShares · scope:memories.share
列出一条记忆的全部生效读授权。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | — | 目标记忆 ID。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
shares | array | 记忆共享记录列表。 |
total | integer | 符合当前查询条件的计数。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/{memoryId}/shares" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"POST /v1/memory/memories/{memoryId}/shares
SDK:Memory.createShare · scope:memories.share
为用户或群组授予单条记忆的读权限。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
memoryId | path | string | 是 | — | 目标记忆 ID。 |
subjectType | body | string | 是 | — | user 或 group。 |
subjectId | body | string | 是 | — | 被授予读取权的用户或分组 ID。 |
expiresAt | body | string | 否 | 空串 | 共享到期时间,ISO 8601 格式。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
share | object | 共享对象。 |
changed | boolean | 本次操作是否改变记录。 |
resourcePolicyRevision | integer | 本次操作后的共享策略版本。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/{memoryId}/shares" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"subjectType": "user",
"subjectId": "user-456",
"expiresAt": "2026-12-31T00: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。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
shareId | string | 共享记录标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
changed | boolean | 本次操作是否改变记录。 |
resourcePolicyRevision | integer | 本次操作后的共享策略版本。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X DELETE "https://<agentbase-host>/v1/memory/memories/{memoryId}/shares/{shareId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{}'POST /v1/memory/memories/search
SDK:Memory.search · scope:memories.read
混合检索记忆记录:dense / sparse / full-text / graph 路由按项目 runtime.recallFusion 配置融合。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
query | body | string | 否 | 空串 | 自然语言查询;图片查询可不传文字,其他检索需非空。 |
searchMode(或 mode) | body | string | 否 | 'hybrid' | 五路混合检索模式:hybrid(默认,融合向量、关键词、稀疏向量、图谱与画像路由)、vector、keyword、graph、profile。 |
retrieval | body | object | 否 | {} | 细粒度检索策略覆盖:支持模型生成稀疏向量 retrieval.sparse: true | false | "auto",以及渐进式召回 retrieval.strategy: "progressive"、entryLevel: "auto"|"overview"|"context"|"fact"|"evidence"、maxDepth: 2、tokenBudget: 1200、deadlineMs: 450、expansionToken: "<token>"。 |
media | body | object | 否 | {} | 同项目 Storage 引用 {bucketId,fileId};格式、大小与权限见本页多模态说明;Node SDK 2.12.0 支持此参数。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
runId | body | string | 否 | 空串 | 按运行过滤。 |
scope | body | string | 否 | 空串 | private、strict_private、user、group、project。 |
memoryType | body | string | 否 | 空串 | 调用方业务类型;推断写入会保留来源并生成派生事实。 |
recordKind | body | string | 否 | 空串 | conversation、fact 或 action。 |
filter | body | object | 否 | — | 结构化过滤对象,字段必须在项目允许列表内。 |
limit | body | integer | 否 | 0 | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
cursor | body | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
sort | body | string | 否 | 空串 | 排序模式。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
groupId | body | string | 否 | 空串 | 群组/实体边界过滤。 |
accessMode | body | string | 否 | 'owned' | owned(默认)或 accessible,后者仍受实际可见权限限制。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
items | array | 逐项结果;结构见本页对应操作说明。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
rewriteTrace | object | 查询改写信息。 |
degraded | object | 本次检索的降级信息,需由调用方检查。 |
progressive | object / null | 选择 progressive 时的分层结果。 |
普通结果位于 items[].memory;score 与 scoreBreakdown 在结果项上。检查 degraded 与 rewriteTrace。hybrid 为默认模式,可选 vector、sparse、keyword、graph。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/search" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"query": "早餐店经营简报",
"retrieval": {
"sparse": true
},
"userId": "user-123",
"agentId": "agent_support",
"runId": "run_20260914_01",
"scope": "user",
"filter": {},
"limit": 10,
"sessionId": "sess_8842",
"accessMode": "accessible"
}'五路混合检索 + 模型生成稀疏向量 + 渐进式召回(Progressive Recall)请求示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/memory/memories/search" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
--data '{
"query": "张伟负责的 OceanBase 生产集群告警阈值与容灾演练偏好是什么?",
"mode": "hybrid",
"searchMode": "hybrid",
"retrieval": {
"sparse": "auto",
"strategy": "progressive",
"entryLevel": "auto",
"maxDepth": 2,
"tokenBudget": 1200,
"deadlineMs": 450,
"expansionToken": ""
},
"userId": "user_zhangwei_001",
"scope": "user",
"memoryType": "long_term",
"limit": 10,
"sessionId": "sess_ob_sre_12turns",
"accessMode": "accessible"
}'
)主要字段示例(ID、正文与评分仅作示意):
{
"items": [
{
"memory": {
"memoryId": "mem-example",
"userId": "user-123",
"scope": "user",
"memoryType": "preference",
"recordKind": "fact",
"content": "用户喜欢拿铁咖啡。",
"version": 1
},
"score": 0.8,
"scoreBreakdown": {}
}
],
"nextCursor": "",
"total": 1,
"degraded": {
"rerank": false,
"profileRewrite": false,
"embedding": false
}
}POST /v1/memory/memories/recall
SDK:Memory.recallKnowledge · scope:memories.read
面向注入的记忆召回:在统一 token 预算内召回记忆、画像、技能与经验,返回带 injectionId 的注入结果供 feedback 归因。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | — | 非空自然语言查询。 |
kinds | body | array | 否 | [] | memory、profile、skill、experience,不重复;默认全部。 |
limit | body | integer | 否 | — | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
tokenBudget | body | integer | 否 | — | 统一召回默认 4096,范围 1–32768。 |
retrieval | body | object | 否 | {} | 按请求覆盖检索路线;可设置 sparse=false。渐进式参数见说明。 |
accessMode | body | string | 否 | 'owned' | owned(默认)或 accessible,后者仍受实际可见权限限制。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
injectionId | string | 本次上下文注入标识,反馈时复用。 |
context | string | 可用于组装模型请求的上下文,或上下文治理结果。 |
items | array | 逐项结果;结构见本页对应操作说明。 |
tokenBudget | integer | 本次上下文 token 预算。 |
usedTokens | integer | 本次实际使用的上下文 token 数。 |
degraded | object | 本次检索的降级信息,需由调用方检查。 |
返回 context、items 与 usedTokens,不返回 total。只有 feedbackEligible=true 的经验/技能结果能反馈;保存同次 injectionId、knowledgeId、revision。召回不会自动执行技能或生成最终聊天回答。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/recall" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"query": "用户每天什么时候查看经营简报?",
"kinds": [
"memory",
"profile",
"skill",
"experience"
],
"limit": 10,
"tokenBudget": 2000,
"retrieval": {},
"accessMode": "owned"
}'主要字段示例(ID、正文与评分仅作示意):
{
"injectionId": "injection-example",
"context": "用户喜欢拿铁咖啡。",
"items": [
{
"kind": "memory",
"knowledgeId": "mem-example",
"knowledgeRevisionId": "1",
"revision": 1,
"content": "用户喜欢拿铁咖啡。",
"score": 0.8,
"tokenCount": 12,
"feedbackEligible": false
}
],
"tokenBudget": 1000,
"usedTokens": 12,
"degraded": {
"rerank": false
}
}GET /v1/memory/memories/skills
SDK:Memory.listSkills · scope:memories.read
列出处于活跃验证状态的技能(Skill)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
cursor | query | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | query | integer | 否 | — | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行过滤。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
items | array | 逐项结果;结构见本页对应操作说明。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/skills" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123' \
--data-urlencode 'limit=20'POST /v1/memory/memories/skills/search
SDK:Memory.searchSkills · scope:memories.read
按语义检索活跃验证的技能。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | — | 非空自然语言查询。 |
cursor | body | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | body | integer | 否 | — | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
retrieval | body | object | 否 | {} | 按请求覆盖检索路线;可设置 sparse=false。渐进式参数见说明。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
items | array | 逐项结果;结构见本页对应操作说明。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
degraded | object | 本次检索的降级信息,需由调用方检查。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/skills/search" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"query": "生成经营简报",
"limit": 5,
"retrieval": {}
}'GET /v1/memory/memories/skills/{knowledgeId}
SDK:Memory.getSkill · scope:memories.read
按 ID 获取单个技能详情。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
knowledgeId | path | string | 是 | — | 技能知识 ID。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
skill | object | 技能知识对象。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/skills/{knowledgeId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123'GET /v1/memory/memories/skills/{knowledgeId}/sources
SDK:Memory.listSkillSources · scope:memories.read
列出技能关联的不可变证据源。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
knowledgeId | path | string | 是 | — | 技能知识 ID。 |
cursor | query | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | query | integer | 否 | 25 | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
sources | array | 当前可见且仍有效的来源。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/skills/{knowledgeId}/sources" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123' \
--data-urlencode 'limit=20'GET /v1/memory/memories/experiences
SDK:Memory.listExperiences · scope:memories.read
列出处于活跃验证状态的经验(Experience)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
cursor | query | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | query | integer | 否 | — | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
items | array | 逐项结果;结构见本页对应操作说明。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/experiences" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123' \
--data-urlencode 'limit=20'POST /v1/memory/memories/experiences/search
SDK:Memory.searchExperiences · scope:memories.read
按语义检索活跃验证的经验。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | — | 非空自然语言查询。 |
cursor | body | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | body | integer | 否 | — | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
retrieval | body | object | 否 | {} | 按请求覆盖检索路线;可设置 sparse=false。渐进式参数见说明。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
items | array | 逐项结果;结构见本页对应操作说明。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
degraded | object | 本次检索的降级信息,需由调用方检查。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/experiences/search" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"query": "周末备货要注意什么",
"limit": 5,
"retrieval": {}
}'GET /v1/memory/memories/experiences/{knowledgeId}
SDK:Memory.getExperience · scope:memories.read
按 ID 获取单个经验详情。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
knowledgeId | path | string | 是 | — | 经验知识 ID。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
experience | object | 经验知识对象。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/experiences/{knowledgeId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123'GET /v1/memory/memories/experiences/{knowledgeId}/sources
SDK:Memory.listExperienceSources · scope:memories.read
列出经验关联的不可变证据源。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
knowledgeId | path | string | 是 | — | 经验知识 ID。 |
cursor | query | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | query | integer | 否 | 25 | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
sources | array | 当前可见且仍有效的来源。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/experiences/{knowledgeId}/sources" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123' \
--data-urlencode 'limit=20'GET /v1/memory/memories/contexts
SDK:Memory.listContexts · scope:memories.read
列出治理上下文聚合(按 scope/定位键过滤,观察 shadow → active 生命周期)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
status | query | string | 否 | 空串 | 按生命周期状态过滤:shadow / quarantine / stale / user-active / agent-active / deprecated。 |
kind | query | string | 否 | 空串 | 按层级过滤:memory_topic / memory_episode / memory_state / memory_overview。 |
cursor | query | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | query | integer | 否 | — | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
contexts | array | 当前可见上下文聚合列表。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/contexts" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123' \
--data-urlencode 'limit=20'GET /v1/memory/memories/contexts/{contextId}
SDK:Memory.getContext · scope:memories.read
按 ID 获取单个治理上下文聚合。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
contextId | path | string | 是 | — | 上下文知识 ID。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
context | object | 可用于组装模型请求的上下文,或上下文治理结果。 |
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/contexts/{contextId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123'POST /v1/memory/memories/contexts/runs
SDK:Memory.createContextRun · scope:memories.write
扫描变更记忆并调度 Dreaming 运行(202 异步)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
changed | integer | 本次操作是否改变记录。 |
scheduled | integer | 本次调度的任务数量。 |
watermark | string | 扫描进度水位。 |
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/contexts/runs" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01"
}'GET /v1/memory/memories/contexts/status
SDK:Memory.getContextStatus · scope:memories.read
查询 Dreaming 的水位(watermark)与任务状态。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
status | object | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/contexts/status" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123'POST /v1/memory/memories/contexts/{contextId}/confirm
SDK:Memory.confirmContext · scope:memories.write
把验证通过的 shadow 上下文确认为活跃(CAS 并发控制)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
contextId | path | string | 是 | — | 上下文知识 ID。 |
expectedVersion | body | integer | 是 | — | 目标知识/上下文的当前 CAS 版本,冲突后重新读取。 |
reason | body | string | 是 | — | 操作原因;上下文确认、重建、回滚时必填且非空。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
context | object | 可用于组装模型请求的上下文,或上下文治理结果。 |
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/contexts/{contextId}/confirm" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"expectedVersion": 5,
"reason": "人工审核通过"
}'POST /v1/memory/memories/contexts/{contextId}/rebuild
SDK:Memory.rebuildContext · scope:memories.write
把单个上下文排入重建(202 异步)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
contextId | path | string | 是 | — | 上下文知识 ID。 |
reason | body | string | 是 | — | 操作原因;上下文确认、重建、回滚时必填且非空。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
jobId | string | 任务标识。 |
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/contexts/{contextId}/rebuild" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"reason": "证据源更新后重算"
}'POST /v1/memory/memories/contexts/{contextId}/rollback
SDK:Memory.rollbackContext · scope:memories.write
把活跃上下文回滚到更早的已验证修订。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
contextId | path | string | 是 | — | 上下文知识 ID。 |
expectedVersion | body | integer | 是 | — | 目标知识/上下文的当前 CAS 版本,冲突后重新读取。 |
targetRevision | body | integer | 是 | — | 上下文回滚目标历史修订号,不代替 expectedVersion。 |
reason | body | string | 是 | — | 操作原因;上下文确认、重建、回滚时必填且非空。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
context | object | 可用于组装模型请求的上下文,或上下文治理结果。 |
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/contexts/{contextId}/rollback" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"expectedVersion": 6,
"targetRevision": 4,
"reason": "最新修订引入事实错误"
}'GET /v1/memory/memories/distillations
SDK:Memory.listDistillations · scope:memories.read
列出蒸馏任务(可按状态过滤)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
status | query | string | 否 | 空串 | 按任务状态过滤:queued / running / succeeded / partial_failed / failed / dead。 |
cursor | query | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | query | integer | 否 | — | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
distillations | array | 蒸馏任务数组。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
total | integer | 符合当前查询条件的计数。 |
任务终态为 succeeded、partial_failed、failed、dead;结果使用 distillation.counts 与 outputs,生成候选不代表已通过人工确认。查询使用 distillationId,不用普通写入 /jobs。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/distillations" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123' \
--data-urlencode 'limit=20'POST /v1/memory/memories/distillations
SDK:Memory.submitDistillation · scope:memories.write
提交有界证据做 Experience/Skill 蒸馏;mode=wait 最长等 20 秒取终态,async 立即返回。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
pipelineId | body | string | 否 | 空串 | 可选已发布 Pipeline ID,省略使用对应场景默认;Node SDK 2.12.0 支持此参数。 |
sourceId | body | string | 否 | 空串 | 已持久化来源 ID;与内联 messages/toolEvents 二选一。 |
sourceType | body | string | 否 | 空串 | 配合 sourceId 使用:conversation、tool-trace、execution-log。 |
messages | body | array | 否 | [] | 有效消息列表,role 与非空 content 必填;消息限制见对应操作说明。 |
toolEvents | body | array | 否 | [] | 最多 100 条工具证据;可与 messages 一起提供,不能与 sourceId 同时提供。 |
mode | body | string | 否 | 'async' | async(默认)或 wait(最长等待 20 秒)。 |
idempotencyKey | body | string | 否 | 空串 | 同一次逻辑请求的幂等标识,也可用 Idempotency-Key 头;两者同时给出须一致。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
distillationId | string | 蒸馏查询标识。 |
jobId | string | 任务标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
idempotentReplay | boolean | 是否复用了相同幂等请求结果。 |
waitTimedOut | boolean | 等待窗口结束,后台任务仍继续执行。 |
message | string | 等待或操作提示。 |
sourceId/sourceType 与内联 messages/toolEvents 必须二选一。messages 最多 100 条,单条最多 16 KiB,合计最多 512 KiB;toolEvents 最多 100 条,单个 arguments/result JSON 最多 64 KiB,事件合计最多 1 MiB。async 默认立即返回 HTTP 202;wait 最长 20 秒,超时仍返回 202、waitTimedOut=true 与 Location,不取消任务。
任务终态为 succeeded、partial_failed、failed、dead;结果使用 distillation.counts 与 outputs,生成候选不代表已通过人工确认。查询使用 distillationId,不用普通写入 /jobs。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/distillations" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"messages": [
{
"role": "user",
"content": "请求被限流时怎么办?"
},
{
"role": "assistant",
"content": "读取 Retry-After 后退避,复用幂等键重试。"
},
{
"role": "user",
"content": "按这个方法重试成功了。"
}
],
"toolEvents": [],
"mode": "async"
}'GET /v1/memory/memories/distillations/{distillationId}
SDK:Memory.getDistillation · scope:memories.read
查询蒸馏任务状态与产出引用。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
distillationId | path | string | 是 | — | 蒸馏任务 ID。 |
scope | query | string | 否 | 'user' | user(默认)、agent、project。 |
userId | query | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | query | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | query | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | query | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | query | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
distillation | object | 蒸馏任务,含 counts、outputs、状态与耗时。 |
任务终态为 succeeded、partial_failed、failed、dead;结果使用 distillation.counts 与 outputs,生成候选不代表已通过人工确认。查询使用 distillationId,不用普通写入 /jobs。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/distillations/{distillationId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'scope=user' \
--data-urlencode 'userId=user-123'POST /v1/memory/memories/distillations/{distillationId}/replay
SDK:Memory.replayDistillation · scope:memories.write
对失败或部分失败的蒸馏任务重放(生成新任务,不改动原任务)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
distillationId | path | string | 是 | — | 要重放的蒸馏任务 ID。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
distillationId | string | 蒸馏查询标识。 |
jobId | string | 任务标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
replayed | boolean | 是否重放了已有蒸馏任务。 |
任务终态为 succeeded、partial_failed、failed、dead;结果使用 distillation.counts 与 outputs,生成候选不代表已通过人工确认。查询使用 distillationId,不用普通写入 /jobs。
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/distillations/{distillationId}/replay" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01"
}'PATCH /v1/memory/memories/knowledge/{knowledgeId}
SDK:Memory.updateKnowledge · scope:memories.write
更新托管知识(记忆/上下文/技能/经验)的治理状态(CAS 并发控制)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
knowledgeId | path | string | 是 | — | 知识 ID。 |
expectedVersion | body | integer | 是 | — | 目标知识/上下文的当前 CAS 版本,冲突后重新读取。 |
status | body | string | 否 | — | 目标治理状态:candidate / shadow / user-active / agent-active / quarantine / deprecated。 |
validationStatus | body | string | 否 | — | 目标验证状态:pending / verified / conflicted / rejected。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
knowledge | object | 知识对象,含 knowledgeId、currentRevision、version、状态与结构化内容。 |
expectedVersion 使用知识项 version,不能与 currentRevision 混用;状态转换仍检查策略与证据。人工确认候选需真实管理用户,不通过此接口绕过确认。
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X PATCH "https://<agentbase-host>/v1/memory/memories/knowledge/{knowledgeId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"expectedVersion": 4,
"status": "user-active",
"validationStatus": "verified"
}'DELETE /v1/memory/memories/knowledge/{knowledgeId}
SDK:Memory.forgetKnowledge · scope:memories.delete
为托管知识写入遗忘标记,停止后续复用;该知识治理操作与主动删除单条记忆的处理方式不同。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
knowledgeId | path | string | 是 | — | 知识 ID。 |
expectedVersion | body | integer | 是 | — | 目标知识/上下文的当前 CAS 版本,冲突后重新读取。 |
reason | body | string | 否 | 空串 | 操作原因;上下文确认、重建、回滚时必填且非空。 |
source | body | string | 否 | 'api' | 操作来源标记;不授予额外权限。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
knowledgeId | string | 知识项标识。 |
version | integer | 当前并发控制版本。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
metadata | object | 响应附带的元数据;知识遗忘含 should_forget 等标记。 |
expectedVersion 使用知识项 version,不能与 currentRevision 混用;状态转换仍检查策略与证据。人工确认候选需真实管理用户,不通过此接口绕过确认。
除所列 scope 外还要求管理访问能力,不能用普通用户会话绕过。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X DELETE "https://<agentbase-host>/v1/memory/memories/knowledge/{knowledgeId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"expectedVersion": 5,
"reason": "知识过时",
"source": "ops-console"
}'POST /v1/memory/memories/feedback
SDK:Memory.createKnowledgeFeedback · scope:memories.write
为一次召回的知识修订记录反馈(仅 Skill/Experience 可评,凭 injectionId 归因)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
injectionId | body | string | 是 | — | 统一召回返回的 injectionId,不能自行生成。 |
knowledgeId | body | string | 是 | — | 被评的 Skill/Experience 知识 ID;Memory 与画像条目不可评。 |
revision | body | integer | 是 | — | 实际召回项的 revision,不是知识项 version。 |
feedbackType | body | string | 是 | — | positive、negative 或 not-relevant;仅对可反馈的经验/技能。 |
reasonCode | body | string | 否 | 空串 | 有界的原因代码(可选)。 |
idempotencyKey | body | string | 否 | 空串 | 同一次逻辑请求的幂等标识,也可用 Idempotency-Key 头;两者同时给出须一致。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 本次反馈或观察记录标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
idempotentReplay | boolean | 是否复用了相同幂等请求结果。 |
revision | integer | 知识内容修订号。 |
injectionId、knowledgeId、revision 必须来自同一次统一召回的可反馈结果;不支持记忆或画像项。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/feedback" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"injectionId": "inj_2ab901",
"knowledgeId": "knw_skill_01",
"revision": 4,
"feedbackType": "positive",
"reasonCode": "helpful-briefing"
}'POST /v1/memory/memories/observations
SDK:Memory.createKnowledgeObservation · scope:memories.write
为知识修订记录一次有界观察证据(工具执行结果等),供可信度推导。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
knowledgeId | body | string | 是 | — | 知识 ID。 |
revision | body | integer | 是 | — | 实际召回项的 revision,不是知识项 version。 |
sourceId | body | string | 否 | 空串 | 形成目标知识的有效来源 ID,不能自报其他来源绕过校验。 |
injectionId | body | string | 否 | 空串 | 统一召回返回的 injectionId,不能自行生成。 |
outcome | body | string | 是 | — | 观察结果:success / failure / not-applicable / security-violation。 |
verificationSource | body | string | 否 | — | 已废弃:平台按认证来源推导可信来源。 |
toolName | body | string | 否 | 空串 | 工具名。 |
toolVersion | body | string | 否 | 空串 | 工具版本。 |
toolSchemaVersion | body | string | 否 | 空串 | 工具 schema 版本。 |
errorFingerprint | body | string | 否 | 空串 | 有界的错误指纹。 |
evidence | body | object | 是 | — | 有界的观察证据对象(必填)。 |
weight | body | number | 否 | — | 已废弃:平台按认证来源推导可信权重。 |
observedAt | body | string | 否 | 空串 | 观察时间戳。 |
idempotencyKey | body | string | 否 | 空串 | 同一次逻辑请求的幂等标识,也可用 Idempotency-Key 头;两者同时给出须一致。 |
scope | body | string | 否 | 'user' | user(默认)、agent、project。 |
userId | body | string | 否 | 空串 | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
agentId | body | string | 否 | 空串 | Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
runId | body | string | 否 | 空串 | 来源运行。 |
memorySubStoreId | body | string | 否 | 空串 | 只能选择当前项目已绑定子存储,不是可任意创建的 Space。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 本次反馈或观察记录标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
idempotentReplay | boolean | 是否复用了相同幂等请求结果。 |
revision | integer | 知识内容修订号。 |
观察的可信来源和权重由认证主体决定,不能自报 verificationSource/weight 来提升可信度。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/observations" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"scope": "user",
"userId": "user-123",
"sessionId": "sess_8842",
"runId": "run_20260914_01",
"knowledgeId": "knw_skill_01",
"revision": 4,
"sourceId": "src_71f0c2",
"injectionId": "inj_2ab901",
"outcome": "success",
"toolName": "briefing-generator",
"toolVersion": "1.4.0",
"toolSchemaVersion": "v2",
"errorFingerprint": "",
"evidence": {
"runId": "run_20260914_01",
"durationMs": 800
},
"observedAt": "2026-09-14T08:00:00.000+00:00"
}'GET /v1/memory/memories/users/{userId}/profile(及直接更新 POST /v1/memory/memories/users/{userId}/profile)
SDK:Memory.getProfile · scope:memories.read / memories.write
读取用户画像(正文 content 或话题摘要 topics);管理端或受控服务亦可通过 POST /v1/memory/memories/users/{userId}/profile(或推荐的 POST .../profile/extractions)提交画像更新。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
profileType | query | string | 否 | 'content' | content(默认)或 topics。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
profile | object | 画像对象,含 profileContent/topics、version、rebuildStatus 等。 |
retrievedAt | string(时间) | 读取时刻。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/users/{userId}/profile" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'profileType=content'DELETE /v1/memory/memories/users/{userId}/profile
SDK:Memory.deleteProfile · scope:memories.delete
删除用户画像及其派生 provenance。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
profileType | body | string | 否 | 'content' | content(默认)或 topics。 |
reason | body | string | 否 | 空串 | 操作原因;上下文确认、重建、回滚时必填且非空。 |
source | body | string | 否 | 'appbase_delete' | 操作来源标记;不授予额外权限。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
profileId | string | 画像标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X DELETE "https://<agentbase-host>/v1/memory/memories/users/{userId}/profile" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"profileType": "content",
"reason": "用户行使删除权",
"source": "ops-console"
}'POST /v1/memory/memories/users/{userId}/profile/extractions
SDK:Memory.createProfileExtraction · scope:memories.write
从证据做画像抽取:默认增量合并,mode=replace 整体替换。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
pipelineId | body | string | 否 | 空串 | 可选已发布 Pipeline ID,省略使用对应场景默认;Node SDK 2.12.0 支持此参数。 |
userId | path | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
profileType | body | string | 否 | 'content' | content(默认)或 topics。 |
messages | body | array | 是 | [] | 有效消息列表,role 与非空 content 必填;消息限制见对应操作说明。 |
sourceMemoryIds | body | array | 否 | [] | 仅 replace 支持,最多 100 条当前用户的有效记忆,不能代替新 messages。 |
sessionId | body | string | 否 | 空串 | 可选会话标识,最多 128 UTF-8 字节;不替代权限。 |
mode | body | string | 否 | 'incremental' | incremental(默认)或 replace。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
memory | object | 记忆对象;包含 memoryId、version、content、归属与模型处理状态。 |
profileExtraction | object | 画像提取结果:status、profileId、profileVersion、profileChanged。 |
返回键是 profileExtraction。incremental 与 replace 都需要有效 messages;sourceMemoryIds 仅 replace 可用,最多 100 条,不能代替新输入。排队时 HTTP 202,读取画像确认最终结果。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/users/{userId}/profile/extractions" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"profileType": "content",
"messages": [
{
"role": "user",
"content": "我最近开始用外卖平台接单了"
}
],
"sourceMemoryIds": [],
"mode": "incremental"
}'POST /v1/memory/memories/users/{userId}/profile/rebuild
SDK:Memory.createProfileRebuild · scope:memories.write
基于全部可见证据全量重建用户画像。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
pipelineId | body | string | 否 | 空串 | 可选已发布 Pipeline ID,省略使用对应场景默认;Node SDK 2.12.0 支持此参数。 |
userId | path | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
profileType | body | string | 否 | 'content' | content(默认)或 topics。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
jobId | string | 任务标识。 |
profileId | string | 画像标识。 |
profileVersion | integer | 画像版本。 |
sourceCount | integer | 参与本次聚合的来源数量。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/users/{userId}/profile/rebuild" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"profileType": "content"
}'GET /v1/memory/memories/users/{userId}/profile/sources
SDK:Memory.listProfileSources · scope:memories.read
列出画像的证据源。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
profileType | query | string | 否 | 'content' | content(默认)或 topics。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
profileType | string | 画像类型 content/topics。 |
sources | array | 当前可见且仍有效的来源。 |
total | integer | 符合当前查询条件的计数。 |
truncated | boolean | 结果或扫描是否因上限截断。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/users/{userId}/profile/sources" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'profileType=content'POST /v1/memory/memories/imports
SDK:Memory.createImport · scope:memories.write
批量导入记忆:结构化数组或原始 JSON/JSONL 串,支持只校验不写入。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
pipelineId | body | string | 否 | 空串 | 可选已发布 Pipeline ID,省略使用对应场景默认;Node SDK 2.12.0 支持此参数。 |
userId | body | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
format | body | string | 否 | 'jsonl' | json 或 jsonl。 |
data | body | string | 否 | 空串 | JSON/JSONL 文本导入内容,与 records 二选一。 |
records | body | array | 否 | [] | 结构化导入列表,最多 500 条;与 data 二选一。 |
dryRun | body | boolean | 否 | false | true 仅验证/预览,不写入业务数据;正式执行使用新的逻辑请求标识。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
importId | string | 导入查询标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
jobId | string | 任务标识。 |
records 与 data 二选一;先 dryRun=true 验证,通过后用新的逻辑幂等键正式导入。顶层 userId 与每条记录归属必须一致。查询用 importId。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/imports" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"userId": "user-123",
"format": "json",
"dryRun": true,
"records": [
{
"userId": "user-123",
"scope": "user",
"memoryType": "preference",
"recordKind": "fact",
"content": "用户喜欢拿铁咖啡。",
"infer": false
}
]
}'GET /v1/memory/memories/imports/{importId}
SDK:Memory.getImport · scope:memories.read
查询导入任务状态与逐条结果。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
importId | path | string | 是 | — | 导入任务 ID。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
importId | string | 导入查询标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
job | object | 异步任务对象,检查 job.status 与 job.result。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/imports/{importId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"POST /v1/memory/memories/exports
SDK:Memory.createExport · scope:memories.export
创建记忆导出任务,返回 exportId、status 与 job。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
format | body | string | 否 | 'jsonl' | json 或 jsonl。 |
includeForgotten | body | boolean | 否 | false | 默认 false;额外敏感导出需系统授权,布尔值不代替权限。 |
includeVectors | body | boolean | 否 | false | 默认 false;导出向量需系统授权。 |
includeRawSources | body | boolean | 否 | false | 默认 false;导出原始来源需系统授权。 |
mode | body | string | 否 | 'async' | async(默认)或 sync。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
exportId | string | 导出查询标识。 |
status | string | 当前业务状态或任务状态,不能只依赖 HTTP 成功码。 |
job | object | 异步任务对象,检查 job.status 与 job.result。 |
includeForgotten/includeVectors/includeRawSources 默认 false,需要额外系统授权。导出不删除线上数据。POST 创建结果为 exportId/status/job,按 exportId 查询 job;需要直接取得编码数据时用 GET /memory/memories/export,返回 data 等字段。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/exports" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"userId": "user-123",
"format": "json",
"includeForgotten": false,
"includeVectors": false,
"includeRawSources": false,
"mode": "async"
}'GET /v1/memory/memories/exports/{exportId}
SDK:Memory.getExportJob · scope:memories.export
查询导出任务状态与产出位置。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
exportId | path | string | 是 | — | 导出任务 ID。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
job | object | 异步任务对象,检查 job.status 与 job.result。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/exports/{exportId}" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"GET /v1/memory/memories/export
SDK:Memory.getExport · scope:memories.export
同步导出一批记忆(mode 固定 sync,直接返回数据)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
userId | query | string | 是 | — | 目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。 |
format | query | string | 否 | 'jsonl' | json 或 jsonl。 |
mode | query | string | 否 | 'sync' | 仅 sync。 |
includeForgotten | query | boolean | 否 | false | 默认 false;额外敏感导出需系统授权,布尔值不代替权限。 |
includeVectors | query | boolean | 否 | false | 默认 false;导出向量需系统授权。 |
includeRawSources | query | boolean | 否 | false | 默认 false;导出原始来源需系统授权。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
schemaVersion | integer | 导出结构版本。 |
format | string | json 或 jsonl 格式。 |
mediaType | string | 导出内容的媒体类型。 |
generatedAt | string(时间) | 导出生成时间。 |
data | string | 编码后的导出文本。 |
memories | array | 记忆对象数组。 |
profiles | array | 导出的画像集合。 |
jobs | array | 导出的任务集合。 |
vectors | array | 按授权可选导出的向量投影。 |
sources | array | 当前可见且仍有效的来源。 |
metadata | object | 响应附带的元数据;知识遗忘含 should_forget 等标记。 |
includeForgotten/includeVectors/includeRawSources 默认 false,需要额外系统授权。导出不删除线上数据。POST 创建结果为 exportId/status/job,按 exportId 查询 job;需要直接取得编码数据时用 GET /memory/memories/export,返回 data 等字段。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/memories/export" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'userId=user-123' \
--data-urlencode 'format=jsonl' \
--data-urlencode 'mode=sync'POST /v1/memory/memories/projections/rebuild
SDK:Memory.createProjectionRebuild · scope:memories.write
按路由有界重建记忆投影(检索索引),多轮推进直至完成;仅允许可信运维调用。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
routes | body | array | 是 | [] | 投影重建必选 dense、sparse、graph 中的一种或多种,不重复。 |
cursor | body | string | 否 | 空串 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
limit | body | integer | 否 | 100 | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
dryRun | body | boolean | 否 | false | true 仅验证/预览,不写入业务数据;正式执行使用新的逻辑请求标识。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
routes | array | 本次请求选定的投影路线。 |
dryRun | boolean | 是否只做预校验或预览。 |
matched | integer | 本次匹配的待处理数量。 |
scheduled | integer | 本次调度的任务数量。 |
conflicts | integer | 本次发生并发冲突的数量。 |
hasMore | boolean | true 时需要继续相同范围的下一批处理。 |
nextCursor | string | 下一页游标;空值表示没有后续页。 |
本次为有界投影修复,先 dryRun=true 检查;hasMore=true 时继续,验证结果不等于自动修复所有差异。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X POST "https://<agentbase-host>/v1/memory/memories/projections/rebuild" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-id-for-this-operation>" \
--data '{
"routes": [
"dense",
"sparse"
],
"limit": 100,
"dryRun": false
}'GET /v1/memory/memories/projections/verification
SDK:Memory.getProjectionVerification · scope:memories.read
读取项目级记忆投影恢复校验结果(重建后的一致性检查)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 无 | — | — | — | — | 无业务请求参数。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
liveRecords | integer | 校验范围内的存活记录数。 |
dense | object | Dense 投影校验结果与就绪状态。 |
sparse | object | Sparse 投影校验结果与就绪状态。 |
graph | object | Graph 投影校验结果与就绪状态。 |
repairRecommended | boolean | 是否建议执行受控修复。 |
limitations | array | 本次校验的限制,不能忽略后宣称完整一致。 |
verifiedAt | string(时间) | 投影校验时刻。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/projections/verification" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"GET /v1/memory/memories/stats
SDK:Memory.getStats · scope:memories.read
读取当前调用者可见的记忆统计。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 无 | — | — | — | — | 无业务请求参数。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
visibleCount | integer | 当前可见记忆数量。 |
forgottenCount | integer | 已遗忘数量。 |
totalCount | integer | 记忆总数。 |
indexStatus | object | 按索引状态的记忆数量。 |
jobStatus | object | 按任务状态的数量。 |
from | string(时间) | 本次统计的起始时间(如提供)。 |
to | string(时间) | 本次统计的结束时间(如提供)。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/stats" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"GET /v1/memory/memories/quality
SDK:Memory.getQuality · scope:memories.read
读取记忆质量报告。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 无 | — | — | — | — | 无业务请求参数。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
visibleCount | integer | 当前可见记忆数量。 |
lowQualityCount | integer | 低质量记忆数量。 |
pendingIndexes | integer | 尚未就绪的索引数量。 |
issues | array | 存在质量提示的记忆及 flags。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/quality" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"GET /v1/memory/memories/timeline
SDK:Memory.getTimeline · scope:memories.read
读取记忆活动时间线。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 无 | — | — | — | — | 无业务请求参数。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
buckets | array | 日期分桶,含 created、updated、forgotten。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/timeline" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"GET /v1/memory/memories/sessions
SDK:Memory.getSessions · scope:memories.read
读取记忆会话聚合。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 无 | — | — | — | — | 无业务请求参数。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
sessions | array | 会话聚合列表。 |
total | integer | 符合当前查询条件的计数。 |
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/sessions" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>"GET /v1/memory/audits
SDK:Memory.listAudits · scope:memories.read
查询项目记忆请求审计(整数偏移分页)。
| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
jobId | query | string | 否 | 空串 | 精确匹配的记忆任务 ID。 |
query | query | string | 否 | 空串 | 审计内容检索关键字,可省略。 |
operation | query | string | 否 | 空串 | 按记忆操作名过滤(如 createMemory)。 |
outcome | query | string | 否 | 空串 | 按请求结果过滤:success / failure。 |
limit | query | integer | 否 | 25 | 本次返回或处理上限;有效范围见参数默认值与相应操作边界。 |
cursor | query | integer | 否 | 0 | 上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。 |
返回字段(只列公开结构,按条件返回的字段可能省略):
| 字段 | 类型 | 说明 |
|---|---|---|
audits | array | 与过滤条件匹配的审计记录。 |
total | integer | 符合当前查询条件的计数。 |
nextCursor | integer / null | 下一页游标;空值表示没有后续页。 |
scanned | integer | 为得到结果实际扫描的数量。 |
truncated | boolean | 结果或扫描是否因上限截断。 |
cursor 为整数偏移,使用返回的 nextCursor;同时检查 scanned/truncated。普通读取与状态轮询不逐次创建请求审计。
请求示例:替换 endpoint、项目凭证和路径中的资源 ID;资源 ID 来自您自己的创建或查询结果。
curl -sS -X GET --get "https://<agentbase-host>/v1/memory/audits" \
-H "X-Appwrite-Project: <project-id>" \
-H "X-Appwrite-Key: <project-api-key>" \
--data-urlencode 'limit=20'多模态输入与渐进式检索
创建记忆可传 media={bucketId,fileId},使用同项目的完整 Storage 文件。写入支持 PNG/JPEG/WebP/PDF,每次一个文件、最多 8 MiB;图片最多 16,000,000 像素,PDF 最多 10 页。媒体解析始终异步,返回 jobId。输入加解析文本最多 20,000 UTF-8 字节,需要 memories.write、files.read、视觉模型与媒体解析支持;no_model 拒绝媒体输入。
搜索图片使用相同 media 引用,需 memories.read 与文件读取权;图片先解析为文本再检索,不写入记忆、不建立图片向量索引。查询不支持 PDF,所有媒体输入不支持外部 URL、base64、音频或视频。Memory 遗忘不会自动删除原 Storage 文件。
渐进式检索可在 search 的 retrieval 中传 strategy=progressive、entryLevel=auto、maxDepth=2、tokenBudget=1200、deadlineMs=450。entryLevel 支持 auto/overview/context/fact/evidence,maxDepth 为 0–3,deadlineMs 最大 450。结果在 progressive.items;L3 概览、L2 上下文、L1 事实、L0 证据,继续展开用 expansionToken,不用普通 cursor。该模式不支持 batch,令牌有时效,来源或权限变化后重新获取;需要相应项目功能与有效聚合。
自进化知识审批与修订治理 API(Evolution Reviews & Revisions)
当经验与技能蒸馏任务(POST /v1/memory/memories/distillations)或直接写入接口(POST /v1/memory/memories/experiences、POST /v1/memory/memories/skills)产出候选(Candidate)知识,或线上修订触发可信度降级时,可通过自进化审批与修订版本治理接口完成查看、编辑、批准(Approve)、驳回(Reject)、历史版本比对(Diff)与一键回滚(Rollback):
| 方法与路径 | 所需权限(Scope + 角色) | 核心参数 | 用途说明 |
|---|---|---|---|
GET /v1/memory/memories/knowledge/reviews/{reviewId} | memories.read + 管理权限 | reviewId(path) | 获取单条知识自进化审批单详情(含候选经验/技能正文、蒸馏来源证据与置信度评分)。 |
PATCH /v1/memory/memories/knowledge/reviews/{reviewId} | memories.write + 管理权限 | title、content、tags、expectedVersion(body) | 审批人在批准前对候选经验/技能正文或适用条件做人工修订。 |
POST /v1/memory/memories/knowledge/reviews/{reviewId}/approve | memories.write + 管理权限 | expectedVersion、reason(body) | 批准候选知识修订并晋升为线上 active 状态,供 /recall 与 /experiences/search、/skills/search 召回。 |
POST /v1/memory/memories/knowledge/reviews/{reviewId}/reject | memories.write + 管理权限 | expectedVersion、reason(body) | 驳回低质量或存在冲突的候选知识修订,归档审批单且不污染线上知识库。 |
GET /v1/memory/memories/knowledge/{knowledgeId}/revisions | memories.read | knowledgeId(path)、limit、cursor(query) | 列出指定经验或技能(knowledgeId)的全部不可变历史修订版本列表。 |
GET /v1/memory/memories/knowledge/{knowledgeId}/diff | memories.read | fromRevision、toRevision(query, integer) | 对比同一条经验/技能在两个历史修订号之间的结构化字段与正文差异。 |
POST /v1/memory/memories/knowledge/{knowledgeId}/rollback | memories.write + 管理权限 | expectedVersion、targetRevision、reason(body) | 将线上经验或技能原子回滚至指定的历史已验证修订号(生成新的追加修订记录)。 |
自进化审批、Diff 与回滚请求示例:
将 APPBASE_ENDPOINT 设置为目标环境的 API 地址(包含 /v1),并确认项目与凭据属于该环境。
查看并人工微调待审批的蒸馏技能候选(GET / PATCH /v1/memory/memories/knowledge/reviews/{reviewId})
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X PATCH "${APPBASE_ENDPOINT}/memory/memories/knowledge/reviews/rev_distill_0089" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
--data '{
"expectedVersion": 1,
"title": "OceanBase 日志盘满 (ERROR 4016) 应急扩容与限流标准技能",
"content": "1. 检查 gv$ob_log_stat 确认卡住的日志流;2. 临时调大 log_disk_utilization_limit_threshold 至 90%;3. 扩容节点日志盘并恢复阈值。",
"reason": "补充步骤 1 视图名称校准"
}'
)批准审批单上线(POST .../reviews/{reviewId}/approve;若驳回则调用 POST .../reviews/{reviewId}/reject)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/memory/memories/knowledge/reviews/rev_distill_0089/approve" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
-H "Idempotency-Key: approve-rev-0089-v1" \
--data '{
"expectedVersion": 2,
"reason": "经 SRE 团队复核验证通过,准予晋升为线上技能"
}'
)查询知识修订列表、对比版本差异并在异常时回滚(GET .../revisions、GET .../diff、POST .../rollback)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X GET "${APPBASE_ENDPOINT}/memory/memories/knowledge/knw_skill_01/diff?fromRevision=3&toRevision=4" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @-
)操作 4(单独执行)。仅在确认目标与影响后单独执行。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/memory/memories/knowledge/knw_skill_01/rollback" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
-H "Idempotency-Key: rollback-knw-skill-01-to-r3" \
--data '{
"scope": "user",
"userId": "user_zhangwei_001",
"expectedVersion": 5,
"targetRevision": 3,
"reason": "Revision 4 在边缘场景下触发误判,回滚至稳定版 Revision 3"
}'
)四类记忆流水线(含艾宾浩斯遗忘 Pipeline)与六大配置命名空间 API
项目级记忆系统通过四类可编排流水线(Memory Pipelines)与六大配置命名空间(Configuration Namespaces)实现从写入抽取、画像构建、经验蒸馏到艾宾浩斯遗忘(Ebbinghaus Forgetting)的全周期治理。上述管理面接口需具备项目或管理权限(Console 管理员凭证或具备管理授权的服务端凭证),配置更新可使用正数 expectedConfigVersion 或 HTTP If-Match 头执行乐观并发控制(CAS),也可同时提供:
已保存流水线版本试运行(2.12.0)
使用项目 API Key 查询试运行结果需要 projects.read 与 memories.read。创建试运行使用具备管理授权的身份调用 POST /v1/memory/pipeline-runs,支持 1–8 个候选配置与 1–20 个样本;202 表示已受理,应继续查询终态。
| 方法与路径 | 权限 | 参数与返回 |
|---|---|---|
GET /v1/memory/pipeline-runs/{runId} | projects.read + memories.read | 查询冻结输入、进度与逐样本结果。 |
GET /v1/memory/pipeline-runs | projects.read + memories.read | 按 scenario 查询;默认 add_memory,可选 profile、distillation 或 forgetting。limit 为 1–50,默认 20;cursor 为不透明分页游标。 |
试运行比较受理时冻结的候选配置与样本,不写入业务记忆;模型调用是否收费取决于实际配置。具体可用性以目标环境为准。
1. 四类记忆流水线 API(/v1/memory/pipelines*)
| 方法与路径 | 核心参数 | 用途说明 |
|---|---|---|
GET /v1/memory/pipelines | scenario(query,可选:add_memory | profile | distillation | forgetting) | 列出当前项目下的四类记忆流水线定义、当前发布版本与默认绑定状态。 |
POST /v1/memory/pipelines | scenario、fromDefaults 或 config | 创建草稿;fromDefaults: true 使用指定场景的默认步骤配置,与 config 互斥。 |
PATCH /v1/memory/pipelines/{id} | expectedRevision、config | 使用当前修订号更新完整流水线配置。 |
POST /v1/memory/pipelines/{id}/validate | versionId、data;系统默认版本另传 scenario | 使用样本验证已保存的版本,不写入业务记忆;请求需 projects.write 和 memories.read。遗忘场景的 data 可包含 userId。 |
POST /v1/memory/pipelines/{id}/publish | versionId、expectedRevision、可选 makeDefault | 发布已通过验证的草稿;makeDefault 控制是否同时设为默认。 |
PUT /v1/memory/pipelines/default | scenario、pipelineId、expectedRevision | 将已发布的流水线设为该场景默认;pipelineId: null 恢复系统默认。 |
流水线的管理操作与示例请参见产品手册的记忆配置中心。
2. 六大配置命名空间 API(GET/PUT /v1/projects/{projectId}/memory/config/{namespace})
项目级记忆配置按职责划分为六个独立命名空间(namespace 枚举:runtime、prompt、policy、retention、provider、evolution),更新可使用从 GET 响应取得的正数 expectedConfigVersion 或 If-Match 请求头,也可同时提供:
命名空间(namespace) | 核心配置项 | 说明 |
|---|---|---|
runtime | recallFusion、queryEmbeddingCache、unifiedRecall | 控制检索融合、查询嵌入缓存与召回阈值。 |
prompt | factExtractionPrompt、profileExtractionPrompt、contextAggregationPrompt | 配置事实抽取、画像与上下文聚合提示词。 |
policy | captureMode、filterAllowlist、forgetting | 控制捕获策略、过滤白名单及遗忘策略。 |
retention | defaultDays、factDays、conversationDays、auditEventDays | 控制不同类型数据的保留天数。 |
provider | llmProviderRef、chatModel、embeddingModel、sparseEmbeddingEnabled | 配置模型提供商、模型及稀疏向量能力。 |
evolution | autoDistillEnabled、requireConfirmation、dreaming | 控制自动蒸馏、确认和上下文聚合。 |
管理端配置查询与更新示例请参见产品手册的记忆配置中心。
错误与边界
400:参数或存储类型不支持;检查消息、大小、范围及媒体限制。
401/403:检查 Key、项目、scope、用户归属与管理权限。
404:资源不存在或不可见;画像可能尚未生成。
409:version、expectedVersion、revision 或幂等冲突;重新读取并核对业务意图,不盲目覆盖。
429:按 Retry-After 退避。
503:初始化或依赖暂不可用;仅对明确可重试错误有界退避,写入复用原幂等键。
未完成的任务继续按自己的状态接口查询。不要重新创建一条请求来代替轮询,也不把示例评分或数量写成业务断言。
与 Server SDK 的对应
端点清单逐行列出 Memory service 方法。2.12.0 Node.js SDK 返回宽类型对象,应用需按本文契约检查响应;完整可运行示例见记忆 SDK 操作。
适用版本
服务端接口以 Agentbase 2.12.0 为基准,Node.js SDK 参考使用已发布的 agentbase-node-sdk@2.12.0。项目生命周期、配置、Pipeline 与人工确认属于管理面;本页不将其列为普通项目 API Key 接口。目标环境启用严格版本校验时,应使用该环境支持的 SDK 版本。
2.12.0 接口与兼容增量
以下路径相对于 /v1。记忆创建、画像和检索属于数据面,可由具备对应权限的项目 API Key 调用;Key 仅留在服务端。Pipeline 运行与校验属于管理操作,其中写入接口需要 projects.write,普通项目 API Key 无此权限,应使用具备相应授权的管理身份。下表权限为必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。
| HTTP | Scope | SDK |
|---|---|---|
POST /memory/memories | memories.write | memory.create |
GET /memory/memories/profiles | memories.read | memory.listProfiles |
POST /memory/memories/search | memories.read | memory.search |
GET /memory/pipeline-runs | projects.read + memories.read | memory.listPipelineRuns |
POST /memory/pipeline-runs | projects.write | memory.createPipelineRun |
GET /memory/pipeline-runs/{runId} | projects.read + memories.read | memory.getPipelineRun |
POST /memory/pipelines/{pipelineId}/validate | projects.write | memory.validatePipeline |
POST /memory/memories
创建记忆
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
pipelineId | body | 否 | string | default="" | 可选的已发布添加记忆 Pipeline ID;不填时使用项目默认或系统默认配置。 |
content | body | 否 | string | default="" | 兼容模式的记忆文本;未提供 messages 和 media 时必填。 |
messages | body | 否 | array[object] | default=[] | 可选的角色和内容消息,作为来源证据。 |
media | body | 否 | object | default=[] | 可选的存储文件引用 {bucketId, fileId};支持一个不超过 8 MiB 的 PNG、JPEG、WebP 或 PDF,PDF 最多 10 页。需要 files.read 权限及已配置的视觉模型路由;写入媒体时须设置 async=true。 |
userId | body | 是 | string | — | 目标用户 ID。 |
agentId | body | 否 | string | default="" | 可选的智能体 ID。 |
runId | body | 否 | string | default="" | 可选的运行 ID。 |
sessionId | body | 否 | string | default="" | 可选的会话 ID,最多 128 个字符。infer=true 时,仅 user、group 和 project 范围会加载有限的历史记录;private 和 strict_private 不加载历史记录。 |
scope | body | 是 | string | enum=private, strict_private, user, group, project | 记忆可见范围。 |
sensitivity | body | 否 | string | enum=normal, confidential, restricted, secret; default="normal" | 内容密级;敏感值须使用 Agentbase Secret 或变量。 |
handlingPolicy | body | 否 | string | enum=standard, no_embedding, no_model; default="standard" | 处理限制;no_model 要求 infer=false。 |
memoryType | body | 是 | string | — | 记忆类型。infer=true 时,输入对话作为来源证据保留,派生记录使用 long_term。 |
recordKind | body | 是 | string | enum=conversation, fact, action | 记忆记录类型。infer=true 时,对话输入会派生 fact 记录。 |
metadata | body | 否 | object | default=[] | 记忆元数据。 |
sourceContext | body | 否 | object | default={} | 可选的来源对话时间 conversationTime(YYYY-MM-DD 或带时区偏移的 RFC3339)与时区 timeZone(IANA)。未提供对话时间时保持未知,不使用事件或导入时间代替。 |
infer | body | 否 | boolean | default=true | 使用已配置的模型辅助提取和跨类型去重,默认 true。 |
reRemember | body | 否 | boolean | default=false | 为已遗忘内容显式创建新证据。 |
async | body | 否 | boolean | — | 将记忆创建任务入队并立即返回。文本默认与 infer 一致;媒体即使在 infer=false 时也必须设置为 true。 |
成功响应:HTTP 200 — any.
GET /memory/memories/profiles
列出用户记忆画像
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
cursor | query | 否 | string | default="" | 不透明的分页游标。 |
limit | query | 否 | integer | format=int32 | 返回画像的最大数量。 |
userId | query | 否 | string | default="" | 目标用户 ID。 |
profileType | query | 否 | string | enum=content, topics; default="" | 画像类型;不填时包含全部类型。 |
成功响应:HTTP 200 — any.
POST /memory/memories/search
检索记忆
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
query | body | 否 | string | default="" | 检索文本;提供 media 时可省略。 |
searchMode | body | 否 | string | default="" | 覆盖本次召回模式。 |
retrieval | body | 否 | object | default=[] | 覆盖本次召回路径;sparse=false 时跳过模型生成的稀疏召回,不填则使用项目配置。 |
media | body | 否 | object | default=[] | 可选的存储图片引用 {bucketId, fileId};支持一张不超过 8 MiB 的 PNG、JPEG 或 WebP 图片。需要 files.read 权限及已配置的视觉模型路由;解析文本仅用于检索,不写入记忆。 |
userId | body | 否 | string | default="" | 目标用户 ID。 |
agentId | body | 否 | string | default="" | 按智能体 ID 过滤。 |
runId | body | 否 | string | default="" | 按运行 ID 过滤。 |
scope | body | 否 | string | default="" | 按可见范围过滤。 |
memoryType | body | 否 | string | default="" | 按记忆类型过滤。 |
recordKind | body | 否 | string | default="" | 按记录类型过滤。 |
filter | body | 否 | object | default={} | 结构化记忆过滤条件。 |
temporal | body | 否 | object | default={} | 可选模式 current、asOf 或 history;asOf 需要带时区的时间戳。不确定的事实单独返回。 |
limit | body | 否 | integer | format=int32; default=0 | 最大返回条数;0 使用项目默认值。 |
cursor | body | 否 | string | default="" | 分页游标。 |
sort | body | 否 | string | default="" | 排序模式。 |
memorySubStoreId | body | 否 | string | default="" | 绑定的记忆子库 ID。 |
sessionId | body | 否 | string | default="" | 按会话 ID 过滤。 |
groupId | body | 否 | string | default="" | 按分组或实体边界过滤。 |
accessMode | body | 否 | string | enum=owned, accessible; default="owned" | owned 按所有者过滤以兼容既有行为;accessible 返回已授权的可见范围并集。 |
成功响应:HTTP 200 — any.
GET /memory/pipeline-runs
列出 Memory Pipeline 试运行
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
scenario | query | 否 | string | enum=add_memory, profile, distillation, forgetting; default="add_memory" | Pipeline 场景。 |
limit | query | 否 | integer | format=int32; default=20 | 最大试运行数。 |
cursor | query | 否 | string | default="" | 不透明的分页游标。 |
成功响应:HTTP 200 — memoryPipelineRunList.
返回字段:runs (array), total (integer), nextCursor (string).
POST /memory/pipeline-runs
创建 Memory Pipeline 试运行
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
name | body | 是 | string | — | 试运行名称,去除首尾空白后为 1–256 个 UTF-8 字节。 |
scenario | body | 是 | string | enum=add_memory, profile, distillation, forgetting | 所有候选配置共用的场景。 |
candidates | body | 是 | array[object] | — | 1–8 个对象,每个对象包含 pipelineId 和已保存的 versionId。 |
samples | body | 是 | array[object] | — | 1–20 个对象,每个对象包含唯一 id 和该场景的数据对象。 |
成功响应:HTTP 202 — memoryPipelineRun.
返回字段:runId (string), name (string), scenario (string), status (string), createdAt (string), updatedAt (string), total (integer), completed (integer), succeeded (integer), failed (integer), candidates (array), samples (array), results (array), error (object).
GET /memory/pipeline-runs/{runId}
查询 Memory Pipeline 试运行
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
runId | path | 是 | string | — | 试运行 ID。 |
成功响应:HTTP 200 — memoryPipelineRun.
返回字段:runId (string), name (string), scenario (string), status (string), createdAt (string), updatedAt (string), total (integer), completed (integer), succeeded (integer), failed (integer), candidates (array), samples (array), results (array), error (object).
POST /memory/pipelines/{pipelineId}/validate
验证 Memory Pipeline
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
pipelineId | path | 是 | string | — | Pipeline ID。 |
versionId | body | 是 | string | — | 已保存的配置版本或当前系统默认配置的哈希。 |
scenario | body | 否 | string | enum=add_memory, profile, distillation, forgetting | 验证系统默认配置时使用的场景。 |
data | body | 是 | object | default={} | Pipeline 场景的样例输入;校验不会产生业务数据写入。 |
成功响应:HTTP 200 — any.
错误与重试边界
400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。