Skip to main content
The Memory API provides persistent memory storage and retrieval for AI agents and users.

​
Endpoints

MethodEndpointDescription
POST/memory-stores/{store_id}/memoriesAdd memories
POST/memory-stores/{store_id}/memories/searchSearch memories
GET/memory-stores/{store_id}/memoriesList memories
GET/memory-stores/{store_id}/memories/{memory_id}Get memory
PUT/memory-stores/{store_id}/memories/{memory_id}Update memory
DELETE/memory-stores/{store_id}/memories/{memory_id}Delete memory
DELETE/memory-stores/{store_id}/memoriesDelete all memories
GET/memory-stores/{store_id}/memories/{memory_id}/historyGet history
POST/memory-stores/{store_id}/resetReset store

​
Authentication

All requests require a Bearer token: 
Authorization: Bearer $HX_API_KEY

​
Store IDs

Memory stores use the ms- prefix: 
ms-abc123def456

​
Quick Example

from hx import Client

client = Client()

# Add memory
client.memory.add(
    store_id="ms-your-store-id",
    user_id="user_123",
    messages=[{"role": "user", "content": "My name is Alex."}]
)

# Search memory
memories = client.memory.search(
    store_id="ms-your-store-id",
    query="What is my name?",
    user_id="user_123"
)

​
Memory Scoping

Memories can be scoped by:
ScopeParameterDescription
Useruser_idPer-user memories
Agentagent_idPer-agent memories
Sessionrun_idPer-session memories

​
Message Format

When adding memories, messages follow this format: 
{
  "messages": [
    {"role": "user", "content": "My name is Alex."},
    {"role": "assistant", "content": "Nice to meet you, Alex!"}
  ]
}
Valid roles: user, assistant, system