Read memories

This guide shows how to read memories with each of Alvia’s six read operations, and which one to use. Every read answers from what applies now.

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

Choose a read

You need	Operation	Endpoint
A short answer to put in a prompt or act on	Context	`POST /v1/memories/context`
The one memory that best matches, with its ID and details	Recall	`POST /v1/memories/recall`
Several candidate memories, ranked	Search	`POST /v1/memories/search`
A memory whose ID you already have	Get	`GET /v1/memories/{memory_id}`
A memory’s versions and relationships	Inspect	`GET /v1/memories/{memory_id}/inspect`
Every memory, for example to show or export them	List	`GET /v1/memories`

Request fields

Context, recall and search take the same request body:

Field	Required	Description
`query`	Yes	The question, 1 to 1,000 characters.
`scope`	No	Limit the read to matching memories. See Projects and scope.
`occurred_after`	No	Only memories from this time on. See Point-in-Time Reasoning and change over time.
`occurred_before`	No	Only memories from before this time.
`limit`	No	Search only: how many results, 1 to 50. Defaults to 25. Values outside the range are clamped.

Write the query as the question your application needs answered, such as “What did Acme decide about the onboarding rollout?”.

Combine read filters

Use scope for the user, agent or application whose memories you need. Scope fields narrow the result together. Add occurred_after and occurred_before only when the date range is part of the question; see Filter by date for what they include.

Get context

Context finds the memory that best matches the query and resolves it with its related and contradicting memories into one to three sentences.

curl https://api.alvia.ai/v1/memories/context \
  -H "Authorization: Bearer $ALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did Acme decide about the rollout?",
    "scope": { "organization_id": "acme" }
  }'

1
import os
2
import requests
3

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

6

7
def get_context(query: str, scope: dict) -> str | None:
8
    """Returns the resolved context, or None when Alvia has none."""
9
    response = requests.post(
10
        "https://api.alvia.ai/v1/memories/context",
11
        headers={"Authorization": f"Bearer {API_KEY}"},
12
        json={"query": query, "scope": scope},
13
        timeout=30,
14
    )
15
    if response.status_code == 404:
16
        return None
17
    response.raise_for_status()
18
    return response.json()["context"]
19

20

21
scope = {"organization_id": "acme"}
22
print(get_context("What did Acme decide about the rollout?", scope))

1
/** Returns the resolved context, or null when Alvia has none. */
2
async function getContext(query, scope) {
3
  const response = await fetch(
4
    "https://api.alvia.ai/v1/memories/context",
5
    {
6
      method: "POST",
7
      headers: {
8
        Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
9
        "Content-Type": "application/json",
10
      },
11
      body: JSON.stringify({ query, scope }),
12
    },
13
  );
14
  if (response.status === 404) return null;
15
  if (!response.ok) {
16
    throw new Error(`${response.status}: ${await response.text()}`);
17
  }
18
  return (await response.json()).context;
19
}
20

21
const scope = { organization_id: "acme" };
22
console.log(
23
  await getContext("What did Acme decide about the rollout?", scope),
24
);

1
package main
2

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

14
var client = &http.Client{Timeout: 30 * time.Second}
15

16
// getContext returns the resolved context. found is false when Alvia
17
// has none.
18
func getContext(query string, scope map[string]string) (
19
  context string, found bool, err error,
20
) {
21
  payload, err := json.Marshal(map[string]any{
22
    "query": query,
23
    "scope": scope,
24
  })
25
  if err != nil {
26
    return "", false, err
27
  }
28
  req, err := http.NewRequest(http.MethodPost,
29
    "https://api.alvia.ai/v1/memories/context",
30
    bytes.NewReader(payload))
31
  if err != nil {
32
    return "", false, err
33
  }
34
  key := os.Getenv("ALVIA_API_KEY")
35
  req.Header.Set("Authorization", "Bearer "+key)
36
  req.Header.Set("Content-Type", "application/json")
37
  resp, err := client.Do(req)
38
  if err != nil {
39
    return "", false, err
40
  }
41
  defer resp.Body.Close()
42
  switch resp.StatusCode {
43
  case http.StatusNotFound:
44
    return "", false, nil
45
  case http.StatusOK:
46
    var answer struct {
47
      Context string `json:"context"`
48
    }
49
    err := json.NewDecoder(resp.Body).Decode(&answer)
50
    return answer.Context, err == nil, err
51
  default:
52
    body, _ := io.ReadAll(resp.Body)
53
    return "", false, fmt.Errorf("%s: %s", resp.Status, body)
54
  }
55
}
56

