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:

```text
http://127.0.0.1:8010
```

Test files:

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

## 1. Health

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

Expected shape:

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

## 2. Create user

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

Expected shape:

```json
{
  "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:

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

Request:

```bash
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:

```json
{
  "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.

```bash
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:

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

## 5. Search chat session

```bash
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:

```json
{
  "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.

```bash
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:

```json
{
  "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

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

Expected shape:

```json
{
  "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

```bash
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:

```json
{
  "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`.