feat: add multipart memory uploads

skill/memory-gateway-agent/references/api.md

@@ -136,6 +136,43 @@ $CLI flush-memory --session-id chat:c_456
 
 `--messages` accepts either a JSON array string or a path to a JSON file. Always flush after all messages for the session have been added.
 
+For local binary files that cannot be converted to base64 by the caller, use the
+multipart API directly. Put an `upload_id` in the content item and send a file
+field with the same name:
+
+```bash
+curl -X POST "$MEMORY_GATEWAY_BASE_URL/memories/add/multipart" \
+  -F user_id="$MEMORY_GATEWAY_USER_ID" \
+  -F user_key="$MEMORY_GATEWAY_USER_KEY" \
+  -F session_id=chat:c_456 \
+  -F app_id=default \
+  -F project_id=default \
+  -F 'messages=[
+    {
+      "sender_id": "u_123",
+      "role": "user",
+      "timestamp": 1781172177000,
+      "content": [
+        {"type": "text", "text": "Remember this image"},
+        {
+          "type": "image",
+          "upload_id": "image_1",
+          "name": "image.png",
+          "ext": "png"
+        }
+      ]
+    }
+  ]' \
+  -F 'image_1=@./image.png;type=image/png'
+```
+
+The multipart endpoint appends messages to the provided chat session. It stores
+the uploaded file under Gateway storage, forwards text/base64 content to the
+upstream memory service, and records an attachment mapping. Call `flush-memory`
+afterward when the session should be extracted and indexed. This differs from
+`upload-resource`, which creates an independent `resource:{user_id}:{resource_id}`
+session and automatically performs add plus flush for resource searches.
+
 ### Override and Delete Memory
 
 Use IDs from a search result:
@@ -188,6 +225,8 @@ Common content items:
 ```
 
 Prefer base64 for local binary files. A `file://` URI is only usable when upstream memory service can access the same filesystem path.
+If that shared path guarantee is not true, use `/memories/add/multipart`,
+`upload-resource`, or `/resources/external`.
 
 ## Search Scopes