57
func main() {
58
  query := "What did Acme decide about the rollout?"
59
  scope := map[string]string{"organization_id": "acme"}
60
  answer, found, err := getContext(query, scope)
61
  if err != nil {
62
    log.Fatal(err)
63
  }
64
  if found {
65
    fmt.Println(answer)
66
  }
67
}

1
using System.Net;
2
using System.Net.Http.Json;
3
using System.Text.Json;
4

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

10
// Returns the resolved context, or null when Alvia has none.
11
async Task<string?> GetContext(string query, object scope)
12
{
13
    var response = await http.PostAsJsonAsync(
14
        "https://api.alvia.ai/v1/memories/context",
15
        new { query, scope });
16
    if (response.StatusCode == HttpStatusCode.NotFound) return null;
17
    response.EnsureSuccessStatusCode();
18
    var body = await response.Content
19
        .ReadFromJsonAsync<JsonElement>();
20
    return body.GetProperty("context").GetString();
21
}
22

23
var scope = new { organization_id = "acme" };
24
Console.WriteLine(await GetContext(
25
    "What did Acme decide about the rollout?", scope));

{
  "context": "Acme replaced its company-wide launch with a finance-team pilot on September 24, 2026. The wider rollout waits until its security review is complete."
}

When Alvia has no context for the question right now, the response is 404 with code not_found: for example, no memory matches the query. Treat it as “no context for now”: answer without it, or ask the user. Each call looks again, so a later call can return context. If context returns 404 on every call, check the scope and that memories have formed.

When context cannot finish its answer in time, it returns 503 with code capacity_exceeded. Answer without context while a user waits, or retry after Retry-After.

Alvia writes the answer from the current text of the best match and of the memories linked to it, with the date each was stated. Use the answer as context for your model or your logic, and keep the decision in your application. A new version or a forget of a memory the answer used shows in the next answer.

Recall the best memory

Recall returns the single best memory, with its ID, so you can show it, give feedback on it or forget it.

curl https://api.alvia.ai/v1/memories/recall \
  -H "Authorization: Bearer $ALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Where should invoices go?",
    "scope": { "organization_id": "acme" }
  }'

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/recall",
8
    headers={"Authorization": f"Bearer {API_KEY}"},
9
    json={
10
        "query": "Where should invoices go?",
11
        "scope": {"organization_id": "acme"},
12
    },
13
    timeout=30,
14
)
15
response.raise_for_status()
16
memory = response.json()
17
if memory["status"] == "active":
18
    print(memory["memory_id"], memory["content"])

1
const response = await fetch(
2
  "https://api.alvia.ai/v1/memories/recall",
3
  {
4
    method: "POST",
5
    headers: {
6
      Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
7
      "Content-Type": "application/json",
8
    },
9
    body: JSON.stringify({
10
      query: "Where should invoices go?",
11
      scope: { organization_id: "acme" },
12
    }),
13
    signal: AbortSignal.timeout(30_000),
14
  },
15
);
16
if (!response.ok) {
17
  throw new Error(`${response.status}: ${await response.text()}`);
18
}
19
const memory = await response.json();
20
if (memory.status === "active") {
21
  console.log(memory.memory_id, memory.content);
22
}

1
package main
2

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

14
func main() {
15
  req, err := http.NewRequest(http.MethodPost,
16
    "https://api.alvia.ai/v1/memories/recall",
17
    strings.NewReader(`{
18
  "query": "Where should invoices go?",
19
  "scope": { "organization_id": "acme" }
20
}`))
21
  if err != nil {
22
    log.Fatal(err)
23
  }
24
  req.Header.Set("Authorization",
25
    "Bearer "+os.Getenv("ALVIA_API_KEY"))
26
  req.Header.Set("Content-Type", "application/json")
27
  client := &http.Client{Timeout: 30 * time.Second}
28
  resp, err := client.Do(req)
29
  if err != nil {
30
    log.Fatal(err)
31
  }
32
  defer resp.Body.Close()
33
  if resp.StatusCode != http.StatusOK {
34
    body, _ := io.ReadAll(resp.Body)
35
    log.Fatalf("%s: %s", resp.Status, body)
36
  }
37
  var memory struct {
38
    Status   string `json:"status"`
39
    MemoryID string `json:"memory_id"`
40
    Content  string `json:"content"`
41
  }
42
  if err := json.NewDecoder(resp.Body).Decode(&memory); err != nil {
43
    log.Fatal(err)
44
  }
45
  if memory.Status == "active" {
46
    fmt.Println(memory.MemoryID, memory.Content)
47
  }
48
}

