AgentbaseDocs
文档目录

记忆 API

本页适用于 Agentbase 2.10.0 的项目级 Memory。第一次接入建议先完成项目与 SDK 准备,再运行完整 SDK 操作示例。

服务与资源边界

项目级记忆系统(Memory)运行于 OceanBase Shared V2 存储架构之上,面向智能客服与企业智能体提供长期事实记忆、对话推理抽取、用户画像(Profile)、上下文做梦整合(Context Dreaming)与经验/技能蒸馏(Experience & Skill Distillation)全生命周期 HTTP 接口。项目启停与 Pipeline 编排属管理面,业务读写、召回、共享、导入导出与请求审计均通过本页定义的 54 项项目级 API 执行。

资源与基础路径

API 基址为当前项目提供的 https://<agentbase-host>/v1。下文路径已包含 /v1,拼接时不要重复。项目须已启用 Memory 且状态 active、数据 ready;启用与配置在 Console 完成。仅支持 Shared V2 项目,不需要创建 Memory Resource 或填写 Space ID。

所有资源标识按字符串处理。记忆使用 memoryId,技能/经验使用 knowledgeId,写入任务使用 jobId,蒸馏查询使用 distillationId;它们不能互换。

认证与权限

每个业务请求携带 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 逐项检查所需权限;上下文治理和知识管理还要求管理访问能力。普通项目用户不能通过请求参数获得系统权限。

请求与响应约定

成功响应直接返回业务对象,不使用 success/data 外层包装。HTTP 202 表示已受理,不保证业务已完成。任务 succeeded 后仍需检查 result.status 与逐项结果,partial_failed 不能当作全部成功。

列表通常使用 limit/cursor,下一页原样传回 nextCursor;审计 cursor 是整数偏移。记忆 list 也接受 SDK Query 表达式,但不能与直接参数提交互相冲突的分页条件。

SDK 列为 agentbase-node-sdk@2.9.0 已有方法。服务端新增的 media/pipelineId 等参数尚未包含在此版本 SDK 签名中,应使用本页 HTTP 契约,不能把额外属性塞进 SDK 对象后假设已经发送。

端点总览

记忆系统共暴露 54 项业务操作,按职责分为:记忆 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/memoriesMemory.create
GET /v1/memory/memoriesMemory.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/memoriesMemory.deleteMany
POST /v1/memory/memories/batchMemory.createBatch
GET /v1/memory/jobs/{jobId}Memory.getJob
GET /v1/memory/memories/{memoryId}/sourcesMemory.listSources
GET /v1/memory/memories/{memoryId}/sharesMemory.listShares
POST /v1/memory/memories/{memoryId}/sharesMemory.createShare
DELETE /v1/memory/memories/{memoryId}/shares/{shareId}Memory.deleteShare
POST /v1/memory/memories/searchMemory.search
POST /v1/memory/memories/recallMemory.recallKnowledge
GET /v1/memory/memories/skillsMemory.listSkills
POST /v1/memory/memories/skills/searchMemory.searchSkills
GET /v1/memory/memories/skills/{knowledgeId}Memory.getSkill
GET /v1/memory/memories/skills/{knowledgeId}/sourcesMemory.listSkillSources
GET /v1/memory/memories/experiencesMemory.listExperiences
POST /v1/memory/memories/experiences/searchMemory.searchExperiences
GET /v1/memory/memories/experiences/{knowledgeId}Memory.getExperience
GET /v1/memory/memories/experiences/{knowledgeId}/sourcesMemory.listExperienceSources
GET /v1/memory/memories/contextsMemory.listContexts
GET /v1/memory/memories/contexts/{contextId}Memory.getContext
POST /v1/memory/memories/contexts/runsMemory.createContextRun
GET /v1/memory/memories/contexts/statusMemory.getContextStatus
POST /v1/memory/memories/contexts/{contextId}/confirmMemory.confirmContext
POST /v1/memory/memories/contexts/{contextId}/rebuildMemory.rebuildContext
POST /v1/memory/memories/contexts/{contextId}/rollbackMemory.rollbackContext
GET /v1/memory/memories/distillationsMemory.listDistillations
POST /v1/memory/memories/distillationsMemory.submitDistillation
GET /v1/memory/memories/distillations/{distillationId}Memory.getDistillation
POST /v1/memory/memories/distillations/{distillationId}/replayMemory.replayDistillation
PATCH /v1/memory/memories/knowledge/{knowledgeId}Memory.updateKnowledge
DELETE /v1/memory/memories/knowledge/{knowledgeId}Memory.forgetKnowledge
POST /v1/memory/memories/feedbackMemory.createKnowledgeFeedback
POST /v1/memory/memories/observationsMemory.createKnowledgeObservation
GET /v1/memory/memories/users/{userId}/profileMemory.getProfile
DELETE /v1/memory/memories/users/{userId}/profileMemory.deleteProfile
POST /v1/memory/memories/users/{userId}/profile/extractionsMemory.createProfileExtraction
POST /v1/memory/memories/users/{userId}/profile/rebuildMemory.createProfileRebuild
GET /v1/memory/memories/users/{userId}/profile/sourcesMemory.listProfileSources
POST /v1/memory/memories/importsMemory.createImport
GET /v1/memory/memories/imports/{importId}Memory.getImport
POST /v1/memory/memories/exportsMemory.createExport
GET /v1/memory/memories/exports/{exportId}Memory.getExportJob
GET /v1/memory/memories/exportMemory.getExport
POST /v1/memory/memories/projections/rebuildMemory.createProjectionRebuild
GET /v1/memory/memories/projections/verificationMemory.getProjectionVerification
GET /v1/memory/memories/statsMemory.getStats
GET /v1/memory/memories/qualityMemory.getQuality
GET /v1/memory/memories/timelineMemory.getTimeline
GET /v1/memory/memories/sessionsMemory.getSessions
GET /v1/memory/auditsMemory.listAudits

