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 -X GET "https://api.horizonplatform.ai/api/agents/agent_001/memories?limit=10&tag=preference" \
  -H "x-api-key: hz_live_abc123def456"

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);

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 -X GET https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4 \
  -H "x-api-key: hz_live_abc123def456"

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();

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 -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"
    }
  }'

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();

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 -X DELETE https://api.horizonplatform.ai/api/agents/agent_001/memories/mem_a1b2c3d4 \
  -H "x-api-key: hz_live_abc123def456"

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

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.

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.

HORIZON® is a registered trademark of Alpine Anchor LLC, Reg. No. 7,898,589.