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

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: Bearer am_sk_your_secret_key

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

Errors

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

Store a memory. The content is embedded automatically so it becomes semantically retrievable. Also accepts importance (0–10), ttl_seconds, tags, namespace, outcome, and detect_conflicts. Requires the write scope.

Body parameters

Example request

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":"Prefers email; on the Pro plan." }'

Semantically search a user's memories with composite scoring (semantic + outcome + importance + recency). Filters: namespace, tags, min_importance, outcome, include_expired. Requires read.

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

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

curl -X DELETE "https://agentmemo.dev/memory/forget?id=mem_..." -H "Authorization: Bearer am_sk_your_key"

Memory types

AgentMemo offers five human-like memory types, all under /memory/* with the same bearer auth.

Episodic — sessions you can replay

curl -X POST /memory/episodes/start -d '{"agent_id":"a1","user_id":"u1","title":"Support chat"}'
curl -X POST /memory/episodes/event -d '{"episode_id":"ep_...","content":"User reported login failure"}'
curl -X POST /memory/episodes/end   -d '{"episode_id":"ep_..."}'

Procedural — how to do things

curl -X POST /memory/procedures -d '{"agent_id":"a1","name":"Generate report","steps":["fetch","analyze","format"]}'
curl "/memory/procedures/match?agent_id=a1&q=user+wants+a+summary"

Working — short-term RAM (1h TTL)

curl -X POST /memory/working -d '{"session_id":"s1","content":{"step":"awaiting confirmation"}}'

Emotional — sentiment & trust

curl -X POST /memory/emotional -d '{"agent_id":"a1","user_id":"u1","sentiment":"positive","intensity":8}'
curl "/memory/emotional/profile?user_id=u1&agent_id=a1"

More

Also available: /memory/context (LLM injection), /memory/batch, /memory/feedback, /memory/stats, /memory/graph/*, /memory/compress, /memory/export, /agents/*. Full machine spec: /openapi.json.

Usage for the calling key. Beta: usage is free and unlimited — used is informational only; a per-key rate limit applies as abuse protection.

Get an API key

Self-serve and agent-first — no auth, no email, no approval. The key is returned directly in the response.

curl -X POST https://agentmemo.dev/signup -d '{ "name": "My Agent" }'
# → { "api_key": "am_sk_...", "tier": "beta", "unlimited": true, "mcp": "..." }

MCP server & Claude Managed Agents

AgentMemo is a native Model Context Protocol server. Add it to any Claude Managed Agent in one line:

{
  "mcp_servers": [{
    "type": "url",
    "name": "agentmemo",
    "url": "https://agentmemo.dev/mcp",
    "authorization_token": "Bearer am_sk_your_key"
  }]
}

Tools: store_memory, retrieve_memory, get_context, forget_memory, give_feedback, get_stats, get_usage. Manifest: server-card.json. SDKs: /sdk.