端点详解

各端点严格区分同步查询(200 OK)与异步抽取/蒸馏/重建任务(202 Accepted 返回 jobId),写操作通过 Idempotency-Key 保证重试幂等,更新与遗忘操作支持基于 expectedVersion 的乐观并发控制(CAS)。

请求与响应

以下示例展示单次操作。批量或知识治理操作执行前核对范围;DELETE 业务参数使用 JSON 正文。

POST /v1/memory/memories

SDK:Memory.create · scope:memories.write

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

参数位置类型必填默认值说明
pipelineIdbodystring否空串可选已发布 Pipeline ID,省略使用对应场景默认;2.9.0 SDK 未提供此参数,使用 HTTP。
contentbodystring否空串正文,非空输入时最多 20,000 UTF-8 字节;与 messages/media 的组合见写入说明。
messagesbodyarray否[]有效消息列表,role 与非空 content 必填;消息限制见对应操作说明。
mediabodyobject否{}同项目 Storage 引用 {bucketId,fileId};格式、大小与权限见本页多模态说明;2.9.0 SDK 未提供此参数。
userIdbodystring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
runIdbodystring否空串归属运行 ID(可选);不作为 sessionId 的回退值。
sessionIdbodystring否空串可选会话标识(最多 128 UTF-8 字节);infer=true 时服务端自动关联同会话最近 12 轮(12-turn context)历史上下文辅助指代消解与事实抽取;不替代权限。
scopebodystring是—可见性隔离域:strict_private(仅写入调用方与指定本人可见,不进入 accessible 共享并集)、private、user、group(须同时传 metadata.groupId)、project。
sensitivitybodystring否'normal'normal(默认)、confidential、restricted;secret 会被拒绝。
handlingPolicybodystring否'standard'standard(默认,执行完整模型抽取与向量化)、no_embedding(仅存文本/结构化元数据,不生成向量)、no_model(纯确定性落库,要求 infer=false 且拒绝媒体输入)。
memoryTypebodystring是—记忆时间衰减层级(Time-decay tiers)或业务分类:核心支持 working(工作记忆,会话级高频读写)、short_term(短期记忆,受艾宾浩斯遗忘半衰期调控)、long_term(长期记忆,高重要度事实沉淀)及业务自定义类型(如 preference)。
recordKindbodystring是—记录种类:conversation(原始对话)、fact(原子事实)或 action(执行动作);结合认知层级 L0(原始来源证据)→ L1(原子事实记忆)→ L2(上下文抽象主题)→ L3(全局领域综述)构成四层认知架构。
metadatabodyobject否{}自定义元数据对象(可携带 cognitiveLayer: "L0"–"L3"、importance: 0.0–1.0 等业务标签);不能直接覆写系统遗忘或治理内部字段。
inferbodyboolean否true默认 true(经 LLM 执行事实抽取、冲突消解与 ADD/UPDATE/DELETE/NONE 决策);false 为确定性直写。
reRememberbodyboolean否false重新学习曾被遗忘(forgotten)的内容时必须显式设 reRemember: true 并携带 Idempotency-Key;创建新版本记忆而不直接复活已归档的旧来源。
asyncbodyboolean否—文本缺省随 infer;多模态 media: {bucketId, fileId} 始终异步处理,不能显式设 false。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
pipelineobject / null实际使用的流程与固定发布版本回执。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
modestring本次处理方式,例如 simple/inferred。
sourceIdstring不可变来源标识。
jobIdstring任务标识。
memoryobject / null记忆对象;包含 memoryId、version、content、归属与模型处理状态。
actionsarray每项含 index、action、status、memoryId 等,action 为 ADD/UPDATE/DELETE/NONE。
errorCodestring可省略的错误分类,例如 LLM_TIMEOUT;有错误信息时返回。
reasonstring本次操作或失败原因。
retryableboolean失败是否仍可重试,不替代任务状态。
fallbackobject / null受控回退信息:strategy 为字符串;errorCode、reason 为可省略的字符串。
idempotencyKeystring本次逻辑写入的幂等标识。

纯文本默认 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)**:

curl -sS -X POST "https://appbuild-sit.oceanbase.com/v1/memory/memories" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -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

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

参数位置类型必填默认值说明
cursorquerystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitqueryinteger否—本次返回或处理上限;有效范围见参数默认值与相应操作边界。
filterqueryobject否—结构化过滤对象,字段必须在项目允许列表内。
queriesqueryarray否[]SDK Query 过滤表达式;不与直接参数提交互相冲突的分页条件。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
accessModequerystring否'owned'owned(默认)或 accessible,后者仍受实际可见权限限制。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
memoriesarray记忆对象数组。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。

请求示例:替换 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 获取单条记忆。

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

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
memoryobject记忆对象;包含 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 乐观锁。

参数位置类型必填默认值说明
memoryIdpathstring是—目标记忆 ID。
versionbodyinteger是—最近获取的记忆版本,正整数;冲突后重新读取。
contentbodystring否—更新后的非空正文,最多 20,000 UTF-8 字节。
metadatabodyobject否{}自定义元数据对象;不能设置系统遗忘或治理字段。
retentionPolicybodystring否—保留策略;当前枚举仅 default。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
memoryobject记忆对象;包含 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 表示该接口的成功结果。