1
using System.Net.Http.Headers;
2
using System.Net.Http.Json;
3
using System.Text.Json;
4

5
using var http = new HttpClient
6
{
7
    Timeout = TimeSpan.FromSeconds(30),
8
};
9
http.DefaultRequestHeaders.Authorization =
10
    new AuthenticationHeaderValue("Bearer",
11
        Environment.GetEnvironmentVariable("ALVIA_API_KEY"));
12
using var response = await http.PostAsJsonAsync(
13
    "https://api.alvia.ai/v1/memories/recall", new
14
{
15
    query = "Where should invoices go?",
16
    scope = new { organization_id = "acme" },
17
});
18
response.EnsureSuccessStatusCode();
19
var memory = await response.Content
20
    .ReadFromJsonAsync<JsonElement>();
21
if (memory.GetProperty("status").GetString() == "active")
22
{
23
    var id = memory.GetProperty("memory_id");
24
    Console.WriteLine($"{id} {memory.GetProperty("content")}");
25
}

{
  "status": "active",
  "memory_id": "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P",
  "content": "Acme's invoices go to ap@acme.example.",
  "category": "preference",
  "is_favorited": false,
  "sentiment": "neutral",
  "occurred_at": "2026-10-02T11:15:00-07:00",
  "ranked_score": 0.8731,
  "scope": {
    "organization_id": "acme",
    "user_id": "u_4821",
    "application_id": null,
    "agent_id": null,
    "team_id": null
  },
  "entities": { "organization/Acme": 0.71, "identifier/ap@acme.example": 0.29 }
}

A recall miss returns 200 with status not_found, so a miss needs no error handling:

{ "status": "not_found" }

Check status to tell a match from a miss. On recall, 404 means the project’s deletion started during the call.

Search memories

Search returns up to limit memories, best first:

curl https://api.alvia.ai/v1/memories/search \
  -H "Authorization: Bearer $ALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Atlas migration plans", "limit": 5 }'

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/search",
8
    headers={"Authorization": f"Bearer {API_KEY}"},
9
    json={"query": "Atlas migration plans", "limit": 5},
10
    timeout=30,
11
)
12
response.raise_for_status()
13
print(response.json())

1
const response = await fetch(
2
  "https://api.alvia.ai/v1/memories/search",
3
  {
4
    method: "POST",
5
    headers: {
6
      Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
7
      "Content-Type": "application/json",
8
    },
9
    body: JSON.stringify({
10
      query: "Atlas migration plans",
11
      limit: 5,
12
    }),
13
    signal: AbortSignal.timeout(30_000),
14
  },
15
);
16
if (!response.ok) {
17
  throw new Error(`${response.status}: ${await response.text()}`);
18
}
19
console.log(await response.json());

1
package main
2

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

13
func main() {
14
  req, err := http.NewRequest(http.MethodPost,
15
    "https://api.alvia.ai/v1/memories/search",
16
    strings.NewReader(`{
17
  "query": "Atlas migration plans",
18
  "limit": 5
19
}`))
20
  if err != nil {
21
    log.Fatal(err)
22
  }
23
  req.Header.Set("Authorization",
24
    "Bearer "+os.Getenv("ALVIA_API_KEY"))
25
  req.Header.Set("Content-Type", "application/json")
26
  client := &http.Client{Timeout: 30 * time.Second}
27
  resp, err := client.Do(req)
28
  if err != nil {
29
    log.Fatal(err)
30
  }
31
  defer resp.Body.Close()
32
  data, err := io.ReadAll(resp.Body)
33
  if err != nil {
34
    log.Fatal(err)
35
  }
36
  if resp.StatusCode != http.StatusOK {
37
    log.Fatalf("%s: %s", resp.Status, data)
38
  }
39
  fmt.Println(string(data))
40
}

1
using System.Net.Http.Headers;
2
using System.Net.Http.Json;
3

