Memory API
This page describes project-level Memory service APIs for Agentbase 2.12.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.
Physical database names in registered Shared V2 resource pools may contain hyphens; this compatibility is provided by the deployed service. Callers keep using the project ID and existing credentials, without passing a physical database name, pool alias, or internal signed context. For initialization or routing failures, ask an administrator to check the service version and pool registration; do not change request fields to bypass project isolation.
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.
Memory scope is private, strict_private, user, group, project; group writes also require metadata.groupId. Visibility scope is not the API Key scope.
Experience, skills, distillation, unified retrieval, feedback, and context use knowledge ownership scopes: user (default), agent, project. The server explicitly passes userId; only for the agent scope is agentId passed, and it must be provided. Ordinary users cannot self-report cross-user ownership.
accessMode defaults to owned; accessible queries the authorized visible set; strict_private is not included in the authorized union.
The idempotency keys in all write request examples are for illustration. Retries of the same logical write reuse the original key, and different operations use different keys; if the API also supports an idempotencyKey parameter, the two values must be identical when both are provided.
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 column is checked against the published agentbase-node-sdk@2.12.0. Fields such as media and pipelineId remain subject to each endpoint’s model, permission, and usage requirements. Follow the relevant method signature; do not assume undeclared properties are sent.
Endpoint overview
The memory system groups business operations 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 Path | SDK Method |
|---|---|
POST /v1/memory/memories | Memory.create |
GET /v1/memory/memories | Memory.list |
GET /v1/memory/memories/{memoryId} | Memory.get |
PATCH /v1/memory/memories/{memoryId} | Memory.update |
DELETE /v1/memory/memories/{memoryId} | Memory.delete |
DELETE /v1/memory/memories | Memory.deleteMany |
POST /v1/memory/memories/batch | Memory.createBatch |
GET /v1/memory/jobs/{jobId} | Memory.getJob |
GET /v1/memory/memories/{memoryId}/sources | Memory.listSources |
GET /v1/memory/memories/{memoryId}/shares | Memory.listShares |
POST /v1/memory/memories/{memoryId}/shares | Memory.createShare |
DELETE /v1/memory/memories/{memoryId}/shares/{shareId} | Memory.deleteShare |
POST /v1/memory/memories/search | Memory.search |
POST /v1/memory/memories/recall | Memory.recallKnowledge |
GET /v1/memory/memories/skills | Memory.listSkills |
POST /v1/memory/memories/skills/search | Memory.searchSkills |
GET /v1/memory/memories/skills/{knowledgeId} | Memory.getSkill |
GET /v1/memory/memories/skills/{knowledgeId}/sources | Memory.listSkillSources |
GET /v1/memory/memories/experiences | Memory.listExperiences |
POST /v1/memory/memories/experiences/search | Memory.searchExperiences |
GET /v1/memory/memories/experiences/{knowledgeId} | Memory.getExperience |
GET /v1/memory/memories/experiences/{knowledgeId}/sources | Memory.listExperienceSources |
GET /v1/memory/memories/contexts | Memory.listContexts |
GET /v1/memory/memories/contexts/{contextId} | Memory.getContext |
POST /v1/memory/memories/contexts/runs | Memory.createContextRun |
GET /v1/memory/memories/contexts/status | Memory.getContextStatus |
POST /v1/memory/memories/contexts/{contextId}/confirm | Memory.confirmContext |
POST /v1/memory/memories/contexts/{contextId}/rebuild | Memory.rebuildContext |
POST /v1/memory/memories/contexts/{contextId}/rollback | Memory.rollbackContext |
GET /v1/memory/memories/distillations | Memory.listDistillations |
POST /v1/memory/memories/distillations | Memory.submitDistillation |
GET /v1/memory/memories/distillations/{distillationId} | Memory.getDistillation |
POST /v1/memory/memories/distillations/{distillationId}/replay | Memory.replayDistillation |
PATCH /v1/memory/memories/knowledge/{knowledgeId} | Memory.updateKnowledge |
DELETE /v1/memory/memories/knowledge/{knowledgeId} | Memory.forgetKnowledge |
POST /v1/memory/memories/feedback | Memory.createKnowledgeFeedback |
POST /v1/memory/memories/observations | Memory.createKnowledgeObservation |
GET /v1/memory/memories/users/{userId}/profile | Memory.getProfile |
DELETE /v1/memory/memories/users/{userId}/profile | Memory.deleteProfile |
POST /v1/memory/memories/users/{userId}/profile/extractions | Memory.createProfileExtraction |
POST /v1/memory/memories/users/{userId}/profile/rebuild | Memory.createProfileRebuild |
GET /v1/memory/memories/users/{userId}/profile/sources | Memory.listProfileSources |
POST /v1/memory/memories/imports | Memory.createImport |
GET /v1/memory/memories/imports/{importId} | Memory.getImport |
POST /v1/memory/memories/exports | Memory.createExport |
GET /v1/memory/memories/exports/{exportId} | Memory.getExportJob |
GET /v1/memory/memories/export | Memory.getExport |
POST /v1/memory/memories/projections/rebuild | Memory.createProjectionRebuild |
GET /v1/memory/memories/projections/verification | Memory.getProjectionVerification |
GET /v1/memory/memories/stats | Memory.getStats |
GET /v1/memory/memories/quality | Memory.getQuality |
GET /v1/memory/memories/timeline | Memory.getTimeline |
GET /v1/memory/memories/sessions | Memory.getSessions |
GET /v1/memory/audits | Memory.listAudits |
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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
pipelineId | body | string | No | Empty string | Optional published Pipeline ID; if omitted, the scenario default is used; Node SDK 2.12.0 supports this parameter. |
content | body | string | No | Empty string | Body text; for non-empty input, at most 20,000 UTF-8 bytes; see the write notes for the combination with messages/media. |
messages | body | array | No | [] | Valid message list; role and non-empty content are required; see the corresponding operation notes for message limits. |
media | body | object | No | {} | Same-project Storage reference {bucketId,fileId}; see the multimodal notes on this page for format, size, and permissions; Node SDK 2.12.0 supports this parameter. |
userId | body | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
runId | body | string | No | Empty string | Owning run ID (optional); not used as a fallback for sessionId. |
sessionId | body | string | No | Empty string | Optional 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. |
scope | body | string | Yes | — | 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. |
sensitivity | body | string | No | 'normal' | normal (default), confidential, restricted; secret will be rejected. |
handlingPolicy | body | string | No | '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). |
memoryType | body | string | Yes | — | 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). |
recordKind | body | string | Yes | — | 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. |
metadata | body | object | No | {} | 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. |
infer | body | boolean | No | true | By default true (performs fact extraction, conflict resolution and ADD/UPDATE/DELETE/NONE decisions via LLM); false performs a deterministic direct write. |
reRemember | body | boolean | No | false | When 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. |
async | body | boolean | No | — | 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):
| Field | Type | Description |
|---|---|---|
pipeline | object / null | Receipt of the pipeline actually used and the fixed released version. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
mode | string | The processing method used this time, e.g. simple/inferred. |
sourceId | string | Immutable source identifier. |
jobId | string | Task identifier. |
memory | object / null | Memory object; contains memoryId, version, content, ownership and model processing status. |
actions | array | Each item contains index, action, status, memoryId, etc.; action is ADD/UPDATE/DELETE/NONE. |
errorCode | string | Omit-able error classification, e.g. LLM_TIMEOUT; returned when error information exists. |
reason | string | Reason for this operation or failure. |
retryable | boolean | Whether the failure can still be retried; does not replace task status. |
fallback | object / null | Controlled fallback information: strategy is a string; errorCode and reason are omit-able strings. |
idempotencyKey | string | Idempotency 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):
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-H "Idempotency-Key: mem-multimodal-20261022-01" \
--data '{
"userId": "user_zhangwei_001",
"sessionId": "sess_ob_sre_12turns",
"scope": "user",
"handlingPolicy": "standard",
"memoryType": "long_term",
"recordKind": "fact",
"content": "张伟负责华东生产集群 OB-Prod-East 的日常容灾演练,告警阈值倾向设置为日志盘 80%。",
"media": {
"bucketId": "agent_multimedia_bucket",
"fileId": "file_topology_arch_png"
},
"metadata": {
"cognitiveLayer": "L1",
"importance": 0.92
},
"infer": true,
"reRemember": true,
"async": true
}'
)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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
cursor | query | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset. |
limit | query | integer | No | — | Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries. |
filter | query | object | No | — | Structured filter object; fields must be within the project allowlist. |
queries | query | array | No | [] | SDK Query filter expressions; pagination conditions that do not conflict with direct parameter submission. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
accessMode | query | string | No | '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):
| Field | Type | Description |
|---|---|---|
memories | array | Array of memory objects. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
memoryId | path | string | Yes | — | Target memory ID. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
memory | object | Memory 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
memoryId | path | string | Yes | — | Target memory ID. |
version | body | integer | Yes | — | The most recently fetched memory version, a positive integer; re-read after a conflict. |
content | body | string | No | — | Updated non-empty content, up to 20,000 UTF-8 bytes. |
metadata | body | object | No | {} | Custom metadata object; cannot set system forgetting or governance fields. |
retentionPolicy | body | string | No | — | Retention policy; the current enumeration only includes default. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
memory | object | Memory 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
memoryId | path | string | Yes | — | Target memory ID. |
memorySubStoreId | body | string | No | Empty string | You can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily. |
reason | body | string | No | Empty string | Reason for the operation; required and non-empty for context confirmation, rebuild, and rollback. |
source | body | string | No | 'appbase_delete' | Operation origin marker; grants no additional permissions. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
memoryId | string | Full string identifier of the memory. |
status | string | Current 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
memorySubStoreId | body | string | No | Empty string | You can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily. |
limit | body | integer | No | 100 | Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries. |
reason | body | string | No | Empty string | Reason for the operation; required and non-empty for context confirmation, rebuild, and rollback. |
source | body | string | No | 'appbase_delete_worker' | Operation origin marker; grants no additional permissions. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
processed | integer | Number of records processed in this batch. |
forgotten | integer | Number of items successfully forgotten in this batch. |
failed | integer | Number of failures; check the per-item errors. |
hasMore | boolean | When true, continue processing the next batch over the same range. |
items | array | Per-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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
items | body | array | Yes | [] | 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):
| Field | Type | Description |
|---|---|---|
items | array | Per-item results; see the corresponding operation description on this page for the structure. |
status | string | Current 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
jobId | path | string | Yes | — | The write task ID (returned in the memory creation async response). |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
pipeline | object / null | Receipt of the pipeline actually used and the fixed released version. |
jobId | string | Task identifier. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
mode | string | The processing method used this time, e.g. simple/inferred. |
sourceId | string | Immutable source identifier. |
attemptCount | integer | The number of execution attempts made so far. |
maxAttempts | integer | The retry budget cap. |
errorCode | string | An optional error classification, e.g. LLM_TIMEOUT; returned when an error message exists, and tasks being retried may also carry it. |
reason | string | Reason for this operation or failure. |
retryable | boolean | Whether the failure can still be retried; does not replace task status. |
result | object / null | The final business result; even after the scheduling status is succeeded, check result.status. |
createdAt | string (time) | Creation time. |
updatedAt | string (time) | Last update time. |
startedAt | string (time) | The time execution first started. |
completedAt | string (time) | The time the task reached a terminal state. |
queueDurationMs | number / null | Queuing duration; null if not yet started. |
executionDurationMs | number / null | Duration from first start to terminal state, including retry backoff; null if not finished. |
totalDurationMs | number / null | Duration 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
memoryId | path | string | Yes | — | Target memory ID. |
cursor | query | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset. |
limit | query | integer | No | 25 | Upper 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):
| Field | Type | Description |
|---|---|---|
sources | array | Sources currently visible and still valid. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
memoryId | path | string | Yes | — | Target memory ID. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
shares | array | List of memory sharing records. |
total | integer | Count 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
memoryId | path | string | Yes | — | Target memory ID. |
subjectType | body | string | Yes | — | user or group. |
subjectId | body | string | Yes | — | The ID of the user or group being granted read access. |
expiresAt | body | string | No | Empty string | Sharing expiration time in ISO 8601 format. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
share | object | The sharing object. |
changed | boolean | Whether this operation changed the record. |
resourcePolicyRevision | integer | The 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
memoryId | path | string | Yes | — | Target memory ID. |
shareId | path | string | Yes | — | The ID of the sharing grant to revoke. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
shareId | string | The sharing record identifier. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
changed | boolean | Whether this operation changed the record. |
resourcePolicyRevision | integer | The 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
query | body | string | No | Empty string | Natural-language query; image queries may omit text, other retrieval requires non-empty. |
searchMode (or mode) | body | string | No | 'hybrid' | Five-way hybrid retrieval mode: hybrid (default; fuses vectors, keywords, sparse vectors, knowledge graph, and profile routing), vector, keyword, graph, profile. |
retrieval | body | object | No | {} | 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>". |
media | body | object | No | {} | Same-project Storage reference {bucketId,fileId}; see the multimodal notes on this page for format, size, and permissions; Node SDK 2.12.0 supports this parameter. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
runId | body | string | No | Empty string | Filter by run. |
scope | body | string | No | Empty string | private, strict_private, user, group, project. |
memoryType | body | string | No | Empty string | The caller's business type; inferred writes preserve the source and generate derived facts. |
recordKind | body | string | No | Empty string | conversation, fact, or action. |
filter | body | object | No | — | Structured filter object; fields must be within the project allowlist. |
limit | body | integer | No | 0 | Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range. |
cursor | body | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; audit cursors are non-negative integer offsets. |
sort | body | string | No | Empty string | Sort mode. |
memorySubStoreId | body | string | No | Empty string | You can only select a sub-storage already bound to the current project; this is not a Space that can be created arbitrarily. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
groupId | body | string | No | Empty string | Group/entity boundary filter. |
accessMode | body | string | No | '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):
| Field | Type | Description |
|---|---|---|
items | array | Per-item results; see the corresponding operation description on this page for the structure. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count of items matching the current query conditions. |
rewriteTrace | object | Query rewrite information. |
degraded | object | Degradation information for this retrieval, to be checked by the caller. |
progressive | object / null | Tiered 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:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/memory/memories/search" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
--data '{
"query": "张伟负责的 OceanBase 生产集群告警阈值与容灾演练偏好是什么?",
"mode": "hybrid",
"searchMode": "hybrid",
"retrieval": {
"sparse": "auto",
"strategy": "progressive",
"entryLevel": "auto",
"maxDepth": 2,
"tokenBudget": 1200,
"deadlineMs": 450,
"expansionToken": ""
},
"userId": "user_zhangwei_001",
"scope": "user",
"memoryType": "long_term",
"limit": 10,
"sessionId": "sess_ob_sre_12turns",
"accessMode": "accessible"
}'
)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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
query | body | string | Yes | — | A non-empty natural-language query. |
kinds | body | array | No | [] | memory, profile, skill, experience, without duplicates; all by default. |
limit | body | integer | No | — | Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range. |
tokenBudget | body | integer | No | — | Unified retrieval defaults to 4096, with a range of 1–32768. |
retrieval | body | object | No | {} | Override retrieval routes per request; sparse=false may be set. See the description for progressive parameters. |
accessMode | body | string | No | 'owned' | owned (default) or accessible; the latter is still limited by actual visibility permissions. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
injectionId | string | The injection identifier for this context, to be reused when providing feedback. |
context | string | The context that can be used to assemble the model request, or the context governance result. |
items | array | Per-item results; see the corresponding operation description on this page for the structure. |
tokenBudget | integer | The token budget for this context. |
usedTokens | integer | The number of context tokens actually used this time. |
degraded | object | Degradation 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
cursor | query | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset. |
limit | query | integer | No | — | Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run filter. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
items | array | Per-item results; see the corresponding operation description on this page for the structure. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
query | body | string | Yes | — | A non-empty natural-language query. |
cursor | body | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; audit cursors are non-negative integer offsets. |
limit | body | integer | No | — | Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range. |
retrieval | body | object | No | {} | Override retrieval routes per request; sparse=false may be set. See the description for progressive parameters. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
items | array | Per-item results; see the corresponding operation description on this page for the structure. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count of items matching the current query conditions. |
degraded | object | Degradation 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
knowledgeId | path | string | Yes | — | Skill knowledge ID. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
skill | object | Skill 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
knowledgeId | path | string | Yes | — | Skill knowledge ID. |
cursor | query | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset. |
limit | query | integer | No | 25 | Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
sources | array | Sources currently visible and still valid. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
cursor | query | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset. |
limit | query | integer | No | — | Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
items | array | Per-item results; see the corresponding operation description on this page for the structure. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
query | body | string | Yes | — | A non-empty natural-language query. |
cursor | body | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; audit cursors are non-negative integer offsets. |
limit | body | integer | No | — | Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range. |
retrieval | body | object | No | {} | Override retrieval routes per request; sparse=false may be set. See the description for progressive parameters. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
items | array | Per-item results; see the corresponding operation description on this page for the structure. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count of items matching the current query conditions. |
degraded | object | Degradation 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
knowledgeId | path | string | Yes | — | Experience knowledge ID. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
experience | object | Experience 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
knowledgeId | path | string | Yes | — | Experience knowledge ID. |
cursor | query | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset. |
limit | query | integer | No | 25 | Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
sources | array | Sources currently visible and still valid. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
status | query | string | No | Empty string | Filter by lifecycle state: shadow / quarantine / stale / user-active / agent-active / deprecated. |
kind | query | string | No | Empty string | Filter by tier: memory_topic / memory_episode / memory_state / memory_overview. |
cursor | query | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset. |
limit | query | integer | No | — | Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
contexts | array | List of currently visible context aggregates. |
nextCursor | string | Cursor 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
contextId | path | string | Yes | — | Context knowledge ID. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
context | object | Context 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
changed | integer | Whether this operation changed records. |
scheduled | integer | Number of tasks scheduled in this operation. |
watermark | string | Scan 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
status | object | Current 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
contextId | path | string | Yes | — | Context knowledge ID. |
expectedVersion | body | integer | Yes | — | Current CAS version of the target knowledge/context; re-read after a conflict. |
reason | body | string | Yes | — | Reason for the operation; required and must be non-empty for context confirmation, rebuild, and rollback. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
context | object | Context 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
contextId | path | string | Yes | — | Context knowledge ID. |
reason | body | string | Yes | — | Reason for the operation; required and must be non-empty for context confirmation, rebuild, and rollback. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
jobId | string | Task 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
contextId | path | string | Yes | — | Context knowledge ID. |
expectedVersion | body | integer | Yes | — | Current CAS version of the target knowledge/context; re-read after a conflict. |
targetRevision | body | integer | Yes | — | Target historical revision number for the context rollback; does not replace expectedVersion. |
reason | body | string | Yes | — | Reason for the operation; required and must be non-empty for context confirmation, rebuild, and rollback. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
context | object | Context 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
status | query | string | No | Empty string | Filter by job status: queued / running / succeeded / partial_failed / failed / dead. |
cursor | query | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; an audit cursor is a non-negative integer offset. |
limit | query | integer | No | — | Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
distillations | array | Array of distillation jobs. |
nextCursor | string | Cursor for the next page; an empty value means there are no further pages. |
total | integer | Count 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
pipelineId | body | string | No | Empty string | Optional published Pipeline ID; if omitted, the scenario default is used; Node SDK 2.12.0 supports this parameter. |
sourceId | body | string | No | Empty string | Persisted source ID; choose either this or inline messages/toolEvents. |
sourceType | body | string | No | Empty string | Used together with sourceId: conversation, tool-trace, execution-log. |
messages | body | array | No | [] | Valid message list; role and non-empty content are required; see the corresponding operation notes for message limits. |
toolEvents | body | array | No | [] | At most 100 tool evidence items; may be provided together with messages, but not simultaneously with sourceId. |
mode | body | string | No | 'async' | async (default) or wait (waits at most 20 seconds). |
idempotencyKey | body | string | No | Empty string | Idempotency identifier for the same logical request; the Idempotency-Key header may also be used; if both are given they must match. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
distillationId | string | Distillation query identifier. |
jobId | string | Task identifier. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
idempotentReplay | boolean | Whether the result of an identical idempotent request was reused. |
waitTimedOut | boolean | Whether the wait window ended while the background job continues to run. |
message | string | Wait 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
distillationId | path | string | Yes | — | Distillation job ID. |
scope | query | string | No | 'user' | user (default), agent, project. |
userId | query | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | query | string | No | Empty string | Agent ownership or filter; provided and required on knowledge endpoints only when scope=agent. |
sessionId | query | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | query | string | No | Empty string | Source run. |
memorySubStoreId | query | string | No | Empty string | Only 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):
| Field | Type | Description |
|---|---|---|
distillation | object | Distillation 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
distillationId | path | string | Yes | — | ID of the distillation job to replay. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
distillationId | string | Distillation query identifier. |
jobId | string | Task identifier. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
replayed | boolean | Whether 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
knowledgeId | path | string | Yes | — | Knowledge ID. |
expectedVersion | body | integer | Yes | — | Current CAS version of the target knowledge/context; re-read after a conflict. |
status | body | string | No | — | Target governance state: candidate / shadow / user-active / agent-active / quarantine / deprecated. |
validationStatus | body | string | No | — | Target verification state: pending / verified / conflicted / rejected. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
knowledge | object | Knowledge 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
knowledgeId | path | string | Yes | — | Knowledge ID. |
expectedVersion | body | integer | Yes | — | Current CAS version of the target knowledge/context; re-read after a conflict. |
reason | body | string | No | Empty string | Reason for the operation; required and non-empty for context confirmation, rebuild, and rollback. |
source | body | string | No | 'api' | Operation source marker; does not grant additional permissions. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
knowledgeId | string | Knowledge item identifier. |
version | integer | Current concurrency control version. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
metadata | object | Metadata 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
injectionId | body | string | Yes | — | injectionId returned by unified retrieval; must not be self-generated. |
knowledgeId | body | string | Yes | — | ID of the Skill/Experience knowledge being rated; Memory and profile entries cannot be rated. |
revision | body | integer | Yes | — | Revision of the actual retrieved item, not the knowledge item's version. |
feedbackType | body | string | Yes | — | positive, negative, or not-relevant; only for feedback-capable experiences/skills. |
reasonCode | body | string | No | Empty string | Bounded reason code (optional). |
idempotencyKey | body | string | No | Empty string | Idempotency identifier for the same logical request; the Idempotency-Key header may also be used; if both are given they must match. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
id | string | Identifier of this feedback or observation record. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
idempotentReplay | boolean | Whether the result of an identical idempotent request was reused. |
revision | integer | Knowledge 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
knowledgeId | body | string | Yes | — | Knowledge ID. |
revision | body | integer | Yes | — | Revision of the actual retrieved item, not the knowledge item's version. |
sourceId | body | string | No | Empty string | Valid source ID that produced the target knowledge; claiming other sources to bypass validation is not allowed. |
injectionId | body | string | No | Empty string | injectionId returned by unified retrieval; must not be self-generated. |
outcome | body | string | Yes | — | Observation outcome: success / failure / not-applicable / security-violation. |
verificationSource | body | string | No | — | Deprecated: the platform derives trusted sources from the authenticated source. |
toolName | body | string | No | Empty string | Tool name. |
toolVersion | body | string | No | Empty string | Tool version. |
toolSchemaVersion | body | string | No | Empty string | Tool schema version. |
errorFingerprint | body | string | No | Empty string | Bounded error fingerprint. |
evidence | body | object | Yes | — | Bounded observation evidence object (required). |
weight | body | number | No | — | Deprecated: the platform derives trusted weights from the authenticated source. |
observedAt | body | string | No | Empty string | Observation timestamp. |
idempotencyKey | body | string | No | Empty string | Idempotency identifier for the same logical request; the Idempotency-Key header may also be used; if both are given they must match. |
scope | body | string | No | 'user' | user (default), agent, project. |
userId | body | string | No | Empty string | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
agentId | body | string | No | Empty string | Agent affiliation or filter; provided by knowledge endpoints only when scope=agent, and required in that case. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
runId | body | string | No | Empty string | The source run. |
memorySubStoreId | body | string | No | Empty string | You 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):
| Field | Type | Description |
|---|---|---|
id | string | Identifier of this feedback or observation record. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
idempotentReplay | boolean | Whether the result of an identical idempotent request was reused. |
revision | integer | Knowledge 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
profileType | query | string | No | 'content' | content (default) or topics. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
profile | object | Profile object, including profileContent/topics, version, rebuildStatus, etc. |
retrievedAt | string (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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
profileType | body | string | No | 'content' | content (default) or topics. |
reason | body | string | No | Empty string | Reason for the operation; required and non-empty for context confirmation, rebuild, and rollback. |
source | body | string | No | 'appbase_delete' | Operation origin marker; grants no additional permissions. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
profileId | string | Profile identifier. |
status | string | Current 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
pipelineId | body | string | No | Empty string | Optional published Pipeline ID; if omitted, the scenario default is used; Node SDK 2.12.0 supports this parameter. |
userId | path | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
profileType | body | string | No | 'content' | content (default) or topics. |
messages | body | array | Yes | [] | List of valid messages; role and non-empty content are required; message limits are described in the corresponding operation. |
sourceMemoryIds | body | array | No | [] | Supported by replace only; at most 100 valid current-user memories; cannot substitute for new messages. |
sessionId | body | string | No | Empty string | Optional conversation identifier, at most 128 UTF-8 bytes; does not substitute for permissions. |
mode | body | string | No | 'incremental' | incremental (default) or replace. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
memory | object | Memory object; contains memoryId, version, content, ownership and model processing status. |
profileExtraction | object | Profile 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
pipelineId | body | string | No | Empty string | Optional published Pipeline ID; if omitted, the scenario default is used; Node SDK 2.12.0 supports this parameter. |
userId | path | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
profileType | body | string | No | 'content' | content (default) or topics. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
jobId | string | Task identifier. |
profileId | string | Profile identifier. |
profileVersion | integer | Profile version. |
sourceCount | integer | Number 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
profileType | query | string | No | 'content' | content (default) or topics. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
profileType | string | Profile type: content/topics. |
sources | array | Sources currently visible and still valid. |
total | integer | Count of items matching the current query conditions. |
truncated | boolean | Whether 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
pipelineId | body | string | No | Empty string | Optional published Pipeline ID; if omitted, the scenario default is used; Node SDK 2.12.0 supports this parameter. |
userId | body | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
format | body | string | No | 'jsonl' | json or jsonl. |
data | body | string | No | Empty string | JSON/JSONL text import content; mutually exclusive with records. |
records | body | array | No | [] | Structured import list, at most 500 entries; mutually exclusive with data. |
dryRun | body | boolean | No | false | true 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):
| Field | Type | Description |
|---|---|---|
importId | string | Import query identifier. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
jobId | string | Task 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
importId | path | string | Yes | — | Import job ID. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
importId | string | Import query identifier. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
job | object | Async 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
format | body | string | No | 'jsonl' | json or jsonl. |
includeForgotten | body | boolean | No | false | Default false; exporting additional sensitive data requires system authorization; the boolean does not substitute for permission. |
includeVectors | body | boolean | No | false | Default false; exporting vectors requires system authorization. |
includeRawSources | body | boolean | No | false | Default false; exporting raw sources requires system authorization. |
mode | body | string | No | 'async' | async (default) or sync. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
exportId | string | Export query identifier. |
status | string | Current business status or task status; do not rely solely on the HTTP success code. |
job | object | Async 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
exportId | path | string | Yes | — | Export job ID. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
job | object | Async 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
userId | query | string | Yes | — | Target user ID; server-side requests must explicitly pass the business user, not substitute it via metadata. |
format | query | string | No | 'jsonl' | json or jsonl. |
mode | query | string | No | 'sync' | sync only. |
includeForgotten | query | boolean | No | false | Default false; exporting additional sensitive data requires system authorization; the boolean does not substitute for permission. |
includeVectors | query | boolean | No | false | Default false; exporting vectors requires system authorization. |
includeRawSources | query | boolean | No | false | Default false; exporting raw sources requires system authorization. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
schemaVersion | integer | Export structure version. |
format | string | json or jsonl format. |
mediaType | string | Media type of the exported content. |
generatedAt | string (time) | Export generation time. |
data | string | Encoded export text. |
memories | array | Array of memory objects. |
profiles | array | Exported profile collection. |
jobs | array | Exported job collection. |
vectors | array | Vector projections optionally exported with authorization. |
sources | array | Sources currently visible and still valid. |
metadata | object | Metadata 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
routes | body | array | Yes | [] | Projection rebuild requires one or more of dense, sparse, graph, without duplicates. |
cursor | body | string | No | Empty string | The nextCursor returned by the previous page, passed back as-is; audit cursors are non-negative integer offsets. |
limit | body | integer | No | 100 | Limit on items returned or processed this time; for the valid range see the parameter defaults and the corresponding operation boundaries. |
dryRun | body | boolean | No | false | true 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):
| Field | Type | Description |
|---|---|---|
routes | array | Projection routes selected for this request. |
dryRun | boolean | Whether this is a precheck or preview only. |
matched | integer | Number of pending items matched in this run. |
scheduled | integer | Number of tasks scheduled in this operation. |
conflicts | integer | Number of concurrency conflicts that occurred in this run. |
hasMore | boolean | When true, continue processing the next batch over the same range. |
nextCursor | string | Cursor 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
| None | — | — | — | — | No business request parameters. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
liveRecords | integer | Number of live records within the verification scope. |
dense | object | Dense projection verification result and ready status. |
sparse | object | Sparse projection verification result and ready status. |
graph | object | Graph projection verification result and ready status. |
repairRecommended | boolean | Whether a controlled repair is recommended. |
limitations | array | Limits of this verification; they cannot be ignored and then claimed to be fully consistent. |
verifiedAt | string (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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
| None | — | — | — | — | No business request parameters. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
visibleCount | integer | Number of currently visible memories. |
forgottenCount | integer | Number of forgotten memories. |
totalCount | integer | Total number of memories. |
indexStatus | object | Memory counts by index status. |
jobStatus | object | Counts by job status. |
from | string (time) | Start time of this statistics run (if provided). |
to | string (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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
| None | — | — | — | — | No business request parameters. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
visibleCount | integer | Number of currently visible memories. |
lowQualityCount | integer | Number of low-quality memories. |
pendingIndexes | integer | Number of indexes not yet ready. |
issues | array | Memories 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
| None | — | — | — | — | No business request parameters. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
buckets | array | Date 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.
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
| None | — | — | — | — | No business request parameters. |
Returned fields (only public structures are listed; conditionally returned fields may be omitted):
| Field | Type | Description |
|---|---|---|
sessions | array | List of session aggregates. |
total | integer | Count 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).
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
jobId | query | string | No | Empty string | Exact match on the memory task ID. |
query | query | string | No | Empty string | Keyword for searching audit content; optional. |
operation | query | string | No | Empty string | Filter by memory operation name (e.g. createMemory). |
outcome | query | string | No | Empty string | Filter by request result: success / failure. |
limit | query | integer | No | 25 | Upper limit on items returned or processed this time; see parameter defaults and the corresponding operation boundaries for the valid range. |
cursor | query | integer | No | 0 | The 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):
| Field | Type | Description |
|---|---|---|
audits | array | Audit records matching the filter conditions. |
total | integer | Count of items matching the current query conditions. |
nextCursor | integer / null | Cursor for the next page; a null value indicates no further pages. |
scanned | integer | The number actually scanned to obtain the results. |
truncated | boolean | Whether 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 path | Required permissions (Scope + role) | Core parameters | Purpose description |
|---|---|---|---|
GET /v1/memory/memories/knowledge/reviews/{reviewId} | memories.read + admin permission | reviewId (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 permission | title, 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}/approve | memories.write + admin permission | expectedVersion, 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}/reject | memories.write + admin permission | expectedVersion, 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}/revisions | memories.read | knowledgeId (path), limit, cursor (query) | List the complete immutable historical revision list of the specified experience or skill (knowledgeId). |
GET /v1/memory/memories/knowledge/{knowledgeId}/diff | memories.read | fromRevision, 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}/rollback | memories.write + admin permission | expectedVersion, 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:
Set APPBASE_ENDPOINT to the target environment API endpoint (including /v1), and confirm the project and credentials belong to that environment.
View and manually fine-tune distillation skill candidates pending approval (GET / PATCH /v1/memory/memories/knowledge/reviews/{reviewId})
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X PATCH "${APPBASE_ENDPOINT}/memory/memories/knowledge/reviews/rev_distill_0089" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
--data '{
"expectedVersion": 1,
"title": "OceanBase 日志盘满 (ERROR 4016) 应急扩容与限流标准技能",
"content": "1. 检查 gv$ob_log_stat 确认卡住的日志流;2. 临时调大 log_disk_utilization_limit_threshold 至 90%;3. 扩容节点日志盘并恢复阈值。",
"reason": "补充步骤 1 视图名称校准"
}'
)Approve the review for release (POST .../reviews/{reviewId}/approve; if rejected, call POST .../reviews/{reviewId}/reject)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/memory/memories/knowledge/reviews/rev_distill_0089/approve" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
-H "Idempotency-Key: approve-rev-0089-v1" \
--data '{
"expectedVersion": 2,
"reason": "经 SRE 团队复核验证通过,准予晋升为线上技能"
}'
)Query the knowledge revision list, compare version differences, and roll back on anomalies (GET .../revisions, GET .../diff, POST .../rollback)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X GET "${APPBASE_ENDPOINT}/memory/memories/knowledge/knw_skill_01/diff?fromRevision=3&toRevision=4" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @-
)Operation 4 (run separately). Run separately only after confirming the target and consequences.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/memory/memories/knowledge/knw_skill_01/rollback" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
-H "Idempotency-Key: rollback-knw-skill-01-to-r3" \
--data '{
"scope": "user",
"userId": "user_zhangwei_001",
"expectedVersion": 5,
"targetRevision": 3,
"reason": "Revision 4 在边缘场景下触发误判,回滚至稳定版 Revision 3"
}'
)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 configuration updates use optimistic concurrency control (CAS) with either expectedConfigVersion or the HTTP If-Match header:
Trial runs for saved Pipeline versions (2.12.0)
Reading trial-run results with a project API key requires projects.read and memories.read. Create a trial using an authorized management identity with POST /v1/memory/pipeline-runs, with 1–8 candidates and 1–20 samples. 202 means accepted; continue polling for a terminal state.
| Method and path | Scope | Parameters and response |
|---|---|---|
GET /v1/memory/pipeline-runs/{runId} | projects.read + memories.read | Retrieves frozen inputs, progress, and per-sample results. |
GET /v1/memory/pipeline-runs | projects.read + memories.read | Lists by scenario: default add_memory, or profile, distillation, or forgetting. limit is 1–50, default 20; cursor is an opaque pagination cursor. |
A trial compares the candidate configurations and samples frozen at acceptance without writing business memories. Model calls may incur charges depending on the configuration. Availability depends on the target deployment.
1. Four Memory Pipelines API (/v1/memory/pipelines*)
| Method and path | Core parameters | Purpose description |
|---|---|---|
GET /v1/memory/pipelines | scenario (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/pipelines | scenario, fromDefaults or config | Create a draft; fromDefaults: true uses the selected scenario defaults and is mutually exclusive with config. |
PATCH /v1/memory/pipelines/{id} | expectedRevision, config | Update the complete pipeline configuration using its current revision. |
POST /v1/memory/pipelines/{id}/validate | versionId, data; scenario for the system default | Validate a saved version with sample data without business memory writes; requires projects.write and memories.read. For forgetting, data may contain userId. |
POST /v1/memory/pipelines/{id}/publish | versionId, expectedRevision, optional makeDefault | Publish a validated draft; makeDefault controls whether it also becomes the default. |
PUT /v1/memory/pipelines/default | scenario, pipelineId, expectedRevision | Select a published pipeline as the scenario default; pipelineId: null restores the system default. |
For pipeline management operations and examples, see the Memory Configuration Center in the product manual.
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); an update may use the positive expectedConfigVersion or the If-Match header obtained from the GET response, or both:
Namespace (namespace) | Core configuration items | Description |
|---|---|---|
runtime | recallFusion, queryEmbeddingCache, unifiedRecall | Configure retrieval fusion, query embedding cache, and recall thresholds. |
prompt | factExtractionPrompt, profileExtractionPrompt, contextAggregationPrompt | Configure fact extraction, profile, and context aggregation prompts. |
policy | captureMode, filterAllowlist, forgetting | Configure capture, filter allowlist, and forgetting policies. |
retention | defaultDays, factDays, conversationDays, auditEventDays | Configure retention periods for different data types. |
provider | llmProviderRef, chatModel, embeddingModel, sparseEmbeddingEnabled | Configure providers, models, and sparse embeddings. |
evolution | autoDistillEnabled, requireConfirmation, dreaming | Configure automatic distillation, confirmation, and context aggregation. |
For management-plane configuration read and update examples, see the Memory Configuration Center in the product manual.
Errors and boundaries
400: Parameter or storage type not supported; check the message, size, range, and media restrictions.
401/403: Check the Key, project, scope, user ownership, and admin permissions.
404: Resource does not exist or is not visible; the profile may not have been generated yet.
409: version, expectedVersion, revision, or idempotency conflict; re-read and verify business intent, do not blindly overwrite.
429: Back off according to Retry-After.
503: Initialization or dependency temporarily unavailable; back off with bounds only for explicitly retryable errors, and reuse the original idempotency key for writes.
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.12.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 based on Agentbase 2.12.0, and the Node.js SDK reference uses the published agentbase-node-sdk@2.12.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. When the environment enforces strict version checks, use an SDK version that it supports.
2.12.0 endpoints and compatibility
Paths below are relative to /v1. Memory creation, profiles and search are data-plane operations and support a project API Key with the required scopes; keep the key on the server. Pipeline runs and validation are management operations. Their write routes require projects.write, which ordinary project API Keys cannot grant; use an authorized management identity. Scopes below are necessary; dataset access, ownership and resource state may add checks. HTTP 202 means accepted; use the returned operation identifier to read its terminal result.
| HTTP | Scope | SDK |
|---|---|---|
POST /memory/memories | memories.write | memory.create |
GET /memory/memories/profiles | memories.read | memory.listProfiles |
POST /memory/memories/search | memories.read | memory.search |
GET /memory/pipeline-runs | projects.read + memories.read | memory.listPipelineRuns |
POST /memory/pipeline-runs | projects.write | memory.createPipelineRun |
GET /memory/pipeline-runs/{runId} | projects.read + memories.read | memory.getPipelineRun |
POST /memory/pipelines/{pipelineId}/validate | projects.write | memory.validatePipeline |
POST /memory/memories
Create memory
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
pipelineId | body | no | string | default="" | Optional published add-memory Pipeline ID. Omit to use the project default or system default. |
content | body | no | string | default="" | Compatibility memory text. Required when messages and media are omitted. |
messages | body | no | array[object] | default=[] | Optional typed role/content messages used as source evidence. |
media | body | no | object | default=[] | Optional Storage file reference {bucketId, fileId}. Accepts one PNG, JPEG, WebP or PDF up to 8 MiB; PDFs allow at most 10 pages. Requires files.read and configured vision routing. Media writes require async=true. |
userId | body | yes | string | — | Target user ID. |
agentId | body | no | string | default="" | Optional agent ID. |
runId | body | no | string | default="" | Optional run ID. |
sessionId | body | no | string | default="" | Optional conversation ID (max 128 characters). With infer=true, bounded history is loaded only for user, group, and project scopes; private and strict_private never hydrate history. |
scope | body | yes | string | enum=private, strict_private, user, group, project | Memory visibility scope. |
sensitivity | body | no | string | enum=normal, confidential, restricted, secret; default="normal" | Content classification. Secret values must use Agentbase Secret or variables. |
handlingPolicy | body | no | string | enum=standard, no_embedding, no_model; default="standard" | Processing restriction. no_model requires infer=false. |
memoryType | body | yes | string | — | Memory type. With infer=true, conversation input is retained as source evidence and derived records use long_term. |
recordKind | body | yes | string | enum=conversation, fact, action | Memory record kind. With infer=true, conversation input derives fact records. |
metadata | body | no | object | default=[] | Memory metadata. |
sourceContext | body | no | object | default={} | Optional source conversationTime (YYYY-MM-DD or RFC3339 with offset) and timeZone (IANA). Missing conversation time stays unknown; it is not the event or import time. |
infer | body | no | boolean | default=true | Use configured model-assisted extraction and cross-type deduplication. Defaults to true. |
reRemember | body | no | boolean | default=false | Explicitly create new evidence for forgotten content. |
async | body | no | boolean | — | Queue memory creation and return immediately. Defaults to the infer value for text; media always requires true, including infer=false. |
Success response: HTTP 200 — any.
GET /memory/memories/profiles
List user memory profiles
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
cursor | query | no | string | default="" | Opaque pagination cursor. |
limit | query | no | integer | format=int32 | Maximum number of profiles. |
userId | query | no | string | default="" | Target user ID. |
profileType | query | no | string | enum=content, topics; default="" | Profile type. Omit to include every type. |
Success response: HTTP 200 — any.
POST /memory/memories/search
Search memories
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
query | body | no | string | default="" | Search query. May be omitted with media. |
searchMode | body | no | string | default="" | Recall mode override. |
retrieval | body | no | object | default=[] | Recall route overrides. sparse=false skips model-generated sparse recall for this request; omitted defaults to the project setting. |
media | body | no | object | default=[] | Optional Storage image reference {bucketId, fileId}. Accepts one PNG, JPEG or WebP up to 8 MiB. Requires files.read and configured vision routing; parsed text is used for retrieval without writing a memory. |
userId | body | no | string | default="" | Target user ID. |
agentId | body | no | string | default="" | Agent ID filter. |
runId | body | no | string | default="" | Run ID filter. |
scope | body | no | string | default="" | Scope filter. |
memoryType | body | no | string | default="" | Memory type filter. |
recordKind | body | no | string | default="" | Record kind filter. |
filter | body | no | object | default={} | Structured memory filter. |
temporal | body | no | object | default={} | Optional mode current, asOf or history; asOf requires a timestamp with timezone. Uncertain facts are returned separately. |
limit | body | no | integer | format=int32; default=0 | Maximum results; zero uses the project default. |
cursor | body | no | string | default="" | Pagination cursor. |
sort | body | no | string | default="" | Sort mode. |
memorySubStoreId | body | no | string | default="" | Bound memory sub-store ID. |
sessionId | body | no | string | default="" | Session ID filter. |
groupId | body | no | string | default="" | Group or entity boundary filter. |
accessMode | body | no | string | enum=owned, accessible; default="owned" | Use owned for owner-filtered compatibility or accessible for the authorized visibility union. |
Success response: HTTP 200 — any.
GET /memory/pipeline-runs
List Memory Pipeline trial runs
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
scenario | query | no | string | enum=add_memory, profile, distillation, forgetting; default="add_memory" | Pipeline scenario. |
limit | query | no | integer | format=int32; default=20 | Maximum number of trial runs. |
cursor | query | no | string | default="" | Opaque pagination cursor. |
Success response: HTTP 200 — memoryPipelineRunList.
Response fields: runs (array), total (integer), nextCursor (string).
POST /memory/pipeline-runs
Create a Memory Pipeline trial run
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
name | body | yes | string | — | Trial run name, from 1 to 256 UTF-8 bytes after trimming. |
scenario | body | yes | string | enum=add_memory, profile, distillation, forgetting | Shared scenario of all candidates. |
candidates | body | yes | array[object] | — | One to eight objects containing pipelineId and saved versionId. |
samples | body | yes | array[object] | — | One to twenty objects containing a unique id and scenario-specific data object. |
Success response: HTTP 202 — memoryPipelineRun.
Response fields: runId (string), name (string), scenario (string), status (string), createdAt (string), updatedAt (string), total (integer), completed (integer), succeeded (integer), failed (integer), candidates (array), samples (array), results (array), error (object).
GET /memory/pipeline-runs/{runId}
Get a Memory Pipeline trial run
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
runId | path | yes | string | — | Trial run ID. |
Success response: HTTP 200 — memoryPipelineRun.
Response fields: runId (string), name (string), scenario (string), status (string), createdAt (string), updatedAt (string), total (integer), completed (integer), succeeded (integer), failed (integer), candidates (array), samples (array), results (array), error (object).
POST /memory/pipelines/{pipelineId}/validate
Validate a Memory Pipeline
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
pipelineId | path | yes | string | — | Pipeline ID. |
versionId | body | yes | string | — | Saved configuration version or current system default hash. |
scenario | body | no | string | enum=add_memory, profile, distillation, forgetting | Scenario for system default validation. |
data | body | yes | object | default={} | Sample input for the Pipeline scenario, evaluated without business writes. |
Success response: HTTP 200 — any.
Errors and retries
400/422: check types, enumerations and rules. 401/403: verify identity and scopes; dataset analyses additionally require trace and dataset read access. 404: check that the resource exists in the current project. 409: read current state before deciding to retry. 429: honor Retry-After. After 5xx or network loss, inspect operation state first. Preserve an idempotency key across retries; change it only for a deliberate new operation. Confirm deletion and clearing targets before writing.