Docs
Contents

Memory API

This page applies to project-level Memory in Agentbase 2.10.0. For first-time integration, we recommend completing project and SDK preparation first, then running the complete SDK operation example.

Service and resource boundaries

The project-level memory system (Memory) runs on the OceanBase Shared V2 storage architecture, providing full-lifecycle HTTP interfaces for intelligent customer service and enterprise agents: long-term factual memory, conversational reasoning extraction, user profiles, Context Dreaming integration, and Experience & Skill Distillation. Project start/stop and Pipeline orchestration belong to the management plane; business reads/writes, retrieval, sharing, import/export, and request auditing are all performed through the 54 project-level APIs defined on this page.

Resources and Base Paths

The API base URL is the https://<agentbase-host>/v1 provided by the current project. The paths below already include /v1; do not duplicate it when concatenating. The project must have Memory enabled with status active and data ready; enabling and configuration are done in the Console. Only Shared V2 projects are supported; there is no need to create a Memory Resource or fill in a Space ID.

All resource identifiers are handled as strings. Memory uses memoryId, skills/experience use knowledgeId, write tasks use jobId, and distillation queries use distillationId; they are not interchangeable.

Authentication and Permissions

Every business request carries X-Appwrite-Project and X-Appwrite-Key; when there is a JSON body, use Content-Type: application/json. API Keys must be stored only on trusted servers. For general conventions see Authentication and Access; Memory's DELETE body and cursor pagination are governed by this page.

Use memories.read for reading, memories.write for writes and write-task queries, memories.delete for forgetting, memories.share for sharing, and memories.export for export. Mixed batches check the required permission per item; context governance and knowledge management also require the management access capability. Ordinary project users cannot gain system permissions through request parameters.

Request and Response Conventions

Successful responses return the business object directly, without a success/data wrapper. HTTP 202 means accepted and does not guarantee the business operation is complete. Even after a task succeeds, check result.status and per-item results; partial_failed must not be treated as complete success.

Lists generally use limit/cursor; pass nextCursor back verbatim for the next page; the audit cursor is an integer offset. Memory list also accepts SDK Query expressions, but they must not conflict with directly submitted pagination parameters.

The SDK lists agentbase-node-sdk@2.9.0 as an existing method. New server-side parameters such as media/pipelineId are not yet included in this version's SDK signatures; use the HTTP contract on this page, and do not stuff extra properties into SDK objects and assume they have been sent.

Endpoint overview

The memory system exposes 54 business operations in total, grouped by responsibility: memory CRUD and batch write tasks (/v1/memory/memories*, /v1/memory/jobs/{jobId}), multimodal search and unified knowledge retrieval (/search, /recall), skill and experience management (/skills*, /experiences*), context dreaming governance (/contexts*), experience/skill distillation (/distillations*), user profile extraction (/users/{userId}/profile*), and import/export plus session auditing (/imports*, /exports*, /sessions, /audits).

Endpoint List

Method and PathSDK Method
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

Endpoint details

The endpoints strictly distinguish synchronous queries (200 OK) from asynchronous extraction/distillation/rebuild tasks (202 Accepted returns jobId); write operations use Idempotency-Key to guarantee retry idempotency, and update and forget operations support optimistic concurrency control (CAS) based on expectedVersion.

Requests and Responses

The examples below show single operations. Before executing batch or knowledge governance operations, verify scopes; DELETE business parameters use a JSON body.

POST /v1/memory/memories

SDK:Memory.create · scope:memories.write

Create a memory: write directly, or with infer=true let the model perform fact extraction, derivation, and cross-type deduplication.

ParameterLocationTypeRequiredDefaultDescription
pipelineIdbodystringNoEmpty stringOptional published Pipeline ID; if omitted, the scenario default is used; 2.9.0 SDK does not provide this parameter, use HTTP.
contentbodystringNoEmpty stringBody text; for non-empty input, at most 20,000 UTF-8 bytes; see the write notes for the combination with messages/media.
messagesbodyarrayNo[]Valid message list; role and non-empty content are required; see the corresponding operation notes for message limits.
mediabodyobjectNo{}Same-project Storage reference {bucketId,fileId}; see the multimodal notes on this page for format, size, and permissions; 2.9.0 SDK does not provide this parameter.
userIdbodystringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
runIdbodystringNoEmpty stringOwning run ID (optional); not used as a fallback for sessionId.
sessionIdbodystringNoEmpty stringOptional session identifier (up to 128 UTF-8 bytes); when infer=true, the server automatically associates the most recent 12 turns of the same session (12-turn context) history to assist coreference resolution and fact extraction; does not replace permissions.
scopebodystringYes—Visibility isolation domain: strict_private (visible only to the caller and the specified owner, not entering the accessible shared union), private, user, group (metadata.groupId must also be passed), project.
sensitivitybodystringNo'normal'normal (default), confidential, restricted; secret will be rejected.
handlingPolicybodystringNo'standard'standard (default, performs full model extraction and vectorization), no_embedding (stores only text/structured metadata, no vectors generated), no_model (purely deterministic persistence, requires infer=false and rejects media input).
memoryTypebodystringYes—Memory time-decay tier or business classification: core supports working (working memory, high-frequency session-level read/write), short_term (short-term memory, regulated by the Ebbinghaus forgetting half-life), long_term (long-term memory, sedimentation of high-importance facts), and business-defined custom types (e.g. preference).
recordKindbodystringYes—Record kind: conversation (raw conversation), fact (atomic facts) or action (executed actions); combined with the cognitive hierarchy L0 (raw source evidence) → L1 (atomic fact memory) → L2 (contextual abstract topics) → L3 (global domain synthesis) forming a four-layer cognitive architecture.
metadatabodyobjectNo{}Custom metadata object (may carry business tags such as cognitiveLayer: "L0"–"L3", importance: 0.0–1.0); cannot directly overwrite system forgetting or governance internal fields.
inferbodybooleanNotrueBy default true (performs fact extraction, conflict resolution and ADD/UPDATE/DELETE/NONE decisions via LLM); false performs a deterministic direct write.
reRememberbodybooleanNofalseWhen re-learning previously forgotten content, you must explicitly set reRemember: true and carry Idempotency-Key; creates a new version of the memory rather than directly reviving the archived old source.
asyncbodybooleanNo—Text defaults to infer; multimodal media: {bucketId, fileId} is always processed asynchronously and cannot be explicitly set to false.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
pipelineobject / nullReceipt of the pipeline actually used and the fixed released version.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
modestringThe processing method used this time, e.g. simple/inferred.
sourceIdstringImmutable source identifier.
jobIdstringTask identifier.
memoryobject / nullMemory object; contains memoryId, version, content, ownership and model processing status.
actionsarrayEach item contains index, action, status, memoryId, etc.; action is ADD/UPDATE/DELETE/NONE.
errorCodestringOmit-able error classification, e.g. LLM_TIMEOUT; returned when error information exists.
reasonstringReason for this operation or failure.
retryablebooleanWhether the failure can still be retried; does not replace task status.
fallbackobject / nullControlled fallback information: strategy is a string; errorCode and reason are omit-able strings.
idempotencyKeystringIdempotency identifier of this logical write.

