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

# 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.

### 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.

## 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.