memory-gateway/tests/test_command.md

Memory Gateway API curl examples

This file keeps only the concrete API curl shapes and short notes. Replace <USER_KEY> with the key returned by POST /users.

Base URL used in the live deployment test:

http://127.0.0.1:8010

Test files:

tests/simple-multimodal-image.png
tests/simple-tone.wav

1. Health

curl -sS http://127.0.0.1:8010/health

Expected shape:

{
  "status": "ok",
  "api": {"status": "ok"},
  "backend": {
    "status": "ok",
    "base_url": "http://0.0.0.0:1995",
    "data": {"status": "ok"}
  }
}

2. Create user

curl -sS -X POST http://127.0.0.1:8010/users \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"gateway_demo_user"}'

Expected shape:

{
  "user_id": "gateway_demo_user",
  "user_key": "uk_REDACTED",
  "created_at": "2026-06-22T06:54:35.823262+00:00"
}

Use the returned user_key in later requests.

3. Add chat memory with multipart files

Use this when files belong to a chat/session message and the client should not or cannot convert the files to base64.

upload_id rules:

• upload_id is defined by the caller.
• Gateway does not generate it.
• Gateway does not require a format such as user_id_filetype_number.
• It only needs to be non-empty, unique inside the request, and equal to the multipart file field name.
• Good simple values are image_1, image_2, audio_1, doc_1.

In the messages JSON, upload_id: "image_1" points to this file field:

-F 'image_1=@tests/simple-multimodal-image.png;type=image/png'

Request:

curl -sS -X POST http://127.0.0.1:8010/memories/add/multipart \
  -F 'user_id=gateway_demo_user' \
  -F 'user_key=<USER_KEY>' \
  -F 'session_id=chat:gateway_demo_conversation' \
  -F 'app_id=default' \
  -F 'project_id=default' \
  -F 'messages=[
    {
      "sender_id": "gateway_demo_user",
      "role": "user",
      "timestamp": 1782111275810,
      "content": [
        {
          "type": "text",
          "text": "请记住这次上传：图片里有左上红色方块、右上蓝色圆形、底部绿色横条；音频是一段短促测试音。"
        },
        {
          "type": "image",
          "upload_id": "image_1",
          "name": "simple-multimodal-image.png",
          "ext": "png"
        },
        {
          "type": "audio",
          "upload_id": "audio_1",
          "name": "simple-tone.wav",
          "ext": "wav"
        }
      ]
    }
  ]' \
  -F 'image_1=@tests/simple-multimodal-image.png;type=image/png' \
  -F 'audio_1=@tests/simple-tone.wav;type=audio/wav'

Expected shape:

{
  "session_id": "chat:gateway_demo_conversation",
  "backend": {
    "request_id": "0d6451f4077040e4af207cc6b034ea34",
    "data": {
      "message_count": 1,
      "status": "accumulated"
    }
  }
}

Gateway stores the uploaded files and forwards upstream-compatible base64 or text content. The client does not send file:// and does not send base64.

Common errors:

• Missing file field for an upload_id: 422
• Duplicate upload_id: 422
• Extra uploaded file field not referenced by messages: 422
• Unsupported MIME type: 415
• File too large: 413

4. Flush chat session

/memories/add/multipart only appends messages. Call flush when the session should be extracted and indexed.

curl -sS -X POST http://127.0.0.1:8010/memories/flush \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "gateway_demo_user",
    "user_key": "<USER_KEY>",
    "session_id": "chat:gateway_demo_conversation",
    "app_id": "default",
    "project_id": "default"
  }'

Expected shape:

{
  "session_id": "chat:gateway_demo_conversation",
  "backend": {
    "request_id": "4df5415115a34f109c564abd2f9012c6",
    "data": {"status": "extracted"}
  }
}

5. Search chat session