4
using var http = new HttpClient
5
{
6
    Timeout = TimeSpan.FromSeconds(30),
7
};
8
http.DefaultRequestHeaders.Authorization =
9
    new AuthenticationHeaderValue("Bearer",
10
        Environment.GetEnvironmentVariable("ALVIA_API_KEY"));
11
using var response = await http.PostAsJsonAsync(
12
    "https://api.alvia.ai/v1/memories/search", new
13
{
14
    query = "Atlas migration plans",
15
    limit = 5,
16
});
17
response.EnsureSuccessStatusCode();
18
Console.WriteLine(await response.Content.ReadAsStringAsync());

{
  "object": "list",
  "data": [
    {
      "status": "active",
      "memory_id": "mem_01K6YB2C8D5E7F9G1H3J4K6M8N",
      "content": "The team froze Atlas schema changes until the cutover on October 6, 2026.",
      "category": "decision",
      "is_favorited": false,
      "sentiment": "neutral",
      "occurred_at": "2026-09-28T16:30:00-04:00",
      "ranked_score": 0.9112,
      "scope": {
        "organization_id": "acme",
        "user_id": null,
        "application_id": "eng-assistant",
        "agent_id": null,
        "team_id": null
      },
      "entities": { "project/Atlas": 0.64, "datetime/October 6, 2026": 0.36 }
    }
  ],
  "has_more": false,
  "url": "/v1/memories/search"
}

Search returns its best candidates ranked by ranked_score, with no minimum score, so it returns results even for a loose match. Compare ranked_score within one response and apply your own cut-off to keep the matches that fit your use. Search returns its results in one response, so has_more is false.

Get one memory

Get returns one active memory, in the same shape as recall but without ranked_score:

curl https://api.alvia.ai/v1/memories/mem_01K6Z1M4TB7D9E2F5G8H3J6K0P \
  -H "Authorization: Bearer $ALVIA_API_KEY"

1
import os
2
import requests
3

4
API_KEY = os.environ["ALVIA_API_KEY"]
5
memory_id = "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P"
6

7
response = requests.get(
8
    f"https://api.alvia.ai/v1/memories/{memory_id}",
9
    headers={"Authorization": f"Bearer {API_KEY}"},
10
    timeout=30,
11
)
12
response.raise_for_status()
13
print(response.json())

1
const memoryId = "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P";
2
const response = await fetch(
3
  `https://api.alvia.ai/v1/memories/${memoryId}`,
4
  {
5
    headers: {
6
      Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
7
    },
8
    signal: AbortSignal.timeout(30_000),
9
  },
10
);
11
if (!response.ok) {
12
  throw new Error(`${response.status}: ${await response.text()}`);
13
}
14
console.log(await response.json());

1
package main
2

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

12
func main() {
13
  memoryID := "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P"
14
  req, err := http.NewRequest(http.MethodGet,
15
    "https://api.alvia.ai/v1/memories/"+memoryID, nil)
16
  if err != nil {
17
    log.Fatal(err)
18
  }
19
  req.Header.Set("Authorization",
20
    "Bearer "+os.Getenv("ALVIA_API_KEY"))
21
  client := &http.Client{Timeout: 30 * time.Second}
22
  resp, err := client.Do(req)
23
  if err != nil {
24
    log.Fatal(err)
25
  }
26
  defer resp.Body.Close()
27
  data, err := io.ReadAll(resp.Body)
28
  if err != nil {
29
    log.Fatal(err)
30
  }
31
  if resp.StatusCode != http.StatusOK {
32
    log.Fatalf("%s: %s", resp.Status, data)
33
  }
34
  fmt.Println(string(data))
35
}

1
using System.Net.Http.Headers;
2
using System.Net.Http.Json;
3

4
using var http = new HttpClient
5
{
6
    Timeout = TimeSpan.FromSeconds(30),
7
};
8
http.DefaultRequestHeaders.Authorization =
9
    new AuthenticationHeaderValue("Bearer",
10
        Environment.GetEnvironmentVariable("ALVIA_API_KEY"));
11
using var response = await http.GetAsync(
12
    "https://api.alvia.ai" +
13
    "/v1/memories/mem_01K6Z1M4TB7D9E2F5G8H3J6K0P");
14
response.EnsureSuccessStatusCode();
15
Console.WriteLine(await response.Content.ReadAsStringAsync());

