# Memory Gateway API Reference

## Contents

- Configuration
- Session IDs
- CLI commands
- Message format
- Search scopes
- Errors and result handling

## Configuration

The CLI reads:

| Variable | Default | Purpose |
|---|---|---|
| `MEMORY_GATEWAY_BASE_URL` | `http://127.0.0.1:8010` | Gateway URL |
| `MEMORY_GATEWAY_USER_ID` | none | Authenticated user ID |
| `MEMORY_GATEWAY_USER_KEY` | none | Authenticated user key |
| `MEMORY_GATEWAY_TIMEOUT_SECONDS` | `120` | HTTP timeout |

Global CLI flags `--base-url`, `--user-id`, `--user-key`, and `--timeout` override these values. Put global flags before the subcommand.

## Session IDs

| Memory source | Format |
|---|---|
| Chat | `chat:{conversation_id}` |
| Uploaded resource | `resource:{user_id}:{resource_id}` |
| Manual correction | `memory_edit:{user_id}` |

Use the exact `session_id` returned by the API whenever possible.

## CLI Commands

Assume:

```bash
CLI="python skill/memory-gateway-agent/scripts/memory_gateway.py"
```

### Health

```bash
$CLI health
```

No credentials required. HTTP 200 may contain `"status": "degraded"` when upstream memory service is unavailable.

### Create User

```bash
$CLI create-user u_123
```

Returns a randomly generated `user_key`. Store it securely. Repeating the same `user_id` returns the existing key.

### Upload Resource

```bash
$CLI upload-resource ./document.pdf \
  --app-id default \
  --project-id default \
  --title "Document title" \
  --description "Optional description"
```

Requires credentials. Supported resources depend on the server MIME allowlist. Success returns:

```json
{
  "resource_id": "r_xxx",
  "session_id": "resource:u_123:r_xxx",
  "uri": "resource://u_123/r_xxx",
  "status": "extracted"
}
```

`failed` means the record exists but upstream memory service ingestion failed. Identical active content for the same user/app/project may return the existing resource.

### List, Get, and Delete Resources

```bash
$CLI list-resources
$CLI get-resource r_xxx
$CLI delete-resource r_xxx
```

Missing or foreign resource details return `{"resources": []}`. Delete excludes the resource from future `resources` searches.

### Search

```bash
$CLI search "payment terms" --scope resources --top-k 8
$CLI search "previous discussion" \
  --scope current_chat \
  --conversation-id c_456
$CLI search "known preferences" --scope all_user_memory
```

Repeat `--scope` to combine scopes:

```bash
$CLI search "query" --scope current_chat --scope resources \
  --conversation-id c_456
```

When no scope is provided, the CLI searches `resources` only unless a conversation ID is supplied; with a conversation ID it searches `current_chat` and `resources`. Explicit `current_chat` scope requires `--conversation-id`.

Each result includes normalized `id`, `session_id`, `text`, `source_scope`, and optional resource metadata. The `raw` field preserves the upstream memory service response.

### Add and Flush Memory

Create `/tmp/messages.json` containing an array:

```json
[
  {
    "sender_id": "u_123",
    "role": "user",
    "timestamp": 1781172177000,
    "content": [
      {"type": "text", "text": "Remember this note"}
    ]
  }
]
```

Then run:

```bash
$CLI add-memory --session-id chat:c_456 --messages /tmp/messages.json
$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:

```bash
$CLI override-memory mem_abc \
  --session-id resource:u_123:r_xxx \
  --text "Corrected memory text"

$CLI delete-memory mem_abc \
  --session-id resource:u_123:r_xxx \
  --reason "User requested deletion"
```

These operations write Gateway overrides or tombstones. They do not modify upstream memory service files directly. The server rejects sessions not owned by the authenticated user.

## Message Format

Each message requires:

| Field | Type | Notes |
|---|---|---|
| `sender_id` | string | Usually the current user ID |
| `role` | string | `user`, `assistant`, or `tool` |
| `timestamp` | integer | Unix milliseconds, greater than zero |
| `content` | string or array | Text or upstream memory service content items |

Common content items:

```json
{"type": "text", "text": "Plain text"}
```

```json
{
  "type": "image",
  "base64": "BASE64_DATA",
  "ext": "png",
  "name": "image.png"
}
```

```json
{
  "type": "audio",
  "base64": "BASE64_DATA",
  "ext": "wav",
  "name": "audio.wav"
}
```

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

| Scope | Behavior |
|---|---|
| `current_chat` | Searches `chat:{conversation_id}`; provide `--conversation-id` |
| `resources` | Searches extracted, non-deleted resources belonging to the user/app/project |
| `all_user_memory` | Searches user memory without a session filter |

Use the narrowest scope that answers the request. This reduces unrelated results and prevents accidental cross-context use.

## Errors and Result Handling

The CLI exits nonzero and writes JSON to stderr:

```json
{"error": "Memory Gateway returned HTTP 401: invalid user credentials"}
```

Common statuses:

| Status | Meaning |
|---|---|
| `401` | Invalid `user_id` or `user_key` |
| `403` | Memory session is not owned by the user |
| `404` | Resource not found for deletion |
| `413` | Upload exceeds server size limit |
| `415` | MIME type is not allowed |
| `422` | Request fields are invalid or missing |

Do not retry `401`, `403`, `413`, `415`, or `422` without changing the request. Retry connectivity or transient server failures only when appropriate for the caller's workflow.