// documentation

AgentRAM API Reference

Everything your AI agent needs to read and write persistent memory. All endpoints return JSON. Authentication is handled via an API key in the request header.

Quickstart

Three steps to give your agent a working memory.

Step 1: Register and get your API key

curl

curl -X POST https://api.agentram.dev/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

response

{
  "success": true,
  "data": {
    "api_key": "agentram_7f3a9b2c...",
    "credits": 100
  }
}

Step 2: Store a memory

curl

curl -X POST https://api.agentram.dev/memory \
  -H "x-api-key: agentram_7f3a9b2c..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agent-01","key":"user_pref","value":"prefers short answers"}'

Step 3: Read it back in any later session

curl

curl https://api.agentram.dev/memory?agent_id=agent-01&key=user_pref \
  -H "x-api-key: agentram_7f3a9b2c..."

That's it. Your agent now has persistent memory that survives across sessions, devices, and restarts.

Authentication

Every request except /register requires your API key in the request header.

header

x-api-key: agentram_your_key_here

Requests without a valid API key return a 401 Unauthorized response. Keep your API key private. Treat it like a password.

Credits

AgentRAM uses a credit system. Each operation costs one credit. Credits are deducted only on success. If a request fails for any reason, your credit is returned automatically.

Operation	Credit cost
POST /memory	1 credit
GET /memory	1 credit
GET /memories	1 credit
GET /memory/search	1 credit
DELETE /memory	1 credit
POST /memory/shared	1 credit
GET /memory/shared	1 credit
GET /memories/shared	1 credit
POST /namespace	0 credits
GET /credits	0 credits
POST /register	0 credits

Running low? Check your balance with GET /credits at any time. Top up at agentram.dev/#pricing.

Endpoints

Register

POST /register

Creates a new account and returns an API key with 100 free credits. One account per email address.

Body param	Type	Required	Description
email	string	required	Your email address. Used to identify your account.

response · 201

{
  "success": true,
  "data": {
    "email": "you@example.com",
    "api_key": "agentram_7f3a9b2c...",
    "credits": 100
  }
}

Write a memory

POST /memory

Stores a value under a key for a given agent. Writing to an existing key updates the value. No duplicates are created.

Body param	Type	Required	Description
agent_id	string	required	A unique identifier for the agent. Max 100 characters.
key	string	required	The memory label. Max 200 characters.
value	string	required	What to remember. Max 5,000 characters.
ttl_days	number	optional	Days until this memory expires automatically. Once expired, reads return 404 and the memory is excluded from lists and searches. Omit for memories that should not expire.

response · 200

{
  "success": true,
  "data": {
    "agent_id": "agent-01",
    "key": "user_pref",
    "credits_remaining": 99
  }
}

Read a memory

GET /memory

Retrieves a stored value by agent ID and key. Returns 404 if the memory does not exist, and refunds the credit.

Query param	Type	Required	Description
agent_id	string	required	The agent identifier used when writing the memory.
key	string	required	The memory label to retrieve.

response · 200

{
  "success": true,
  "data": {
    "agent_id": "agent-01",
    "key": "user_pref",
    "value": "prefers short answers",
    "created_at": "2026-05-09T18:00:00.000Z",
    "credits_remaining": 98
  }
}

Delete a memory

DELETE /memory

Permanently removes a stored memory. This cannot be undone.

Body param	Type	Required	Description
agent_id	string	required	The agent identifier.
key	string	required	The memory label to delete.

response · 200

{
  "success": true,
  "data": { "deleted": true, "credits_remaining": 97 }
}

Check credit balance

GET /credits

Returns the current credit balance for your account. This endpoint never deducts a credit. Safe to call as often as needed.

response · 200

{
  "success": true,
  "data": {
    "email": "you@example.com",
    "credits": 97
  }
}

List all memories for an agent

GET /memories

Returns all memories stored under a given agent ID, ordered by most recently written. Expired memories are silently excluded.

Query param	Type	Required	Description
agent_id	string	required	The agent identifier.
limit	integer	optional	Max results to return. Default 50, max 200.

response · 200

{
  "success": true,
  "data": [
    { "key": "user_lang", "value": "French", "created_at": "...", "expires_at": null },
    { "key": "tone", "value": "formal", "created_at": "...", "expires_at": null }
  ],
  "credits_remaining": 96
}

Search memories by text

