API Overview

The MemoryRelay API provides persistent memory storage and retrieval for AI agents. All endpoints follow RESTful conventions and return JSON responses.

Base URL

https://api.memoryrelay.net

All endpoints are versioned under the /v1/ prefix (or /v2/ for async operations).

Content Type

All requests must include the Content-Type: application/json header. All responses are returned as application/json.

Authentication

Every request (except GET /v1/health) must include an API key using one of two methods:

Method	Header	Example
Bearer token	Authorization	Authorization: Bearer mem_prod_abc123...
API key header	X-API-Key	X-API-Key: mem_prod_abc123...

Both methods are equivalent. Use whichever fits your application. See API Keys for key management.

tip

API keys are prefixed with mem_prod_ and should be stored securely. The full key is only shown once at creation time.

Error Responses

All errors return a consistent JSON structure:

{
  "type": "not_found",
  "message": "Memory not found",
  "code": 404,
  "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Type	Description
type	string	Machine-readable error type (validation_error, not_found, unauthorized, rate_limit_exceeded, internal_error)
message	string	Human-readable error description
code	integer	HTTP status code
request_id	string	Unique request identifier for debugging

Validation errors include field-level details:

{
  "type": "validation_error",
  "message": "Request validation failed",
  "code": 422,
  "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "details": [
    {
      "field": "content",
      "message": "Content cannot be empty or whitespace"
    }
  ]
}

Common HTTP Status Codes

Code	Meaning
200	Success
201	Resource created
202	Accepted (async processing)
204	Deleted (no content)
400	Bad request
401	Unauthorized (missing or invalid API key)
403	Forbidden (insufficient scopes)
404	Resource not found
422	Validation error
429	Rate limit exceeded
500	Internal server error

Pagination

List endpoints support cursor-based pagination:

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

Paginated responses include metadata:

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "next_cursor": "cursor_abc123",
  "total_count": 142
}

Rate Limiting

The API enforces rate limits per API key. Rate limit status is returned in response headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

The default rate limit is 100 requests per minute. When exceeded, the API returns a 429 status code:

{
  "type": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "code": 429,
  "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Request IDs

Every response includes an X-Request-ID header. You can also provide your own request ID for distributed tracing:

curl https://api.memoryrelay.net/v1/memories \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "X-Request-ID: my-trace-id-12345"

The server will use your provided ID (or generate one if omitted). Include the request ID when contacting support for faster debugging.

Resources

Resource	Description
Memories	Store, search, and manage agent memories
Agents	Create and manage agent namespaces
Entities	Knowledge graph nodes and relationships
Sessions	Group memories by work sessions
Decisions	Record and track architectural decisions
Patterns	Reusable coding patterns across projects
Projects	Register and scope work to projects
API Keys	Manage authentication keys
Webhooks	Event-driven notifications
v2 Async	Asynchronous memory processing