Auld

Docs Memory API

Quickstart

Send a fact, send the fact that replaces it, wait for processing, and recall as one identity. Four calls, using curl.

#Before you start

You need a project key and the host for your project. Keys are created per project; see authentication.

Environment
export AULD_API_BASE="https://YOUR-AULD-HOST"   # your project's endpoint
export AULD_API_KEY="sk_live_…"                 # a project secret key

#1. Send the fact at its original time

Use the time the fact was true, not the time you are sending it. That is what lets later facts supersede earlier ones correctly.

Request
curl -X POST "$AULD_API_BASE/v1/records" \
  -H "Authorization: Bearer $AULD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "email-0603",
    "title": "Kickoff email",
    "text": "Halden Outdoor will renew on 1 October 2026 with a 40k budget.",
    "occurredAt": "2026-06-03T09:00:00Z",
    "author": "user_ruth",
    "visibility": "audience:account-team"
  }'

#2. Send the fact that supersedes it

Request
curl -X POST "$AULD_API_BASE/v1/records" \
  -H "Authorization: Bearer $AULD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "crm-4471",
    "title": "Renewal call notes",
    "text": "Renewal moved to 1 November. Budget is now 32k.",
    "occurredAt": "2026-09-12T15:30:00Z",
    "author": "user_ruth",
    "visibility": "audience:account-team"
  }'
202 Accepted
{ "jobId": "job_01J9Z6…", "sourceId": "crm-4471", "state": "queued" }

#3. Poll the job until it completes

Ingestion is asynchronous. Poll with a short backoff (for example 0.5 s, 1 s, 2 s) until state is completed or failed.

Request
curl "$AULD_API_BASE/v1/jobs/job_01J9Z6…" \
  -H "Authorization: Bearer $AULD_API_KEY"
200 OK
{ "jobId": "job_01J9Z6…", "state": "completed",
  "memories": { "created": 1, "superseded": 2, "unchanged": 0 } }

#4. Recall as one identity

The viewer must be allowed to see the records. Here user_ruth is a member of account-team.

Request
curl -X POST "$AULD_API_BASE/v1/recall" \
  -H "Authorization: Bearer $AULD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "When does Halden renew and for how much?", "viewer": "user_ruth", "maxTokens": 1500 }'
200 OK
{
  "memories": [
    {
      "id": "mem_7Q2…",
      "text": "Halden Outdoor's renewal starts on 1 November 2026.",
      "state": "current",
      "validFrom": "2026-09-12T15:30:00Z",
      "validTo": null,
      "visibility": "audience:account-team",
      "sources": [{ "sourceId": "crm-4471", "title": "Renewal call notes",
                    "occurredAt": "2026-09-12T15:30:00Z",
                    "excerpt": "wants the renewal moved to 1 November" }],
      "history": [{ "text": "Renewal starts on 1 October 2026.", "validFrom": "2026-06-03T09:00:00Z",
                    "validTo": "2026-09-12T15:30:00Z", "sourceId": "email-0603" }]
    }
  ],
  "tokens": 214,
  "truncated": false
}

Illustrative interface example · replace the host and key placeholders

#What just happened

  • The second record superseded the renewal date and the budget; both earlier values are kept under history.
  • Each memory names the record it came from, so your agent can cite “Renewal call notes, 12 Sep”.
  • A viewer outside account-team would receive project-visible memory only — none here.

Next: set up a production integration.