Memory formation

This page explains what happens to text after you send it to Alvia, and what a memory is. Read it before you design how your application writes and reads.

Storing every message and returning the most similar ones looks sufficient, but it returns the same fact several times, an old fact next to the one that replaced it, and whole messages where a prompt needs one fact. Formation is the work Alvia does at write time so that reads avoid those problems. See Why memory for AI is hard.

Memories

A memory is one durable fact, such as “The Atlas service uses PostgreSQL 17 as its primary database.” Each memory has:

an ID that starts with mem_
its current text
a category, such as decision, preference or event
the time it was stated or observed, occurred_at
the scope it belongs to: the user, agent, application, team or organization it is about
the entities it names, such as a project or a tool, each with a weight from 0 to 1

A memory evolves forward. When a later fact supersedes or refines it, the change becomes the memory’s next version. Earlier versions keep its lineage: how it reached its current state. Reads return the current version, and every earlier version is kept. Your application reads a memory’s history, versions and relationships through the API, and the dashboard shows the same history. See Change over time.

From text to memories

A write does not store your text as it is. It starts formation, which runs in the background after the API answers 202:

Read the input. By default (infer: true), Alvia reads the text as a passage and takes out each durable fact in it as a candidate memory. With infer: false, the whole text is one candidate. Alvia still normalizes its wording.
Compare. Alvia finds the memories closest to the candidate, in the same project and scope.
Classify. Alvia classifies how the candidate relates to what it already holds.
Commit. Alvia stores the result. The memory becomes readable.

With infer on, text that holds no durable fact forms no memory. A project’s memory policy can also exclude content by keyword or meaning, such as personally identifiable information (PII) or health information. In both cases the write still answers 202. See Memory policies.

How a new fact joins the others

Classification gives each candidate one outcome:

Outcome	What Alvia does
Supersession	Adds the candidate as the next version of the memory it replaces.
Refinement	Merges the candidate into the next version of the memory it adds detail to.
Duplicate	Stores nothing new. The fact is already held.
Contradiction	Stores a new memory and links the two as contradicting, so your application sees the disagreement.
Related	Stores a new memory and links it to the memory it relates to.
Novel	Stores a new memory.

Supersession is how Alvia keeps answers current. The old text stays in the memory’s history, but reads return the new version. A contradiction is different: neither fact replaces the other, so Alvia keeps both and the context operation reports both.

Alvia classifies a fact by its meaning against the memories it is compared with: a fact with no close memory is novel, a dated event repeated on another day stays a separate memory, and a new version commits only against the memory’s current version. A change that says what it replaces, as in “Atlas moved from PostgreSQL 16 to PostgreSQL 17”, gives the clearest signal of a supersession. For a supersession or a refinement, Alvia writes the new version’s text, so when a change keeps part of an earlier rule, restate that part in the new fact. The dashboard shows each memory’s outcome and Alvia’s explanation.

What reads return

Reads use committed memories: a memory becomes readable once it commits. A forgotten memory leaves every read, as Forget a memory describes.

Operation	Returns
`POST /v1/memories/context`	One to three sentences that resolve the best match with its related and contradicting memories.
`POST /v1/memories/recall`	The single best memory for the query, with its `ranked_score`.
`POST /v1/memories/search`	A ranked list of memories, each with its `ranked_score`.
`GET /v1/memories/{memory_id}`	One memory by ID.
`GET /v1/memories`	All active memories, newest first by when each first formed, one page at a time.

List orders memories by when each first formed, so a new version keeps its place. See Read memories.

Ranking

Search, recall and context rank memories by how relevant each one is to the query, in two passes. Alvia first finds the memories closest in meaning to the query, then orders them by how well each one answers it. It then adjusts each score with a few signals:

Category and age. Each category carries a small boost that fades with age. See Age and temporal decay.
Use. A recall that returns a memory counts as a use, so that memory ranks a little higher in later reads. The boost fades with time since the last use. Search and context do not count as a use.
Favorites and feedback. A memory you mark as a favorite ranks higher, and feedback can raise or lower a memory’s rank. See Manage memories.

The ranked_score field is a number from 0 to 1. Compare scores within one response only; scores from different queries are not on the same scale.

Timing

Formation runs several processing steps after a write returns, so write first and read later. Formation finishes in less than a minute, so a new memory is readable shortly after the write. Treat a miss right after a write as “not yet”, not “never”.