curl -sS -X POST http://127.0.0.1:8010/memories/search \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "gateway_demo_user",
    "user_key": "<USER_KEY>",
    "conversation_id": "gateway_demo_conversation",
    "query": "图片里的蓝色圆形在哪里？底部是什么颜色的横条？",
    "scope": ["current_chat"],
    "top_k": 5,
    "app_id": "default",
    "project_id": "default"
  }'

Expected result excerpt:

{
  "results": [
    {
      "session_id": "chat:gateway_demo_conversation",
      "source_scope": "current_chat",
      "text": "The image contained a red square, a blue circle, and a green horizontal rectangle.",
      "attachments": [
        {
          "type": "image",
          "name": "simple-multimodal-image.png",
          "internal_uri": "file:///home/tom/memory-gateway/data/storage/..."
        },
        {
          "type": "audio",
          "name": "simple-tone.wav",
          "internal_uri": "file:///home/tom/memory-gateway/data/storage/..."
        }
      ]
    }
  ]
}

6. Upload an independent resource

Use /resources when the file is an independent resource, not just an attachment inside one chat message.

curl -sS -X POST http://127.0.0.1:8010/resources \
  -F 'user_id=gateway_demo_user' \
  -F 'user_key=<USER_KEY>' \
  -F 'app_id=default' \
  -F 'project_id=default' \
  -F 'title=Gateway demo image resource' \
  -F 'description=Demo upload for simple multimodal image' \
  -F 'file=@tests/simple-multimodal-image.png;type=image/png'

Expected shape:

{
  "resource_id": "r_1678eacf3e8c49f9a8863454c5b35e68",
  "session_id": "resource:gateway_demo_user:r_1678eacf3e8c49f9a8863454c5b35e68",
  "uri": "resource://gateway_demo_user/r_1678eacf3e8c49f9a8863454c5b35e68",
  "status": "extracted"
}

Unlike /memories/add/multipart, /resources automatically calls upstream add and flush.

7. List resources

curl -sS \
  'http://127.0.0.1:8010/resources?user_id=gateway_demo_user&user_key=<USER_KEY>'

Expected shape:

{
  "resources": [
    {
      "resource_id": "r_1678eacf3e8c49f9a8863454c5b35e68",
      "filename": "simple-multimodal-image.png",
      "content_type": "image",
      "mime_type": "image/png",
      "uri": "resource://gateway_demo_user/r_1678eacf3e8c49f9a8863454c5b35e68",
      "session_id": "resource:gateway_demo_user:r_1678eacf3e8c49f9a8863454c5b35e68",
      "status": "extracted"
    }
  ]
}

8. Search resources

curl -sS -X POST http://127.0.0.1:8010/memories/search \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "gateway_demo_user",
    "user_key": "<USER_KEY>",
    "query": "这张资源图片里有哪些几何图形和颜色？",
    "scope": ["resources"],
    "top_k": 5,
    "app_id": "default",
    "project_id": "default"
  }'

Expected result excerpt:

{
  "results": [
    {
      "source_scope": "resources",
      "resource_id": "r_1678eacf3e8c49f9a8863454c5b35e68",
      "resource_uri": "resource://gateway_demo_user/r_1678eacf3e8c49f9a8863454c5b35e68",
      "text": "The image displayed a red square, a blue circle, and a green rectangle.",
      "attachments": [
        {
          "type": "image",
          "name": "simple-multimodal-image.png",
          "internal_uri": "file:///home/tom/memory-gateway/data/storage/..."
        }
      ]
    }
  ]
}

Multipart vs resources

Use /memories/add/multipart when the upload belongs to a chat/session message:

• caller supplies session_id, usually chat:{conversation_id};
• caller defines upload_id values in messages;
• caller uploads files as form fields with names matching upload_id;
• Gateway only calls upstream add;
• caller should call /memories/flush;
• search normally uses current_chat or all_user_memory.

Use /resources when the upload is an independent resource:

• Gateway creates resource_id;
• Gateway creates session_id = resource:{user_id}:{resource_id};
• Gateway writes user_resources;
• Gateway automatically calls upstream add and flush;
• search normally uses resources.