Memory API

Store and retrieve key-value memory for agents

Memory API

Store and retrieve persistent key-value data for your agents. All endpoints require session authentication. GET requests with a specific agentId verify ownership; omitting the parameter or passing all returns memories across all of your agents.

Get memory

GET /api/memory?agentId=agent_123

Retrieve memory for a specific agent, or for all of your agents at once.

Query parameters

Parameter	Type	Required	Description
agentId	string	No	ID of the agent. Pass all or omit to return memories across all of your agents. When a specific agent ID is provided, an ownership check is performed.

Response

When agentId is a specific agent ID:

{
  "memory": {
    "preferences": { "theme": "dark" },
    "context": "Last conversation was about scheduling"
  },
  "agentId": "agent_123",
  "count": 2,
  "lastUpdated": "2026-03-19T00:00:00Z"
}

When agentId is all or omitted:

{
  "memory": {
    "preferences": { "theme": "dark" },
    "context": "Last conversation was about scheduling",
    "other_agent_key": "value from another agent"
  },
  "agentId": null,
  "count": 3,
  "lastUpdated": "2026-03-19T00:00:00Z"
}

Errors

Code	Description
401	Unauthorized
404	Agent not found (only when a specific agentId is provided)
500	Failed to fetch memory

Store memory (single key)

POST /api/memory

Write a single key-value pair to agent memory.

Request body

Field	Type	Required	Description
agentId	string	Yes	ID of the agent
key	string	Yes	Memory key
memory	any	Yes	Value to store (max 100 KB)

Response

{
  "success": true,
  "agentId": "agent_123",
  "key": "preferences",
  "saved": "2026-03-19T00:00:00Z"
}

Errors

Code	Description
400	agentId required, memory data required, or value too large (max 100 KB)
401	Unauthorized
404	Agent not found
500	Failed to save memory

Store memory (bulk)

POST /api/memory

Write multiple key-value pairs in a single request.

Request body

Field	Type	Required	Description
agentId	string	Yes	ID of the agent
memory	object	Yes	Object of key-value pairs to store (max 50 keys)

{
  "agentId": "agent_123",
  "memory": {
    "preferences": { "theme": "dark" },
    "context": "Scheduling discussion"
  }
}

Response

{
  "success": true,
  "agentId": "agent_123",
  "keysUpdated": 2,
  "saved": "2026-03-19T00:00:00Z"
}

Errors

Code	Description
400	agentId required, memory data required, or too many keys (max 50)
401	Unauthorized
404	Agent not found
500	Failed to save memory