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:

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

Health

$CLI health

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

Create User

$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

$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:

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

$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

$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:

$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:

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

Then run:

$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:

$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:

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

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

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

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