Agent Memory

The Agent Memory API gives you programmatic control over the long-term memory store that backs each Horizon agent. Memories are stored in Supabase and allow agents to recall context, preferences, and learned information across conversations. Every endpoint in this section requires x-api-key authentication.

---

List Memories

GET /api/agents/:agentId/memories

Retrieve a paginated list of memories for a specific agent, with optional tag filtering.

Requires authentication via x-api-key header.

Path Parameters

Parameter	Type	Description
agentId required	string	The unique identifier of the agent whose memories to list.

Query Parameters

Parameter	Type	Description
limit	number	Maximum number of memories to return. Default: 50, Max: 200.
offset	number	Number of results to skip for pagination. Default: 0.
tag	string	Filter memories by tag (exact match). For example, 'preference' or 'customer-context'.

Request

curl

curl -X GET "https://api.horizonplatform.ai/api/agents/agent_001/memories?limit=10&tag=preference" \
  -H "x-api-key: hz_live_abc123def456"

JavaScript

const params = new URLSearchParams({
  limit: '10',
  tag: 'preference',
});

const response = await fetch(
  `https://api.horizonplatform.ai/api/agents/agent_001/memories?${params}`,
  { headers: { 'x-api-key': 'hz_live_abc123def456' } }
);

const memories = await response.json();
console.log(memories);

Python

import requests

response = requests.get(
    'https://api.horizonplatform.ai/api/agents/agent_001/memories',
    headers={'x-api-key': 'hz_live_abc123def456'},
    params={
        'limit': 10,
        'tag': 'preference',
    }
)

memories = response.json()
print(memories)

Response

// 200 OK
{
  "data": [
    {
      "id": "mem_a1b2c3d4",
      "agent_id": "agent_001",
      "content": "User prefers accrual-basis accounting for all financial reports.",
      "tag": "preference",
      "metadata": {
        "source": "conversation",
        "conversation_id": "conv_8f3a2b1c"
      },
      "created_at": "2026-03-10T08:15:00Z",
      "updated_at": "2026-03-10T08:15:00Z"
    },
    {
      "id": "mem_e5f6g7h8",
      "agent_id": "agent_001",
      "content": "Default reporting currency is USD.",
      "tag": "preference",
      "metadata": {},
      "created_at": "2026-03-08T14:22:00Z",
      "updated_at": "2026-03-08T14:22:00Z"
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0
}

---

Get a Memory

GET /api/agents/:agentId/memories/:memoryId

Retrieve a single memory by its identifier.

Requires authentication via x-api-key header.

Path Parameters

Parameter	Type	Description
agentId required	string	The agent identifier.
memoryId required	string	The unique memory identifier.

Request

curl

curl -X GET https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4 \
  -H "x-api-key: hz_live_abc123def456"

JavaScript

const response = await fetch(
  'https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4',
  { headers: { 'x-api-key': 'hz_live_abc123def456' } }
);

const memory = await response.json();

Python

import requests

response = requests.get(
    'https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4',
    headers={'x-api-key': 'hz_live_abc123def456'}
)

memory = response.json()

Response

// 200 OK
{
  "id": "mem_a1b2c3d4",
  "agent_id": "agent_001",
  "content": "User prefers accrual-basis accounting for all financial reports.",
  "tag": "preference",
  "metadata": {
    "source": "conversation",
    "conversation_id": "conv_8f3a2b1c"
  },
  "created_at": "2026-03-10T08:15:00Z",
  "updated_at": "2026-03-10T08:15:00Z"
}

---

Update a Memory

PUT /api/agents/:agentId/memories/:memoryId

Update the content, tag, or metadata of an existing memory.

Requires authentication via x-api-key header.

Path Parameters

Parameter	Type	Description
agentId required	string	The agent identifier.
memoryId required	string	The memory identifier to update.

Request Body

Parameter	Type	Description
content	string	The updated memory content text.
tag	string	A tag for categorizing the memory (e.g., 'preference', 'fact', 'customer-context').
metadata	object	Arbitrary key-value metadata to attach to the memory.

Request

curl

curl -X PUT https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4 \
  -H "x-api-key: hz_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers accrual-basis accounting. Also prefers quarterly breakdowns.",
    "tag": "preference",
    "metadata": {
      "source": "conversation",
      "conversation_id": "conv_8f3a2b1c",
      "updated_reason": "User clarified reporting preference"
    }
  }'

JavaScript

const response = await fetch(
  'https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4',
  {
    method: 'PUT',
    headers: {
      'x-api-key': 'hz_live_abc123def456',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content: 'User prefers accrual-basis accounting. Also prefers quarterly breakdowns.',
      tag: 'preference',
      metadata: {
        source: 'conversation',
        conversation_id: 'conv_8f3a2b1c',
        updated_reason: 'User clarified reporting preference',
      },
    }),
  }
);

const updated = await response.json();

Python

import requests

response = requests.put(
    'https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4',
    headers={
        'x-api-key': 'hz_live_abc123def456',
        'Content-Type': 'application/json',
    },
    json={
        'content': 'User prefers accrual-basis accounting. Also prefers quarterly breakdowns.',
        'tag': 'preference',
        'metadata': {
            'source': 'conversation',
            'conversation_id': 'conv_8f3a2b1c',
            'updated_reason': 'User clarified reporting preference',
        },
    }
)

updated = response.json()

Response

// 200 OK
{
  "id": "mem_a1b2c3d4",
  "agent_id": "agent_001",
  "content": "User prefers accrual-basis accounting. Also prefers quarterly breakdowns.",
  "tag": "preference",
  "metadata": {
    "source": "conversation",
    "conversation_id": "conv_8f3a2b1c",
    "updated_reason": "User clarified reporting preference"
  },
  "created_at": "2026-03-10T08:15:00Z",
  "updated_at": "2026-03-18T11:42:00Z"
}

---

Delete a Memory

DELETE /api/agents/:agentId/memories/:memoryId

Permanently delete a memory. This action cannot be undone.

Requires authentication via x-api-key header.

Path Parameters

Parameter	Type	Description
agentId required	string	The agent identifier.
memoryId required	string	The memory identifier to delete.

Request

curl

curl -X DELETE https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4 \
  -H "x-api-key: hz_live_abc123def456"

JavaScript

const response = await fetch(
  'https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4',
  {
    method: 'DELETE',
    headers: { 'x-api-key': 'hz_live_abc123def456' },
  }
);
// 204 No Content on success

Python

import requests

response = requests.delete(
    'https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4',
    headers={'x-api-key': 'hz_live_abc123def456'}
)
# 204 No Content on success

Response

A successful deletion returns 204 No Content with an empty response body.

Caution

Deleting a memory is irreversible. If the agent relies on a specific memory for context during skill execution, removing it may change the agent’s behavior in future conversations.

---

Error Responses

Status	Error	Description
401	authentication_required	Missing or invalid API key.
403	insufficient_scope	API key lacks the required scope for this agent.
404	not_found	The specified agent or memory does not exist.
400	validation_error	Invalid request body or query parameter values.
429	rate_limit_exceeded	API key rate limit exceeded.