Agents

Agents are namespaces that isolate memories. Each agent has its own set of memories, sessions, and statistics. A typical setup has one agent per AI assistant or use case.

Create Agent

POST /v1/agents

Request Body

Field	Type	Required	Description
name	string	Yes	Agent name (1-255 characters)
description	string	No	Agent description or role (max 1,000 characters)
metadata	object	No	Custom metadata (max 10KB)

Response 201 Created

{
  "object": "agent",
  "id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "name": "customer-support-bot",
  "description": "Handles customer support queries and escalations",
  "config": {},
  "metadata": {
    "version": "1.0",
    "team": "support"
  },
  "memory_count": 0,
  "session_count": 0,
  "project_count": 0,
  "last_active_at": null,
  "created_at": "2026-03-17T10:00:00Z",
  "updated_at": "2026-03-17T10:00:00Z"
}

curl

curl -X POST https://api.memoryrelay.net/v1/agents \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-bot",
    "description": "Handles customer support queries and escalations",
    "metadata": { "version": "1.0", "team": "support" }
  }'

Python SDK

from memoryrelay import MemoryRelay

client = MemoryRelay(api_key="mem_prod_...")

agent = client.agents.create(
    name="customer-support-bot",
    description="Handles customer support queries and escalations",
    metadata={"version": "1.0", "team": "support"},
)
print(agent.id)

---

List Agents

GET /v1/agents

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Results per page (1-100)
offset	integer	0	Number of results to skip

Response

{
  "object": "list",
  "data": [
    {
      "object": "agent",
      "id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
      "name": "customer-support-bot",
      "description": "Handles customer support queries",
      "config": {},
      "metadata": { "version": "1.0" },
      "memory_count": 42,
      "session_count": 8,
      "project_count": 2,
      "last_active_at": "2026-03-17T09:30:00Z",
      "created_at": "2026-02-11T10:00:00Z",
      "updated_at": "2026-03-17T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

curl

curl "https://api.memoryrelay.net/v1/agents?limit=20&offset=0" \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

agents = client.agents.list(limit=20)
for agent in agents.data:
    print(f"{agent.name}: {agent.memory_count} memories")

---

Get Agent

GET /v1/agents/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Agent ID

Response

Returns a single agent object (same schema as items in the list response).

curl

curl https://api.memoryrelay.net/v1/agents/d4e5f6a7-b8c9-0123-4567-890abcdef012 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

agent = client.agents.get("d4e5f6a7-b8c9-0123-4567-890abcdef012")
print(f"{agent.name} has {agent.memory_count} memories")

---

Update Agent

PATCH /v1/agents/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Agent ID

Request Body

Field	Type	Required	Description
name	string	No	Updated name (1-255 characters)
description	string	No	Updated description (max 1,000 characters)
metadata	object	No	Updated metadata (merged with existing)

Response

Returns the updated agent object.

curl

curl -X PATCH https://api.memoryrelay.net/v1/agents/d4e5f6a7-b8c9-0123-4567-890abcdef012 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot-v2",
    "metadata": { "version": "2.0" }
  }'

Python SDK

updated = client.agents.update(
    "d4e5f6a7-b8c9-0123-4567-890abcdef012",
    name="support-bot-v2",
    metadata={"version": "2.0"},
)

---

Delete Agent

DELETE /v1/agents/{id}

Soft-delete an agent and all associated memories.

Path Parameters

Parameter	Type	Description
id	UUID	Agent ID

Response

Returns 204 No Content on success.

curl

curl -X DELETE https://api.memoryrelay.net/v1/agents/d4e5f6a7-b8c9-0123-4567-890abcdef012 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

client.agents.delete("d4e5f6a7-b8c9-0123-4567-890abcdef012")

---

Get Agent Stats

GET /v1/agents/{id}/stats

Returns aggregated statistics for an agent, including memory counts by tier, session counts, entity counts, and recall analytics.

Path Parameters

Parameter	Type	Description
id	UUID	Agent ID

Response

{
  "object": "agent_stats",
  "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "total_memories": 156,
  "memories_this_week": 23,
  "memories_this_month": 89,
  "active_sessions": 2,
  "entity_count": 34,
  "tier_breakdown": {
    "hot": 12,
    "warm": 128,
    "cold": 16
  },
  "last_active": "2026-03-17T09:30:00Z",
  "recall_activity": {
    "total_searches": 420,
    "avg_score": 0.78,
    "avg_results": 6.3
  },
  "search_analytics": {
    "top_queries": ["user preferences", "project deadlines", "meeting notes"],
    "avg_response_ms": 45.2
  }
}

curl

curl https://api.memoryrelay.net/v1/agents/d4e5f6a7-b8c9-0123-4567-890abcdef012/stats \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

stats = client.agents.stats("d4e5f6a7-b8c9-0123-4567-890abcdef012")
print(f"Total memories: {stats.total_memories}")
print(f"Hot: {stats.tier_breakdown.hot}, Warm: {stats.tier_breakdown.warm}, Cold: {stats.tier_breakdown.cold}")