PolarDB Memory Management mem0 API Reference-PolarDB(PolarDB)-阿里云帮助中心

PolarDBMemory Managementis compatible with the open-source mem0 REST API protocol and provides rich memory enhancement features. This document provides a comprehensive API quick reference for developers,covering all interfaces including memory write, search, governance, prompt customization, and profile/personality management.

Important

memOS engine uses a different API system. Refer to http://<memOS_host>:<port>/docs for its API documentation.

Overview

This guide provides developers with a quick reference to the PolarDB Memory Management REST API: each interface is organized in a four-part structure of Feature Description, Key Parameters, Interface Definition, and Example. You can copy the curl examples for quick validation. The document contains five chapters:

Chapter	Content	Use Case
I. Memory Management	Memory write, search, CRUD, batch operations, history, and reset	Foundational capability for all integrations
II. Features	Merge, retry, categorization, authorization sharing, expiration, time decay, reference count, async tasks, Per-User Key, conflict detection, and other production-grade features	Scenarios requiring memory governance, multi-tenant isolation, and O&M capabilities
III. Prompts Management	Built-in Prompt types, CRUD for custom templates, request-level overrides, and Variable Substitution	Scenarios requiring customization of LLM extraction, merge, and Q&A behavior
IV. Profile and AI Personality Management	Schema definition, extraction, and query for user profiles and AI personalities	Scenarios requiring personalized interaction experiences
V. Multimodal Memory	File Upload, image/audio/video memory write, image-to-image search, text-to-image search, Hybrid Search, and video streams	Scenarios requiring non-text media processing

Conventions

Auth header Authorization: Token <MEM0_API_KEY>;Example base URL http://{endpoint}:8080;Request body is JSON;output_format default v1.1.

I. Memory Management

Write/Extract Memories (POST /v1/memories)

Extract memory fragments from conversation messages via LLM and store them in the vector store;infer=false the entire original text is stored as a single memory (for failure retry).

POST /v1/memories

Key Parameters

Parameter	Required	Default	Description
`messages`	Yes	—	List of conversation messages, each containing `role`/`content`, Optional `created_at`
`user_id`/`agent_id`/`run_id`	Yes	—	Business identifier, at least one required
`infer`	No	`true`	Whether to use LLM inference
`async_mode`	No	`false`	`true` immediately returns job_id
`message_id`	No	—	Message identifier, used for merge/retry
`metadata`	No	—	Metadata; special fields `created_at`/`timestamp`/`expiration_date`
`categories` / `custom_categories` / `category_template`	No	—	Manual tags (highest priority) / direct categorization dictionary / template reference
`timestamp` / `expiration_date`	No	—	Unix timestamp / expiration date(`YYYY-MM-DD`,ISO,`7d`/`24h`)
`temperature`	No	—	Request-level LLM temperature(0.0~2.0)
`org_id` / `project_id` / `app_id`	No	—	Organization / project / application ID

Example

curl -X POST http://localhost:8888/v1/memories \
  -H "Authorization: Token apikey" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "I like playing basketball"}],
    "user_id": "alice",
    "async_mode": false
  }'

Returns results[],each containingincluding id/event(ADD/UPDATE/DELETE)/data.memory.

Search Memories by Semantics (POST /v2/memories/search)

Three-way recall (vector semantics + BM25 + entity-enhanced) Hybrid Search, with support for reranking, graph retrieval, shared memories, and time decay.

POST /v2/memories/search

Key Parameters

Parameter	Required	Default	Description
`query`	Yes	—	Search query
`filters`	Yes	—	Filter conditions; must contain at least one business identifier
`top_k` / `threshold`	No	`5` / `0.3`	Number of results / minimum similarity threshold
`rerank`	No	`false`	Whether to rerank
`fields`	No	—	Response field whitelist
`shared_user_ids` / `enable_search_shared`	No	— / `false`	Specify shared users / automatically merge authorized party memories
`time_decay` / `time_decay_half_life_days` / `time_decay_cutoff`	No	`false`/`7`/`0.01`	Time decay toggle / half-life / cutoff threshold

Example

curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token apikey" \
  -H "Content-Type: application/json" \
  -d '{"query": "What coffee do you like", "filters": {"user_id": "Zhang San"}, "top_k": 5}'

Retrieve/Filter Memories - In-Memory Pagination (POST /v2/memories)

List memories with pagination based on filter conditions;filters.categories Supports in/nin/contains/icontains/*/_ALL_ Syntax.

POST /v2/memories

Key Parameters

Parameter	Required	Default	Description
`filters`	Yes	—	Filter conditions; must contain at least one business identifier
`page` / `page_size`	No	`1` / `100`	Page number / page size
`fields`	No	—	Response field whitelist

Example

curl -X POST http://localhost:8888/v2/memories \
  -H "Authorization: Token apikey" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"user_id": "alice"}, "page": 1, "page_size": 50}'

Get Memory List - Database-Level Pagination (POST /v2/memories/list)

Database-level paginated query. Returns pagination information with total count, suitable for large datasets.

Key Parameters

Parameter	Default	Description
Business identifier (at least one required)	—	`user_id`/`agent_id`/`run_id`
`filters`	—	Filter conditions
`fields`	—	Response fields
`page` / `page_size`	`1` / `20`	Page number / page size
`org_id`/`project_id`	—	Organization / project ID

Example

curl -X POST http://localhost:8888/v2/memories/list \
  -H "Authorization: Token apikey" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "page": 1, "page_size": 20}'
# Returns results + pagination{total, page, page_size, total_pages}

Get Single Memory (GET /v1/memories/{memory_id})

Query a single memory by ID.Optional query output_format.

curl http://localhost:8888/v1/memories/<MEMORY_ID> -H "Authorization: Token apikey"

Query Memories by message_id (GET /v1/memories/by-message/{message_id})

Note

This API is currently in the grayscale phase. To use it, submit a ticket to contact us.

Query all memories extracted from a specific message_id, Returns results + message_id + total.

curl http://localhost:8888/v1/memories/by-message/msg-001 -H "Authorization: Token apikey"

Update Memory (PUT /v1/memories/{memory_id})

Directly update memory text and/or metadata. Body:text/metadata at least one required.

curl -X PUT http://localhost:8888/v1/memories/<MEMORY_ID> \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"text": "Likes oat latte"}'

Delete Single Memory (DELETE /v1/memories/{memory_id})

by ID Delete Single Memory.

curl -X DELETE http://localhost:8888/v1/memories/<MEMORY_ID> -H "Authorization: Token apikey"

Batch Delete Memories (DELETE /v1/memories)

Batch delete by identifiers.

Query:user_id/agent_id/app_id/run_id at least one required
Optional org_id/project_id/metadata.

curl -X DELETE "http://localhost:8888/v1/memories?user_id=alice" -H "Authorization: Token apikey"

Batch Update Memories (PUT /v1/batch)

BatchUpdate,per request ≤1000 records. Body:memories[],each containingincluding memory_id + text/metadata at least one required.

curl -X PUT http://localhost:8888/v1/batch \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"memories": [{"memory_id": "uuid-1", "text": "Updated content"}]}'

Batch Delete Memories ID List (DELETE /v1/batch)

by ID ListBatchDelete,per request ≤1000 records. Body:memory_ids[].

curl -X DELETE http://localhost:8888/v1/batch \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"memory_ids": ["uuid-1", "uuid-2"]}'

Get Memory Change History (GET /v1/memories/{memory_id}/history)

Query the complete change event chain of a memory(ADD/UPDATE/DELETE).

curl http://localhost:8888/v1/memories/<MEMORY_ID>/history -H "Authorization: Token apikey"

Reset All Memories (POST /v1/reset)

Warning

Deletes all memories under the specified identifiers (including profile and personality data). This operation is irreversible. Body:user_id/agent_id/run_id at least one required.

curl -X POST http://localhost:8888/v1/reset \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice"}'

Entity List (GET /v1/entities/list)

List entity IDs of the specified type with pagination. Queryrequirementssuch asunder:

Business identifierid_type(Required,at least one required):user_id/agent_id/run_id
page:default 1
page_size:default 50,max 1000

curl "http://localhost:8888/v1/entities/list?id_type=user_id" -H "Authorization: Token apikey"

II. Features

Note

Production-grade features added or enhanced compared to open-source mem0.

Memory Merge (POST /v1/memories/merge)

Merge fragmented memories into complete memories. Supports message_ids mode and time-range mode, three conflict strategies.

Key Parameters

Parameter	Required	Description
`message_ids`	Yes	List of message_ids to merge (mutually exclusive with user_id/agent_id, takes priority)
`user_id` / `agent_id`	Yes	Time range mode identifier (choose one)
`run_id`	No	When provided, conflict detection only matches the same run_id
`start_time` / `end_time`	No	Time range (ISO 8601)
`range_days`	No	Lookback days, default 7
`merge_type`	No	`none`(default,only ADD)/ `append`(UPDATE create versioned copy)/ `update`(full ADD/UPDATE/DELETE)
`delete_old`	No	Whether to delete source memories, default `false`

Example

curl -X POST http://localhost:8888/v1/memories/merge \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"message_ids": ["msg-001", "msg-002"]}'

# Time range + update strategy + delete source memories
curl -X POST http://localhost:8888/v1/memories/merge \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "user-123", "range_days": 7, "merge_type": "update", "delete_old": true}'

Returns merged_memory.results[] + source_message_ids + merged_count + merge_type.

Retry Failed Memories (POST /v1/memories/retry)

infer=false(LLM inference failed) memories with the original configuration to rerun inference and extraction.

Key Parameters:

user_id/agent_id/run_id/app_id/message_ids at least one required
max_retries:default5.

Example

curl -X POST http://localhost:8888/v1/memories/retry \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "message_ids": ["msg-001"]}'

allsucceededReturns 200;partialfailedReturns 201(including failed_count/failed_message_ids).

Auto-Categorization/Tagging

Predefined categorization templates. LLM automatically applies multi-label categorization during write. Results are stored in metadata.categories.priority:categories(manual)> custom_categories > category_template;Unmatched items are assigned to _RESERVED_.

Category Template CRUD

POST   /v1/category-templates                              # user_id(omit=public template) + template_name(Required, globallyly unique) + categories(Required)
GET    /v1/category-templates(?user_id=&include_public=)   # List
GET    /v1/category-templates/public                       # Public templates
GET    /v1/category-templates/{template_name}(?user_id=)   # Single
PUT    /v1/category-templates/{template_name}(?user_id=)   # Update(full replacement categories)
DELETE /v1/category-templates/{template_name}(?user_id=)   # Delete

Example

curl -X POST http://localhost:8888/v1/category-templates \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "template_name": "user_profile",
    "categories": {"basic_info": "Name, age, etc.", "hobby": "Hobbies and interests"}
  }'

# Reference template for tagging during write
curl -X POST http://localhost:8888/v1/memories \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "My name is Zhang San, I like cycling"}], "user_id": "alice", "category_template": "user_profile"}'

Search by category(search and list interface's filters.categories):

Syntax	Description
`{"categories": "hobby"}`	Exact match
`{"categories": ["a","b"]}` or `{"in": [...]}`	OR match
`{"nin": ["_RESERVED_"]}`	Exclude
`{"contains": "food"}` / `{"icontains": "FOOD"}`	Substring match
`"_ALL_"`	Equivalent to excluding `_RESERVED_`

Memory Authorization Sharing

Users or agents authorize memory access to other users or agents (one-way). Authorized parties automatically receive the authorizer's memories via enable_search_shared=true automatically receive the authorizer's memories.

Authorization management interfaces

POST   /v1/shared_authorization    # Create:user_id/agent_id(authorizer,at least one required) + to_user_id/to_agent_id(at least one required),idempotent
GET    /v1/shared_authorization    # Query the authorizer's authorization list(?user_id= or ?agent_id=)
DELETE /v1/shared_authorization    # Delete: body contains authorizer identifiers; omitting to_* deletes all authorizations

Example

# alice authorizationto bob
curl -X POST http://localhost:8888/v1/shared_authorization \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "to_user_id": "bob"}'

# bob search merges memories from alice memories
curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"query": "Dietary preferences", "filters": {"user_id": "bob"}, "enable_search_shared": true}'

Results are deduplicated by id, each retaining the original user_id to distinguish the source.

Memory Expiration Management

Set expiration times for memories. Expired memories are automatically filtered and physically deleted during retrieval (Lazy GC). format:YYYY-MM-DD,ISO 8601,relative duration(7d/24h/30m/60s);Invalid formats are treated as never expiring.

Set expiration on write:`POST /v1/memories` `expiration_date` parameter.

curl -X POST http://localhost:8888/v1/memories \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "messages": [{"role": "user", "content": "Temporary verification code"}], "expiration_date": "30m"}'

Actively delete expired memories (DELETE /v1/memories/expired)

Query:user_id/agent_id at least one required, Optional run_id,dry_run=true(preview only).

curl -X DELETE "http://localhost:8888/v1/memories/expired?user_id=user1&dry_run=true" \
  -H "Authorization: Token apikey"

Default expiration policies

Note

This API is currently in the grayscale phase. To use it, submit a ticket to contact us.

Preset default expiration policies by dimension. When expiration_date is not provided during write, the policy is automatically applied. priority:run_id > agent_id > user_id.

POST   /v1/expiration-policy    # body: dimension_type(user_id/agent_id/run_id) + dimension_value + expiration_value
GET    /v1/expiration-policy    # Query (filterable by dimension)
DELETE /v1/expiration-policy    # body: dimension_type + dimension_value

curl -X POST http://localhost:8888/v1/expiration-policy \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"dimension_type": "user_id", "dimension_value": "alice", "expiration_value": "7d"}'

Memory Time Decay

Weight memories by freshness during search:final_score = vector_score × exp(-elapsed/half_life × ln2).onlywhen rerank=false applied(reranking already provides the final ordering,no further decay needed).

Key Parameters:

time_decay:default false)
time_decay_half_life_days:default 7
time_decay_cutoff:default 0.01,memories below this score are not returned.

curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"query": "What have you been doing recently", "filters": {"user_id": "alice"}, "time_decay": true, "time_decay_half_life_days": 7}'

Refresh active time(extend effective lifespan):POST /v1/memories/{memory_id}/touch(no body).

curl -X POST http://localhost:8888/v1/memories/<MEMORY_ID>/touch -H "Authorization: Token apikey"

Procedural Memory

via memory_type="procedural_memory" to write step-by-step operational knowledge (such as tool invocation workflows). The original text is not inferred or distilled.

curl -X POST http://localhost:8888/v1/memories \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "memory_type": "procedural_memory",
    "messages": [{"role": "user", "content": "Flight booking process: 1. Search flights 2. Select cabin class 3. Pay"}]
  }'

Memory Reference Count

Count the number of times a memory has been merged or updated, used to identify core memories (higher reference counts indicate greater deletion risk).

GET  /v1/memories/{memory_id}/ref_count             # Single memory reference count (returns 0 if no records)
GET  /v1/memories/ref_count/by_message_id?message_id={message_id}   # by message_id Query
POST /v1/memories/ref_count/batch                   # Batch:body  memory_ids[] or message_ids[](choose one,≤1000)
GET  /v1/memories/ref_count/zero                    # Zero-reference memories(?page=1&page_size=100)
GET  /api/v1/dashboard/ref_count_distribution       # Reference count distribution (5 buckets, for dashboard)
GET  /api/v1/dashboard/ref_count_detail?bucket={bucket}   # Bucket details(bucket: 0-9/10-49/50-99/100-999/1000+)

curl -X POST http://localhost:8888/v1/memories/ref_count/batch \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"memory_ids": ["uuid-1", "uuid-2"]}'

Async Tasks and Webhooks

Task query

async_mode=true write/merge//ingest operationsReturns job_id, Query status via the following interfaces.

GET    /v1/jobs/{job_id}        # Single task status(pending/running/completed/failed)andresults
GET    /v1/jobs                 # Task list(?user_id=&status=&limit=&offset=)
DELETE /v1/jobs/expired         # Clean up expired task records(?days=,default 7)

curl http://localhost:8888/v1/jobs/<JOB_ID> -H "Authorization: Token apikey"

Webhook Notifications

Push results to the registered URL push results,signature header X-Mem0-Signature(HMAC-SHA256).

POST   /v1/webhooks                 # url (Required) + events (Required, e.g. ["memory.add_completed"]) + secret (optional, auto-generated if not provided)
GET    /v1/webhooks                 # List (secret not echoed)
DELETE /v1/webhooks/{webhook_id}    # Delete

curl -X POST http://localhost:8888/v1/webhooks \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hook", "events": ["memory.add_completed"], "secret": "my-secret"}'

Multi-Tenant Isolation (User-Level API Key)

Note

This API is currently in the grayscale phase. To use it, submit a ticket to contact us.

In multi-tenant scenarios, you can issue independent Keys (m0sk_ prefix) to end users, automatically binding user_id for data isolation. The plaintext key is returned only once at creation.

POST   /v1/user-keys                        # Create:user_id(Required) + description;response includes plaintext api_key
GET    /v1/user-keys                        # List (metadata only)
GET    /v1/user-keys/{key_id}               # Details
DELETE /v1/user-keys/{key_id}               # Delete (immediately invalidated)
PUT    /v1/user-keys/{key_id}/binding       # Change bound user:body {"user_id": "ID"}

Dashboard equivalentendpoint(same functionality, only global Key available):

POST   /api/v1/dashboard/user-keys
GET    /api/v1/dashboard/user-keys
GET    /api/v1/dashboard/user-keys/{key_id}
DELETE /api/v1/dashboard/user-keys/{key_id}

Example

curl -X POST http://localhost:8888/v1/user-keys \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "description": "alice application endpoint"}'
# Returns {"key_id": "...", "api_key": "m0sk_****(only thisonce)"}

# End users call with their dedicated Key call,no needto pass user_id
curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token m0sk_xxx" -H "Content-Type: application/json" \
  -d '{"query": "My preferences", "filters": {}}'

Memory Conflict Detection

Note

This API is currently in the grayscale phase. To use it, submit a ticket to contact us.

Detect semantically similar but potentially contradictory memory pairs, with support for manual resolution.

POST /v1/memories/conflicts                    # Synchronous detection
POST /v1/memories/conflicts/async              # Asyncdetection, Returns job_id
GET  /v1/memories/conflicts/history            # Historical detection records
POST /v1/memories/conflicts/{conflict_id}/resolve   # resolution:keep_a / keep_b / keep_both / merge

Key Parameters(detection interface):user_id/agent_id(at least one required),similarity_threshold(default 0.7),max_pairs(default 50),run_id(optional,only matches the same run).

Conflict types: factual contradiction, temporal contradiction, granularity contradiction.

curl -X POST http://localhost:8888/v1/memories/conflicts \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "similarity_threshold": 0.75}'

III. Prompts Management

Prompts have two levels: types (14 built-in) and implementations (multiple implementations per type). Selection priority: request-level prompts parameter > database custom implementation > built-indefault.

Built-in Prompt Types Overview

Type	Purpose
`FACT_RETRIEVAL_PROMPT`	Fact extraction(default)
`MERGE_MEMORY_PROMPT`	Memory Mergeresolution
`UPDATE_MEMORY_PROMPT_V1`	ADD/UPDATE/DELETE decision during write
`DELETE_RELATIONS_SYSTEM_PROMPT`	Graph relation deletion
`EXTRACT_ENTITIES_PROMPT`	Entity extraction
`GRAPH_PROMPT`	Graph relation extraction
`PROFILE_EXTRACTION_PROMPT`	Profile extraction
`PROFILE_MERGE_PROMPT`	Profile merge
`PERSONALITY_EXTRACTION_PROMPT`	AI personalityextract
`ANSWER_PROMPT`	Intelligent Q&A response
`QUERY_REWRITE_PROMPT`	Query rewrite
`MULTIMODAL_CAPTION_PROMPT`	Multimodal caption generation

Reload Prompt (POST /v1/config/reload)

from disk/reload the specified Prompt from disk/database Prompt. Query:prompt_name(Required).

curl -X POST "http://localhost:8888/v1/config/reload?prompt_name=FACT_RETRIEVAL_PROMPT" \
  -H "Authorization: Token apikey"

Query Prompt List (GET /v1/config/prompts)

List all Prompt Typeand implementations. Optional query prompt_name filter.

curl "http://localhost:8888/v1/config/prompts" -H "Authorization: Token apikey"

Create Custom Prompt (POST /v1/config/prompts)

Body:prompt_name(Required,must be a known type),prompt_content(Required,including {variable} placeholders),is_default(optional,is the default implementation).

curl -X POST http://localhost:8888/v1/config/prompts \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"prompt_name": "FACT_RETRIEVAL_PROMPT", "prompt_content": "Extract facts about {user_id} from the conversation: {input}", "is_default": false}'

Update Prompt Content (PUT /v1/config/prompts/{prompt_name}/content)

Body:prompt_content(Required).

curl -X PUT http://localhost:8888/v1/config/prompts/FACT_RETRIEVAL_PROMPT/content \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"prompt_content": "New template content: {input}"}'

Delete Custom Prompt (DELETE /v1/config/prompts/{prompt_name})

Only custom implementations can be deleted; built-in defaults cannot be deleted. After deletion, the system falls back to the built-in version.

curl -X DELETE http://localhost:8888/v1/config/prompts/FACT_RETRIEVAL_PROMPT \
  -H "Authorization: Token apikey"

Request-Level Prompt Override (prompts parameter)

The prompts parameter in the write/merge interface temporarily overrides templates of the specified type (does not affect the database).Supports overriding multiple types simultaneously (e.g., customizing extraction and merge in parallel).

curl -X POST http://localhost:8888/v1/memories \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "messages": [{"role": "user", "content": "I live in Beijing"}],
    "prompts": {"FACT_RETRIEVAL_PROMPT": "Extract only residence information: {input}"}
  }'

Prompt Variable Substitution (prompt_vars parameter)

Two-level nesting: outer level by template name (or "_default"),), inner level is {placeholders: }.Reserved keys (such as input)) cannot be overridden; unspecified placeholders are retained as-is.

curl -X POST http://localhost:8888/v1/memories \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "messages": [{"role": "user", "content": "I live in Beijing"}],
    "prompt_vars": {"FACT_RETRIEVAL_PROMPT": {"language": "Chinese", "focus": "Residence"}}
  }'

IV. Profile and AI Personality Management

Profile Schema Management

Schema Defines the structured fields of a profile (the target format for LLM extraction).

POST   /v1/profile/schemas                 # Create:name(Required) + description + fields(Required)
GET    /v1/profile/schemas                 # List
GET    /v1/profile/schemas/{schema_id}     # Details
PUT    /v1/profile/schemas/{schema_id}     # Update
DELETE /v1/profile/schemas/{schema_id}     # Delete

curl -X POST http://localhost:8888/v1/profile/schemas \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{
    "name": "Customer profile",
    "fields": [
      {"name": "nickname", "type": "string", "description": "Nickname"},
      {"name": "preferences", "type": "array", "description": "Preference list"}
    ]
  }'

Get User Profile (GET /v1/profile/users/{user_id})

Query:schema_id(Required).Returnsschema-structured profile and version information.

curl "http://localhost:8888/v1/profile/users/alice?schema_id=<SCHEMA_ID>" \
  -H "Authorization: Token apikey"

Delete User Profile (DELETE /v1/profile/users/{user_id})

Query:schema_id(Required).

curl -X DELETE "http://localhost:8888/v1/profile/users/alice?schema_id=<SCHEMA_ID>" \
  -H "Authorization: Token apikey"

4.4 Trigger Profile Extraction (POST /v1/profile/extract)

Two-stage process:PROFILE_EXTRACTION_PROMPT extracts candidate fields from memories → PROFILE_MERGE_PROMPT merges with existing profile (retains historical versions).

Key Parameters:

user_id:Required.
schema_id:Required.
limit:Number of memories to extract from,default 100.
start_time/end_time:Time window; automatically inferred when omitted.

Example

curl -X POST http://localhost:8888/v1/profile/extract \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "schema_id": "<SCHEMA_ID>"}'

Initialize Profile (POST /v1/profile/init)

Note

This API is currently in the grayscale phase. To use it, submit a ticket to contact us.

Initialize a profile based on all historical memories at once (suitable for onboarding existing users).Body:user_id(Required),schema_id(Required).

curl -X POST http://localhost:8888/v1/profile/init \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "schema_id": "<SCHEMA_ID>"}'

AI personality Schema Management

AI personalityis a user-level global dimension (describing the tone/role the AI should use when interacting with the user). The structure is the same as the profile Schema.

POST   /v1/personality/schemas                 # Create
GET    /v1/personality/schemas                 # List
GET    /v1/personality/schemas/{schema_id}     # Details
PUT    /v1/personality/schemas/{schema_id}     # Update
DELETE /v1/personality/schemas/{schema_id}     # Delete

curl -X POST http://localhost:8888/v1/personality/schemas \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{
    "name": "Personality template",
    "fields": [
      {"name": "tone", "type": "string", "description": "Tone style"},
      {"name": "formality", "type": "string", "description": "Formality level"}
    ]
  }'

Query User AI Personality (GET /v1/personality/users/{user_id})

Query:schema_id(Required).

curl "http://localhost:8888/v1/personality/users/alice?schema_id=<SCHEMA_ID>" \
  -H "Authorization: Token apikey"

Trigger Personality Extraction (POST /v1/personality/extract)

Body:user_id(Required),schema_id(Required), Optional limit/start_time/end_time.

curl -X POST http://localhost:8888/v1/personality/extract \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "schema_id": "<SCHEMA_ID>"}'

V. Multimodal Memory

Note

Multimodal memory is currently in the grayscale phase. To use it, submit a ticket to contact us.

File Upload (POST /v3/files/upload)

multipart Upload raw files (images/audio/video). Supports two modes: upload to server local directory and OSS storage. Returns a unique file identifier for subsequent interface references.

Key Parameters(form-data):file(Required),user_id/agent_id/run_id(at least one required).

curl -X POST http://localhost:8888/v3/files/upload \
  -H "Authorization: Token apikey" \
  -F "file=@photo.jpg" -F "user_id=alice"

Multimodal MemoryWrite (POST /v3/memories/multimodal)

Perform understanding on images/audio/video (VLM captioning, ASR transcription, video frame extraction) and write to memory. Supports local paths(access_type=local),URL(Http,OSS),base64,file_id.

Key Parameters

Parameter	Description
`image` / `audio` / `video`	Three media input types; when multiple are provided, priority is video > audio > image
`user_id`/`agent_id`/`run_id`	at least one required
`access_type`	`local`(Local path)/ `url` / `base64` / `file_id`
`force`	`true` bypasses the entropy trigger for forced processing
`messages`	Optional contextual conversation
`metadata`	Metadata

curl -X POST http://localhost:8888/v3/memories/multimodal \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "image": "/tmp/photo.jpg", "access_type": "local", "force": true}'
# Returns caption(VLM description),memory(extracted memories),media reference

Visual Search - Image-to-Image Search (POST /v3/memories/visual-search)

Use an image as a query to search for similar multimodal memories in the visual vector space (CLIP/visual embeddings).

Key Parameters:image(Required),access_type,user_id(Required or filters),top_k(default 5),threshold.

curl -X POST http://localhost:8888/v3/memories/visual-search \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "image": "/tmp/query.jpg", "access_type": "local", "top_k": 5}'

5.4 Text-to-Image Search (Reuse Search API)

Note

This feature reuses POST /v2/memories/search endpoint (verified working), does not depend on /v3/ endpoint.

Text search for multimodal memories has no dedicated endpoint; it reuses POST /v2/memories/search:caption are stored as text memories, so a text query can match multimodal memories (results include media references).

curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"query": "Sunset at the beach", "filters": {"user_id": "alice"}}'

Hybrid Search (POST /v3/memories/hybrid-search)

Text + visual joint retrieval with RRF fusion ranking(final_score lower is better),resultsincluding fusion_source indicates the source.

Key Parameters:query(text, optional),image(image, optional; at least one of the two),user_id,top_k,threshold.

curl -X POST http://localhost:8888/v3/memories/hybrid-search \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "query": "Travel photos", "image": "/tmp/q.jpg", "access_type": "local", "top_k": 10}'

Get Multimodal Raw Content (GET /v3/memories/{memory_id}/raw)

ReturnsMultimodal Memory's raw media references (paths/URLs) and transcribed text.

curl http://localhost:8888/v3/memories/<MEMORY_ID>/raw -H "Authorization: Token apikey"

Video Stream Write (POST /v3/memories/video-stream)

Video frame extraction + GPS track writing, with support for per-frame retrieval and track interpolation. Body:frames[],gps_points[],user_id(Required).Result types include frame memories, scene summaries, gps, and transcript.

curl -X POST http://localhost:8888/v3/memories/video-stream \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "frames": [{"image": "/tmp/frame1.jpg", "timestamp": 0}],
    "gps_points": [{"lat": 31.23, "lon": 121.47, "timestamp": 0}]
  }'

Overview

Conventions

I. Memory Management

Write/Extract Memories (POST /v1/memories)

Search Memories by Semantics (POST /v2/memories/search)

Retrieve/Filter Memories - In-Memory Pagination (POST /v2/memories)

Get Memory List - Database-Level Pagination (POST /v2/memories/list)

Get Single Memory (GET /v1/memories/{memory_id})

Query Memories by message_id (GET /v1/memories/by-message/{message_id})

Update Memory (PUT /v1/memories/{memory_id})

Delete Single Memory (DELETE /v1/memories/{memory_id})

Batch Delete Memories (DELETE /v1/memories)

Batch Update Memories (PUT /v1/batch)

Batch Delete Memories ID List (DELETE /v1/batch)

Get Memory Change History (GET /v1/memories/{memory_id}/history)

Reset All Memories (POST /v1/reset)

Entity List (GET /v1/entities/list)

II. Features

Memory Merge (POST /v1/memories/merge)

Retry Failed Memories (POST /v1/memories/retry)

Auto-Categorization/Tagging

Category Template CRUD

Memory Authorization Sharing

Authorization management interfaces

Memory Expiration Management

Set expiration on write:POST /v1/memories expiration_date parameter.

Actively delete expired memories (DELETE /v1/memories/expired)

Default expiration policies

Memory Time Decay

Procedural Memory

Memory Reference Count

Async Tasks and Webhooks

Task query

Webhook Notifications

Multi-Tenant Isolation (User-Level API Key)

Memory Conflict Detection

III. Prompts Management

Built-in Prompt Types Overview

Reload Prompt (POST /v1/config/reload)

Query Prompt List (GET /v1/config/prompts)

Create Custom Prompt (POST /v1/config/prompts)

Update Prompt Content (PUT /v1/config/prompts/{prompt_name}/content)

Delete Custom Prompt (DELETE /v1/config/prompts/{prompt_name})

Request-Level Prompt Override (prompts parameter)

Prompt Variable Substitution (prompt_vars parameter)

IV. Profile and AI Personality Management

Profile Schema Management

Get User Profile (GET /v1/profile/users/{user_id})

Delete User Profile (DELETE /v1/profile/users/{user_id})

4.4 Trigger Profile Extraction (POST /v1/profile/extract)

Initialize Profile (POST /v1/profile/init)

AI personality Schema Management

Query User AI Personality (GET /v1/personality/users/{user_id})

Trigger Personality Extraction (POST /v1/personality/extract)

V. Multimodal Memory

File Upload (POST /v3/files/upload)

Multimodal MemoryWrite (POST /v3/memories/multimodal)

Visual Search - Image-to-Image Search (POST /v3/memories/visual-search)

5.4 Text-to-Image Search (Reuse Search API)

Hybrid Search (POST /v3/memories/hybrid-search)

Get Multimodal Raw Content (GET /v3/memories/{memory_id}/raw)

Video Stream Write (POST /v3/memories/video-stream)

Set expiration on write:`POST /v1/memories` `expiration_date` parameter.