Backboard API home pagelight logo
  1. Core Concepts
  2. Memory

Memory enables assistants to remember facts, preferences, and context across conversations and threads.

​
How It Works

  1. Extraction — automatically extracts key facts from conversations
  2. Storage — stores them in a semantic knowledge base
  3. Retrieval — retrieves relevant memories for future messages
  4. Cross-thread — works across all threads for the same assistant

​
Memory Modes

Set on each message via the memory or memory_pro parameter:

ParameterValueSaves?Retrieves?Description
memory"Auto"YesYesMemory Lite — recommended default
memory"Readonly"NoYesOnly retrieves, never writes
memory"off"NoNoDisabled (default)
memory_pro"Auto"YesYesMemory Pro — higher accuracy, higher cost
memory_pro"Readonly"NoYesPro retrieval only

memory and memory_pro cannot be used together in the same message. Pick one.

​
Example

import requests

headers = {"X-API-Key": "YOUR_API_KEY"}
thread_id = "your-thread-id"

response = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers=headers,
    json={
        "thread_id": thread_id,
        "content": "I prefer Python over JavaScript for backend work",
        "stream": False,
        "memory": "Auto"
    }
)
print(response.json()["content"])

In a later thread with the same assistant, that preference is automatically recalled.

​
Managing Memories

​
List Memories

Supports pagination with page (1-indexed) and page_size (1–100, default 25). Omit page to fetch all.

memories = requests.get(
    f"https://app.backboard.io/api/assistants/{assistant_id}/memories",
    headers=headers,
    params={"page": 1, "page_size": 25}
).json()

for m in memories["memories"]:
    print(m["content"])
print(f"Total: {memories['total_count']}, Page: {memories.get('page')}/{memories.get('total_pages')}")

​
Add a Memory

response = requests.post(
    f"https://app.backboard.io/api/assistants/{assistant_id}/memories",
    headers=headers,
    json={
        "content": "User is a senior software engineer with 10 years of experience",
        "metadata": {"source": "manual", "confidence": "high"}
    }
)
print(response.json()["memory_id"])

​
Search Memories

Semantic search across an assistant’s memories. Returns results ranked by relevance.

results = requests.post(
    f"https://app.backboard.io/api/assistants/{assistant_id}/memories/search",
    headers=headers,
    json={"query": "programming language preferences", "limit": 5}
).json()

for m in results["memories"]:
    print(f"[{m.get('score', 0):.2f}] {m['content']}")

​
Get, Update & Delete a Memory

# Get
memory = requests.get(
    f"https://app.backboard.io/api/assistants/{assistant_id}/memories/{memory_id}",
    headers=headers
).json()

# Update
requests.put(
    f"https://app.backboard.io/api/assistants/{assistant_id}/memories/{memory_id}",
    headers=headers,
    json={"content": "User is a staff engineer with 12 years of experience"}
)

# Delete
requests.delete(
    f"https://app.backboard.io/api/assistants/{assistant_id}/memories/{memory_id}",
    headers=headers
)

​
Operation Status

Memory operations can be asynchronous. The message response includes a memory_operation_id when memory is active. Poll it to check completion:

op = requests.get(
    f"https://app.backboard.io/api/assistants/memories/operations/{operation_id}",
    headers=headers
).json()
print(op["status"])  # "COMPLETED", "IN_PROGRESS", or "ERROR"

​
Related Endpoints