参数位置类型必填默认值说明
memoryIdpathstring是—目标记忆 ID。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。
reasonbodystring否空串操作原因;上下文确认、重建、回滚时必填且非空。
sourcebodystring否'appbase_delete'操作来源标记;不授予额外权限。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
memoryIdstring记忆的完整字符串标识。
statusstring当前业务状态或任务状态,不能只依赖 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 时循环调用直到清完。

参数位置类型必填默认值说明
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。
limitbodyinteger否100本次返回或处理上限;有效范围见参数默认值与相应操作边界。
reasonbodystring否空串操作原因;上下文确认、重建、回滚时必填且非空。
sourcebodystring否'appbase_delete_worker'操作来源标记;不授予额外权限。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
processedinteger本批已处理记录数量。
forgotteninteger本批成功遗忘的数量。
failedinteger失败数量,需检查逐项错误。
hasMorebooleantrue 时需要继续相同范围的下一批处理。
itemsarray逐项结果;结构见本页对应操作说明。

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 操作。

参数位置类型必填默认值说明
itemsbodyarray是[]有界的操作数组;每项按 operation 携带对应负载(create/delete/search 三选一)。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
itemsarray逐项结果;结构见本页对应操作说明。
statusstring当前业务状态或任务状态,不能只依赖 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

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

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

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
pipelineobject / null实际使用的流程与固定发布版本回执。
jobIdstring任务标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
modestring本次处理方式,例如 simple/inferred。
sourceIdstring不可变来源标识。
attemptCountinteger已经尝试执行的次数。
maxAttemptsinteger重试预算上限。
errorCodestring可省略的错误分类,例如 LLM_TIMEOUT;有错误信息时返回,重试中的任务也可能携带。
reasonstring本次操作或失败原因。
retryableboolean失败是否仍可重试,不替代任务状态。
resultobject / null终态业务结果;调度 succeeded 后仍需检查 result.status。
createdAtstring(时间)创建时间。
updatedAtstring(时间)最后更新时间。
startedAtstring(时间)首次开始执行时间。
completedAtstring(时间)任务终态时间。
queueDurationMsnumber / null排队耗时,尚未开始时为 null。
executionDurationMsnumber / null首次开始至终态耗时,含重试退避;未结束时为 null。
totalDurationMsnumber / 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)。

参数位置类型必填默认值说明
memoryIdpathstring是—目标记忆 ID。
cursorquerystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitqueryinteger否25本次返回或处理上限;有效范围见参数默认值与相应操作边界。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
sourcesarray当前可见且仍有效的来源。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。

请求示例:替换 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

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

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

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
sharesarray记忆共享记录列表。
totalinteger符合当前查询条件的计数。

请求示例:替换 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

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

参数位置类型必填默认值说明
memoryIdpathstring是—目标记忆 ID。
subjectTypebodystring是—user 或 group。
subjectIdbodystring是—被授予读取权的用户或分组 ID。
expiresAtbodystring否空串共享到期时间,ISO 8601 格式。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
shareobject共享对象。
changedboolean本次操作是否改变记录。
resourcePolicyRevisioninteger本次操作后的共享策略版本。

请求示例:替换 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

撤销一条记忆读授权。

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

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
shareIdstring共享记录标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
changedboolean本次操作是否改变记录。
resourcePolicyRevisioninteger本次操作后的共享策略版本。

请求示例:替换 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 配置融合。

参数位置类型必填默认值说明
querybodystring否空串自然语言查询;图片查询可不传文字,其他检索需非空。
searchMode(或 mode)bodystring否'hybrid'五路混合检索模式:hybrid(默认,融合向量、关键词、稀疏向量、图谱与画像路由)、vector、keyword、graph、profile。
retrievalbodyobject否{}细粒度检索策略覆盖:支持模型生成稀疏向量 `retrieval.sparse: truefalse"auto",以及渐进式召回 retrieval.strategy: "progressive"、entryLevel: "auto""overview""context""fact""evidence"、maxDepth: 2、tokenBudget: 1200、deadlineMs: 450、expansionToken: "<token>"`。
mediabodyobject否{}同项目 Storage 引用 {bucketId,fileId};格式、大小与权限见本页多模态说明;2.9.0 SDK 未提供此参数。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
runIdbodystring否空串按运行过滤。
scopebodystring否空串private、strict_private、user、group、project。
memoryTypebodystring否空串调用方业务类型;推断写入会保留来源并生成派生事实。
recordKindbodystring否空串conversation、fact 或 action。
filterbodyobject否—结构化过滤对象,字段必须在项目允许列表内。
limitbodyinteger否0本次返回或处理上限;有效范围见参数默认值与相应操作边界。
cursorbodystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
sortbodystring否空串排序模式。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
groupIdbodystring否空串群组/实体边界过滤。
accessModebodystring否'owned'owned(默认)或 accessible,后者仍受实际可见权限限制。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
itemsarray逐项结果;结构见本页对应操作说明。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。
rewriteTraceobject查询改写信息。
degradedobject本次检索的降级信息,需由调用方检查。
progressiveobject / 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)请求示例:

curl -sS -X POST "https://appbuild-sit.oceanbase.com/v1/memory/memories/search" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -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 归因。

