Quickstart

Install the SDK, store your first memory, and query it back with citations — in five minutes.

SDKs ship Saturday, May 9, 2026. The pip install aurra and npm install aurra commands below will work after that. Until then, use the cURL examples — they hit the same API.

1. Get an API key

Sign up at app.aurra.us and open your dashboard. In the API Keys section, click Create key and copy the value (it starts with aurra_).

You only see the full key once. Store it somewhere safe — environment variable, secret manager, password manager.

export AURRA_API_KEY="aurra_your_key_here"

2. Install the SDK

pip install aurra

Requires Python 3.8+. Source: aurra on PyPI.

npm install aurra

Works in Node 18+ and modern browsers. TypeScript types included. Source: aurra on npm.

No install needed — just curl and a key.

3. Store your first memory

Aurra extracts durable facts from raw conversation. Send a messages array; Aurra figures out what is worth remembering.

from aurra import Aurra

client = Aurra(api_key="aurra_your_key_here")

result = client.memories.add(
    messages=[
        {"role": "user", "content": "Hi, I am Alice. I am a senior engineer at Acme."},
        {"role": "assistant", "content": "Nice to meet you, Alice."},
    ],
    session_id="alice-session-1",
)

print(result)

import { Aurra } from "aurra";

const client = new Aurra({ apiKey: "aurra_your_key_here" });

const result = await client.memories.add({
  messages: [
    { role: "user", content: "Hi, I am Alice. I am a senior engineer at Acme." },
    { role: "assistant", content: "Nice to meet you, Alice." },
  ],
  sessionId: "alice-session-1",
});

console.log(result);

curl -X POST https://api.aurra.us/agent/memories \
  -H "Authorization: Bearer $AURRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hi, I am Alice. I am a senior engineer at Acme."},
      {"role": "assistant", "content": "Nice to meet you, Alice."}
    ],
    "session_id": "alice-session-1"
  }'

You will get back something like:

{
  "status": "saved",
  "memory_ids": ["mem_abc123", "mem_def456"],
  "extracted": [
    "Alice is a senior engineer at Acme",
    "User name is Alice"
  ]
}

Aurra extracted two atomic facts from that exchange. Each gets its own memory ID, timestamp, and source provenance.

4. Query with citations

Now ask Aurra a question. It will retrieve relevant memories and return an answer that cites which memories it used.

result = client.agent.query(
    question="Where does Alice work?",
)

print(result["answer"])
print(result["answer_with_citations"])
print(result["citations"])

const result = await client.agent.query({
  question: "Where does Alice work?",
});

console.log(result.answer);
console.log(result.answerWithCitations);
console.log(result.citations);

curl -X POST https://api.aurra.us/agent/query \
  -H "Authorization: Bearer $AURRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Where does Alice work?"
  }'

Response shape:

{
  "answer": "Alice works at Acme.",
  "answer_with_citations": "Alice works at Acme [mem-1].",
  "citations": [
    {
      "index": 1,
      "memory_id": "mem_abc123",
      "content": "Alice is a senior engineer at Acme",
      "similarity": 0.89,
      "cited_by_llm": true,
      "valid_from": "2026-05-05T19:20:00Z",
      "is_superseded": false,
      "source": "agent"
    }
  ],
  "memories_searched": 2
}

The citations array gives you the exact memories the answer is grounded in — with similarity scores, validity windows, and a cited_by_llm flag indicating whether the model actually used each one.

5. Watch supersession in action

Aurra bi-temporal memory tracks when facts change over time. Send a contradicting fact:

client.memories.add(
    messages=[
        {"role": "user", "content": "Update: I just joined Globex as a staff engineer."},
    ],
    session_id="alice-session-1",
)

result = client.agent.query(
    question="Where does Alice work?",
)

print(result["answer"])

await client.memories.add({
  messages: [
    { role: "user", content: "Update: I just joined Globex as a staff engineer." },
  ],
  sessionId: "alice-session-1",
});

const result = await client.agent.query({
  question: "Where does Alice work?",
});

console.log(result.answer);

curl -X POST https://api.aurra.us/agent/memories \
  -H "Authorization: Bearer $AURRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Update: I just joined Globex as a staff engineer."}
    ],
    "session_id": "alice-session-1"
  }'

curl -X POST https://api.aurra.us/agent/query \
  -H "Authorization: Bearer $AURRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Where does Alice work?"
  }'

The new query returns "Alice works at Globex" — but the old memory is not deleted. Inspect the timeline:

curl https://api.aurra.us/memories/mem_abc123/timeline \
  -H "Authorization: Bearer $AURRA_API_KEY"

You will see both facts, with valid_from / valid_to timestamps showing when the supersession happened. Full audit trail. No data loss.

What is next

API Reference

Every endpoint, request shape, and error code.

Citation-Grounded Query

Deep dive on how citations work and when to use cited_by_llm.

Source-Filtered Retrieval

Restrict retrieval to specific sources at query time.

Bi-temporal Memory

The full supersession + audit story.

Troubleshooting

401 Unauthorized — Your API key is missing, malformed, or revoked. Check app.aurra.us/dashboard and confirm the key is active.

429 Too Many Requests — You are rate-limited on your current plan. See Pricing.

Empty extracted array — The conversation did not contain extractable facts (Aurra skips greetings, filler, etc.). This is correct behavior, not a bug.

Memory IDs differ from the docs — Memory IDs are unique per request. Use whatever memory_id your response contains, not the docs example values.