It returns 404 when the memory does not exist, was forgotten, is still forming or belongs to another project.

Inspect a memory

Inspect returns one active memory with its versions, how Alvia classified each one and why, and its relationships to other active memories. Use it to show how a memory changed and what it relates to. To read a memory’s current text, use get.

curl \
  https://api.alvia.ai/v1/memories/mem_01K6R8QJ2N4P6S8T0V2X4Z6B8D/inspect \
  -H "Authorization: Bearer $ALVIA_API_KEY"

1
import os
2
import requests
3

4
API_KEY = os.environ["ALVIA_API_KEY"]
5
memory_id = "mem_01K6R8QJ2N4P6S8T0V2X4Z6B8D"
6

7
response = requests.get(
8
    f"https://api.alvia.ai/v1/memories/{memory_id}/inspect",
9
    headers={"Authorization": f"Bearer {API_KEY}"},
10
    timeout=30,
11
)
12
response.raise_for_status()
13
print(response.json())

1
const memoryId = "mem_01K6R8QJ2N4P6S8T0V2X4Z6B8D";
2
const response = await fetch(
3
  `https://api.alvia.ai/v1/memories/${memoryId}/inspect`,
4
  {
5
    headers: {
6
      Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
7
    },
8
    signal: AbortSignal.timeout(30_000),
9
  },
10
);
11
if (!response.ok) {
12
  throw new Error(`${response.status}: ${await response.text()}`);
13
}
14
console.log(await response.json());

1
package main
2

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

12
func main() {
13
  memoryID := "mem_01K6R8QJ2N4P6S8T0V2X4Z6B8D"
14
  req, err := http.NewRequest(http.MethodGet,
15
    "https://api.alvia.ai/v1/memories/"+memoryID+"/inspect",
16
    nil)
17
  if err != nil {
18
    log.Fatal(err)
19
  }
20
  req.Header.Set("Authorization",
21
    "Bearer "+os.Getenv("ALVIA_API_KEY"))
22
  client := &http.Client{Timeout: 30 * time.Second}
23
  resp, err := client.Do(req)
24
  if err != nil {
25
    log.Fatal(err)
26
  }
27
  defer resp.Body.Close()
28
  data, err := io.ReadAll(resp.Body)
29
  if err != nil {
30
    log.Fatal(err)
31
  }
32
  if resp.StatusCode != http.StatusOK {
33
    log.Fatalf("%s: %s", resp.Status, data)
34
  }
35
  fmt.Println(string(data))
36
}

1
using System.Net.Http.Headers;
2
using System.Net.Http.Json;
3

4
using var http = new HttpClient
5
{
6
    Timeout = TimeSpan.FromSeconds(30),
7
};
8
http.DefaultRequestHeaders.Authorization =
9
    new AuthenticationHeaderValue("Bearer",
10
        Environment.GetEnvironmentVariable("ALVIA_API_KEY"));
11
using var response = await http.GetAsync(
12
    "https://api.alvia.ai/v1/memories" +
13
    "/mem_01K6R8QJ2N4P6S8T0V2X4Z6B8D/inspect");
14
response.EnsureSuccessStatusCode();
15
Console.WriteLine(await response.Content.ReadAsStringAsync());

This response is for the Atlas memory in Example: a database upgrade in Change over time. In this example, Alvia classifies the September statement as a supersession, so the memory has two versions:

{
  "memory_id": "mem_01K6R8QJ2N4P6S8T0V2X4Z6B8D",
  "scope": {
    "organization_id": "acme",
    "user_id": null,
    "application_id": "eng-assistant",
    "agent_id": null,
    "team_id": null
  },
  "occurred_at": "2026-09-29T09:00:00-04:00",
  "is_favorited": false,
  "sentiment": "neutral",
  "head_version": 2,
  "versions": [
    {
      "version": 2,
      "content": "Atlas uses PostgreSQL 17 as its primary database (stated September 29, 2026).",
      "category": "decision",
      "entities": { "project/Atlas": 0.51, "tool/PostgreSQL 17": 0.49 },
      "occurred_at": "2026-09-29T09:00:00-04:00",
      "created_at": "2026-09-29T13:00:41.218Z",
      "outcome": "supersession",
      "explanation": "The new statement replaces PostgreSQL 16 with PostgreSQL 17 as the Atlas primary database."
    },
    {
      "version": 1,
      "content": "The Atlas team chose PostgreSQL 16 as its primary database (stated March 10, 2026).",
      "category": "decision",
      "entities": { "project/Atlas": 0.52, "tool/PostgreSQL 16": 0.48 },
      "occurred_at": "2026-03-10T10:00:00-05:00",
      "created_at": "2026-03-10T15:00:38.402Z",
      "outcome": "novel"
    }
  ],
  "relationships": [
    {
      "target_id": "mem_01K6S4H7MC3R5T7V9X1Z3B5D7F",
      "edge_type": "related",
      "created_at": "2026-04-02T14:21:07.730Z"
    }
  ]
}