参数位置类型必填默认值说明
querybodystring是—非空自然语言查询。
kindsbodyarray否[]memory、profile、skill、experience,不重复;默认全部。
limitbodyinteger否—本次返回或处理上限;有效范围见参数默认值与相应操作边界。
tokenBudgetbodyinteger否—统一召回默认 4096,范围 1–32768。
retrievalbodyobject否{}按请求覆盖检索路线;可设置 sparse=false。渐进式参数见说明。
accessModebodystring否'owned'owned(默认)或 accessible,后者仍受实际可见权限限制。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
injectionIdstring本次上下文注入标识,反馈时复用。
contextstring可用于组装模型请求的上下文,或上下文治理结果。
itemsarray逐项结果;结构见本页对应操作说明。
tokenBudgetinteger本次上下文 token 预算。
usedTokensinteger本次实际使用的上下文 token 数。
degradedobject本次检索的降级信息,需由调用方检查。

返回 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)。

参数位置类型必填默认值说明
cursorquerystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitqueryinteger否—本次返回或处理上限;有效范围见参数默认值与相应操作边界。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行过滤。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
itemsarray逐项结果;结构见本页对应操作说明。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。

请求示例:替换 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

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

参数位置类型必填默认值说明
querybodystring是—非空自然语言查询。
cursorbodystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitbodyinteger否—本次返回或处理上限;有效范围见参数默认值与相应操作边界。
retrievalbodyobject否{}按请求覆盖检索路线;可设置 sparse=false。渐进式参数见说明。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
itemsarray逐项结果;结构见本页对应操作说明。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。
degradedobject本次检索的降级信息,需由调用方检查。

请求示例:替换 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 获取单个技能详情。

参数位置类型必填默认值说明
knowledgeIdpathstring是—技能知识 ID。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
skillobject技能知识对象。

请求示例:替换 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

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

参数位置类型必填默认值说明
knowledgeIdpathstring是—技能知识 ID。
cursorquerystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitqueryinteger否25本次返回或处理上限;有效范围见参数默认值与相应操作边界。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
sourcesarray当前可见且仍有效的来源。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。

请求示例:替换 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)。

参数位置类型必填默认值说明
cursorquerystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitqueryinteger否—本次返回或处理上限;有效范围见参数默认值与相应操作边界。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
itemsarray逐项结果;结构见本页对应操作说明。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。

请求示例:替换 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

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

参数位置类型必填默认值说明
querybodystring是—非空自然语言查询。
cursorbodystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitbodyinteger否—本次返回或处理上限;有效范围见参数默认值与相应操作边界。
retrievalbodyobject否{}按请求覆盖检索路线;可设置 sparse=false。渐进式参数见说明。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
itemsarray逐项结果;结构见本页对应操作说明。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。
degradedobject本次检索的降级信息,需由调用方检查。

请求示例:替换 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 获取单个经验详情。

参数位置类型必填默认值说明
knowledgeIdpathstring是—经验知识 ID。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
experienceobject经验知识对象。

请求示例:替换 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

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

参数位置类型必填默认值说明
knowledgeIdpathstring是—经验知识 ID。
cursorquerystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitqueryinteger否25本次返回或处理上限;有效范围见参数默认值与相应操作边界。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
sourcesarray当前可见且仍有效的来源。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。

请求示例:替换 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 生命周期)。

参数位置类型必填默认值说明
statusquerystring否空串按生命周期状态过滤:shadow / quarantine / stale / user-active / agent-active / deprecated。
kindquerystring否空串按层级过滤:memory_topic / memory_episode / memory_state / memory_overview。
cursorquerystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitqueryinteger否—本次返回或处理上限;有效范围见参数默认值与相应操作边界。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
contextsarray当前可见上下文聚合列表。
nextCursorstring下一页游标;空值表示没有后续页。

除所列 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 获取单个治理上下文聚合。

参数位置类型必填默认值说明
contextIdpathstring是—上下文知识 ID。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
contextobject可用于组装模型请求的上下文,或上下文治理结果。

除所列 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 异步)。

参数位置类型必填默认值说明
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
changedinteger本次操作是否改变记录。
scheduledinteger本次调度的任务数量。
watermarkstring扫描进度水位。

除所列 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)与任务状态。

参数位置类型必填默认值说明
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
statusobject当前业务状态或任务状态,不能只依赖 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 并发控制)。

参数位置类型必填默认值说明
contextIdpathstring是—上下文知识 ID。
expectedVersionbodyinteger是—目标知识/上下文的当前 CAS 版本,冲突后重新读取。
reasonbodystring是—操作原因;上下文确认、重建、回滚时必填且非空。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
contextobject可用于组装模型请求的上下文,或上下文治理结果。

除所列 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 异步)。

参数位置类型必填默认值说明
contextIdpathstring是—上下文知识 ID。
reasonbodystring是—操作原因;上下文确认、重建、回滚时必填且非空。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
jobIdstring任务标识。

除所列 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

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

参数位置类型必填默认值说明
contextIdpathstring是—上下文知识 ID。
expectedVersionbodyinteger是—目标知识/上下文的当前 CAS 版本,冲突后重新读取。
targetRevisionbodyinteger是—上下文回滚目标历史修订号,不代替 expectedVersion。
reasonbodystring是—操作原因;上下文确认、重建、回滚时必填且非空。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
contextobject可用于组装模型请求的上下文,或上下文治理结果。

除所列 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

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

参数位置类型必填默认值说明
statusquerystring否空串按任务状态过滤:queued / running / succeeded / partial_failed / failed / dead。
cursorquerystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitqueryinteger否—本次返回或处理上限;有效范围见参数默认值与相应操作边界。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
distillationsarray蒸馏任务数组。
nextCursorstring下一页游标;空值表示没有后续页。
totalinteger符合当前查询条件的计数。

