Manage memories

This guide shows how to forget a memory and how to tell Alvia which memories are useful. Both operations need the memory’s ID, which you get from recall, search or list.

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

Forget a memory

curl -X DELETE \
  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.delete(
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()  # 202 Accepted, empty body

1
const memoryId = "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P";
2

3
const response = await fetch(
4
  `https://api.alvia.ai/v1/memories/${memoryId}`,
5
  {
6
    method: "DELETE",
7
    headers: { Authorization: `Bearer ${process.env.ALVIA_API_KEY}` },
8
  },
9
);
10
// 202 Accepted, empty body
11
if (!response.ok) {
12
  throw new Error(`${response.status}: ${await response.text()}`);
13
}

1
package main
2

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

11
func main() {
12
  memoryID := "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P"
13
  req, err := http.NewRequest(http.MethodDelete,
14
    "https://api.alvia.ai/v1/memories/"+memoryID, nil)
15
  if err != nil {
16
    log.Fatal(err)
17
  }
18
  key := os.Getenv("ALVIA_API_KEY")
19
  req.Header.Set("Authorization", "Bearer "+key)
20

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
  // 202 Accepted, empty body
28
  if resp.StatusCode != http.StatusAccepted {
29
    body, _ := io.ReadAll(resp.Body)
30
    log.Fatalf("%s: %s", resp.Status, body)
31
  }
32
}

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

6
var memoryId = "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P";
7
var response = await http.DeleteAsync(
8
    $"https://api.alvia.ai/v1/memories/{memoryId}");
9
response.EnsureSuccessStatusCode(); // 202 Accepted, empty body

The response is 202 with an empty body. Forgetting the same memory again also returns 202.

Forgetting is permanent. A forgotten memory leaves every read:

Get, list and context drop it at once, in context both as a match and as a related or contradicting memory
Search and recall drop it as well
The memory stops counting against the stored-memory limit

When a fact changes, send the new fact: Alvia records it as the memory’s next version, so the memory stays. Forget a memory when a user asks your application to forget something, or when a fact was stored by mistake.

Give feedback

curl -X PUT \
  https://api.alvia.ai/v1/memories/mem_01K6Y3V9QF2W8H4N7C5X0RZB1D/feedback \
  -H "Authorization: Bearer $ALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_favorited": true, "sentiment": "positive" }'

1
import os
2
import requests
3

4
API_KEY = os.environ["ALVIA_API_KEY"]
5
MEMORY_ID = "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D"
6

7
response = requests.put(
8
    f"https://api.alvia.ai/v1/memories/{MEMORY_ID}/feedback",
9
    headers={"Authorization": f"Bearer {API_KEY}"},
10
    json={"is_favorited": True, "sentiment": "positive"},
11
    timeout=30,
12
)
13
response.raise_for_status()  # 204 No Content

1
const memoryId = "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D";
2

3
const response = await fetch(
4
  `https://api.alvia.ai/v1/memories/${memoryId}/feedback`,
5
  {
6
    method: "PUT",
7
    headers: {
8
      Authorization: `Bearer ${process.env.ALVIA_API_KEY}`,
9
      "Content-Type": "application/json",
10
    },
11
    body: JSON.stringify({
12
      is_favorited: true,
13
      sentiment: "positive",
14
    }),
15
  },
16
);
17
// 204 No Content
18
if (!response.ok) {
19
  throw new Error(`${response.status}: ${await response.text()}`);
20
}

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
  memoryID := "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D"
15
  payload, err := json.Marshal(map[string]any{
16
    "is_favorited": true,
17
    "sentiment":    "positive",
18
  })
19
  if err != nil {
20
    log.Fatal(err)
21
  }
22
  req, err := http.NewRequest(http.MethodPut,
23
    "https://api.alvia.ai/v1/memories/"+memoryID+"/feedback",
24
    bytes.NewReader(payload))
25
  if err != nil {
26
    log.Fatal(err)
27
  }
28
  key := os.Getenv("ALVIA_API_KEY")
29
  req.Header.Set("Authorization", "Bearer "+key)
30
  req.Header.Set("Content-Type", "application/json")
31

32
  client := &http.Client{Timeout: 30 * time.Second}
33
  resp, err := client.Do(req)
34
  if err != nil {
35
    log.Fatal(err)
36
  }
37
  defer resp.Body.Close()
38
  // 204 No Content
39
  if resp.StatusCode != http.StatusNoContent {
40
    body, _ := io.ReadAll(resp.Body)
41
    log.Fatalf("%s: %s", resp.Status, body)
42
  }
43
}

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 memoryId = "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D";
9
var response = await http.PutAsJsonAsync(
10
    $"https://api.alvia.ai/v1/memories/{memoryId}/feedback",
11
    new { is_favorited = true, sentiment = "positive" });
12
response.EnsureSuccessStatusCode(); // 204 No Content

Request fields

Field	Required	Description
`is_favorited`	Yes	`true` raises the memory’s rank in future reads. `false` removes that boost.
`sentiment`	Yes	`positive`: useful. `negative`: wrong, outdated or irrelevant. `neutral`: mixed or informational.

Forget takes no request body.

Response

Feedback returns 204 with no body. Each call replaces the memory’s earlier feedback, and ranking updates within moments.

Feedback changes ranking and leaves the memory’s text as it is. negative sentiment lowers a memory’s rank; to remove a memory from reads, forget it.

Cost

Forget and feedback count as writes for Rate limits, but they never use your monthly write allowance.

Retries

Forget is safe to repeat. Forgetting a memory that is already forgotten returns 202 again.
Feedback is safe to repeat. Each call replaces the earlier feedback, so a repeat changes nothing.
Retry only calls that failed: network errors, 5xx responses and 429 responses, after the wait in Retry-After. See Production checklist.

Errors

Error	Cause
`400` `validation_error`	Feedback: a field is missing or has a value the API does not accept.
`401` `unauthorized`	The API key is missing or not valid.
`404` `not_found`	The memory does not exist or belongs to another project. Feedback: also a forgotten memory.
`429` `rate_limit_exceeded`	Too many requests per second.

See Errors for every code.