Recall API Docs

REST API for persistent AI agent memory. No SDK required — just fetch.

Core Concepts

Agent ID

A unique identifier for your AI agent. All memories are scoped to an agent. Use the same agentId across sessions for continuity.

Context ID

A logical grouping within an agent — like a customer ID, project name, or session ID. Memories in different contexts are isolated by default.

Importance

Critical memories never decay. Normal memories decay slowly based on access frequency. Ephemeral memories are meant to be short-lived.

Recall Score

A 0-1 score indicating how relevant a memory is to the search query. Higher = more relevant. Based on semantic similarity and recency.

POST/api/recall/memories

Store a Memory

Create a new memory for an agent in a given context.

Request

{
  "agentId": "support-bot",
  "contextId": "customer-42",
  "content": "User prefers email over phone. Had billing issue on March 3.",
  "importance": "normal",
  "metadata": { "source": "chat" }
}

Response

{
  "success": true,
  "memory": {
    "id": "a1b2c3...",
    "agentId": "support-bot",
    "contextId": "customer-42",
    "content": "User prefers email over phone...",
    "importance": "normal",
    "metadata": { "source": "chat" },
    "accessCount": 0,
    "createdAt": "2026-09-09T12:00:00Z"
  }
}

GET/api/recall/memories?agentId={agentId}

List Memories

Retrieve memories for an agent, optionally filtered by context.

Request

GET /api/recall/memories?agentId=support-bot&contextId=customer-42&limit=50

Response

{
  "success": true,
  "memories": [
    {
      "id": "a1b2c3...",
      "content": "User prefers email over phone...",
      "importance": "normal",
      "accessCount": 3,
      "createdAt": "2026-09-09T12:00:00Z"
    }
  ]
}

POST/api/recall/recall

Recall (Search)

Semantic search across agent memories. Returns ranked results by relevance.

Request

{
  "agentId": "support-bot",
  "contextId": "customer-42",
  "query": "What issues has this customer had?",
  "limit": 5
}

Response

{
  "success": true,
  "results": [
    {
      "id": "a1b2c3...",
      "content": "Had billing issue on March 3...",
      "score": 0.94,
      "importance": "normal"
    }
  ]
}

POST/api/recall/summarize

Summarize Context

Compress all memories in a context into a concise summary. Reduces token costs by up to 90%.

Request

{
  "agentId": "support-bot",
  "contextId": "customer-42",
  "maxMemories": 100
}

Response

{
  "success": true,
  "summary": "Customer prefers email communication. Had billing issue resolved on March 3. Generally satisfied with service.",
  "memoryCount": 47,
  "tokenEstimate": 24
}

POST/api/recall/forget

Forget Memories

Delete specific memories, all memories in a context, or memories older than a date.

Request

{
  "agentId": "support-bot",
  "memoryIds": ["a1b2c3..."]
}

// Or delete by context:
{
  "agentId": "support-bot",
  "contextId": "customer-42"
}

// Or delete old ephemeral memories:
{
  "agentId": "support-bot",
  "importance": "ephemeral",
  "olderThan": "2026-06-01T00:00:00Z"
}

Response

{
  "success": true,
  "deleted": 3
}

GET/api/recall/stats?agentId={agentId}

Get Stats

Memory statistics for an agent: total count, context count, importance breakdown, token estimates.

Request

GET /api/recall/stats?agentId=support-bot

Response

{
  "success": true,
  "stats": {
    "totalMemories": 1247,
    "uniqueContexts": 89,
    "importanceBreakdown": {
      "critical": 12,
      "normal": 1100,
      "ephemeral": 135
    },
    "recentMemories": 23,
    "summaryCount": 15,
    "estimatedTokens": 48000
  }
}

Quick Start

// 1. Store a memory
await fetch("/api/recall/memories", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    agentId: "my-agent",
    contextId: "user-123",
    content: "User prefers dark mode and compact layouts",
  }),
});

// 2. Recall it later
const { results } = await fetch("/api/recall/recall", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    agentId: "my-agent",
    contextId: "user-123",
    query: "What are this user's UI preferences?",
  }),
}).then((r) => r.json());

// results[0].content === "User prefers dark mode..."
// results[0].score === 0.94

Open the Dashboard