任务终态为 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 立即返回。

参数位置类型必填默认值说明
pipelineIdbodystring否空串可选已发布 Pipeline ID,省略使用对应场景默认;2.9.0 SDK 未提供此参数,使用 HTTP。
sourceIdbodystring否空串已持久化来源 ID;与内联 messages/toolEvents 二选一。
sourceTypebodystring否空串配合 sourceId 使用:conversation、tool-trace、execution-log。
messagesbodyarray否[]有效消息列表,role 与非空 content 必填;消息限制见对应操作说明。
toolEventsbodyarray否[]最多 100 条工具证据;可与 messages 一起提供,不能与 sourceId 同时提供。
modebodystring否'async'async(默认)或 wait(最长等待 20 秒)。
idempotencyKeybodystring否空串同一次逻辑请求的幂等标识,也可用 Idempotency-Key 头;两者同时给出须一致。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
distillationIdstring蒸馏查询标识。
jobIdstring任务标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
idempotentReplayboolean是否复用了相同幂等请求结果。
waitTimedOutboolean等待窗口结束,后台任务仍继续执行。
messagestring等待或操作提示。

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

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

参数位置类型必填默认值说明
distillationIdpathstring是—蒸馏任务 ID。
scopequerystring否'user'user(默认)、agent、project。
userIdquerystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdquerystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdquerystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdquerystring否空串来源运行。
memorySubStoreIdquerystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
distillationobject蒸馏任务,含 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

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

参数位置类型必填默认值说明
distillationIdpathstring是—要重放的蒸馏任务 ID。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
distillationIdstring蒸馏查询标识。
jobIdstring任务标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
replayedboolean是否重放了已有蒸馏任务。

任务终态为 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 并发控制)。

参数位置类型必填默认值说明
knowledgeIdpathstring是—知识 ID。
expectedVersionbodyinteger是—目标知识/上下文的当前 CAS 版本,冲突后重新读取。
statusbodystring否—目标治理状态:candidate / shadow / user-active / agent-active / quarantine / deprecated。
validationStatusbodystring否—目标验证状态:pending / verified / conflicted / rejected。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
knowledgeobject知识对象,含 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

为托管知识写入遗忘标记,停止后续复用;该知识治理操作与主动删除单条记忆的处理方式不同。

参数位置类型必填默认值说明
knowledgeIdpathstring是—知识 ID。
expectedVersionbodyinteger是—目标知识/上下文的当前 CAS 版本,冲突后重新读取。
reasonbodystring否空串操作原因;上下文确认、重建、回滚时必填且非空。
sourcebodystring否'api'操作来源标记;不授予额外权限。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
knowledgeIdstring知识项标识。
versioninteger当前并发控制版本。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
metadataobject响应附带的元数据;知识遗忘含 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 归因)。

参数位置类型必填默认值说明
injectionIdbodystring是—统一召回返回的 injectionId,不能自行生成。
knowledgeIdbodystring是—被评的 Skill/Experience 知识 ID;Memory 与画像条目不可评。
revisionbodyinteger是—实际召回项的 revision,不是知识项 version。
feedbackTypebodystring是—positive、negative 或 not-relevant;仅对可反馈的经验/技能。
reasonCodebodystring否空串有界的原因代码(可选)。
idempotencyKeybodystring否空串同一次逻辑请求的幂等标识,也可用 Idempotency-Key 头;两者同时给出须一致。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
idstring本次反馈或观察记录标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
idempotentReplayboolean是否复用了相同幂等请求结果。
revisioninteger知识内容修订号。

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

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

参数位置类型必填默认值说明
knowledgeIdbodystring是—知识 ID。
revisionbodyinteger是—实际召回项的 revision,不是知识项 version。
sourceIdbodystring否空串形成目标知识的有效来源 ID,不能自报其他来源绕过校验。
injectionIdbodystring否空串统一召回返回的 injectionId,不能自行生成。
outcomebodystring是—观察结果:success / failure / not-applicable / security-violation。
verificationSourcebodystring否—已废弃:平台按认证来源推导可信来源。
toolNamebodystring否空串工具名。
toolVersionbodystring否空串工具版本。
toolSchemaVersionbodystring否空串工具 schema 版本。
errorFingerprintbodystring否空串有界的错误指纹。
evidencebodyobject是—有界的观察证据对象(必填)。
weightbodynumber否—已废弃:平台按认证来源推导可信权重。
observedAtbodystring否空串观察时间戳。
idempotencyKeybodystring否空串同一次逻辑请求的幂等标识,也可用 Idempotency-Key 头;两者同时给出须一致。
scopebodystring否'user'user(默认)、agent、project。
userIdbodystring否空串目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
agentIdbodystring否空串Agent 归属或过滤;知识接口仅 scope=agent 时提供且必填。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
runIdbodystring否空串来源运行。
memorySubStoreIdbodystring否空串只能选择当前项目已绑定子存储,不是可任意创建的 Space。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
idstring本次反馈或观察记录标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
idempotentReplayboolean是否复用了相同幂等请求结果。
revisioninteger知识内容修订号。

观察的可信来源和权重由认证主体决定,不能自报 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)提交画像更新。

参数位置类型必填默认值说明
userIdpathstring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
profileTypequerystring否'content'content(默认)或 topics。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
profileobject画像对象,含 profileContent/topics、version、rebuildStatus 等。
retrievedAtstring(时间)读取时刻。

请求示例:替换 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。