Plain text defaults to infer=true and async=true; for deterministic direct writes, explicitly set infer=false and async=false. At most 100 messages per request, each content up to 10,000 UTF-8 bytes, and the total length of the source text including roles/separators up to 20,000 UTF-8 bytes. Group-scope writes must carry metadata.groupId. Synchronous result status is completed, partial_failed or failed; inferred actions are ADD/UPDATE/DELETE/NONE. Asynchronous acceptance is HTTP 202, returning jobId and Location.

For each item in actions, errorCode and reason are also omit-able strings, and retryable is an omit-able boolean. Error fields appear only when the corresponding information exists; do not assume a successful response carries an empty error object; when a fallback occurs, also check the fallback strategy and per-item results.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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
}'

Multimodal and multi-tier inferred write example (infer=true, sessionId with 12-turn context, media: {bucketId, fileId} and 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
}'

Example of key fields (IDs, content, and scores are illustrative only):

{
  "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

List memory records visible to the current caller (opaque cursor pagination).

ParameterLocationTypeRequiredDefaultDescription
cursorquerystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset.
limitqueryintegerNo—Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries.
filterqueryobjectNo—Structured filter object; fields must be within the project allowlist.
queriesqueryarrayNo[]SDK Query filter expressions; pagination conditions that do not conflict with direct parameter submission.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
accessModequerystringNo'owned'owned (default) or accessible; the latter is still subject to actual visibility permissions.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
memoriesarrayArray of memory objects.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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'

Example of key fields (IDs, content, and scores are illustrative only):

{
  "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

Get a single memory by ID.

ParameterLocationTypeRequiredDefaultDescription
memoryIdpathstringYes—Target memory ID.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
memoryobjectMemory object; contains memoryId, version, content, ownership and model processing status.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

curl -sS -X GET "https://<agentbase-host>/v1/memory/memories/{memoryId}" \
  -H "X-Appwrite-Project: <project-id>" \
  -H "X-Appwrite-Key: <project-api-key>"

Example of key fields (IDs, content, and scores are illustrative only):

{
  "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

Update memory text/metadata by ID, using version as a CAS optimistic lock.

ParameterLocationTypeRequiredDefaultDescription
memoryIdpathstringYes—Target memory ID.
versionbodyintegerYes—The most recently fetched memory version, a positive integer; re-read after a conflict.
contentbodystringNo—Updated non-empty content, up to 20,000 UTF-8 bytes.
metadatabodyobjectNo{}Custom metadata object; cannot set system forgetting or governance fields.
retentionPolicybodystringNo—Retention policy; the current enumeration only includes default.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
memoryobjectMemory object; contains memoryId, version, content, ownership and model processing status.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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"
}'

Example of key fields (IDs, content, and scores are illustrative only):

{
  "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

Actively delete a single memory and its retrieval data; irreversible; the success result of this endpoint is still indicated by status=forgotten.

ParameterLocationTypeRequiredDefaultDescription
memoryIdpathstringYes—Target memory ID.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.
reasonbodystringNoEmpty stringReason for the operation; required and non-empty for context confirmation, rebuild, and rollback.
sourcebodystringNo'appbase_delete'Operation origin marker; grants no additional permissions.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
memoryIdstringFull string identifier of the memory.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.

Returns status=forgotten. Active deletion clears the memory record and retrieval projections; source evidence and audit logs may still be retained, and Storage original files are not deleted along with it; not controlled by the adaptive archival “permanent forgetting” switch. Subsequent create/update of the same content may return 409 due to forgotten-protection; when re-learning is truly needed, use create with reRemember=true and a new idempotency key to create new evidence.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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"
}'

Example of key fields (IDs, content, and scores are illustrative only):

{
  "memoryId": "mem-example",
  "status": "forgotten"
}

DELETE /v1/memory/memories

SDK:Memory.deleteMany · scope:memories.delete

Bounded batch forgetting: each round processes at most limit (≤500) items; when hasMore=true, call in a loop until everything is cleared.

ParameterLocationTypeRequiredDefaultDescription
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.
limitbodyintegerNo100Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries.
reasonbodystringNoEmpty stringReason for the operation; required and non-empty for context confirmation, rebuild, and rollback.
sourcebodystringNo'appbase_delete_worker'Operation origin marker; grants no additional permissions.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
processedintegerNumber of records processed in this batch.
forgottenintegerNumber of items successfully forgotten in this batch.
failedintegerNumber of failures; check the per-item errors.
hasMorebooleanWhen true, continue processing the next batch over the same range.
itemsarrayPer-item results; see the corresponding operation description on this page for the structure.

limit defaults to 100 with a maximum of 500; the service may process fewer. When hasMore=true, continue over the same range and handle failed and per-item errors. Avoid running project-scope cleanup with userId omitted.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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:按批次各项操作授权

Execute mixed create / delete / search operations in bounded batches.

ParameterLocationTypeRequiredDefaultDescription
itemsbodyarrayYes[]A bounded operations array; each item carries the corresponding payload according to operation (one of create/delete/search).

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
itemsarrayPer-item results; see the corresponding operation description on this page for the structure.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.

items holds at most 50 entries. The response returns status and items; check status/publicCode/retryable per item, and do not read a non-existent results field.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Query the execution status and result of an asynchronous memory write task.

ParameterLocationTypeRequiredDefaultDescription
jobIdpathstringYes—The write task ID (returned in the memory creation async response).

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
pipelineobject / nullReceipt of the pipeline actually used and the fixed released version.
jobIdstringTask identifier.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
modestringThe processing method used this time, e.g. simple/inferred.
sourceIdstringImmutable source identifier.
attemptCountintegerThe number of execution attempts made so far.
maxAttemptsintegerThe retry budget cap.
errorCodestringAn optional error classification, e.g. LLM_TIMEOUT; returned when an error message exists, and tasks being retried may also carry it.
reasonstringReason for this operation or failure.
retryablebooleanWhether the failure can still be retried; does not replace task status.
resultobject / nullThe final business result; even after the scheduling status is succeeded, check result.status.
createdAtstring (time)Creation time.
updatedAtstring (time)Last update time.
startedAtstring (time)The time execution first started.
completedAtstring (time)The time the task reached a terminal state.
queueDurationMsnumber / nullQueuing duration; null if not yet started.
executionDurationMsnumber / nullDuration from first start to terminal state, including retry backoff; null if not finished.
totalDurationMsnumber / nullDuration from creation to terminal state; null if not finished.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

curl -sS -X GET "https://<agentbase-host>/v1/memory/jobs/{jobId}" \
  -H "X-Appwrite-Project: <project-id>" \
  -H "X-Appwrite-Key: <project-api-key>"

Example of key fields (IDs, content, and scores are illustrative only):

{
  "jobId": "job-example",
  "status": "succeeded",
  "retryable": false,
  "result": {
    "status": "completed",
    "mode": "inferred",
    "actions": [
      {
        "index": 0,
        "action": "ADD",
        "status": "completed",
        "memoryId": "mem-example"
      }
    ]
  }
}

The key fields of a failed task are shown below; errorCode in both the task and result is a string. Error fields not present may be omitted, and must not be read as empty objects.

{
  "jobId": "job-failed-example",
  "status": "failed",
  "errorCode": "LLM_REQUEST_REJECTED",
  "reason": "模型请求被拒绝",
  "retryable": false,
  "result": {
    "status": "failed",
    "mode": "inferred",
    "errorCode": "LLM_REQUEST_REJECTED",
    "reason": "模型请求被拒绝"
  }
}

In a partial failure, result.status is partial_failed; check every actions item and do not resubmit successful actions as new writes. Only the key fields of the business result are shown below; errors may also exist only in failed actions without a top-level 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

List the immutable evidence sources (provenance) associated with a memory.

ParameterLocationTypeRequiredDefaultDescription
memoryIdpathstringYes—Target memory ID.
cursorquerystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset.
limitqueryintegerNo25Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
sourcesarraySources currently visible and still valid.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

List all effective read grants for a memory.

ParameterLocationTypeRequiredDefaultDescription
memoryIdpathstringYes—Target memory ID.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
sharesarrayList of memory sharing records.
totalintegerCount of items matching the current query conditions.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Grant read permission for a single memory to a user or group.

ParameterLocationTypeRequiredDefaultDescription
memoryIdpathstringYes—Target memory ID.
subjectTypebodystringYes—user or group.
subjectIdbodystringYes—The ID of the user or group being granted read access.
expiresAtbodystringNoEmpty stringSharing expiration time in ISO 8601 format.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
shareobjectThe sharing object.
changedbooleanWhether this operation changed the record.
resourcePolicyRevisionintegerThe sharing policy version after this operation.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Revoke a memory read grant.

ParameterLocationTypeRequiredDefaultDescription
memoryIdpathstringYes—Target memory ID.
shareIdpathstringYes—The ID of the sharing grant to revoke.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
shareIdstringThe sharing record identifier.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
changedbooleanWhether this operation changed the record.
resourcePolicyRevisionintegerThe sharing policy version after this operation.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Hybrid retrieval of memory records: dense / sparse / full-text / graph routing is fused according to the project runtime.recallFusion configuration.

ParameterLocationTypeRequiredDefaultDescription
querybodystringNoEmpty stringNatural-language query; image queries may omit text, other retrieval requires non-empty.
searchMode (or mode)bodystringNo'hybrid'Five-way hybrid retrieval mode: hybrid (default; fuses vectors, keywords, sparse vectors, knowledge graph, and profile routing), vector, keyword, graph, profile.
retrievalbodyobjectNo{}Fine-grained retrieval strategy overrides: supports model-generated sparse vectors retrieval.sparse: true | false | "auto" and progressive retrieval retrieval.strategy: "progressive", entryLevel: "auto"|"overview"|"context"|"fact"|"evidence", maxDepth: 2, tokenBudget: 1200, deadlineMs: 450, expansionToken: "<token>".
mediabodyobjectNo{}Same-project Storage reference {bucketId,fileId}; see the multimodal notes on this page for format, size, and permissions; 2.9.0 SDK does not provide this parameter.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
runIdbodystringNoEmpty stringFilter by run.
scopebodystringNoEmpty stringprivate, strict_private, user, group, project.
memoryTypebodystringNoEmpty stringThe caller's business type; inferred writes preserve the source and generate derived facts.
recordKindbodystringNoEmpty stringconversation, fact, or action.
filterbodyobjectNo—Structured filter object; fields must be within the project allowlist.
limitbodyintegerNo0Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range.
cursorbodystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; audit cursors are non-negative integer offsets.
sortbodystringNoEmpty stringSort mode.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
groupIdbodystringNoEmpty stringGroup/entity boundary filter.
accessModebodystringNo'owned'owned (default) or accessible; the latter is still limited by actual visibility permissions.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
itemsarrayPer-item results; see the corresponding operation description on this page for the structure.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.
rewriteTraceobjectQuery rewrite information.
degradedobjectDegradation information for this retrieval, to be checked by the caller.
progressiveobject / nullTiered results when progressive is selected.

Regular results are located at items[].memory; score and scoreBreakdown are on each result item. Check degraded and rewriteTrace. hybrid is the default mode; vector, sparse, keyword, and graph are optional.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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"
}'

Five-way hybrid retrieval + model-generated sparse vectors + Progressive Recall request example:

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"
}'

