API Documentation

// POST https://api.retainr.dev/v1/memories
{
  "content": "Customer prefers email over phone calls and is on a budget",
  "namespace": "customer:alice",
  "tags": ["preference", "contact-method"]
}

// POST https://api.retainr.dev/v1/memories/search
{
  "query": "how should I contact this customer?",
  "namespace": "customer:alice",
  "limit": 5
}

// Response
{
  "results": [
    {
      "id": "mem_8xKp2...",
      "content": "Customer prefers email over phone calls and is on a budget",
      "score": 0.94,
      "namespace": "customer:alice",
      "tags": ["preference", "contact-method"],
      "created_at": "2026-03-10T09:00:00Z"
    }
  ],
  "total": 1
}

Request body

Example request

{
  "content": "Customer opened a refund ticket for order #8821. Issue: wrong size delivered.",
  "namespace": "customer:acme",
  "tags": ["support", "refund", "order-issue"],
  "ttl_seconds": 2592000,
  "dedup_threshold": 0.92
}

Response - 201 Created (new) / 200 OK (deduplicated)

{
  "id": "mem_8xKp2mQ4nR...",
  "workspace_id": "ws_01JK...",
  "namespace": "customer:acme",
  "ttl_at": "2026-04-10T09:00:00Z",
  "created_at": "2026-03-10T09:00:00Z",
  "deduplicated": false
}

Request body

Example request

{
  "query": "how should I approach this customer?",
  "namespace": "customer:acme",
  "limit": 3,
  "tags": ["preference"]
}

Response - 200 OK

{
  "results": [
    {
      "id": "mem_8xKp2mQ4nR...",
      "content": "Customer prefers email over phone calls and is on a budget",
      "score": 0.94,
      "namespace": "customer:acme",
      "tags": ["preference", "contact-method"],
      "metadata": {},
      "created_at": "2026-03-10T09:00:00Z"
    },
    {
      "id": "mem_3fLm9nB2kS...",
      "content": "Customer prefers concise replies — skip long explanations",
      "score": 0.87,
      "namespace": "customer:acme",
      "tags": ["preference"],
      "metadata": {},
      "created_at": "2026-03-09T14:22:00Z"
    }
  ],
  "total": 2
}

Query parameters

Response - 200 OK

{
  "memories": [
    {
      "id": "mem_8xKp2mQ4nR...",
      "content": "Customer is price-sensitive, prefers email",
      "namespace": "customer:acme",
      "tags": ["preference"],
      "metadata": {},
      "created_at": "2026-03-10T09:00:00Z"
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Request body

Example request

{
  "query": "How should I greet this customer?",
  "namespace": "customer:acme",
  "limit": 5,
  "format": "system_prompt"
}

Response - 200 OK

{
  "context": "User context (3 memories):\n- Customer is price-sensitive, prefers email over phone calls (4 days ago)\n- Opened refund ticket for order #8821 (2 days ago)\n- Resolved: issued full refund (1 day ago)",
  "memories_used": 3,
  "token_estimate": 48
}

Example request

# Download full workspace export
curl https://api.retainr.dev/v1/memories/export \
  -H "Authorization: Bearer rec_live_..." \
  -o memories.jsonl

# Export only a specific namespace
curl "https://api.retainr.dev/v1/memories/export?namespace=customer:acme" \
  -H "Authorization: Bearer rec_live_..." \
  -o acme_memories.jsonl

Response format (JSONL)

{"id":"mem_8xKp2...","content":"Customer prefers email","namespace":"customer:acme","tags":["preference"],"created_at":"2026-03-10T09:00:00Z"}
{"id":"mem_3fLm9...","content":"Opened refund ticket for order #8821","namespace":"customer:acme","tags":["support"],"created_at":"2026-03-08T14:22:00Z"}

Request body

Example - delete all memories for a namespace (GDPR erasure)

{
  "namespace": "customer:acme"
}

Response - 200 OK

{
  "deleted": 14
}

n8n

Install the official retainr community node. In n8n, go to Settings - Community Nodes - Install and enter n8n-nodes-retainr. Available operations: Store Memory, Search Memory, Delete Memory.

// n8n - Store Memory node (JSON body)
{
  "content": "{{ $json.message }}",
  "namespace": "user:{{ $json.userId }}",
  "tags": ["{{ $json.intent }}"]
}

// n8n - Search Memory node (before your AI Call node)
{
  "query": "{{ $json.userMessage }}",
  "namespace": "user:{{ $json.userId }}",
  "limit": 5
}
// Output: $json.memories - inject into your system prompt

Make.com

The native Make.com app is submitted for marketplace review. Install it from the Make.com app directory: search for retainr. Available modules: Store Memory, Search Memory, List Memories, Delete Memories.

// Make.com — Store Memory module
Content: {{1.message}}
Namespace: customer:{{1.userId}}

// Make.com — Search Memory module (before your AI module)
Query: {{1.userMessage}}
Namespace: customer:{{1.userId}}
Max Results: 5
// Output: bundle of memory items — map content into your AI system prompt

Until the marketplace listing is live, use Make.com's HTTP module to call the REST API directly — set the URL to https://api.retainr.dev/v1/memories with Authorization: Bearer rec_live_....