The response holds the memory’s memory_id, scope, occurred_at, is_favorited and sentiment, as get does, and these fields:

Field	Description
`head_version`	The number of the current version.
`versions`	The memory’s newest versions, up to 100, newest first. The first is the current one.
`relationships`	The memory’s newest relationships to active memories, up to 20, newest first.

Each version has these fields:

Field	Description
`version`	The version number. The first version is `1`.
`content`	The text of this version.
`category`	The kind of fact. See Category.
`entities`	The things this version names, as `"type/name"` keys with a weight from 0 to 1.
`occurred_at`	The memory’s `occurred_at` as of this version. A new version keeps the previous version’s time when it is later.
`created_at`	When Alvia recorded this version, in UTC.
`outcome`	How Alvia classified the fact that formed this version. See Classification.
`explanation`	Why the classifier chose the outcome. A `novel` first version has none, so the field is left out.

Each relationship has these fields:

Field	Description
`target_id`	The related memory’s ID. Get or inspect that memory by its ID.
`edge_type`	`related`, or `contradiction` when the two memories conflict.
`created_at`	When Alvia recorded the relationship, in UTC.

The dashboard shows the same versions and relationships in a memory’s History and Relationships. Inspect returns 404 when the memory does not exist, was forgotten, is still forming or belongs to another project.

List memories

List orders active memories by when each first formed, newest first: a memory imported today with an older occurred_at lists before memories written earlier, and a new version keeps a memory’s place. It takes these query parameters:

limit: 1 to 20, default 10
starting_after: the ID of the last memory on the previous page, to get the next page
ending_before: the ID of the first memory on the current page, to go back a page
the scope fields, such as organization_id

curl "https://api.alvia.ai/v1/memories?limit=20&organization_id=acme" \
  -H "Authorization: Bearer $ALVIA_API_KEY"

To get every page, repeat the request with starting_after set to the last ID until has_more is false. Send the same scope parameters on every page:

1
import os
2
import requests
3

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

6
params = {"limit": 20, "organization_id": "acme"}
7
while True:
8
    response = requests.get(
9
        "https://api.alvia.ai/v1/memories",
10
        headers={"Authorization": f"Bearer {API_KEY}"},
11
        params=params,
12
        timeout=30,
13
    )
14
    response.raise_for_status()
15
    page = response.json()
16
    for memory in page["data"]:
17
        print(memory["memory_id"], memory["content"])
18
    if not page["has_more"]:
19
        break
20
    params["starting_after"] = page["data"][-1]["memory_id"]

1
const params = new URLSearchParams({
2
  limit: "20",
3
  organization_id: "acme",
4
});
5
while (true) {
6
  const response = await fetch(
7
    `https://api.alvia.ai/v1/memories?${params}`,
8
    {
9
      headers: {
10
        Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
11
      },
12
    },
13
  );
14
  if (!response.ok) {
15
    throw new Error(`${response.status}: ${await response.text()}`);
16
  }
17
  const page = await response.json();
18
  for (const memory of page.data) {
19
    console.log(memory.memory_id, memory.content);
20
  }
21
  if (!page.has_more) break;
22
  params.set("starting_after", page.data.at(-1).memory_id);
23
}

1
package main
2

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

14
type page struct {
15
  Data []struct {
16
    MemoryID string `json:"memory_id"`
17
    Content  string `json:"content"`
18
  } `json:"data"`
19
  HasMore bool `json:"has_more"`
20
}
21

