API Reference

AgentMemo gives your AI agents persistent, semantically-searchable memory over a tiny REST API. Three verbs — store, retrieve, forget — plus authentication and usage.

Introduction

Every request is JSON over HTTPS. All memory is scoped to your API key, so data from different keys is fully isolated. Embeddings and vector ranking are handled for you — you send plain text, we make it searchable.

Base URL

base url

https://agentmemo.dev

Authentication

Authenticate every request with your secret API key in the Authorization header as a bearer token. Keys look like am_sk_... and are shown only once when created.

Authorization header

Authorization: Bearer am_sk_your_secret_key

Keys carry scopes: read (retrieve, usage) and write (store, forget). Don't have a key yet? Request one here.

Keep keys secret. Treat am_sk_ keys like passwords — use them only from server-side code, never in a browser or mobile client.

Errors

Errors return the matching HTTP status and a JSON body of the form { "error": { "status", "message" } }.

Status	Meaning
`400`	Invalid request — missing or malformed fields.
`401`	Missing or invalid API key.
`403`	Key is revoked or lacks the required scope.
`404`	Resource (e.g. a memory id) not found.

POST/memory/store

Store a memory. The content is embedded automatically so it becomes semantically retrievable. Requires the write scope.

Body parameters

Field	Type	Description
`user_id` required	string	End-user this memory belongs to.
`agent_id` required	string	Agent that produced or owns the memory.
`content` required	string	The memory text. Up to 100,000 chars.
`metadata` optional	object	Arbitrary JSON returned with the memory.

Example request

cURL

curl -X POST https://agentmemo.dev/memory/store \
  -H "Authorization: Bearer am_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "agent_id": "support_bot",
    "content": "The customer prefers email and is on the Pro plan.",
    "metadata": { "channel": "email", "plan": "pro" }
  }'

Example response 201 Created

200 OK · application/json

{
  "id": "mem_52fd593fd8b74f6db96a",
  "user_id": "user_123",
  "agent_id": "support_bot",
  "content": "The customer prefers email and is on the Pro plan.",
  "metadata": { "channel": "email", "plan": "pro" },
  "embedded": true,
  "created_at": 1781729785946
}

GET/memory/retrieve

Semantically search a user's memories. The query is embedded and memories are ranked by cosine similarity; results are edge-cached. Requires the read scope.

Query parameters

Param	Type	Description
`q` required	string	Natural-language search query.
`user_id` required	string	Scope the search to this user.
`agent_id` optional	string	Further narrow to one agent.
`limit` optional	int	Max results (default 10, max 100).
`min_score` optional	float	Drop results below this similarity.

Example request

cURL

curl "https://agentmemo.dev/memory/retrieve?user_id=user_123&q=how+to+contact+them&limit=3" \
  -H "Authorization: Bearer am_sk_your_key"

JavaScript

fetch

const params = new URLSearchParams({
  user_id: "user_123",
  q: "how should we contact this user"
});
const res = await fetch("https://agentmemo.dev/memory/retrieve?" + params, {
  headers: { Authorization: "Bearer am_sk_your_key" }
});
const { results } = await res.json();

Example response 200 OK

200 OK · application/json

{
  "query": "how should we contact this user",
  "semantic": true,
  "count": 1,
  "results": [
    {
      "id": "mem_52fd593fd8b74f6db96a",
      "content": "The customer prefers email and is on the Pro plan.",
      "metadata": { "channel": "email" },
      "score": 0.617785,
      "created_at": 1781729785946
    }
  ]
}

Recency fallback. If the embedding service is briefly unavailable, retrieval returns the most recent memories with "semantic": false and score: null instead of failing.

DELETE/memory/forget

Delete a single memory by id, or wipe an entire scope by user_id (optionally narrowed by agent_id). Deletes are always restricted to your own key. Requires the write scope.

Query parameters

Param	Type	Description
`id`	string	Delete one specific memory. Returns `404` if not found.
`user_id`	string	Delete all of a user's memories.
`agent_id` optional	string	With `user_id`, limit deletion to one agent.

Provide either id or user_id.

Example requests

cURL

# delete one memory
curl -X DELETE "https://agentmemo.dev/memory/forget?id=mem_52fd593fd8b74f6db96a" \
  -H "Authorization: Bearer am_sk_your_key"

# forget everything for a user + agent
curl -X DELETE "https://agentmemo.dev/memory/forget?user_id=user_123&agent_id=support_bot" \
  -H "Authorization: Bearer am_sk_your_key"

Example response 200 OK

200 OK · application/json

{ "deleted": 1 }

GET/usage

Return usage for the calling key — total requests, embedding tokens, average latency, a per-route breakdown, and daily buckets.

Query parameters

Param	Type	Description
`from` optional	int (ms)	Window start. Default: 30 days ago.
`to` optional	int (ms)	Window end. Default: now.
`days` optional	int	Daily buckets to return (max 365).

cURL

curl "https://agentmemo.dev/usage" -H "Authorization: Bearer am_sk_your_key"

200 OK · application/json

{
  "totals": { "requests": 128, "tokens": 3940, "errors": 2, "avg_latency_ms": 41 },
  "by_route": [ { "route": "POST /memory/store", "requests": 90 } ],
  "daily": [ { "day": "2026-06-18", "requests": 128 } ]
}