memory-gateway/skill/memory-gateway-agent/SKILL.md

name, description

name	description
memory-gateway-agent	Use when an AI agent needs to create or authenticate a Memory Gateway user, upload and manage user resources, add or flush chat memories, search scoped memory, or apply user-approved memory corrections and deletions through the Memory Gateway HTTP API.

Memory Gateway Agent

Use the bundled CLI instead of constructing HTTP requests manually. It produces JSON output and uses only the Python standard library.

Configure

Set these variables before authenticated operations:

export MEMORY_GATEWAY_BASE_URL="http://127.0.0.1:8010"
export MEMORY_GATEWAY_USER_ID="u_123"
export MEMORY_GATEWAY_USER_KEY="uk_xxx"
SKILL_DIR="/path/to/memory-gateway-agent"
CLI="python $SKILL_DIR/scripts/memory_gateway.py"

Do not write a real user_key into source files, prompts, logs, or committed documentation. Command-line flags may override environment variables, but environment variables are preferred because process arguments may be observable.

Workflow

1. Run $CLI health when connectivity or upstream memory service availability is uncertain.
2. Use an existing user_id and user_key. Run create-user only when the user explicitly needs a new Gateway identity.
3. Choose the operation:
   • Upload durable user files with upload-resource.
   • Add conversational or multimodal messages with add-memory, then call flush-memory.
   • Search with the narrowest useful scope.
   • List or inspect resources before deleting them.
4. Treat JSON output as the source of truth. Preserve returned resource_id, memory id, and session_id exactly.
5. For override or deletion, use the memory id and session_id returned by search. Never invent IDs or apply changes across users.

Common Commands

$CLI health
$CLI list-resources
$CLI upload-resource ./contract.pdf --title "Contract"
$CLI search "What are the payment terms?" --scope resources --top-k 8
$CLI search "What did we discuss?" --scope current_chat --conversation-id c_456
$CLI override-memory mem_abc --session-id resource:u_123:r_xxx --text "Corrected text"
$CLI delete-memory mem_abc --session-id resource:u_123:r_xxx --reason "User requested deletion"

For chat ingestion, put the Gateway messages array in a JSON file:

$CLI add-memory --session-id chat:c_456 --messages /tmp/messages.json
$CLI flush-memory --session-id chat:c_456

Read references/api.md when choosing scopes, constructing multimodal messages, interpreting errors, or using less common commands.

Safety Rules

• Do not expose internal file paths. Return the Gateway's resource://{user_id}/{resource_id} URI to users.
• Do not claim ingestion succeeded unless the upload status is extracted or flush reports success.
• Treat health.status = degraded as Gateway available but upstream memory service unavailable.
• Resource deletion is soft deletion in Gateway search scope and removes the Gateway upload copy; it does not delete upstream memory service internal indexes.
• Memory override and deletion require an owned resource:{user_id}:{resource_id} or memory_edit:{user_id} session.
• Ask for confirmation before destructive deletion unless the user's current request explicitly instructs deletion.