GET /memory/search

Case-insensitive text search across both the key and value fields for a given agent. Returns matching memories ordered by most recent. No embeddings or configuration required.

Query param	Type	Required	Description
agent_id	string	required	The agent identifier.
q	string	required	The search term. Matched against key and value fields.

response · 200

{
  "success": true,
  "data": [
    { "key": "user_lang", "value": "French", "created_at": "..." }
  ],
  "credits_remaining": 95
}

Shared memory

Shared namespaces allow multiple agents or API key holders to read and write to a common memory pool. Create a namespace first, then share the namespace_key with any agent that needs access.

Create a namespace

POST /namespace

Creates a new shared namespace and returns a unique namespace key. Free — costs no credits. Any agent with a valid API key and the namespace key can then read and write to that namespace.

Body param	Type	Required	Description
label	string	optional	A human-readable name for the namespace. Max 100 characters.

response · 201

{
  "success": true,
  "data": { "namespace_key": "ns_a1b2c3d4...", "label": "team-alpha" }
}

Write a shared memory

POST /memory/shared

Writes a value to a shared namespace. Any API key holder who knows the namespace key can write. Supports optional TTL.

Body param	Type	Required	Description
namespace_key	string	required	The namespace key returned from POST /namespace.
key	string	required	The memory label. Max 200 characters.
value	string	required	What to store. Max 5,000 characters.
ttl_days	number	optional	Days until this memory expires automatically.

Read a shared memory

GET /memory/shared

Retrieves a value from a shared namespace by key.

Query param	Type	Required	Description
namespace_key	string	required	The namespace key.
key	string	required	The memory label to retrieve.

List all shared memories

GET /memories/shared

Returns all memories in a shared namespace, ordered by most recent. Expired memories are silently excluded.

Query param	Type	Required	Description
namespace_key	string	required	The namespace key.
limit	integer	optional	Max results. Default 50, max 200.

Error codes

All errors return a consistent shape with a success: false flag and a plain-language message.

Status	Meaning	Common cause
200	Success	Request completed, memory read or written.
201	Created	New account registered successfully.
400	Bad request	Missing or invalid body parameters.
401	Unauthorized	Missing or invalid API key.
402	Payment required	Credit balance is zero. Top up to continue.
404	Not found	Memory does not exist. Credit refunded.
429	Rate limited	Too many requests. Slow down and retry.
500	Server error	Something went wrong on our end. Try again shortly.

error shape

{
  "success": false,
  "error": "Insufficient credits"
}

Rate limits

Endpoint	Limit	Window
POST /register	10 requests	Per hour, per IP
POST /memory	60 requests	Per hour, per API key
GET /memory	120 requests	Per hour, per API key
GET /memories	120 requests	Per hour, per API key
GET /memory/search	120 requests	Per hour, per API key
DELETE /memory	60 requests	Per hour, per API key
POST /namespace	20 requests	Per hour, per API key
POST /memory/shared	60 requests	Per hour, per API key
GET /memory/shared	120 requests	Per hour, per API key
GET /memories/shared	120 requests	Per hour, per API key
GET /credits	120 requests	Per hour, per API key
Global fallback	60 requests	Per minute, per API key

Rate-limited requests return a 429 status. Credits are not deducted for rate-limited requests.

Code examples

Python

python

# pip install requests
import requests

API_KEY = "agentram_your_key_here"
BASE = "https://api.agentram.dev"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# Write a memory
requests.post(f"{BASE}/memory", json={
    "agent_id": "agent-01",
    "key": "user_language",
    "value": "French"
}, headers=HEADERS)

# Read it back
res = requests.get(f"{BASE}/memory",
    params={"agent_id": "agent-01", "key": "user_language"},
    headers=HEADERS)
print(res.json()["data"]["value"])  # → "French"

JavaScript / Node

javascript

const API_KEY = "agentram_your_key_here";
const BASE = "https://api.agentram.dev";
const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" };

// Write a memory
await fetch(`${BASE}/memory`, {
  method: "POST", headers,
  body: JSON.stringify({ agent_id: "agent-01", key: "tone", value: "formal" })
});

// Read it back
const res = await fetch(`${BASE}/memory?agent_id=agent-01&key=tone`, { headers });
const { data } = await res.json();
console.log(data.value); // → "formal"

Need help? Email hello@agentram.dev and we'll get back to you within one business day.