Documentation

Core API Guide (Memory Management)

Use these endpoints to manually manage a user's memory graph, bypassing the autonomous /chat routing engine.

1. Create a Memory

Manually insert a memory node into a user's graph.

Python

JavaScript

payload = {
    "content": "User prefers dark mode.",
    "metadata": {"tags": ["preferences", "ui"]}
}
response = requests.post(f"{API_URL}/memories", json=payload, headers=HEADERS)

const payload = {
  content: "User prefers dark mode.",
  metadata: { tags: ["preferences", "ui"] }
};
const response = await fetch(API_URL + '/memories', {
  method: 'POST',
  headers: HEADERS,
  body: JSON.stringify(payload)
});

2. List & Filter Memories

Retrieve a paginated list of memories, optionally filtered by metadata.

Python

JavaScript

# Fetch page 1, 20 items per page
response = requests.get(f"{API_URL}/memories?page=1&page_size=20", headers=HEADERS)

// Fetch page 1, 20 items per page
const response = await fetch(API_URL + '/memories?page=1&page_size=20', { headers: HEADERS });

3. Retrieve a Specific Memory

Python

JavaScript

response = requests.get(f"{API_URL}/memories/402", headers=HEADERS)

const response = await fetch(API_URL + '/memories/402', { headers: HEADERS });

4. Update a Memory

Python

JavaScript

update_payload = {"content": "User prefers dark mode and vim keybindings."}
response = requests.put(f"{API_URL}/memories/402", json=update_payload, headers=HEADERS)

const updatePayload = { content: "User prefers dark mode and vim keybindings." };
const response = await fetch(API_URL + '/memories/402', {
  method: 'PUT',
  headers: HEADERS,
  body: JSON.stringify(updatePayload)
});

5. Delete a Memory

Python

JavaScript

response = requests.delete(f"{API_URL}/memories/402", headers=HEADERS)

const response = await fetch(API_URL + '/memories/402', {
  method: 'DELETE',
  headers: HEADERS
});

6. Bulk Delete by Metadata

Python

JavaScript

bulk_payload = {"filters": {"tags": ["deprecated"]}}
# Tip: Pass ?dry_run=true in the URL to safely check the deletion count first
response = requests.delete(f"{API_URL}/memories/bulk", json=bulk_payload, headers=HEADERS)

const bulkPayload = { filters: { tags: ["deprecated"] } };
// Tip: Pass ?dry_run=true in the URL to safely check the deletion count first
const response = await fetch(API_URL + '/memories/bulk', {
  method: 'DELETE',
  headers: HEADERS,
  body: JSON.stringify(bulkPayload)
});