agimemagimem
Back to docs
Documentation

REST API Reference

Access your capsule memories over standard HTTP. Same data, same limits, no MCP client required.

Base URL

https://agimem.dev/api/rest

Authentication

All requests require a Bearer token. Use the same API key from your capsule — each key is scoped to exactly one capsule.

Authorization: Bearer mcp_your_api_key

Rate Limits

60 requests per minute per account, shared across MCP and REST. Rate limited responses return 429 with a Retry-After: 60 header.

Errors

All errors return JSON with an error field:

{ "error": "description of what went wrong" }
400Bad request
401Invalid or missing API key
404Resource not found
409Limit exceeded
429Rate limited
500Internal server error

Memory

PUT/memory

Store or update a memory. Returns 201 for new keys, 200 for updates.

Request Body

{
  "key": "user-preferences",
  "value": "Prefers dark mode, concise answers",
  "tags": ["settings", "ui"],
  "ttlMinutes": 1440
}

Response

{
  "key": "user-preferences",
  "stored": true,
  "tags": ["settings", "ui"],
  "expiresAt": "2026-05-11T12:00:00.000Z",
  "isNew": true
}
GET/memory?key=X

Retrieve a memory by key. Returns the value, tags, timestamps, and expiration.

Query Parameters

keyrequiredThe memory key to retrieve

Response

{
  "key": "user-preferences",
  "value": "Prefers dark mode, concise answers",
  "tags": ["settings", "ui"],
  "expiresAt": "2026-05-11T12:00:00.000Z",
  "createdAt": "2026-05-10T12:00:00.000Z",
  "updatedAt": "2026-05-10T12:00:00.000Z"
}
DELETE/memory?key=X

Delete a memory by key.

Query Parameters

keyrequiredThe memory key to delete

Response

{ "key": "user-preferences", "deleted": true }

List & Search

GET/memories

List non-expired memories with their keys and last-updated timestamps. Paginated.

Query Parameters

pagePage number (default 1)
pageSizeItems per page (1–200, default 50)

Response

{
  "keys": [
    { "key": "config", "updatedAt": "2026-05-10T12:00:00.000Z" },
    { "key": "notes", "updatedAt": "2026-05-09T08:00:00.000Z" }
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 2,
  "totalPages": 1
}
GET/memories?q=search

Search memories by key or value (case-insensitive substring match).

Query Parameters

qrequiredSearch query
limitMax results (1–50, default 20)

Response

{
  "results": [
    { "key": "config", "preview": "Dark mode enabled, font size 14..." }
  ],
  "count": 1
}
GET/memories/keys

List only key names (no values). Lighter than full list.

Response

{ "keys": ["config", "notes", "preferences"] }
GET/memories/count

Get the number of non-expired memories and the capsule limit.

Response

{ "count": 42, "limit": 200 }
GET/memories/exists?key=X

Check whether a key exists without fetching its value.

Query Parameters

keyrequiredThe key to check

Response

{ "key": "config", "exists": true }
DELETE/memories

Delete all memories in the capsule.

Response

{ "cleared": true }

Bulk Operations

POST/memories/bulk/set

Store multiple memories in one request (up to 20 items).

Request Body

{
  "items": [
    { "key": "k1", "value": "v1", "tags": ["t1"] },
    { "key": "k2", "value": "v2", "ttlMinutes": 60 }
  ]
}

Response

{
  "storedCount": 2,
  "errorCount": 0,
  "results": [""k1": stored with 1 tag(s)", ""k2": stored"]
}
POST/memories/bulk/get

Retrieve multiple memories by key (up to 50 keys).

Request Body

{ "keys": ["k1", "k2", "k3"] }

Response

{
  "items": [
    { "key": "k1", "found": true, "value": "v1", "tags": ["t1"] },
    { "key": "k2", "found": true, "value": "v2", "tags": [] },
    { "key": "k3", "found": false }
  ],
  "foundCount": 2,
  "missingCount": 1
}
POST/memories/bulk/delete

Delete multiple memories by key (up to 50 keys).

Request Body

{ "keys": ["k1", "k2"] }

Response

{
  "deletedCount": 2,
  "missingCount": 0,
  "results": [
    { "key": "k1", "deleted": true },
    { "key": "k2", "deleted": true }
  ]
}

Tags

GET/tags

List all tags in the capsule.

Response

{ "tags": ["config", "notes", "ui"] }
POST/tags

Create a new tag. Returns 201 if created, 200 if it already exists.

Request Body

{ "name": "my-tag" }

Response

{ "name": "my-tag", "created": true }
DELETE/tags?name=X

Delete a tag and unlink it from all memories.

Query Parameters

namerequiredThe tag name to delete

Response

{ "name": "my-tag", "deleted": true }
GET/tags/memories?tag=X

List memory keys that have a specific tag.

Query Parameters

tagrequiredTag to filter by

Response

{ "keys": ["config", "preferences"] }
POST/tags/memories

List memory keys matching all given tags (AND filter).

Request Body

{ "tags": ["config", "ui"] }

Response

{ "keys": ["preferences"] }

Capsule

GET/capsule

Get a summary of the capsule: name, description, usage, and limits.

Response

{
  "name": "my-project",
  "description": "Production agent memory",
  "memoryCount": 42,
  "memoryLimit": 200,
  "tagCount": 5,
  "tagLimit": 20,
  "lastUsed": "2026-05-10T12:00:00.000Z"
}