Example of key fields (IDs, content, and scores are illustrative only):

{
  "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

Injection-oriented memory retrieval: retrieve memories, profiles, skills, and experiences within a unified token budget, and return injection results carrying injectionId for feedback attribution.

ParameterLocationTypeRequiredDefaultDescription
querybodystringYes—A non-empty natural-language query.
kindsbodyarrayNo[]memory, profile, skill, experience, without duplicates; all by default.
limitbodyintegerNo—Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range.
tokenBudgetbodyintegerNo—Unified retrieval defaults to 4096, with a range of 1–32768.
retrievalbodyobjectNo{}Override retrieval routes per request; sparse=false may be set. See the description for progressive parameters.
accessModebodystringNo'owned'owned (default) or accessible; the latter is still limited by actual visibility permissions.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
injectionIdstringThe injection identifier for this context, to be reused when providing feedback.
contextstringThe context that can be used to assemble the model request, or the context governance result.
itemsarrayPer-item results; see the corresponding operation description on this page for the structure.
tokenBudgetintegerThe token budget for this context.
usedTokensintegerThe number of context tokens actually used this time.
degradedobjectDegradation information for this retrieval, to be checked by the caller.

Returns context, items, and usedTokens, without total. Only experience/skill results with feedbackEligible=true can receive feedback; save the same injectionId, knowledgeId, and revision. Retrieval does not automatically execute skills or generate a final chat answer.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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"
}'

