Store memories

This guide shows how to send information to Alvia with POST /v1/memories. To send a whole chat, see Import conversations.

For endpoint schemas and status codes, use the API reference.

Send a passage

By default, Alvia reads content as a passage and forms one memory from each durable fact in it. Send text as your application receives it: a note, a message or a summary of a step.

curl https://api.alvia.ai/v1/memories \
  -H "Authorization: Bearer $ALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Dana Reyes leads the Atlas migration. The team agreed to freeze schema changes until the cutover on October 6.",
    "occurred_at": "2026-09-28T16:30:00-04:00",
    "scope": { "organization_id": "acme", "application_id": "eng-assistant" }
  }'

1
import os
2
import requests
3

4
API_KEY = os.environ["ALVIA_API_KEY"]
5

6
response = requests.post(
7
    "https://api.alvia.ai/v1/memories",
8
    headers={"Authorization": f"Bearer {API_KEY}"},
9
    json={
10
        "content": (
11
            "Dana Reyes leads the Atlas migration. The team agreed "
12
            "to freeze schema changes until the cutover on October 6."
13
        ),
14
        "occurred_at": "2026-09-28T16:30:00-04:00",
15
        "scope": {
16
            "organization_id": "acme",
17
            "application_id": "eng-assistant",
18
        },
19
    },
20
    timeout=30,
21
)
22
response.raise_for_status()  # 202 Accepted, empty body

1
const response = await fetch("https://api.alvia.ai/v1/memories", {
2
  method: "POST",
3
  headers: {
4
    Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
5
    "Content-Type": "application/json",
6
  },
7
  body: JSON.stringify({
8
    content:
9
      "Dana Reyes leads the Atlas migration. The team agreed " +
10
      "to freeze schema changes until the cutover on October 6.",
11
    occurred_at: "2026-09-28T16:30:00-04:00",
12
    scope: {
13
      organization_id: "acme",
14
      application_id: "eng-assistant",
15
    },
16
  }),
17
});
18
// 202 Accepted, empty body
19
if (!response.ok) {
20
  throw new Error(`${response.status}: ${await response.text()}`);
21
}

1
package main
2

3
import (
4
  "bytes"
5
  "encoding/json"
6
  "io"
7
  "log"
8
  "net/http"
9
  "os"
10
  "time"
11
)
12

13
func main() {
14
  payload, err := json.Marshal(map[string]any{
15
    "content": "Dana Reyes leads the Atlas migration. The team " +
16
      "agreed to freeze schema changes until the cutover " +
17
      "on October 6.",
18
    "occurred_at": "2026-09-28T16:30:00-04:00",
19
    "scope": map[string]string{
20
      "organization_id": "acme",
21
      "application_id":  "eng-assistant",
22
    },
23
  })
24
  if err != nil {
25
    log.Fatal(err)
26
  }
27
  req, err := http.NewRequest(http.MethodPost,
28
    "https://api.alvia.ai/v1/memories", bytes.NewReader(payload))
29
  if err != nil {
30
    log.Fatal(err)
31
  }
32
  key := os.Getenv("ALVIA_API_KEY")
33
  req.Header.Set("Authorization", "Bearer "+key)
34
  req.Header.Set("Content-Type", "application/json")
35

36
  client := &http.Client{Timeout: 30 * time.Second}
37
  resp, err := client.Do(req)
38
  if err != nil {
39
    log.Fatal(err)
40
  }
41
  defer resp.Body.Close()
42
  // 202 Accepted, empty body
43
  if resp.StatusCode != http.StatusAccepted {
44
    body, _ := io.ReadAll(resp.Body)
45
    log.Fatalf("%s: %s", resp.Status, body)
46
  }
47
}

1
using System.Net.Http.Json;
2

3
var key = Environment.GetEnvironmentVariable("ALVIA_API_KEY");
4
using var http = new HttpClient();
5
http.Timeout = TimeSpan.FromSeconds(30);
6
http.DefaultRequestHeaders.Authorization = new("Bearer", key);
7

8
var response = await http.PostAsJsonAsync(
9
    "https://api.alvia.ai/v1/memories",
10
    new
11
    {
12
        content = "Dana Reyes leads the Atlas migration. The team "
13
            + "agreed to freeze schema changes until the cutover "
14
            + "on October 6.",
15
        occurred_at = "2026-09-28T16:30:00-04:00",
16
        scope = new
17
        {
18
            organization_id = "acme",
19
            application_id = "eng-assistant",
20
        },
21
    });
22
response.EnsureSuccessStatusCode(); // 202 Accepted, empty body

In this example the passage forms two memories: who leads the migration, and the schema freeze.

Send one statement as one memory

Set infer to false to store content as a single memory. Use it when your text is already one fact, such as a value from a form or a record you have already summarized.

{
  "content": "Acme's billing contact is ap@acme.example.",
  "infer": false,
  "scope": { "organization_id": "acme" }
}

With infer: false, content can be at most 1,000 characters. Alvia normalizes the wording and adds resolved dates.

Decide what should become memory

Set the project’s memory policy before you send information that could hold sensitive facts: its keyword and meaning exclusions keep matching facts from becoming memory. See Filter memories and Memory policies.

Send older information with its original occurred_at, so it is ranked by its real age. See Point-in-Time Reasoning and change over time.

Request fields

Field	Required	Description
`content`	Yes	The text: 1 to 32,000 characters, with at least one letter or digit. At most 1,000 when `infer` is `false`.
`infer`	No	`true` (default) forms a memory from each fact in the text. `false` stores the text as one memory.
`occurred_at`	No	When the text was stated or observed, as an ISO 8601 date-time. Defaults to now. See Point-in-Time Reasoning and change over time.
`scope`	No	Who or what the memory is about. See Projects and scope.

Send only these fields: an unknown field returns 400 validation_error.

Response

A successful write returns 202 with an empty body. Formation runs after the response and forms one memory from each durable fact. Formation finishes in less than a minute, so find the memories with search, recall or list shortly after the write. See Read memories.

Cost

Each write uses your plan’s monthly write allowance:

A write with infer: false uses one write.
A passage uses one write, plus one write for each fact that formation takes from it.

Alvia accepts writes up to your plan’s monthly write allowance, which resets each month. At the stored-memory limit, writes return 409. See Limits and allowances.

Retries

Retry only requests that failed: network errors, 5xx responses and 429 responses, after the wait in Retry-After. A 202 means Alvia accepted the write, so do not send it again. When you retry, send the same content and occurred_at. Each accepted request uses writes.

A 429 with monthly_write_quota_reached succeeds only after the allowance resets. See Production checklist.
Do not retry a 400. Fix the request first.

Errors

Error	Cause
`400` `validation_error`	A field is missing, too long or unknown. `errors` names each field.
`400` `invalid_argument` `occurred_at_in_future`	`occurred_at` is in the future.
`400` `invalid_argument` `occurred_at_too_old`	`occurred_at` is before 1970.
`401` `unauthorized`	The API key is missing or not valid.
`404` `not_found`	The project’s deletion started while the request was in progress.
`409` `conflict` `memory_limit_reached`	The account holds its plan’s stored-memory limit.
`429` `rate_limit_exceeded`	Too many requests per second.
`429` `rate_limit_exceeded` `monthly_write_quota_reached`	The monthly write allowance is used up.

See Errors for every code.