参数位置类型必填默认值说明
userIdpathstring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
profileTypebodystring否'content'content(默认)或 topics。
reasonbodystring否空串操作原因;上下文确认、重建、回滚时必填且非空。
sourcebodystring否'appbase_delete'操作来源标记;不授予额外权限。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
profileIdstring画像标识。
statusstring当前业务状态或任务状态,不能只依赖 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 整体替换。

参数位置类型必填默认值说明
pipelineIdbodystring否空串可选已发布 Pipeline ID,省略使用对应场景默认;2.9.0 SDK 未提供此参数,使用 HTTP。
userIdpathstring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
profileTypebodystring否'content'content(默认)或 topics。
messagesbodyarray是[]有效消息列表,role 与非空 content 必填;消息限制见对应操作说明。
sourceMemoryIdsbodyarray否[]仅 replace 支持,最多 100 条当前用户的有效记忆,不能代替新 messages。
sessionIdbodystring否空串可选会话标识,最多 128 UTF-8 字节;不替代权限。
modebodystring否'incremental'incremental(默认)或 replace。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
memoryobject记忆对象;包含 memoryId、version、content、归属与模型处理状态。
profileExtractionobject画像提取结果: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

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

参数位置类型必填默认值说明
pipelineIdbodystring否空串可选已发布 Pipeline ID,省略使用对应场景默认;2.9.0 SDK 未提供此参数,使用 HTTP。
userIdpathstring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
profileTypebodystring否'content'content(默认)或 topics。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
jobIdstring任务标识。
profileIdstring画像标识。
profileVersioninteger画像版本。
sourceCountinteger参与本次聚合的来源数量。

请求示例:替换 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

列出画像的证据源。

参数位置类型必填默认值说明
userIdpathstring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
profileTypequerystring否'content'content(默认)或 topics。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
profileTypestring画像类型 content/topics。
sourcesarray当前可见且仍有效的来源。
totalinteger符合当前查询条件的计数。
truncatedboolean结果或扫描是否因上限截断。

请求示例:替换 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 串,支持只校验不写入。

参数位置类型必填默认值说明
pipelineIdbodystring否空串可选已发布 Pipeline ID,省略使用对应场景默认;2.9.0 SDK 未提供此参数,使用 HTTP。
userIdbodystring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
formatbodystring否'jsonl'json 或 jsonl。
databodystring否空串JSON/JSONL 文本导入内容,与 records 二选一。
recordsbodyarray否[]结构化导入列表,最多 500 条;与 data 二选一。
dryRunbodyboolean否falsetrue 仅验证/预览,不写入业务数据;正式执行使用新的逻辑请求标识。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
importIdstring导入查询标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
jobIdstring任务标识。

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

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

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

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
importIdstring导入查询标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
jobobject异步任务对象,检查 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。

参数位置类型必填默认值说明
userIdbodystring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
formatbodystring否'jsonl'json 或 jsonl。
includeForgottenbodyboolean否false默认 false;额外敏感导出需系统授权,布尔值不代替权限。
includeVectorsbodyboolean否false默认 false;导出向量需系统授权。
includeRawSourcesbodyboolean否false默认 false;导出原始来源需系统授权。
modebodystring否'async'async(默认)或 sync。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
exportIdstring导出查询标识。
statusstring当前业务状态或任务状态,不能只依赖 HTTP 成功码。
jobobject异步任务对象,检查 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

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

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

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
jobobject异步任务对象,检查 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,直接返回数据)。

参数位置类型必填默认值说明
userIdquerystring是—目标用户 ID;服务端请求显式传业务用户,不通过 metadata 代替。
formatquerystring否'jsonl'json 或 jsonl。
modequerystring否'sync'仅 sync。
includeForgottenqueryboolean否false默认 false;额外敏感导出需系统授权,布尔值不代替权限。
includeVectorsqueryboolean否false默认 false;导出向量需系统授权。
includeRawSourcesqueryboolean否false默认 false;导出原始来源需系统授权。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
schemaVersioninteger导出结构版本。
formatstringjson 或 jsonl 格式。
mediaTypestring导出内容的媒体类型。
generatedAtstring(时间)导出生成时间。
datastring编码后的导出文本。
memoriesarray记忆对象数组。
profilesarray导出的画像集合。
jobsarray导出的任务集合。
vectorsarray按授权可选导出的向量投影。
sourcesarray当前可见且仍有效的来源。
metadataobject响应附带的元数据;知识遗忘含 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

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

参数位置类型必填默认值说明
routesbodyarray是[]投影重建必选 dense、sparse、graph 中的一种或多种,不重复。
cursorbodystring否空串上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。
limitbodyinteger否100本次返回或处理上限;有效范围见参数默认值与相应操作边界。
dryRunbodyboolean否falsetrue 仅验证/预览,不写入业务数据;正式执行使用新的逻辑请求标识。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
routesarray本次请求选定的投影路线。
dryRunboolean是否只做预校验或预览。
matchedinteger本次匹配的待处理数量。
scheduledinteger本次调度的任务数量。
conflictsinteger本次发生并发冲突的数量。
hasMorebooleantrue 时需要继续相同范围的下一批处理。
nextCursorstring下一页游标;空值表示没有后续页。

本次为有界投影修复,先 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

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

参数位置类型必填默认值说明
无————无业务请求参数。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
liveRecordsinteger校验范围内的存活记录数。
denseobjectDense 投影校验结果与就绪状态。
sparseobjectSparse 投影校验结果与就绪状态。
graphobjectGraph 投影校验结果与就绪状态。
repairRecommendedboolean是否建议执行受控修复。
limitationsarray本次校验的限制,不能忽略后宣称完整一致。
verifiedAtstring(时间)投影校验时刻。