Example of key fields (IDs, content, and scores are illustrative only):

{
  "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

List skills in an active verification state.

ParameterLocationTypeRequiredDefaultDescription
cursorquerystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset.
limitqueryintegerNo—Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run filter.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
itemsarrayPer-item results; see the corresponding operation description on this page for the structure.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Retrieve active, verified skills by semantic search.

ParameterLocationTypeRequiredDefaultDescription
querybodystringYes—A non-empty natural-language query.
cursorbodystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; audit cursors are non-negative integer offsets.
limitbodyintegerNo—Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range.
retrievalbodyobjectNo{}Override retrieval routes per request; sparse=false may be set. See the description for progressive parameters.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
itemsarrayPer-item results; see the corresponding operation description on this page for the structure.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.
degradedobjectDegradation information for this retrieval, to be checked by the caller.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Get details of a single skill by ID.

ParameterLocationTypeRequiredDefaultDescription
knowledgeIdpathstringYes—Skill knowledge ID.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
skillobjectSkill knowledge object.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

List the immutable evidence sources associated with a skill.

ParameterLocationTypeRequiredDefaultDescription
knowledgeIdpathstringYes—Skill knowledge ID.
cursorquerystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset.
limitqueryintegerNo25Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
sourcesarraySources currently visible and still valid.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

List experiences that are in the active-verified state.

ParameterLocationTypeRequiredDefaultDescription
cursorquerystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset.
limitqueryintegerNo—Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
itemsarrayPer-item results; see the corresponding operation description on this page for the structure.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Retrieve active, verified experiences by semantic search.

ParameterLocationTypeRequiredDefaultDescription
querybodystringYes—A non-empty natural-language query.
cursorbodystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; audit cursors are non-negative integer offsets.
limitbodyintegerNo—Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range.
retrievalbodyobjectNo{}Override retrieval routes per request; sparse=false may be set. See the description for progressive parameters.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
itemsarrayPer-item results; see the corresponding operation description on this page for the structure.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.
degradedobjectDegradation information for this retrieval, to be checked by the caller.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Get details of a single experience by ID.

ParameterLocationTypeRequiredDefaultDescription
knowledgeIdpathstringYes—Experience knowledge ID.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
experienceobjectExperience knowledge object.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

List the immutable evidence sources associated with an experience.

ParameterLocationTypeRequiredDefaultDescription
knowledgeIdpathstringYes—Experience knowledge ID.
cursorquerystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset.
limitqueryintegerNo25Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
sourcesarraySources currently visible and still valid.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

List governance context aggregates (filter by scope/locator key, observe the shadow → active lifecycle).

ParameterLocationTypeRequiredDefaultDescription
statusquerystringNoEmpty stringFilter by lifecycle state: shadow / quarantine / stale / user-active / agent-active / deprecated.
kindquerystringNoEmpty stringFilter by tier: memory_topic / memory_episode / memory_state / memory_overview.
cursorquerystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset.
limitqueryintegerNo—Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
contextsarrayList of currently visible context aggregates.
nextCursorstringCursor for the next page; an empty value means there are no further pages.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Get a single governance context aggregate by ID.

ParameterLocationTypeRequiredDefaultDescription
contextIdpathstringYes—Context knowledge ID.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
contextobjectContext usable for assembling model requests, or a context governance result.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Scan changed memories and schedule Dreaming runs (202 asynchronous).

ParameterLocationTypeRequiredDefaultDescription
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
changedintegerWhether this operation changed records.
scheduledintegerNumber of tasks scheduled in this operation.
watermarkstringScan progress watermark.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Query the Dreaming watermark and task status.

ParameterLocationTypeRequiredDefaultDescription
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
statusobjectCurrent business status or task status; do not rely solely on the HTTP success code.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Confirm a verified shadow context as active (CAS concurrency control).

ParameterLocationTypeRequiredDefaultDescription
contextIdpathstringYes—Context knowledge ID.
expectedVersionbodyintegerYes—Current CAS version of the target knowledge/context; re-read after a conflict.
reasonbodystringYes—Reason for the operation; required and must be non-empty for context confirmation, rebuild, and rollback.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
contextobjectContext usable for assembling model requests, or a context governance result.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Enqueue a single context for rebuild (202 asynchronous).

ParameterLocationTypeRequiredDefaultDescription
contextIdpathstringYes—Context knowledge ID.
reasonbodystringYes—Reason for the operation; required and must be non-empty for context confirmation, rebuild, and rollback.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
jobIdstringTask identifier.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Roll back an active context to an earlier verified revision.

ParameterLocationTypeRequiredDefaultDescription
contextIdpathstringYes—Context knowledge ID.
expectedVersionbodyintegerYes—Current CAS version of the target knowledge/context; re-read after a conflict.
targetRevisionbodyintegerYes—Target historical revision number for the context rollback; does not replace expectedVersion.
reasonbodystringYes—Reason for the operation; required and must be non-empty for context confirmation, rebuild, and rollback.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
contextobjectContext usable for assembling model requests, or a context governance result.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

List distillation jobs (can be filtered by status).

ParameterLocationTypeRequiredDefaultDescription
statusquerystringNoEmpty stringFilter by job status: queued / running / succeeded / partial_failed / failed / dead.
cursorquerystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset.
limitqueryintegerNo—Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
distillationsarrayArray of distillation jobs.
nextCursorstringCursor for the next page; an empty value means there are no further pages.
totalintegerCount of items matching the current query conditions.

Terminal job states are succeeded, partial_failed, failed, and dead; results use distillation.counts and outputs, and generating a candidate does not mean it has passed human confirmation. Queries use distillationId, not the ordinary write /jobs endpoint.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Submit bounded evidence for Experience/Skill distillation; mode=wait waits up to 20 seconds for a terminal state, async returns immediately.

ParameterLocationTypeRequiredDefaultDescription
pipelineIdbodystringNoEmpty stringOptional published Pipeline ID; if omitted, the scenario default is used; 2.9.0 SDK does not provide this parameter, use HTTP.
sourceIdbodystringNoEmpty stringPersisted source ID; choose either this or inline messages/toolEvents.
sourceTypebodystringNoEmpty stringUsed together with sourceId: conversation, tool-trace, execution-log.
messagesbodyarrayNo[]Valid message list; role and non-empty content are required; see the corresponding operation notes for message limits.
toolEventsbodyarrayNo[]At most 100 tool evidence items; may be provided together with messages, but not simultaneously with sourceId.
modebodystringNo'async'async (default) or wait (waits at most 20 seconds).
idempotencyKeybodystringNoEmpty stringIdempotency identifier for the same logical request; the Idempotency-Key header may also be used; if both are given they must match.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
distillationIdstringDistillation query identifier.
jobIdstringTask identifier.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
idempotentReplaybooleanWhether the result of an identical idempotent request was reused.
waitTimedOutbooleanWhether the wait window ended while the background job continues to run.
messagestringWait or operation hint.

sourceId/sourceType and inline messages/toolEvents are mutually exclusive: choose one. messages allows at most 100 items, each at most 16 KiB, totaling at most 512 KiB; toolEvents allows at most 100 items, each arguments/result JSON at most 64 KiB, with events totaling at most 1 MiB. async returns HTTP 202 immediately by default; wait lasts at most 20 seconds, and on timeout still returns 202, waitTimedOut=true, and Location, without canceling the job.

Terminal job states are succeeded, partial_failed, failed, and dead; results use distillation.counts and outputs, and generating a candidate does not mean it has passed human confirmation. Queries use distillationId, not the ordinary write /jobs endpoint.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Query the status and output references of a distillation job.

ParameterLocationTypeRequiredDefaultDescription
distillationIdpathstringYes—Distillation job ID.
scopequerystringNo'user'user (default), agent, project.
userIdquerystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdquerystringNoEmpty stringAgent ownership or filter; provided and required on knowledge endpoints only when scope=agent.
sessionIdquerystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdquerystringNoEmpty stringSource run.
memorySubStoreIdquerystringNoEmpty stringOnly sub-stores already bound to the current project can be selected; this is not a freely creatable Space.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
distillationobjectDistillation job, including counts, outputs, status, and duration.

Terminal job states are succeeded, partial_failed, failed, and dead; results use distillation.counts and outputs, and generating a candidate does not mean it has passed human confirmation. Queries use distillationId, not the ordinary write /jobs endpoint.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Replay a failed or partially failed distillation job (creates a new job without modifying the original).

ParameterLocationTypeRequiredDefaultDescription
distillationIdpathstringYes—ID of the distillation job to replay.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
distillationIdstringDistillation query identifier.
jobIdstringTask identifier.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
replayedbooleanWhether an existing distillation job was replayed.

Terminal job states are succeeded, partial_failed, failed, and dead; results use distillation.counts and outputs, and generating a candidate does not mean it has passed human confirmation. Queries use distillationId, not the ordinary write /jobs endpoint.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Update the governance state of managed knowledge (memory/context/skill/experience) (CAS concurrency control).

ParameterLocationTypeRequiredDefaultDescription
knowledgeIdpathstringYes—Knowledge ID.
expectedVersionbodyintegerYes—Current CAS version of the target knowledge/context; re-read after a conflict.
statusbodystringNo—Target governance state: candidate / shadow / user-active / agent-active / quarantine / deprecated.
validationStatusbodystringNo—Target verification state: pending / verified / conflicted / rejected.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
knowledgeobjectKnowledge object, including knowledgeId, currentRevision, version, states, and structured content.

expectedVersion uses the knowledge item's version and must not be mixed with currentRevision; state transitions are still checked against policy and evidence. Human confirmation of candidates requires a real administrative user and cannot be bypassed through this endpoint.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Write a forget marker for managed knowledge to stop further reuse; this knowledge governance operation is handled differently from proactively deleting a single memory.

ParameterLocationTypeRequiredDefaultDescription
knowledgeIdpathstringYes—Knowledge ID.
expectedVersionbodyintegerYes—Current CAS version of the target knowledge/context; re-read after a conflict.
reasonbodystringNoEmpty stringReason for the operation; required and non-empty for context confirmation, rebuild, and rollback.
sourcebodystringNo'api'Operation source marker; does not grant additional permissions.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
knowledgeIdstringKnowledge item identifier.
versionintegerCurrent concurrency control version.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
metadataobjectMetadata attached to the response; knowledge forgetting includes markers such as should_forget.

expectedVersion uses the knowledge item's version and must not be mixed with currentRevision; state transitions are still checked against policy and evidence. Human confirmation of candidates requires a real administrative user and cannot be bypassed through this endpoint.

In addition to the listed scopes, administrative access capability is required; ordinary user sessions cannot bypass this.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Record feedback for knowledge revisions retrieved in a single retrieval (only Skill/Experience can be rated, attributed via injectionId).

ParameterLocationTypeRequiredDefaultDescription
injectionIdbodystringYes—injectionId returned by unified retrieval; must not be self-generated.
knowledgeIdbodystringYes—ID of the Skill/Experience knowledge being rated; Memory and profile entries cannot be rated.
revisionbodyintegerYes—Revision of the actual retrieved item, not the knowledge item's version.
feedbackTypebodystringYes—positive, negative, or not-relevant; only for feedback-capable experiences/skills.
reasonCodebodystringNoEmpty stringBounded reason code (optional).
idempotencyKeybodystringNoEmpty stringIdempotency identifier for the same logical request; the Idempotency-Key header may also be used; if both are given they must match.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
idstringIdentifier of this feedback or observation record.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
idempotentReplaybooleanWhether the result of an identical idempotent request was reused.
revisionintegerKnowledge content revision number.

injectionId, knowledgeId, and revision must come from the same feedback-capable result of one unified retrieval; memory or profile items are not supported.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Record a bounded observation evidence item (such as a tool execution result) for a knowledge revision, for trustworthiness derivation.

ParameterLocationTypeRequiredDefaultDescription
knowledgeIdbodystringYes—Knowledge ID.
revisionbodyintegerYes—Revision of the actual retrieved item, not the knowledge item's version.
sourceIdbodystringNoEmpty stringValid source ID that produced the target knowledge; claiming other sources to bypass validation is not allowed.
injectionIdbodystringNoEmpty stringinjectionId returned by unified retrieval; must not be self-generated.
outcomebodystringYes—Observation outcome: success / failure / not-applicable / security-violation.
verificationSourcebodystringNo—Deprecated: the platform derives trusted sources from the authenticated source.
toolNamebodystringNoEmpty stringTool name.
toolVersionbodystringNoEmpty stringTool version.
toolSchemaVersionbodystringNoEmpty stringTool schema version.
errorFingerprintbodystringNoEmpty stringBounded error fingerprint.
evidencebodyobjectYes—Bounded observation evidence object (required).
weightbodynumberNo—Deprecated: the platform derives trusted weights from the authenticated source.
observedAtbodystringNoEmpty stringObservation timestamp.
idempotencyKeybodystringNoEmpty stringIdempotency identifier for the same logical request; the Idempotency-Key header may also be used; if both are given they must match.
scopebodystringNo'user'user (default), agent, project.
userIdbodystringNoEmpty stringTarget user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
agentIdbodystringNoEmpty stringAgent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
runIdbodystringNoEmpty stringThe source run.
memorySubStoreIdbodystringNoEmpty stringYou can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
idstringIdentifier of this feedback or observation record.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
idempotentReplaybooleanWhether the result of an identical idempotent request was reused.
revisionintegerKnowledge content revision number.

The trusted source and weight of an observation are determined by the authenticated principal; self-reporting verificationSource/weight cannot increase trustworthiness.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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 (and directly updating POST /v1/memory/memories/users/{userId}/profile)

SDK:Memory.getProfile · scope:memories.read / memories.write

Read the user profile (body content or topic summary topics); the admin console or controlled services can also submit profile updates via POST /v1/memory/memories/users/{userId}/profile (or the recommended POST .../profile/extractions).

ParameterLocationTypeRequiredDefaultDescription
userIdpathstringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
profileTypequerystringNo'content'content (default) or topics.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
profileobjectProfile object, including profileContent/topics, version, rebuildStatus, etc.
retrievedAtstring (time)Time of reading.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Delete the user profile and its derived provenance.

ParameterLocationTypeRequiredDefaultDescription
userIdpathstringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
profileTypebodystringNo'content'content (default) or topics.
reasonbodystringNoEmpty stringReason for the operation; required and non-empty for context confirmation, rebuild, and rollback.
sourcebodystringNo'appbase_delete'Operation origin marker; grants no additional permissions.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
profileIdstringProfile identifier.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Profile extraction from evidence: incremental merge by default, mode=replace replaces entirely.

ParameterLocationTypeRequiredDefaultDescription
pipelineIdbodystringNoEmpty stringOptional published Pipeline ID; if omitted, the scenario default is used; 2.9.0 SDK does not provide this parameter, use HTTP.
userIdpathstringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
profileTypebodystringNo'content'content (default) or topics.
messagesbodyarrayYes[]List of valid messages; role and non-empty content are required; message limits are described in the corresponding operation.
sourceMemoryIdsbodyarrayNo[]Supported by replace only; at most 100 valid current-user memories; cannot substitute for new messages.
sessionIdbodystringNoEmpty stringOptional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions.
modebodystringNo'incremental'incremental (default) or replace.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
memoryobjectMemory object; contains memoryId, version, content, ownership and model processing status.
profileExtractionobjectProfile extraction result: status, profileId, profileVersion, profileChanged.

The return key is profileExtraction. Both incremental and replace require valid messages; sourceMemoryIds is only available for replace, limited to at most 100 entries, and cannot substitute for new input. While queued, HTTP 202 is returned; read the profile to confirm the final result.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Fully rebuild the user profile from all visible evidence.

ParameterLocationTypeRequiredDefaultDescription
pipelineIdbodystringNoEmpty stringOptional published Pipeline ID; if omitted, the scenario default is used; 2.9.0 SDK does not provide this parameter, use HTTP.
userIdpathstringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
profileTypebodystringNo'content'content (default) or topics.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
jobIdstringTask identifier.
profileIdstringProfile identifier.
profileVersionintegerProfile version.
sourceCountintegerNumber of sources that participated in this aggregation.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

List the evidence sources of the profile.

ParameterLocationTypeRequiredDefaultDescription
userIdpathstringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
profileTypequerystringNo'content'content (default) or topics.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
profileTypestringProfile type: content/topics.
sourcesarraySources currently visible and still valid.
totalintegerCount of items matching the current query conditions.
truncatedbooleanWhether the result or scan was truncated due to limits.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Bulk import memories: structured arrays or raw JSON/JSONL strings, with validation-only support.

ParameterLocationTypeRequiredDefaultDescription
pipelineIdbodystringNoEmpty stringOptional published Pipeline ID; if omitted, the scenario default is used; 2.9.0 SDK does not provide this parameter, use HTTP.
userIdbodystringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
formatbodystringNo'jsonl'json or jsonl.
databodystringNoEmpty stringJSON/JSONL text import content; mutually exclusive with records.
recordsbodyarrayNo[]Structured import list, at most 500 entries; mutually exclusive with data.
dryRunbodybooleanNofalsetrue validates/previews only and does not write business data; use a new logical request identifier for the actual execution.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
importIdstringImport query identifier.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
jobIdstringTask identifier.

Choose either records or data; first validate with dryRun=true, then perform the actual import with a new logical idempotency key. The top-level userId must be consistent with the ownership of each record. Query using importId.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Query import job status and per-item results.

ParameterLocationTypeRequiredDefaultDescription
importIdpathstringYes—Import job ID.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
importIdstringImport query identifier.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
jobobjectAsync job object; check job.status and job.result.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Create a memory export job; returns exportId, status, and job.

ParameterLocationTypeRequiredDefaultDescription
userIdbodystringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
formatbodystringNo'jsonl'json or jsonl.
includeForgottenbodybooleanNofalseDefault false; exporting additional sensitive data requires system authorization; the boolean does not substitute for permission.
includeVectorsbodybooleanNofalseDefault false; exporting vectors requires system authorization.
includeRawSourcesbodybooleanNofalseDefault false; exporting raw sources requires system authorization.
modebodystringNo'async'async (default) or sync.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
exportIdstringExport query identifier.
statusstringCurrent business status or task status; do not rely solely on the HTTP success code.
jobobjectAsync job object; check job.status and job.result.

includeForgotten/includeVectors/includeRawSources default to false and require additional system authorization. Exporting does not delete live data. The POST creation result is exportId/status/job; query the job by exportId; to obtain the encoded data directly use GET /memory/memories/export, which returns data and other fields.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Query export job status and output location.

ParameterLocationTypeRequiredDefaultDescription
exportIdpathstringYes—Export job ID.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
jobobjectAsync job object; check job.status and job.result.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Synchronously export a batch of memories (mode fixed to sync, returns data directly).

ParameterLocationTypeRequiredDefaultDescription
userIdquerystringYes—Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata.
formatquerystringNo'jsonl'json or jsonl.
modequerystringNo'sync'sync only.
includeForgottenquerybooleanNofalseDefault false; exporting additional sensitive data requires system authorization; the boolean does not substitute for permission.
includeVectorsquerybooleanNofalseDefault false; exporting vectors requires system authorization.
includeRawSourcesquerybooleanNofalseDefault false; exporting raw sources requires system authorization.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
schemaVersionintegerExport structure version.
formatstringjson or jsonl format.
mediaTypestringMedia type of the exported content.
generatedAtstring (time)Export generation time.
datastringEncoded export text.
memoriesarrayArray of memory objects.
profilesarrayExported profile collection.
jobsarrayExported job collection.
vectorsarrayVector projections optionally exported with authorization.
sourcesarraySources currently visible and still valid.
metadataobjectMetadata attached to the response; knowledge forgetting includes markers such as should_forget.

includeForgotten/includeVectors/includeRawSources default to false and require additional system authorization. Exporting does not delete live data. The POST creation result is exportId/status/job; query the job by exportId; to obtain the encoded data directly use GET /memory/memories/export, which returns data and other fields.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Route-bounded rebuild of memory projections (retrieval indexes), progressing over multiple rounds until complete; only trusted operations may call it.

ParameterLocationTypeRequiredDefaultDescription
routesbodyarrayYes[]Projection rebuild requires one or more of dense, sparse, graph, without duplicates.
cursorbodystringNoEmpty stringThe nextCursor returned by the previous page, passed back as-is; audit cursors are non-negative integer offsets.
limitbodyintegerNo100Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries.
dryRunbodybooleanNofalsetrue validates/previews only and does not write business data; use a new logical request identifier for the actual execution.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
routesarrayProjection routes selected for this request.
dryRunbooleanWhether this is a precheck or preview only.
matchedintegerNumber of pending items matched in this run.
scheduledintegerNumber of tasks scheduled in this operation.
conflictsintegerNumber of concurrency conflicts that occurred in this run.
hasMorebooleanWhen true, continue processing the next batch over the same range.
nextCursorstringCursor for the next page; an empty value means there are no further pages.

This is a bounded projection repair; check first with dryRun=true; continue while hasMore=true; a validated result does not equal automatically repairing all differences.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Read the project-level memory projection recovery verification result (post-rebuild consistency check).

ParameterLocationTypeRequiredDefaultDescription
None————No business request parameters.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
liveRecordsintegerNumber of live records within the verification scope.
denseobjectDense projection verification result and ready status.
sparseobjectSparse projection verification result and ready status.
graphobjectGraph projection verification result and ready status.
repairRecommendedbooleanWhether a controlled repair is recommended.
limitationsarrayLimits of this verification; they cannot be ignored and then claimed to be fully consistent.
verifiedAtstring (time)Projection verification time.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Read memory statistics visible to the current caller.

ParameterLocationTypeRequiredDefaultDescription
None————No business request parameters.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
visibleCountintegerNumber of currently visible memories.
forgottenCountintegerNumber of forgotten memories.
totalCountintegerTotal number of memories.
indexStatusobjectMemory counts by index status.
jobStatusobjectCounts by job status.
fromstring (time)Start time of this statistics run (if provided).
tostring (time)The end time of this statistics period (if provided).

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Read the memory quality report.

ParameterLocationTypeRequiredDefaultDescription
None————No business request parameters.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
visibleCountintegerNumber of currently visible memories.
lowQualityCountintegerNumber of low-quality memories.
pendingIndexesintegerNumber of indexes not yet ready.
issuesarrayMemories with quality flags and their flags.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Read the memory activity timeline.

ParameterLocationTypeRequiredDefaultDescription
None————No business request parameters.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
bucketsarrayDate buckets, including created, updated, forgotten.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Read memory session aggregates.

ParameterLocationTypeRequiredDefaultDescription
None————No business request parameters.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
sessionsarrayList of session aggregates.
totalintegerCount of items matching the current query conditions.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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

Query project memory request audits (integer offset pagination).

ParameterLocationTypeRequiredDefaultDescription
jobIdquerystringNoEmpty stringExact match on the memory task ID.
queryquerystringNoEmpty stringKeyword for searching audit content; optional.
operationquerystringNoEmpty stringFilter by memory operation name (e.g. createMemory).
outcomequerystringNoEmpty stringFilter by request result: success / failure.
limitqueryintegerNo25Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range.
cursorqueryintegerNo0The nextCursor returned by the previous page, passed back as-is; the audit cursor is a non-negative integer offset.

Returned fields (only public structures are listed; conditionally returned fields may be omitted):

FieldTypeDescription
auditsarrayAudit records matching the filter conditions.
totalintegerCount of items matching the current query conditions.
nextCursorinteger / nullCursor for the next page; a null value indicates no further pages.
scannedintegerThe number actually scanned to obtain the results.
truncatedbooleanWhether the result or scan was truncated due to limits.

The cursor is an integer offset; use the returned nextCursor, and also check scanned/truncated. Ordinary reads and status polling do not create a request audit each time.

Request example: replace the endpoint, project credentials, and resource IDs in the path; resource IDs come from your own creation or query results.

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'

Multimodal Input and Progressive Retrieval

When creating a memory, you can pass media={bucketId,fileId} to use a complete Storage file from the same project. Writes support PNG/JPEG/WebP/PDF, one file at a time and at most 8 MiB; images at most 16,000,000 pixels, PDFs at most 10 pages. Media parsing is always asynchronous and returns a jobId. Input plus parsed text is at most 20,000 UTF-8 bytes, and requires memories.write, files.read, a vision model, and media parsing support; no_model rejects media input.

Image search uses the same media reference and requires memories.read and file read permission; images are first parsed into text before retrieval, and are not written into memory nor used to build an image vector index. Queries do not support PDF, and all media inputs do not support external URLs, base64, audio, or video. Forgetting a memory does not automatically delete the original Storage file.

Progressive retrieval can pass strategy=progressive, entryLevel=auto, maxDepth=2, tokenBudget=1200, deadlineMs=450 in the retrieval of search. entryLevel supports auto/overview/context/fact/evidence, maxDepth ranges from 0–3, and deadlineMs is at most 450. Results are in progressive.items; L3 overview, L2 context, L1 facts, L0 evidence; use expansionToken to expand further, not the ordinary cursor. This mode does not support batch; tokens are time-limited and must be re-obtained after sources or permissions change; requires the corresponding project feature and a valid aggregation.

Self-Evolving Knowledge Approval and Revision Governance API (Evolution Reviews & Revisions)

When experience and skill distillation tasks (POST /v1/memory/memories/distillations) or direct write interfaces (POST /v1/memory/memories/experiences, POST /v1/memory/memories/skills) produce candidate (Candidate) knowledge, or an online revision triggers a confidence downgrade, you can use the self-evolution approval and revision version governance interfaces to view, edit, approve (Approve), reject (Reject), compare historical versions (Diff), and roll back (Rollback) with one click:

Method and pathRequired permissions (Scope + role)Core parametersPurpose description
GET /v1/memory/memories/knowledge/reviews/{reviewId}memories.read + admin permissionreviewId (path)Get the details of a single knowledge self-evolution approval ticket (including candidate experience/skill content, distillation source evidence, and confidence score).
PATCH /v1/memory/memories/knowledge/reviews/{reviewId}memories.write + admin permissiontitle, content, tags, expectedVersion (body)The approver manually revises the candidate experience/skill content or applicability conditions before approval.
POST /v1/memory/memories/knowledge/reviews/{reviewId}/approvememories.write + admin permissionexpectedVersion, reason (body)Approve the candidate knowledge revision and promote it to the online active status, available for /recall and /experiences/search, /skills/search retrieval.
POST /v1/memory/memories/knowledge/reviews/{reviewId}/rejectmemories.write + admin permissionexpectedVersion, reason (body)Reject low-quality or conflicting candidate knowledge revisions, archive the approval ticket without polluting the online knowledge base.
GET /v1/memory/memories/knowledge/{knowledgeId}/revisionsmemories.readknowledgeId (path), limit, cursor (query)List the complete immutable historical revision list of the specified experience or skill (knowledgeId).
GET /v1/memory/memories/knowledge/{knowledgeId}/diffmemories.readfromRevision, toRevision (query, integer)Compare structured field and content differences of the same experience/skill between two historical revision numbers.
POST /v1/memory/memories/knowledge/{knowledgeId}/rollbackmemories.write + admin permissionexpectedVersion, targetRevision, reason (body)Atomically roll back the online experience or skill to the specified historical validated revision number (generating a new appended revision record).

Self-evolution approval, Diff, and rollback request example:

# 1. View and manually fine-tune distillation skill candidates pending approval (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. Approve the review for release (POST .../reviews/{reviewId}/approve; if rejected, call 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. Query the knowledge revision list, compare version differences, and roll back on anomalies (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"
}'

