65 lines
3.2 KiB
Markdown
65 lines
3.2 KiB
Markdown
---
|
|
name: memory-gateway-agent
|
|
description: 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
$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:
|
|
|
|
```bash
|
|
$CLI add-memory --session-id chat:c_456 --messages /tmp/messages.json
|
|
$CLI flush-memory --session-id chat:c_456
|
|
```
|
|
|
|
Read [references/api.md](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.
|