agent-memory

🧠 Memory API Reference

Persistent, semantic memory for AI agents. Store memories with types and metadata, then retrieve them with semantic search or direct lookup.

🔑 Base URL: https://api.agenttool.dev · All endpoints require Authorization: Bearer YOUR_API_KEY

POST /v1/memories

Store a new memory. Embeddings are generated automatically for semantic search.

🔒 Bearer token required

Request Body

Field	Type	Required	Description
type	string	required	One of: `episodic`, `semantic`, `procedural`, `working`
content	string	required	The memory text. 1–100,000 characters.
key	string \| null	optional	Namespace key for grouping memories (e.g. `"user-prefs"`).
agent_id	string \| null	optional	ID of the agent creating this memory.
metadata	object	optional	Arbitrary key-value pairs for filtering and context.
importance	number	optional	0.0–1.0, default `0.5`. Higher = more important in search ranking.
ttl_seconds	integer \| null	optional	Auto-delete after N seconds. `null` = no expiry.

curl

curl -X POST https://api.agenttool.dev/v1/memories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "semantic",
    "content": "User prefers concise replies. Timezone: UTC+8.",
    "key": "user-prefs",
    "agent_id": "agent-42",
    "metadata": {"source": "onboarding"},
    "importance": 0.8
  }'

SDK

await at.memory.store("User prefers concise replies", {
  type: "semantic",
  key: "user-prefs",
  agentId: "agent-42",
  importance: 0.8
})

Response · 201

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-03-09T12:00:00Z"
}

422 · Validation Error

Returned when type doesn't match the allowed pattern or content is empty. Check that type is one of: episodic, semantic, procedural, working.

POST /v1/memories/search

Semantic search across stored memories. Returns results ranked by similarity score. No exact keyword matching needed — the API understands meaning.

🔒 Bearer token required

Request Body

Field	Type	Required	Description
query	string	required	Natural language query. Minimum 1 character.
type	string \| null	optional	Filter by memory type.
agent_id	string \| null	optional	Filter to a specific agent's memories.
limit	integer	optional	Max results, 1–100. Default: `10`.
min_score	number	optional	Minimum similarity score, 0.0–1.0. Default: `0`.

curl

curl -X POST https://api.agenttool.dev/v1/memories/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does the user like to communicate?",
    "limit": 5,
    "min_score": 0.7
  }'

SDK

const results = await at.memory.search("communication style", {
  limit: 5,
  minScore: 0.7
})

Response · 200

JSON

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "semantic",
    "key": "user-prefs",
    "content": "User prefers concise replies. Timezone: UTC+8.",
    "agent_id": "agent-42",
    "metadata": { "source": "onboarding" },
    "importance": 0.8,
    "created_at": "2026-03-09T12:00:00Z",
    "accessed_at": "2026-03-09T14:30:00Z",
    "score": 0.97
  }
]

GET /v1/memories/{memory_id}

Retrieve a single memory by its UUID. Updates the accessed_at timestamp.

🔒 Bearer token required

Path Parameters

Field	Type	Required	Description
memory_id	uuid	required	The memory's UUID, returned from create or search.

curl

curl https://api.agenttool.dev/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

const mem = await at.memory.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

Response · 200

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "semantic",
  "key": "user-prefs",
  "content": "User prefers concise replies. Timezone: UTC+8.",
  "agent_id": "agent-42",
  "metadata": { "source": "onboarding" },
  "importance": 0.8,
  "created_at": "2026-03-09T12:00:00Z",
  "accessed_at": "2026-03-09T15:00:00Z"
}

404 · Not Found

No memory with that ID exists. Check the UUID — it's returned from POST /v1/memories or search results.

GET /v1/memories?key={key}

Retrieve all memories with a given key. Useful for loading a namespace of related memories.

🔒 Bearer token required

Query Parameters

Field	Type	Required	Description
key	string	required	The namespace key to look up.
agent_id	string	optional	Filter by agent ID within the key.

curl

curl "https://api.agenttool.dev/v1/memories?key=user-prefs&agent_id=agent-42" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

const mems = await at.memory.list({ key: "user-prefs", agentId: "agent-42" })

Response · 200

JSON — array of MemoryOut objects

[
  {
    "id": "a1b2c3d4-...",
    "type": "semantic",
    "key": "user-prefs",
    "content": "User prefers concise replies...",
    "agent_id": "agent-42",
    "metadata": {},
    "importance": 0.5,
    "created_at": "2026-03-09T12:00:00Z",
    "accessed_at": null
  }
]

DELETE /v1/memories/{memory_id}

Delete a single memory by its UUID. Permanent — cannot be undone.

🔒 Bearer token required

Path Parameters

Field	Type	Required	Description
memory_id	uuid	required	The memory's UUID.

curl

curl -X DELETE https://api.agenttool.dev/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

await at.memory.delete("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

Response · 200

JSON

{ "deleted": 1 }

DELETE /v1/memories?key={key}

Delete all memories with a given key. Use with caution — this is a bulk delete.

🔒 Bearer token required

Query Parameters

Field	Type	Required	Description
key	string	required	All memories with this key will be permanently deleted.

curl

curl -X DELETE "https://api.agenttool.dev/v1/memories?key=user-prefs" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

await at.memory.deleteByKey("user-prefs")

Response · 200

JSON

{ "deleted": 7 }

GET /v1/usage

Get usage statistics for the current project. Shows reads, writes, searches, total memories, and current plan.

🔒 Bearer token required

curl

curl https://api.agenttool.dev/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

const usage = await at.memory.usage()

Response · 200

JSON

{
  "writes": 1247,
  "reads": 3891,
  "searches": 562,
  "total_memories": 842,
  "plan": "builder"
}

Memory Types

Memories are categorized by cognitive type, inspired by human memory systems:

Type	Use for	Example
`episodic`	Events and experiences	"User asked about pricing on March 9th"
`semantic`	Facts and knowledge	"User's timezone is UTC+8"
`procedural`	How-to knowledge	"To deploy, run `npm run deploy`"
`working`	Temporary/session context	"Currently debugging the auth flow"

💡 Tip: Use working with ttl_seconds for context that should auto-expire when a session ends.

Error Reference

401 · Unauthorized

Missing or invalid API key. Ensure Authorization: Bearer YOUR_API_KEY is set.

404 · Not Found

Memory ID doesn't exist or belongs to a different project.

422 · Validation Error

Request body is invalid. The response includes a detail array with the exact field and error message. Common causes: missing type or content, invalid type value, importance outside 0–1 range.

429 · Rate Limited

You've exceeded your plan's request limit. Upgrade your plan or wait until the next billing cycle.