feat: extend memory search and attachment mapping

README.md

@@ -282,7 +282,8 @@ curl -X POST http://127.0.0.1:8010/resources \
 }
 ```
 
-对外返回的 `uri` 永远是 `resource://{user_id}/{resource_id}`，不会泄露内部 `file://` 路径。
+资源上传接口返回的 `uri` 始终是 `resource://{user_id}/{resource_id}`。按文件名
+命中的记忆搜索结果会另外通过 `attachments[].internal_uri` 返回真实 URI。
 
 ### 4. 查询资源列表
 
@@ -438,10 +439,16 @@ Content-Type: application/json
 |---|---|---|---|---|
 | `user_id` | string | 是 | 无 | 用户 ID |
 | `user_key` | string | 是 | 无 | 用户 key |
+| `agent_id` | string | 否 | `null` | 设置后查询该 agent 的记忆；`user_id` 仍用于 Gateway 鉴权和本地数据隔离 |
 | `query` | string | 是 | 无 | 搜索问题 |
 | `conversation_id` | string | 否 | `null` | `scope` 包含 `current_chat` 时使用 |
 | `scope` | string[] | 否 | `["current_chat", "resources"]` | 搜索范围 |
-| `top_k` | integer | 否 | `8` | 每次上游记忆服务搜索返回数量，范围 `1..100` |
+| `method` | string | 否 | `hybrid` | 搜索方法：`keyword`、`vector`、`hybrid` 或 `agentic` |
+| `top_k` | integer | 否 | `8` | 每次上游搜索返回数量，支持 `-1` 或 `1..100`；`-1` 表示使用上游默认数量 |
+| `radius` | number | 否 | `null` | 相似度半径，范围 `0..1`；未提供时不发送给上游 |
+| `include_profile` | boolean | 否 | `true` | 是否同时获取用户 profile；agent 查询由上游决定是否忽略该参数 |
+| `enable_llm_rerank` | boolean | 否 | `true` | 是否启用上游 LLM rerank；具体生效范围由搜索方法和记忆类型决定 |
+| `filters` | object | 否 | `null` | 上游过滤 DSL，支持字段条件以及嵌套 `AND`、`OR` |
 | `app_id` | string | 否 | `default` | 上游记忆服务 app scope |
 | `project_id` | string | 否 | `default` | 上游记忆服务 project scope |
 
@@ -464,7 +471,13 @@ curl -X POST http://127.0.0.1:8010/memories/search \
     "conversation_id": "c_456",
     "query": "合同里的付款条款是什么？",
     "scope": ["current_chat", "resources"],
+    "method": "hybrid",
     "top_k": 8,
+    "include_profile": true,
+    "enable_llm_rerank": true,
+    "filters": {
+      "type": "Conversation"
+    },
     "app_id": "default",
     "project_id": "default"
   }'
@@ -475,9 +488,39 @@ curl -X POST http://127.0.0.1:8010/memories/search \
 1. `current_chat`：调用上游记忆服务 search，过滤 `filters.session_id = chat:{conversation_id}`。
 2. `resources`：先查当前用户的 `user_resources`，只取 `status = extracted` 且未删除资源；再按批次调用上游记忆服务 search，过滤这些资源的 `session_id`。
 3. `all_user_memory`：调用上游记忆服务 search，不加 `session_id` 过滤。
-4. 合并结果。
-5. 过滤 `memory_tombstones` 命中的 `memory_id` 或 `session_id`。
-6. 应用 active `memory_overrides`，把 `text` 替换为 `override_text`。
+4. 同时存在请求 `filters` 和 scope 生成的 session 条件时，使用 `{"AND": [filters, scope_filters]}` 合并，避免调用方过滤条件覆盖资源或聊天隔离条件。
+5. 设置 `agent_id` 时，上游请求只发送 `agent_id`；否则发送已鉴权的 `user_id`。
+6. 合并结果。
+7. 过滤 `memory_tombstones` 命中的 `memory_id` 或 `session_id`。
+8. 应用 active `memory_overrides`，把 `text` 替换为 `override_text`。
+
+响应中的 `memory_type` 对应上游结果类型：
+
+| `memory_type` | 说明 |
+|---|---|
+| `episode` | 用户 episode |
+| `profile` | 用户 profile |
+| `agent_case` | agent case |
+| `agent_skill` | agent skill |
+| `unprocessed_message` | 尚未完成边界提取的原始消息 |
+
+附件路径映射规则：
+
+1. `/resources` 上传成功后，将资源真实 URI 与资源 session 写入
+   `memory_attachments`。数据库初始化会自动回填已有 `user_resources`。
+2. `/memories/add` 中含 `uri` 的 content item 会直接登记 URI。
+3. `/memories/add` 中只有 `base64` 的 content item 会保存到
+   `MEMORY_GATEWAY_STORAGE_DIR/{user_id}/memory_attachments/{sha256}/`，再登记
+   生成的 `file://` URI。相同用户、session、文件名和内容的重试会复用路径。
+4. 搜索时根据当前用户和结果 `session_id` 查询附件，递归检查 `raw` 中的字符串
+   值。只有完整文件名出现时才返回对应附件；匹配不区分大小写。
+5. `raw` 中键名为 `base64` 的内容不会参与匹配。未匹配时返回
+   `"attachments": []`。
+6. 历史 `/memories/add` 请求未保存在 Gateway 数据库中，无法自动补录映射；新
+   版本上线后的请求会建立映射。
+
+`attachments[].internal_uri` 会按配置和调用方输入直接暴露服务器真实 URI，调用
+该接口的客户端必须被视为可信客户端。
 
 响应示例：
 
@@ -486,12 +529,20 @@ curl -X POST http://127.0.0.1:8010/memories/search \
   "results": [
     {
       "id": "mem_abc",
+      "memory_type": "episode",
       "session_id": "resource:u_123:r_xxx",
       "text": "付款期限为收到发票后 30 天内。",
       "score": 0.82,
       "source_scope": "resources",
       "resource_id": "r_xxx",
       "resource_uri": "resource://u_123/r_xxx",
+      "attachments": [
+        {
+          "type": "pdf",
+          "name": "contract.pdf",
+          "internal_uri": "file:///srv/memory-gateway/u_123/r_xxx/contract.pdf"
+        }
+      ],
       "raw": {
         "id": "mem_abc",
         "session_id": "resource:u_123:r_xxx",