记忆管理 API 使用说明-云原生数据库 PolarDB(PolarDB)-阿里云帮助中心

PolarDB Agent Memory兼容开源mem0 REST API协议，并提供丰富的记忆增强特性功能。本文档为开发者提供完整的 API 快速参考，涵盖记忆写入、检索、治理、提示词定制、画像与性格管理等全部接口。

概述

本手册面向开发者，提供PolarDB Agent Memory REST API 的快速参考：每个接口均按“功能介绍、关键参数、接口定义、示例”四段式组织，可直接拷贝 curl 示例快速验证。全文共五章：

章节	内容	适用场景
一、记忆管理	记忆的写入、检索、增删改查、批量操作、历史与重置	所有接入方的基础能力
二、功能特性	合并、重试、分类、授权共享、过期、时间衰减、引用计数、异步任务、Per-User Key、冲突检测等生产级特性	需要记忆治理、多租户隔离与运维能力的场景
三、Prompts 管理	内置 Prompt 类型、自定义模板的增删改查、请求级覆盖与变量替换	需要定制 LLM 提取/合并/问答行为的场景
四、画像与 AI 性格管理	用户画像与 AI 性格的 Schema 定义、抽取、查询	需要构建个性化交互体验的场景
五、全模态记忆	文件上传、图片/音频/视频记忆写入、以图搜图、以文搜图、混合检索、视频流	需要处理非文本媒体的场景

通用约定

认证头 Authorization: Token <MEM0_API_KEY>；示例基础地址 http://{endpoint}:8080；请求体为 JSON；output_format 默认 v1.1。

一、记忆管理

写入/提取记忆（POST /v1/memories）

通过 LLM 从对话消息中提取记忆片段存入向量库；infer=false 时原文整体存为一条记忆（用于失败重试）。

POST /v1/memories

关键参数

参数名	必填	默认值	说明
`messages`	是	—	对话消息列表，每条含 `role`/`content`，可选 `created_at`
`user_id`/`agent_id`/`run_id`	是	—	业务标识符，至少一个
`infer`	否	`true`	是否 LLM 推断
`async_mode`	否	`false`	`true` 时立即返回 job_id
`message_id`	否	—	消息标识，用于合并/重试
`metadata`	否	—	元数据；特殊字段 `created_at`/`timestamp`/`expiration_date`
`categories` / `custom_categories` / `category_template`	否	—	手动标签（优先级最高）/ 直接分类字典 / 模板引用
`timestamp` / `expiration_date`	否	—	Unix 时间戳 / 过期日期（`YYYY-MM-DD`、ISO、`7d`/`24h`）
`temperature`	否	—	请求级 LLM temperature（0.0~2.0）
`org_id` / `project_id` / `app_id`	否	—	组织 / 项目 / 应用 ID

示例

curl -X POST http://localhost:8888/v1/memories \
  -H "Authorization: Token apikey" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "我喜欢打篮球"}],
    "user_id": "alice",
    "async_mode": false
  }'

返回 results[]，每项含 id/event（ADD/UPDATE/DELETE）/data.memory。

按语义检索记忆（POST /v2/memories/search）

三路召回（向量语义 + BM25 + 实体增强）混合检索，支持重排序、图检索、共享记忆与时间衰减。

POST /v2/memories/search

关键参数

参数名	必填	默认值	说明
`query`	是	—	搜索语句
`filters`	是	—	过滤条件，须含至少一个业务标识符
`top_k` / `threshold`	否	`5` / `0.3`	返回条数 / 最低相似度
`rerank`	否	`false`	是否重排序
`fields`	否	—	返回字段白名单
`shared_user_ids` / `enable_search_shared`	否	— / `false`	指定共享用户 / 自动合并被授权方记忆
`time_decay` / `time_decay_half_life_days` / `time_decay_cutoff`	否	`false`/`7`/`0.01`	时间衰减开关 / 半衰期 / 截止阈值

示例

curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token apikey" \
  -H "Content-Type: application/json" \
  -d '{"query": "喜欢喝什么咖啡", "filters": {"user_id": "张三"}, "top_k": 5}'