22
func main() {
23
  client := &http.Client{Timeout: 30 * time.Second}
24
  key := os.Getenv("ALVIA_API_KEY")
25
  params := url.Values{"limit": {"20"}, "organization_id": {"acme"}}
26
  for {
27
    endpoint := "https://api.alvia.ai/v1/memories?" + params.Encode()
28
    req, err := http.NewRequest(http.MethodGet, endpoint, nil)
29
    if err != nil {
30
      log.Fatal(err)
31
    }
32
    req.Header.Set("Authorization", "Bearer "+key)
33
    resp, err := client.Do(req)
34
    if err != nil {
35
      log.Fatal(err)
36
    }
37
    if resp.StatusCode != http.StatusOK {
38
      body, _ := io.ReadAll(resp.Body)
39
      log.Fatalf("%s: %s", resp.Status, body)
40
    }
41
    var p page
42
    err = json.NewDecoder(resp.Body).Decode(&p)
43
    resp.Body.Close()
44
    if err != nil {
45
      log.Fatal(err)
46
    }
47
    for _, memory := range p.Data {
48
      fmt.Println(memory.MemoryID, memory.Content)
49
    }
50
    if !p.HasMore {
51
      break
52
    }
53
    params.Set("starting_after", p.Data[len(p.Data)-1].MemoryID)
54
  }
55
}

1
using System.Net.Http.Json;
2
using System.Text.Json;
3

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

9
string? startingAfter = null;
10
while (true)
11
{
12
    var url = "https://api.alvia.ai/v1/memories"
13
        + "?limit=20&organization_id=acme";
14
    if (startingAfter is not null)
15
    {
16
        url += $"&starting_after={startingAfter}";
17
    }
18
    var page = await http.GetFromJsonAsync<JsonElement>(url);
19
    var memories = page.GetProperty("data").EnumerateArray().ToList();
20
    foreach (var memory in memories)
21
    {
22
        var id = memory.GetProperty("memory_id");
23
        Console.WriteLine($"{id} {memory.GetProperty("content")}");
24
    }
25
    if (!page.GetProperty("has_more").GetBoolean()) break;
26
    startingAfter = memories[^1].GetProperty("memory_id").GetString();
27
}

Response fields

Field	Description
`status`	`active` for a memory, `not_found` for a recall miss.
`memory_id`	The memory’s ID: `mem_` and 26 characters.
`content`	The current text. Alvia can add resolved dates to it, as in “(stated September 23, 2026)”.
`category`	The kind of fact. See Category.
`is_favorited`	Whether you marked the memory as a favorite.
`sentiment`	The feedback you gave: `neutral`, `positive` or `negative`.
`occurred_at`	When the memory’s content was stated or observed, in the offset it was sent with.
`ranked_score`	Search and recall only. Relevance from 0 to 1; compare within one response only.
`scope`	All five scope fields, in lowercase. Fields you did not set are `null`.
`entities`	The things the memory names, as `"type/name"` keys with a weight from 0 to 1.

New fields can appear in responses. Ignore fields you do not use, and handle category values you do not know.

Cost

Each completed read uses reads from your monthly allowance, whatever it returns:

Context uses five reads, a 404 included.
Inspect uses three reads, a 404 included.
Recall, search and get use one read each, and each page of a list uses one.

See Limits and allowances.

Retries

Retry only reads that failed: network errors, 5xx responses and 429 responses, after the wait in Retry-After or, without one, a delay. A 400 or a 5xx uses no read. See Production checklist.
A 429 with monthly_read_quota_reached succeeds only after the allowance resets.
Do not retry a 400. Fix the request first.
Do not retry a 404 from get or inspect: there is no such memory. After a 404 from context, ask again on a later call, such as the next turn, rather than in a loop.

Errors

Error	Cause
`400` `validation_error`	A field is missing, out of range, too long or unknown, or `occurred_before` is not after `occurred_after`. `errors` names each field.
`400` `invalid_argument`	List: a cursor is not a memory ID, or both cursors were sent.
`401` `unauthorized`	The API key is missing or not valid.
`404` `not_found`	Context: no context for the query right now. Get and inspect: no such active memory. Any read: the project’s deletion started during the call.
`429` `rate_limit_exceeded`	Too many requests per second, or context is briefly limited in high demand. Retry after `Retry-After`.
`429` `rate_limit_exceeded` `monthly_read_quota_reached`	The monthly read allowance is used up.
`503` `capacity_exceeded`	Alvia is briefly at capacity, or context could not finish its answer in time. Retry after `Retry-After`.

See Errors for every code.