Memory · 记忆相册 API

索引：backend/real-agent-web/src/main/java/com/ai/agent/real/web/controller/memory/MemoryController.java

记忆相册（Memory Album）是 VOLO AI 的多模态记忆系统——上传图片/文档后，AI 在对话中可语义检索并引用。

---

端点总览

Method	Path	用途
POST	/api/memories/upload	上传文件 + 用户描述
GET	/api/memories/list	分页列出我的记忆
POST	/api/memories/search	语义搜索
DELETE	/api/memories/{memoryId}	删除记忆

---

1 · 上传记忆

POST /api/memories/upload
Authorization: Bearer $VOLO_API_KEY
Content-Type: multipart/form-data

Form Field	类型	必填	说明
file	File	是	文件（图片/文档/视频）
userTitle	string	否	用户自定义标题
userDescription	string	否	用户描述（参与语义索引）

cURL 示例

curl -X POST "https://api.volo.ai/api/memories/upload" \
  -H "Authorization: Bearer $VOLO_API_KEY" \
  -F "file=@/path/to/photo.jpg" \
  -F "userTitle=春节家宴" \
  -F "userDescription=2026 年春节，全家在北京聚餐的照片"

响应 · MemoryVO

{
  "code": 200,
  "data": {
    "memoryId": "uuid-...",
    "userTitle": "春节家宴",
    "userDescription": "2026 年春节...",
    "aiSummary": "[AI 自动生成的语义摘要]",
    "tags": ["家庭", "节日", "聚餐"],
    "fileUrl": "https://cdn.volo.ai/...",
    "thumbnailUrl": "https://cdn.volo.ai/.../thumb.jpg",
    "mimeType": "image/jpeg",
    "sizeBytes": 2458320,
    "createdAt": "2026-05-14T10:30:00+08:00"
  }
}

多模态处理

图片自动经腾讯云 COS 处理（?imageMogr2）生成缩略图与提取语义。视频/音频路由到外部转码服务。这些计算不在 JVM 内执行（后端计算外包红线）。

---

2 · 列出我的记忆

GET /api/memories/list?page=0&pageSize=20

参数	默认	说明
page	0	页码
pageSize	20	每页条数（max 200）

返回 List<MemoryVO>，按 createdAt 倒序。

---

3 · 语义搜索

POST /api/memories/search
Content-Type: application/json

{
  "query": "春节",
  "topK": 10,
  "minScore": 0.6
}

字段	类型	说明
query	string	自然语言查询
topK	int	返回最相关的 N 条（默认 10）
minScore	float	最小相关度阈值 0-1（默认 0.5）

返回按相关度倒序的 List<MemoryVO>。

[TODO: SearchMemoryRequest 完整字段需对照 backend/real-agent-contract/.../SearchMemoryRequest.java]

---

4 · 删除记忆

DELETE /api/memories/{memoryId}

返回：

{
  "code": 200,
  "message": "success"
}

删除即彻底

删除是物理删除，不可恢复。AI 上下文中已引用的记忆 ID 将失效。

---

在对话中引用记忆

使用 @ 触发符在对话中引用云盘文件或 Memory：

@春节家宴 帮我写一段配文

VOLO AI 自动检索 Memory，注入 aiSummary 作为上下文，AI 可见但不重复展示 fileUrl。

---

多模态扩展（[ENFORCED]）

参考 project_multimodal_architecture.md：

• ContentBlock 协议：消息内容支持 text / image / video / file 多 block
• Thumbnailator 已废弃（计算外包），统一走外部图片处理服务
• 三级压缩策略：原图 / 标清 / 缩略图
• stripExcessMediaItems 防止 LLM 上下文爆炸

---

相关

• Skill API · @ 触发符
• Chat API · multimodal attachments