Memory 附件真实路径映射设计

目标

让 /resources 和 /memories/add 两种摄入方式都保存附件与 session 的映射。 /memories/search 返回结果时，根据结果 session_id 查询当前用户附件，并且只有当附件完整文件名出现在结果 raw 的字符串字段中时，才返回该附件真实 URI。

数据模型

新增 SQLite 表 memory_attachments：

id TEXT PRIMARY KEY
user_id TEXT NOT NULL
app_id TEXT NOT NULL DEFAULT 'default'
project_id TEXT NOT NULL DEFAULT 'default'
session_id TEXT NOT NULL
resource_id TEXT
content_type TEXT NOT NULL
name TEXT NOT NULL
internal_uri TEXT NOT NULL
source TEXT NOT NULL
sha256 TEXT
created_at TIMESTAMP NOT NULL
deleted_at TIMESTAMP

以 (user_id, session_id, internal_uri) 建立唯一索引，避免幂等上传产生重复映射；以 (user_id, session_id, deleted_at) 建立查询索引。

数据库初始化时，将现有未删除 user_resources 回填为附件映射。历史 /memories/add 请求没有保存在 Gateway 数据库中，因此无法自动回填。

摄入规则

`/resources`

资源记录创建后，为保存的真实 file:// URI 创建附件映射：

session_id 使用 resource:{user_id}:{resource_id}；
resource_id 指向资源；
source 为 resource_upload；
content_type、文件名、SHA256 复用资源元数据。

重复资源上传时确保已有资源对应的附件映射存在。

`/memories/add`

API 将已鉴权的 user_id 一并传给 service。逐条检查 message 的 content item：

只有字符串 content 或纯文本 item 时不创建附件；
有 uri 时记录该 URI，source=memory_add_uri；
没有 uri 但有 base64 时，解码并保存到 storage/{user_id}/memory_attachments/{attachment_id}/{safe_name}，记录生成的 file:// URI，source=memory_add_base64；
同时存在 uri 和 base64 时优先使用 uri，不重复落盘；
文件名优先使用 name，否则从 URI 路径或 ext 生成安全名称。

上游 add 调用失败时，删除本次 base64 生成的文件，不写入映射。调用成功后写入附件映射。上游请求体保持原样，不修改现有 add 行为。

搜索匹配规则

对每条标准化搜索结果：

根据已鉴权 user_id 和结果 session_id 查询未删除附件；
递归遍历 raw 中 dict、list 的字符串值；
跳过键名为 base64 的值，避免扫描大块编码数据；
使用附件完整文件名做不区分大小写的子串匹配；
仅命中的附件进入 attachments，按 internal_uri 去重；
没有 session 或没有命中时返回 attachments: []。

响应附件格式：

{
  "type": "image",
  "name": "simple-multimodal-image.png",
  "internal_uri": "file:///home/tom/memory-gateway/tests/simple-multimodal-image.png"
}

episode 是 session 级记忆，因此只能在同一 session 的附件中按文件名匹配，不能证明具体附件是向量召回的直接来源。

删除与隔离

所有附件查询必须同时匹配 user_id 和 session_id；
删除 /resources 时，对应附件映射设置 deleted_at；
真实路径按用户明确要求直接出现在搜索结果中；
不改变资源列表和详情现有的 resource:// 对外 URI。

测试

资源上传创建附件映射；
资源搜索仅在 raw 出现文件名时返回真实 URI；
raw 不含文件名时返回空附件数组；
/memories/add 的 URI content 创建映射；
/memories/add 的 base64 content 落盘并创建映射；
不扫描 raw 中的 base64 字段；
不返回其他用户同 session 的附件；
现有测试继续通过。

3.7 KiB Raw Blame History Unescape Escape