Four Memory Pipelines (Including Ebbinghaus Forgetting Pipeline) and Six Configuration Namespaces API

The project-level memory system achieves full-lifecycle governance from write extraction, profile building, experience distillation to Ebbinghaus Forgetting through four orchestratable pipelines (Memory Pipelines) and six configuration namespaces (Configuration Namespaces). The above management-plane interfaces require project or admin permissions (Console administrator credentials or server-side credentials with admin authorization), and all configuration updates enforce optimistic concurrency control (CAS) using expectedConfigVersion and the HTTP If-Match header:

1. Four Memory Pipelines API (/v1/memory/pipelines*)

Method and pathCore parametersPurpose description
GET /v1/memory/pipelinesscenario (query, optional: add_memory | profile | distillation | forgetting)List the definitions, currently published versions, and default binding status of the four memory pipelines under the current project.
POST /v1/memory/pipelinesname, scenario (required, enum: add_memory | profile | distillation | forgetting), spec (DAG node and model operator configuration)Create a new memory processing pipeline draft (Draft).
PATCH /v1/memory/pipelines/{id}name, spec, expectedVersion (body)Update the operator parameters, prompt templates, or forgetting decay threshold configuration of the specified pipeline.
POST /v1/memory/pipelines/{id}/validatedryRun (boolean), sampleUserId (e.g. "user_zhangwei_001"), simulatedDays (number)Validate pipeline topology legality; when scenario="forgetting", supports the single-user Ebbinghaus forgetting Dry-run preview, computing the Retention Score of each short-term/working memory using the formula $R = e^{-t / (S_0 \cdot 2^{k \cdot n} \cdot w)}$, previewing the memories to be downgraded or forgotten without actually deleting data.
POST /v1/memory/pipelines/{id}/publishexpectedVersion, releaseNotes (body)Publish the validated pipeline draft as an immutable production version.
PUT /v1/memory/pipelines/defaultscenario (add_memory | profile | distillation | forgetting), pipelineId, versionSet the specified published pipeline as the default execution pipeline for the corresponding scenario of this project.