获取/过滤记忆 - 内存分页（POST /v2/memories）

按过滤条件分页列出记忆；filters.categories 支持 in/nin/contains/icontains/*/_ALL_ 语法。

POST /v2/memories

关键参数

参数名	必填	默认值	说明
`filters`	是	—	过滤条件，须含至少一个业务标识符
`page` / `page_size`	否	`1` / `100`	页码 / 每页条数
`fields`	否	—	返回字段白名单

示例

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

获取记忆列表 - 数据库级分页（POST /v2/memories/list）

数据库级分页查询，返回含总数的分页信息，适合大数据量。

关键参数

参数名	默认值	说明
业务标识符（至少一个）	—	`user_id`/`agent_id`/`run_id`
`filters`	—	过滤条件
`fields`	—	返回字段
`page` / `page_size`	`1` / `20`	页码 / 每页条数
`org_id`/`project_id`	—	组织 / 项目 ID

示例

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}'
# 返回 results + pagination{total, page, page_size, total_pages}

获取单条记忆（GET /v1/memories/{memory_id}）

按 ID 精确查询单条记忆。Query 可选 output_format。

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

按 message_id 查询记忆（GET /v1/memories/by-message/{message_id}）

说明

当前API暂时处于灰度阶段，如需使用，请提交工单联系我们给您处理。

查询某 message_id 提取出的所有记忆，返回 results + message_id + total。

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

更新记忆（PUT /v1/memories/{memory_id}）

直接更新记忆文本和/或元数据。Body：text/metadata 至少一个。

curl -X PUT http://localhost:8888/v1/memories/<MEMORY_ID> \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"text": "喜欢喝燕麦拿铁"}'

删除单条记忆（DELETE /v1/memories/{memory_id}）

按 ID 删除单条记忆。

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

批量删除记忆（DELETE /v1/memories）

按标识符批量删除。

Query：user_id/agent_id/app_id/run_id 至少一个
可选 org_id/project_id/metadata。

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

批量更新记忆（PUT /v1/batch）

批量更新，单次 ≤1000 条。Body：memories[]，每项含 memory_id + text/metadata 至少一个。

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

批量删除记忆 ID 列表（DELETE /v1/batch）

按 ID 列表批量删除，单次 ≤1000 条。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 /v1/memories/{memory_id}/history）

查询某条记忆的完整变更事件链（ADD/UPDATE/DELETE）。

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

重置所有记忆（POST /v1/reset）

警告

删除指定标识符下所有记忆（含画像与性格数据），不可恢复。Body：user_id/agent_id/run_id 至少一个。

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

实体列表（GET /v1/entities/list）

分页列出所有指定类型的实体 ID。Query要求如下：

业务标识符id_type（必填，至少一个）：user_id/agent_id/run_id
page：默认 1
page_size：默认 50，最大 1000

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

二、功能特性

说明

相对开源 mem0 新增/增强的生产级特性。

记忆合并（POST /v1/memories/merge）

将碎片记忆合并为完整记忆。支持 message_ids 模式与时间范围模式，三种冲突策略。

关键参数

参数名	必填	说明
`message_ids`	是	要合并的 message_id 列表（与 user_id/agent_id 二选一，优先）
`user_id` / `agent_id`	是	时间范围模式标识符（二选一）
`run_id`	否	提供时冲突检测仅匹配同一 run_id
`start_time` / `end_time`	否	时间范围（ISO 8601）
`range_days`	否	回溯天数，默认 7
`merge_type`	否	`none`（默认，仅 ADD）/ `append`（UPDATE 建版本副本）/ `update`（完整 ADD/UPDATE/DELETE）
`delete_old`	否	是否删除源记忆，默认 `false`

示例

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

# 时间范围 + update 策略 + 删除源记忆
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}'

返回 merged_memory.results[] + source_message_ids + merged_count + merge_type。

重试失败记忆（POST /v1/memories/retry）

对 infer=false（LLM 推断失败）的记忆按原配置重新执行推断提取。

关键参数：

user_id/agent_id/run_id/app_id/message_ids 至少一个
max_retries：默认5。

示例

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

全部成功返回 200；部分失败返回 201（含 failed_count/failed_message_ids）。

记忆自动分类/打标

预定义分类模板，写入时由 LLM 自动多标签分类，结果存 metadata.categories。优先级：categories（手动）> custom_categories > category_template；未匹配归入 _RESERVED_。

分类模板 CRUD

POST   /v1/category-templates                              # user_id(省略=公共模板) + template_name(必填，全局唯一) + categories（必填）
GET    /v1/category-templates(?user_id=&include_public=)   # 列表
GET    /v1/category-templates/public                       # 公共模板
GET    /v1/category-templates/{template_name}(?user_id=)   # 单个
PUT    /v1/category-templates/{template_name}(?user_id=)   # 更新（完整替换 categories）
DELETE /v1/category-templates/{template_name}(?user_id=)   # 删除

示例

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": "姓名、年龄等", "hobby": "兴趣爱好"}
  }'

# 写入时引用模板打标
curl -X POST http://localhost:8888/v1/memories \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "我叫张三，喜欢骑行"}], "user_id": "alice", "category_template": "user_profile"}'

按分类检索（search 与列表接口的 filters.categories）：

语法	说明
`{"categories": "hobby"}`	精确匹配
`{"categories": ["a","b"]}` 或 `{"in": [...]}`	OR 匹配
`{"nin": ["_RESERVED_"]}`	排除
`{"contains": "food"}` / `{"icontains": "FOOD"}`	子串匹配
`"_ALL_"`	等价于排除 `_RESERVED_`

记忆授权共享

用户/Agent 将记忆授权给其他用户/Agent（单向），被授权方通过 enable_search_shared=true 自动获取授权方记忆。

授权管理接口

POST   /v1/shared_authorization    # 创建：user_id/agent_id(授权方，至少一个) + to_user_id/to_agent_id(至少一个)，幂等
GET    /v1/shared_authorization    # 查询授权方的授权列表（?user_id= 或 ?agent_id=）
DELETE /v1/shared_authorization    # 删除：body 含授权方标识；不传 to_* 则删除其全部授权

示例

# alice 授权给 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 查询时合并 alice 的记忆
curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"query": "饮食偏好", "filters": {"user_id": "bob"}, "enable_search_shared": true}'

结果按 id 去重，每条保留原始 user_id 可区分来源。

记忆过期管理

为记忆设置过期时间，过期后检索自动过滤并物理删除（Lazy GC）。格式：YYYY-MM-DD、ISO 8601、相对时长（7d/24h/30m/60s）；格式非法视为永不过期。

写入过期时间：`POST /v1/memories` 的 `expiration_date` 参数。

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": "临时验证码"}], "expiration_date": "30m"}'

主动删除过期记忆（DELETE /v1/memories/expired）

Query：user_id/agent_id 至少一个，可选 run_id、dry_run=true（仅预览）。

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

默认过期策略

按维度预设默认过期策略，写入未传 expiration_date 时自动应用。优先级：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    # 查询（可按维度过滤）
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"}'

记忆时间衰减

检索时按记忆新鲜度加权：final_score = vector_score × exp(-elapsed/half_life × ln2)。仅当 rerank=false 时生效（重排序已给出最终排序，无需再衰减）。

关键参数：

time_decay：默认 false）
time_decay_half_life_days：默认 7
time_decay_cutoff：默认 0.01，低于该分不返回。

curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"query": "最近在做什么", "filters": {"user_id": "alice"}, "time_decay": true, "time_decay_half_life_days": 7}'

刷新活跃时间（延长有效寿命）：POST /v1/memories/{memory_id}/touch（无 body）。

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

程序记忆

通过 memory_type="procedural_memory" 写入步骤化操作知识（如工具调用流程），原文不推断、不蒸馏。

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": "订机票流程：1. 查询航班 2. 选择舱位 3. 支付"}]
  }'

记忆引用计数

统计记忆被合并/更新的引用次数，用于识别核心记忆（引用数越高，删除风险越大）。

GET  /v1/memories/{memory_id}/ref_count             # 单条引用数（无记录返回 0）
GET  /v1/memories/ref_count/by_message_id?message_id={message_id}   # 按 message_id 查询
POST /v1/memories/ref_count/batch                   # 批量：body 传 memory_ids[] 或 message_ids[]（二选一，≤1000）
GET  /v1/memories/ref_count/zero                    # 零引用记忆（?page=1&page_size=100）
GET  /api/v1/dashboard/ref_count_distribution       # 引用数分布（5 段统计，Dashboard 看板用）
GET  /api/v1/dashboard/ref_count_detail?bucket={bucket}   # 分段明细（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"]}'

异步任务与 Webhook

任务查询

async_mode=true 的写入/合并/摄取等操作返回 job_id，通过以下接口查询状态。

GET    /v1/jobs/{job_id}        # 单任务状态（pending/running/completed/failed）与结果
GET    /v1/jobs                 # 任务列表（?user_id=&status=&limit=&offset=）
DELETE /v1/jobs/expired         # 清理已过期任务记录（?days=，默认 7）

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

Webhook 通知

任务完成时向注册 URL 推送结果，签名头 X-Mem0-Signature（HMAC-SHA256）。

POST   /v1/webhooks                 # url（必填） + events(必填，如 ["memory.add_completed"]) + secret(可选，不传自动生成)
GET    /v1/webhooks                 # 列表（secret 不回显）
DELETE /v1/webhooks/{webhook_id}    # 删除

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

多租户隔离（用户级 API Key）

多租户场景下可为终端用户颁发独立 Key（m0sk_ 前缀），自动绑定 user_id 实现数据隔离。明文 key 仅在创建时返回一次。

POST   /v1/user-keys                        # 创建：user_id（必填） + label（必填）；响应含明文 api_key
GET    /v1/user-keys                        # 列表（仅元数据）
GET    /v1/user-keys/{key_id}               # 详情
DELETE /v1/user-keys/{key_id}               # 删除（立即失效）
PUT    /v1/user-keys/{key_id}/binding       # 变更绑定用户：body {"user_id": "新ID"}

Dashboard 等效端点（功能一致，仅全局 Key 可用）：

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}

示例

curl -X POST http://localhost:8888/v1/user-keys \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "label": "alice 的应用端"}'
# 返回 {"key_id": "...", "api_key": "m0sk_****（仅此一次）"}

# 终端用户用专属 Key 调用，无需再传 user_id
curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token m0sk_xxx" -H "Content-Type: application/json" \
  -d '{"query": "我的偏好", "filters": {}}'

记忆冲突检测

检测语义相近但可能矛盾的记忆对，支持人工裁决。

POST /v1/memories/conflicts                    # 同步检测
POST /v1/memories/conflicts/async              # 异步检测，返回 job_id
GET  /v1/memories/conflicts/history            # 历史检测记录
POST /v1/memories/conflicts/{conflict_id}/resolve   # 裁决：keep_a / keep_b / keep_both / merge

关键参数（检测接口）：user_id/agent_id（至少一个）、similarity_threshold（默认 0.7）、max_pairs（默认 50）、run_id（可选，仅匹配同 run）。

冲突类型：事实矛盾、时间矛盾、粒度矛盾。

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

三、Prompts 管理

Prompt 分两级：类型（14 种内置）与实现（同一类型可注册多个实现）。选择优先级：请求级 prompts 参数 > 数据库自定义实现 > 内置默认。

内置 Prompt 类型一览

类型	用途
`FACT_RETRIEVAL_PROMPT`	事实提取（默认）
`MERGE_MEMORY_PROMPT`	记忆合并裁决
`UPDATE_MEMORY_PROMPT_V1`	写入时 ADD/UPDATE/DELETE 决策
`DELETE_RELATIONS_SYSTEM_PROMPT`	图关系删除
`EXTRACT_ENTITIES_PROMPT`	实体抽取
`GRAPH_PROMPT`	图关系抽取
`PROFILE_EXTRACTION_PROMPT`	画像抽取
`PROFILE_MERGE_PROMPT`	画像合并
`PERSONALITY_EXTRACTION_PROMPT`	AI 性格抽取
`ANSWER_PROMPT`	智能问答回答
`QUERY_REWRITE_PROMPT`	查询改写
`MULTIMODAL_CAPTION_PROMPT`	全模态描述生成

重载 Prompt（POST /v1/config/reload）

从磁盘/数据库重新加载指定 Prompt。Query：prompt_name（必填）。

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

查询 Prompt 列表（GET /v1/config/prompts）

列出所有 Prompt 类型及实现。Query 可选 prompt_name 过滤。

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

创建自定义 Prompt（POST /v1/config/prompts）

Body：prompt_name（必填）、prompt_type（必填，须为已知 Prompt 类型）、content（必填，含 {变量} 占位符）、is_default（可选，设为该类型默认实现）。

curl -X POST http://localhost:8888/v1/config/prompts \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"prompt_name": "MY_FACT_PROMPT", "prompt_type": "FACT_RETRIEVAL_PROMPT", "content": "从对话中提取{user_id}的事实：{input}", "is_default": false}'

更新 Prompt 内容（PUT /v1/config/prompts/{prompt_name}/content）

Body：prompt_type（必填）、content（必填）。

curl -X PUT http://localhost:8888/v1/config/prompts/MY_FACT_PROMPT/content \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"prompt_type": "FACT_RETRIEVAL_PROMPT", "content": "新的模板内容：{input}"}'

删除自定义 Prompt（DELETE /v1/config/prompts/{prompt_name}）

仅可删除自定义实现，内置默认不可删；删除后回退到内置版本。Query：prompt_type（必填）。

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

请求级 Prompt 覆盖（prompts 参数）

写入合并接口的 prompts 参数可指定使用已注册的 Prompt 实现（不影响数据库默认配置）。格式为 list of dicts：[{"prompt_type": "prompt_name"}]。支持同时指定多个类型。

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": "我住在北京"}],
    "prompts": [{"FACT_RETRIEVAL_PROMPT": "FACT_RETRIEVAL_PROMPT"}]
  }'

Prompt 变量替换（prompt_vars 参数）

格式为 list of dicts：外层 key 为 scope（模板名或通配符 "*"），内层为 [{占位符: 值}] 列表。保留 key（如 input）不可覆盖；未提供的占位符保留原样。

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": "我住在北京"}],
    "prompt_vars": [{"FACT_RETRIEVAL_PROMPT": [{"language": "中文", "focus": "居住"}]}]
  }'

四、画像与 AI 性格管理

画像 Schema 管理

Schema 定义画像的结构化字段（LLM 抽取的目标格式）。

POST   /v1/profile/schemas                 # 创建：name(必填) + description + attributes(必填)
GET    /v1/profile/schemas                 # 列表
GET    /v1/profile/schemas/{schema_id}     # 详情
PUT    /v1/profile/schemas/{schema_id}     # 更新
DELETE /v1/profile/schemas/{schema_id}     # 删除

# 创建画像模板
curl -X POST http://localhost:8888/v1/profile/schemas \
  -H "Authorization: Token apikey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo_basic_profile",
    "description": "演示用基础画像模板",
    "attributes": [
      {"name": "age",        "description": "用户年龄（岁）", "type": "integer", "required": false, "default": null},
      {"name": "occupation", "description": "用户职业",       "type": "string",  "required": true,  "default": null},
      {"name": "hobbies",    "description": "兴趣爱好列表",   "type": "list",    "required": false, "default": []}
    ]
  }'

# 查询全部画像模板
curl http://localhost:8888/v1/profile/schemas -H "Authorization: Token apikey"

# 查询指定画像模板
curl http://localhost:8888/v1/profile/schemas/<schema_id> \
  -H "Authorization: Token apikey"

# 更新指定的画像模版
curl -X PUT http://localhost:8888/v1/profile/schemas/<schema_id> \
  -H "Authorization: Token apikey" \
  -H "Content-Type: application/json" \
  -d '{"description": "更新后的演示模板描述"}'

# 删除指定画像模板（级联删除关联画像）
curl -X DELETE http://localhost:8888/v1/profile/schemas/<schema_id> \
  -H "Authorization: Token apikey\"

手动触发画像抽取（POST /v1/profile/extract）

两阶段流程：PROFILE_EXTRACTION_PROMPT 从记忆抽取候选字段 → PROFILE_MERGE_PROMPT 与既有画像合并（保留历史版本）。

关键参数：

user_id：必填。
schema_id：必填。
limit：抽取的记忆条数，默认 100。
start_time/end_time：时间窗口，缺省时自动推导。

示例

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

查询用户画像（GET /v1/profile/users/{user_id}）

Query：schema_id（必填）。返回按 schema 结构化的画像及版本信息。

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

删除用户画像（DELETE /v1/profile/users/{user_id}）

Query：schema_id（必填）。

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

初始化画像（POST /v1/profile/init）

说明

当前API暂时处于灰度阶段，如需使用，请提交工单联系我们给您处理。

基于全部历史记忆一次性初始化画像（适合存量用户接入）。Body：user_id（必填）、schema_id（必填）。

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 性格 Schema 管理

AI 性格为用户级全局维度（描述 AI 应以何种语气/角色与该用户交互），结构与画像 Schema 相同。

POST   /v1/personality/schemas                 # 创建
GET    /v1/personality/schemas/{schema_id}     # 详情
PUT    /v1/personality/schemas/{schema_id}     # 更新
DELETE /v1/personality/schemas/{schema_id}     # 删除

# 创建AI性格模板
curl -X POST http://localhost:8888/v1/personality/schemas \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{
    "name": "demo_personality_v1",
    "description": "演示：AI 性格模板",
    "dimensions": [
      {"name": "humor", "description": "幽默感程度", "kind": "quantitative", "min_score": 1, "max_score": 10},
      {"name": "tone", "description": "说话语气风格", "kind": "qualitative", "options": ["正式", "轻松", "活泼"]},
      {"name": "openness", "description": "开放程度", "kind": "quantitative", "min_score": 1, "max_score": 5}
    ]
  }'

# 查询指定性格模版
curl http://localhost:8888/v1/personality/schemas/<schema_id> \
  -H "Authorization: Token apikey"

# 更新指定AI性格模板
curl -X PUT http://localhost:8888/v1/personality/schemas/<schema_id> \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"description": "更新后的性格模板描述"}'

# 删除指定AI性格模板（级联删除关联性格）
curl -X DELETE http://localhost:8888/v1/personality/schemas/<schema_id> \
  -H "Authorization: Token apikey\"

查询用户 AI 性格（GET /v1/personality/users/{user_id}）

Query：schema_id（必填）。

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

手动触发性格抽取（POST /v1/personality/extract）

Body：user_id（必填）、personality_schema_id（必填）、可选 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", "personality_schema_id": "<SCHEMA_ID>"}'

五、全模态记忆

说明

全模态记忆目前处于灰度阶段，如需使用，请提交工单联系我们给您处理。

文件上传（POST /v3/files/upload）

multipart 上传原始文件（图片/音频/视频），支持上传至服务端本地目录及OSS存储两种模式，返回文件唯一标识供后续接口引用。

关键参数（form-data）：file（必填）、user_id/agent_id/run_id（至少一个）。

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

全模态记忆写入（POST /v3/memories/multimodal）

对图片/音频/视频执行理解（VLM 描述、ASR 转写、视频抽帧）并写入记忆。支持本地路径（access_type=local）、URL（Http、OSS）、base64、file_id。

关键参数

参数名	说明
`image` / `audio` / `video`	三种媒体输入，同时传时优先级 video > audio > image
`user_id`/`agent_id`/`run_id`	至少一个
`access_type`	`local`（本地路径）/ `url` / `base64` / `file_id`
`force`	`true` 时绕过熵触发器强制处理
`messages`	可选上下文对话
`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}'
# 返回 caption（VLM 描述）、memory（提取的记忆）、media 引用

视觉检索 - 以图搜图（POST /v3/memories/visual-search）

以图片为查询，在视觉向量空间检索相似全模态记忆（CLIP/视觉嵌入）。

关键参数：image（必填）、access_type、user_id（必填或filters）、top_k（默认 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}'

以文搜图（复用搜索接口）

说明

该功能复用 POST /v2/memories/search 端点，不依赖 /v3/ 端点。

文本检索全模态记忆无独立端点，复用 POST /v2/memories/search：caption 已作为文本记忆入库，文本 query 即可命中全模态记忆（结果含 media 引用）。

curl -X POST http://localhost:8888/v2/memories/search \
  -H "Authorization: Token apikey" -H "Content-Type: application/json" \
  -d '{"query": "海边日落", "filters": {"user_id": "alice"}}'

混合检索（POST /v3/memories/hybrid-search）

文本 + 视觉联合检索，RRF 融合排序（final_score 越小越靠前），结果含 fusion_source 标识来源。

关键参数：query（文本，可选）、image（图片，可选，两者至少一个）、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": "旅行照片", "image": "/tmp/q.jpg", "access_type": "local", "top_k": 10}'

获取全模态原始内容（GET /v3/memories/{memory_id}/raw）

返回全模态记忆的原始媒体引用（路径/URL）与转写文本。

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

视频流写入（POST /v3/memories/video-stream）

视频抽帧 + GPS 轨迹写入，支持按帧检索与轨迹插值。Body：frames[]、gps_points[]、user_id（必填）。结果类型含 frame 记忆、scene 摘要、gps、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}]
  }'

概述

通用约定

一、记忆管理

写入/提取记忆（POST /v1/memories）

按语义检索记忆（POST /v2/memories/search）

获取/过滤记忆 - 内存分页（POST /v2/memories）

获取记忆列表 - 数据库级分页（POST /v2/memories/list）

获取单条记忆（GET /v1/memories/{memory_id}）

按 message_id 查询记忆（GET /v1/memories/by-message/{message_id}）

更新记忆（PUT /v1/memories/{memory_id}）

删除单条记忆（DELETE /v1/memories/{memory_id}）

批量删除记忆（DELETE /v1/memories）

批量更新记忆（PUT /v1/batch）

批量删除记忆 ID 列表（DELETE /v1/batch）

获取记忆变更历史（GET /v1/memories/{memory_id}/history）

重置所有记忆（POST /v1/reset）

实体列表（GET /v1/entities/list）

二、功能特性

记忆合并（POST /v1/memories/merge）

重试失败记忆（POST /v1/memories/retry）

记忆自动分类/打标

分类模板 CRUD

记忆授权共享

授权管理接口

记忆过期管理

写入过期时间：POST /v1/memories 的 expiration_date 参数。

主动删除过期记忆（DELETE /v1/memories/expired）

默认过期策略

记忆时间衰减

程序记忆

记忆引用计数

异步任务与 Webhook

任务查询

Webhook 通知

多租户隔离（用户级 API Key）

记忆冲突检测

三、Prompts 管理

内置 Prompt 类型一览

重载 Prompt（POST /v1/config/reload）

查询 Prompt 列表（GET /v1/config/prompts）

创建自定义 Prompt（POST /v1/config/prompts）

更新 Prompt 内容（PUT /v1/config/prompts/{prompt_name}/content）

删除自定义 Prompt（DELETE /v1/config/prompts/{prompt_name}）

请求级 Prompt 覆盖（prompts 参数）

Prompt 变量替换（prompt_vars 参数）

四、画像与 AI 性格管理

画像 Schema 管理

手动触发画像抽取（POST /v1/profile/extract）

查询用户画像（GET /v1/profile/users/{user_id}）

删除用户画像（DELETE /v1/profile/users/{user_id}）

初始化画像（POST /v1/profile/init）

AI 性格 Schema 管理

查询用户 AI 性格（GET /v1/personality/users/{user_id}）

手动触发性格抽取（POST /v1/personality/extract）

五、全模态记忆

文件上传（POST /v3/files/upload）

全模态记忆写入（POST /v3/memories/multimodal）

视觉检索 - 以图搜图（POST /v3/memories/visual-search）

以文搜图（复用搜索接口）

混合检索（POST /v3/memories/hybrid-search）

获取全模态原始内容（GET /v3/memories/{memory_id}/raw）

视频流写入（POST /v3/memories/video-stream）

写入过期时间：`POST /v1/memories` 的 `expiration_date` 参数。