AppMage
Home MemoryRpc

Memory

This endpoint group provides functionalities for managing persistent memories, allowing applications to save, recall, delete, and list pieces of information associated with users or global project contexts. It leverages a vector database for efficient semantic search and retrieval of memories.

Endpoints

POST /api/rpc (Method: MemoryRpc.saveMemory)

  • Description: Saves a piece of information (memory).
  • Request Body:
    {
  "method": "MemoryRpc.saveMemory",
  "params": {
    "scope": "user",
    "memory": {
      "id": "a-uuid-string",
      "content": "The actual memory content.",
      "metadata": {
        "key": "value"
      }
    },
    "targetUserId": "user-123"
  }
}
  • Parameters:
    Name Type Required Description
    scope String ("user" or "global") Yes Defines the scope of the memory. "user" for user-specific memories, "global" for project-wide shared memories.
    memory Object Yes The memory object to save.
    memory.id String (UUID) No A unique identifier for the memory. If not provided, a new UUID will be generated.
    memory.content String Yes The actual content of the memory. Must not be empty.
    memory.metadata Object No Optional, arbitrary key-value pairs to associate with the memory.
    targetUserId String No The appUserId for whom this user-scoped memory is being saved. Required if scope is 'user' and the call is made by an agent on behalf of another user; otherwise, the userId from the current session context is used.
  • Response:
    {
  "success": true,
  "data": {
    "success": true,
    "memoryId": "a-uuid-string",
    "message": "Memory saved."
  }
}
  • Example (cURL):
    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "MemoryRpc.saveMemory",
    "params": {
      "scope": "user",
      "memory": {
        "content": "User prefers dark mode.",
        "metadata": {
          "preference": "darkMode"
        }
      },
      "targetUserId": "user-123"
    }
  }'

POST /api/rpc (Method: MemoryRpc.recallMemories)

  • Description: Recalls relevant memories based on a query.
  • Request Body:
    {
  "method": "MemoryRpc.recallMemories",
  "params": {
    "scope": "user",
    "queryText": "What are my preferences?",
    "topK": 3,
    "filter": {},
    "targetUserId": "user-123"
  }
}
  • Parameters:
    Name Type Required Description
    scope String ("user" or "global") Yes Defines the scope of memories to recall. "user" for user-specific, "global" for project-wide.
    queryText String Yes The text query used to find relevant memories. Must not be empty.
    topK Number No The maximum number of top-scoring memories to return. Defaults to 3.
    filter Any No An optional filter object to apply to the memory search, typically for filtering by metadata.
    targetUserId String No The appUserId for whom to recall user-scoped memories. Required if scope is 'user' and the call is made by an agent on behalf of another user; otherwise, the userId from the current session context is used.
  • Response:
    {
  "success": true,
  "data": {
    "success": true,
    "memories": [
      {
        "id": "memory-uuid-1",
        "content": "User prefers dark mode.",
        "metadata": {
          "preference": "darkMode"
        },
        "score": 0.95
      }
    ]
  }
}
  • Example (cURL):
    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "MemoryRpc.recallMemories",
    "params": {
      "scope": "user",
      "queryText": "What did I say about my favorite color?",
      "topK": 1,
      "targetUserId": "user-123"
    }
  }'

POST /api/rpc (Method: MemoryRpc.deleteMemory)

  • Description: Deletes a specific memory by its ID.
  • Request Body:
    {
  "method": "MemoryRpc.deleteMemory",
  "params": {
    "scope": "user",
    "memoryId": "a-uuid-string",
    "targetUserId": "user-123"
  }
}
  • Parameters:
    Name Type Required Description
    scope String ("user" or "global") Yes Defines the scope of the memory to delete. "user" for user-specific, "global" for project-wide.
    memoryId String (UUID) Yes The unique identifier of the memory to delete.
    targetUserId String No The appUserId for whom to delete user-scoped memory. Required if scope is 'user' and the call is made by an agent on behalf of another user; otherwise, the userId from the current session context is used.
  • Response:
    {
  "success": true,
  "data": {
    "success": true,
    "message": "Memory deleted."
  }
}
  • Example (cURL):
    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "MemoryRpc.deleteMemory",
    "params": {
      "scope": "user",
      "memoryId": "some-memory-uuid",
      "targetUserId": "user-123"
    }
  }'

POST /api/rpc (Method: MemoryRpc.listMemories)

  • Description: Lists memories within a specified scope, with optional pagination.
  • Request Body:
    {
  "method": "MemoryRpc.listMemories",
  "params": {
    "scope": "user",
    "limit": 10,
    "offset": "last-memory-uuid",
    "targetUserId": "user-123"
  }
}
  • Parameters:
    Name Type Required Description
    scope String ("user" or "global") Yes Defines the scope of memories to list. "user" for user-specific, "global" for project-wide.
    limit Number No The maximum number of memories to return per page. Defaults to 10.
    offset String (UUID) or Number No An optional offset for pagination. Can be a UUID (for cursor-based pagination) or a number (for index-based pagination).
    targetUserId String No The appUserId for whom to list user-scoped memories. Required if scope is 'user' and the call is made by an agent on behalf of another user; otherwise, the userId from the current session context is used.
  • Response:
    {
  "success": true,
  "data": {
    "success": true,
    "memories": [
      {
        "id": "memory-uuid-1",
        "content": "Memory content 1",
        "metadata": {}
      },
      {
        "id": "memory-uuid-2",
        "content": "Memory content 2",
        "metadata": {}
      }
    ],
    "next_page_offset": "next-memory-uuid"
  }
}
  • Example (cURL):
    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "MemoryRpc.listMemories",
    "params": {
      "scope": "global",
      "limit": 5
    }
  }'