Ebbinghaus forgetting pipeline orchestration and single-user Dry-run preview example:

# 1. Create or update the Ebbinghaus forgetting pipeline (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. Run a single-user Ebbinghaus forgetting dry-run validation preview (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. Publish the pipeline and bind it as the default pipeline for the forgetting scenario (POST .../publish and 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. Six Configuration Namespaces API (GET/PUT /v1/projects/{projectId}/memory/config/{namespace})

Project-level memory configuration is divided by responsibility into six independent namespaces (namespace enum: runtime, prompt, policy, retention, provider, evolution); each PUT update must carry the expectedConfigVersion and If-Match request headers obtained from the GET response:

Namespace (namespace)Core configuration itemsDescription
runtimerecallFusion (five-way fusion weights and RRF parameters), progressiveRecallEnabled, defaultTokenBudget, maxDeadlineMs (450)Control hybrid retrieval routing fusion, progressive retrieval timeout fences, and concurrency.
promptfactExtractionPrompt, profileMergePrompt, dreamingSynthesisPrompt, distillationPromptCustomize prompts for fact extraction, profile aggregation, context dreaming, and experience/skill distillation.
policydefaultScope, allowedFilterFields, strictPrivateIsolation, defaultHandlingPolicyMemory access boundaries, whitelist of metadata allowed for filtering, and sensitivity level policies.
retentionworkingTtlHours, shortTermHalfLifeDays, forgettingCron, protectLongTermWorking memory TTL, short-term memory Ebbinghaus decay cycles, and scheduled forgetting policies.
providerchatProviderRef (e.g. "project:dashscope-prod"), chatModel ("qwen-plus"), embeddingModel ("text-embedding-v3"), rerankModel ("qwen3.7-text-rerank"), visionModel ("qwen-vl-max"), sparseMode ("auto")Pin the LLM Gateway models dedicated to the memory module and the model-generated sparse vector switch.
evolutionautoDistillEnabled, requireHumanReview (true | false), autoApproveConfidenceThreshold, dreamingScheduleControl experience/skill self-evolution distillation trigger conditions, manual approval gates, and dreaming consolidation cycles.

Example of reading and CAS-updating configuration namespaces (expectedConfigVersion + If-Match):

# 1. Read the project memory runtime namespace configuration and current version number
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. Atomically update the runtime config with If-Match and expectedConfigVersion
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
  }
}'

Errors and boundaries

Unfinished tasks should continue to be queried via their own status interfaces. Do not recreate a request to replace polling, and do not treat example scores or counts as business assertions.

Correspondence with the Server SDK

The endpoint list enumerates Memory service methods line by line. The 2.9.0 Node.js SDK returns loosely typed objects, and applications must check responses according to the contract in this document; for complete runnable examples, see Memory SDK operations.

Applicable Versions

The server-side interface is Agentbase 2.10.0, and the Node.js examples use agentbase-node-sdk@2.9.0. Project lifecycle, configuration, Pipeline, and manual confirmation belong to the management plane; this page does not list them as ordinary project API Key interfaces. SDK versions and server versions are chosen independently; documentation updates do not imply that a new SDK has been released.