请求示例:替换 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

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

参数位置类型必填默认值说明
无————无业务请求参数。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
visibleCountinteger当前可见记忆数量。
forgottenCountinteger已遗忘数量。
totalCountinteger记忆总数。
indexStatusobject按索引状态的记忆数量。
jobStatusobject按任务状态的数量。
fromstring(时间)本次统计的起始时间(如提供)。
tostring(时间)本次统计的结束时间(如提供)。

请求示例:替换 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

读取记忆质量报告。

参数位置类型必填默认值说明
无————无业务请求参数。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
visibleCountinteger当前可见记忆数量。
lowQualityCountinteger低质量记忆数量。
pendingIndexesinteger尚未就绪的索引数量。
issuesarray存在质量提示的记忆及 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

读取记忆活动时间线。

参数位置类型必填默认值说明
无————无业务请求参数。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
bucketsarray日期分桶,含 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

读取记忆会话聚合。

参数位置类型必填默认值说明
无————无业务请求参数。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
sessionsarray会话聚合列表。
totalinteger符合当前查询条件的计数。

请求示例:替换 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

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

参数位置类型必填默认值说明
jobIdquerystring否空串精确匹配的记忆任务 ID。
queryquerystring否空串审计内容检索关键字,可省略。
operationquerystring否空串按记忆操作名过滤(如 createMemory)。
outcomequerystring否空串按请求结果过滤:success / failure。
limitqueryinteger否25本次返回或处理上限;有效范围见参数默认值与相应操作边界。
cursorqueryinteger否0上一页返回的 nextCursor,原样传回;审计 cursor 是非负整数偏移。

返回字段(只列公开结构,按条件返回的字段可能省略):

字段类型说明
auditsarray与过滤条件匹配的审计记录。
totalinteger符合当前查询条件的计数。
nextCursorinteger / null下一页游标;空值表示没有后续页。
scannedinteger为得到结果实际扫描的数量。
truncatedboolean结果或扫描是否因上限截断。

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}/approvememories.write + 管理权限expectedVersion、reason(body)批准候选知识修订并晋升为线上 active 状态,供 /recall 与 /experiences/search、/skills/search 召回。
POST /v1/memory/memories/knowledge/reviews/{reviewId}/rejectmemories.write + 管理权限expectedVersion、reason(body)驳回低质量或存在冲突的候选知识修订,归档审批单且不污染线上知识库。
GET /v1/memory/memories/knowledge/{knowledgeId}/revisionsmemories.readknowledgeId(path)、limit、cursor(query)列出指定经验或技能(knowledgeId)的全部不可变历史修订版本列表。
GET /v1/memory/memories/knowledge/{knowledgeId}/diffmemories.readfromRevision、toRevision(query, integer)对比同一条经验/技能在两个历史修订号之间的结构化字段与正文差异。
POST /v1/memory/memories/knowledge/{knowledgeId}/rollbackmemories.write + 管理权限expectedVersion、targetRevision、reason(body)将线上经验或技能原子回滚至指定的历史已验证修订号(生成新的追加修订记录)。

自进化审批、Diff 与回滚请求示例:

# 1. 查看并人工微调待审批的蒸馏技能候选(GET / PATCH /v1/memory/memories/knowledge/reviews/{reviewId})
curl -sS -X PATCH "https://appbuild-sit.oceanbase.com/v1/memory/memories/knowledge/reviews/rev_distill_0089" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -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 视图名称校准"
}'

# 2. 批准审批单上线(POST .../reviews/{reviewId}/approve;若驳回则调用 POST .../reviews/{reviewId}/reject)
curl -sS -X POST "https://appbuild-sit.oceanbase.com/v1/memory/memories/knowledge/reviews/rev_distill_0089/approve" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: approve-rev-0089-v1" \
  --data '{
  "expectedVersion": 2,
  "reason": "经 SRE 团队复核验证通过,准予晋升为线上技能"
}'

# 3. 查询知识修订列表、对比版本差异并在异常时回滚(GET .../revisions、GET .../diff、POST .../rollback)
curl -sS -X GET "https://appbuild-sit.oceanbase.com/v1/memory/memories/knowledge/knw_skill_01/diff?fromRevision=3&toRevision=4" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>"

curl -sS -X POST "https://appbuild-sit.oceanbase.com/v1/memory/memories/knowledge/knw_skill_01/rollback" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -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):

1. 四类记忆流水线 API(/v1/memory/pipelines*)

方法与路径核心参数用途说明
GET /v1/memory/pipelinesscenario(query,可选:add_memory \profile \distillation \forgetting)列出当前项目下的四类记忆流水线定义、当前发布版本与默认绑定状态。
POST /v1/memory/pipelinesname、scenario(必填,枚举:add_memory \profile \distillation \forgetting)、spec(DAG 节点与模型算子配置)创建新的记忆处理流水线草稿(Draft)。
PATCH /v1/memory/pipelines/{id}name、spec、expectedVersion(body)更新指定流水线的算子参数、提示词模板或遗忘衰减阈值配置。
POST /v1/memory/pipelines/{id}/validatedryRun(boolean)、sampleUserId(如 "user_zhangwei_001")、simulatedDays(number)校验流水线拓扑合法性;当 scenario="forgetting" 时支持单用户艾宾浩斯遗忘 Dry-run 预览,按公式 $R = e^{-t / (S_0 \cdot 2^{k \cdot n} \cdot w)}$ 计算每条短期/工作记忆的保留分(Retention Score),预览将被降级或遗忘的记忆明细而不实际删除数据。
POST /v1/memory/pipelines/{id}/publishexpectedVersion、releaseNotes(body)将校验通过的流水线草稿发布为不可变生产版本。
PUT /v1/memory/pipelines/defaultscenario(add_memory \profile \distillation \forgetting)、pipelineId、version将指定已发布流水线设为该项目对应场景的默认执行流水线。

