harden memory edits and uploads

README.md

@@ -12,8 +12,9 @@ Memory Gateway 2 是一个轻量级 FastAPI 服务，用于在 EverOS 现有
 - 上传用户资源：文件、图片、音频、PDF、HTML、普通文档、纯文本。
 - 保存资源元数据到 SQLite。
 - 为每个资源生成独立 EverOS `session_id`。
-- 调用 EverOS `add` 和 `flush` 完成资源记忆摄入。
+- 调用 EverOS `add` 和 `flush` 完成资源记忆摄入，并对临时失败做轻量重试。
 - 提供资源列表、详情、软删除。
+- 支持上传大小限制、MIME 白名单、同用户同 app/project 下按 sha256 幂等复用资源。
 - 编排记忆搜索，支持当前聊天、资源记忆、全部用户记忆。
 - 支持记忆 tombstone 软删除。
 - 支持记忆手动 override。
@@ -53,6 +54,11 @@ cp .env.example .env
 | `MEMORY_GATEWAY_DB_PATH` | `./data/memory_gateway.sqlite3` | Gateway 自己的 SQLite 数据库路径 |
 | `MEMORY_GATEWAY_STORAGE_DIR` | `./data/storage` | 用户上传原始文件保存路径 |
 | `MEMORY_GATEWAY_RESOURCE_SEARCH_BATCH_SIZE` | `50` | resources scope 搜索时每批 session_id 数量 |
+| `MEMORY_GATEWAY_MAX_UPLOAD_BYTES` | `26214400` | 单个上传文件最大字节数，默认 25MB |
+| `MEMORY_GATEWAY_ALLOWED_MIME_TYPES` | 常见图片、音频、PDF、HTML、文本和 Office 文档 | 逗号分隔的上传 MIME 白名单，支持 `image/*` 这类前缀匹配 |
+| `MEMORY_GATEWAY_EVEROS_INGEST_ATTEMPTS` | `3` | EverOS `add` 和 `flush` 各自最多重试次数 |
+| `MEMORY_GATEWAY_EVEROS_RETRY_DELAY_SECONDS` | `0.25` | EverOS 摄入重试间隔秒数 |
+| `MEMORY_GATEWAY_EVEROS_TIMEOUT_SECONDS` | `120` | 单次 EverOS HTTP 请求超时秒数 |
 | `MEMORY_GATEWAY_HOST` | `127.0.0.1` | Gateway API 监听地址 |
 | `MEMORY_GATEWAY_PORT` | `8010` | Gateway API 监听端口 |
 | `MEMORY_GATEWAY_RELOAD` | `false` | 是否启用 uvicorn reload，开发时可设为 `true` |
@@ -223,6 +229,13 @@ Content-Type: multipart/form-data
 8. 调用 EverOS `/api/v1/memory/flush`。
 9. 成功后状态改为 `extracted`，失败后状态改为 `failed`。
 
+上传策略：
+
+- 文件会按流式方式写入磁盘，超过 `MEMORY_GATEWAY_MAX_UPLOAD_BYTES` 会返回 `413`，不会写入资源记录。
+- MIME 类型不在 `MEMORY_GATEWAY_ALLOWED_MIME_TYPES` 白名单内会返回 `415`。
+- 同一用户在同一 `app_id`、`project_id` 下重复上传相同 sha256 的活跃资源，会直接返回已有资源，避免重复调用 EverOS 摄入。
+- EverOS `add` 和 `flush` 临时失败时会分别按配置重试；单次请求受 `MEMORY_GATEWAY_EVEROS_TIMEOUT_SECONDS` 控制；全部失败后资源状态为 `failed`，并记录 `error_message`。
+
 content type 映射：
 
 | 文件类型 | EverOS content type |
@@ -381,6 +394,7 @@ DELETE /resources/{resource_id}?user_id={user_id}&user_key={user_key}
 - 设置 `deleted_at = now()`。
 - 设置 `status = deleted`。
 - 后续 `resources` scope 搜索会排除该资源的 `session_id`。
+- 清理 Gateway 自己在 `MEMORY_GATEWAY_STORAGE_DIR` 下保存的原始上传文件。
 - 不物理删除 EverOS 内部记忆或索引。
 
 请求示例：
@@ -490,10 +504,10 @@ Content-Type: application/json
 |---|---|---|---|
 | `user_id` | string | 是 | 用户 ID |
 | `user_key` | string | 是 | 用户 key |
-| `session_id` | string | 否 | memory 所属 session |
+| `session_id` | string | 是 | memory 所属 session，必须属于当前用户 |
 | `override_text` | string | 是 | 修正后的记忆文本 |
 
-该接口只写入或更新 `memory_overrides`，不会修改 EverOS 原始文件。后续搜索结果命中该 `memory_id` 时，返回的 `text` 会替换为 `override_text`，但保留原始 memory id。
+该接口只写入或更新 `memory_overrides`，不会修改 EverOS 原始文件。写入前会校验 `session_id` 属于当前用户：当前版本支持当前用户的 `resource:{user_id}:{resource_id}` 和 `memory_edit:{user_id}`。后续搜索结果命中该 `memory_id` 时，返回的 `text` 会替换为 `override_text`，但保留原始 memory id。
 
 请求示例：
 
@@ -531,10 +545,10 @@ Content-Type: application/json
 |---|---|---|---|
 | `user_id` | string | 是 | 用户 ID |
 | `user_key` | string | 是 | 用户 key |
-| `session_id` | string | 否 | memory 所属 session |
+| `session_id` | string | 是 | memory 所属 session，必须属于当前用户 |
 | `reason` | string | 否 | 删除原因 |
 
-该接口只写入 `memory_tombstones`，不会修改 EverOS 原始文件。后续搜索结果如果命中 tombstone 的 `memory_id` 或 `session_id`，会被过滤。
+该接口只写入 `memory_tombstones`，不会修改 EverOS 原始文件。写入前会校验 `session_id` 属于当前用户：当前版本支持当前用户的 `resource:{user_id}:{resource_id}` 和 `memory_edit:{user_id}`。后续搜索结果如果命中 tombstone 的 `memory_id` 或 `session_id`，会被过滤。
 
 请求示例：