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 agm_your_api_key

Keys start with agm_ and are 40 characters long — see the API key format reference.

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. Missing tags are created automatically within the capsule tag limit. 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)
prefixOnly include keys starting with this prefix (case-sensitive), e.g. project.acme.

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 topic. Matches any query word in keys or values (including word forms like plurals) or the exact text, best matches first.

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.

Query Parameters

prefixOnly include keys starting with this prefix (case-sensitive), e.g. project.acme.

Response

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

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

Query Parameters

prefixOnly include keys starting with this prefix (case-sensitive), e.g. project.acme.

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