艾宾浩斯遗忘流水线编排与单用户 Dry-run 预览示例:

# 1. 创建或更新艾宾浩斯遗忘流水线(scenario=forgetting)
curl -sS -X POST "https://appbuild-sit.oceanbase.com/v1/memory/pipelines" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "企业客服短期记忆艾宾浩斯遗忘流水线",
  "scenario": "forgetting",
  "spec": {
    "halfLifeDays": 7.0,
    "rehearsalBoostFactor": 0.35,
    "importanceFloor": 0.75,
    "archiveThreshold": 0.35,
    "forgetThreshold": 0.15,
    "targetMemoryTypes": ["working", "short_term"]
  }
}'

# 2. 执行单用户艾宾浩斯遗忘 Dry-run 校验预览(POST /v1/memory/pipelines/{id}/validate)
curl -sS -X POST "https://appbuild-sit.oceanbase.com/v1/memory/pipelines/pipe_forgetting_01/validate" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  --data '{
  "dryRun": true,
  "sampleUserId": "user_zhangwei_001",
  "simulatedDays": 14
}'

# 3. 发布流水线并绑定为 forgetting 场景默认流水线(POST .../publish 与 PUT /v1/memory/pipelines/default)
curl -sS -X POST "https://appbuild-sit.oceanbase.com/v1/memory/pipelines/pipe_forgetting_01/publish" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  --data '{
  "expectedVersion": 1,
  "releaseNotes": "启用 7 天半衰期与 0.15 遗忘阈值"
}'

curl -sS -X PUT "https://appbuild-sit.oceanbase.com/v1/memory/pipelines/default" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  --data '{
  "scenario": "forgetting",
  "pipelineId": "pipe_forgetting_01",
  "version": 1
}'

2. 六大配置命名空间 API(GET/PUT /v1/projects/{projectId}/memory/config/{namespace})

项目级记忆配置按职责划分为六个独立命名空间(namespace 枚举:runtime、prompt、policy、retention、provider、evolution),每次 PUT 更新均需携带从 GET 响应取得的 expectedConfigVersion 及 If-Match 请求头:

命名空间(namespace)核心配置项说明
runtimerecallFusion(五路融合权重与 RRF 参数)、progressiveRecallEnabled、defaultTokenBudget、maxDeadlineMs(450)控制混合检索路由融合、渐进式召回超时围栏与并发度。
promptfactExtractionPrompt、profileMergePrompt、dreamingSynthesisPrompt、distillationPrompt自定义事实抽取、画像聚合、上下文做梦与经验技能蒸馏提示词。
policydefaultScope、allowedFilterFields、strictPrivateIsolation、defaultHandlingPolicy记忆访问边界、允许过滤的元数据白名单与敏感级别策略。
retentionworkingTtlHours、shortTermHalfLifeDays、forgettingCron、protectLongTerm工作记忆 TTL、短期记忆艾宾浩斯衰减周期与定时遗忘调度策略。
providerchatProviderRef(如 "project:dashscope-prod")、chatModel("qwen-plus")、embeddingModel("text-embedding-v3")、rerankModel("qwen3.7-text-rerank")、visionModel("qwen-vl-max")、sparseMode("auto")钉定记忆模块专属的 LLM Gateway 模型与模型生成稀疏向量开关。
evolutionautoDistillEnabled、requireHumanReview(true \false)、autoApproveConfidenceThreshold、dreamingSchedule控制经验/技能自进化蒸馏触发条件、人工审批门禁与做梦整合周期。

**读取与 CAS 更新配置命名空间示例(expectedConfigVersion + If-Match)**:

# 1. 读取项目记忆 runtime 命名空间配置与当前版本号
curl -sS -X GET "https://appbuild-sit.oceanbase.com/v1/projects/enterprise-ai-hub-210/memory/config/runtime" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>"

# 2. 携带 If-Match 与 expectedConfigVersion 原子更新 runtime 配置
curl -sS -X PUT "https://appbuild-sit.oceanbase.com/v1/projects/enterprise-ai-hub-210/memory/config/runtime" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <project-api-key>" \
  -H "If-Match: \"4\"" \
  -H "Content-Type: application/json" \
  --data '{
  "expectedConfigVersion": 4,
  "config": {
    "recallFusion": {
      "mode": "hybrid",
      "sparse": "auto"
    },
    "progressiveRecallEnabled": true,
    "defaultTokenBudget": 2000,
    "maxDeadlineMs": 450
  }
}'

错误与边界

未完成的任务继续按自己的状态接口查询。不要重新创建一条请求来代替轮询,也不把示例评分或数量写成业务断言。

与 Server SDK 的对应

端点清单逐行列出 Memory service 方法。2.9.0 Node.js SDK 返回宽类型对象,应用需按本文契约检查响应;完整可运行示例见记忆 SDK 操作。

适用版本

服务端接口为 Agentbase 2.10.0,Node.js 调用示例使用 agentbase-node-sdk@2.9.0。项目生命周期、配置、Pipeline 与人工确认属于管理面;本页不将其列为普通项目 API Key 接口。SDK 版本与服务端版本分开选择,不以文档更新暗示新 SDK 已发布。

事实源