Skip to content

Keep a memory of facts#

A memory is a knowledge base of kind memory that keeps dated facts instead of documents: Ana leads the data team (as of 12 October, from the reorg chat). Facts come from conversations you choose: a small model, the base's extractor, reads the conversation and proposes the facts in it; you keep the ones you want. When a newer fact says otherwise — Ana moved to research — it replaces the older one, which stays in the memory's history.

Facts are searched and cited like documents, current facts first, so an assistant that searches your memory answers with what holds now.

Before you begin#

  • An embedding model deployed with Eos (as for any base: step 1 of Build a knowledge base).
  • A small chat model as the extractor. Qwen3 4B (qwen3:4b, 2.5 GB at Q4_K_M) is a good choice: it runs on a CPU beside the embedding model, follows the instructions and answers in valid JSON reliably, reads conversations in many languages, and is Apache-2.0. Reading a conversation takes from seconds to a couple of minutes on a CPU. A larger chat model you already serve works too.
  • Permission to add to it (knowledge-bases:write-content).

1. Serve the extractor#

Eos → Models → Library, open Qwen3, choose 4B and its default quantisation, and press Deploy. Name: qwen3-4b. Runs on: CPUs only. Clear Scale to zero when idle (the memory calls it on the workspace's network, which does not wake a deployment scaled to zero).

$ astra eos add qwen3:4b
$ astra eos deploy qwen3-4b-q4-k-m --name qwen3-4b --cpu --min 1 --max 1

2. Create the memory#

Metis ▸ Memory, New memory: a name (team), the embedding model (bge-m3) and the extractor (qwen3-4b). A memory needs no drive.

$ curl -fsS -X POST "$ASTRALYX_API/metis/knowledge-bases" -H "Authorization: Bearer $ASTRALYX_TOKEN" \
    -H 'content-type: application/json' -d '{
      "metadata": {"name": "team"},
      "spec": {"kind": "memory", "sources": [], "embedding": {"deployment": "bge-m3"}, "extractor": {"deployment": "qwen3-4b"}}
    }'

3. Remember a conversation#

In the app's chat, open the conversation's menu and choose Remember this conversation; in the Playground, Remember this conversation under the conversation. Choose the memory.

  1. Choose Find facts to remember. The extractor reads the conversation and proposes facts, each with what it would replace. Facts already known are shown unticked.
  2. Untick what you do not want kept (to change a fact's wording, keep it and Edit it in Metis ▸ Memory).
  3. Choose Remember N facts.

From a conversation saved as JSON ([{"role": "user", "content": "…"}, …]) or plain text:

$ astra metis remember team --from standup.json
reading the conversation for facts (a small model on a CPU takes a minute or two)…
new  Ana — role: Ana works in research.  (2026-10-12, conversation: standup.json)
      replaces: Ana leads the data team.
new  Launch — date: The launch moved to Friday 16 October.  (2026-10-12, conversation: standup.json)
Keep 2 fact(s) in team? [y/N] y
kept 2; 1 replaced an older fact

One fact by hand:

$ astra metis remember team --subject Bruno --attribute city --fact "Bruno lives in Recife."

Extraction proposes; nothing is kept until you post the facts you chose:

$ curl -fsS -X POST "$ASTRALYX_API/metis/knowledge-bases/team/memory/extract" \
    -H "Authorization: Bearer $ASTRALYX_TOKEN" -H 'content-type: application/json' \
    -d '{"source": "chat: standup", "messages": [{"role": "user", "content": "Ana moved to research this week."}]}'
$ curl -fsS -X POST "$ASTRALYX_API/metis/knowledge-bases/team/memory" \
    -H "Authorization: Bearer $ASTRALYX_TOKEN" -H 'content-type: application/json' \
    -d '{"facts": [{"subject": "Ana", "attribute": "role", "fact": "Ana works in research.", "source": "chat: standup"}]}'

How facts replace each other#

A fact is a subject (who or what), an attribute (what about it: role, employer, deadline, preferred language), the fact in one sentence, its source and when it was said. The extractor is told the subjects and attributes the memory already knows, so it names the same thing the same way.

You keep It becomes
A fact on a new subject or attribute Current
A fact on the same subject and attribute, said later Current; the older one moves to the history, with until when it held and what replaced it
A fact said before the one that holds now History straight away: an old message does not overrule a newer one
The same fact again Nothing: it is not kept twice

Searches answer current facts before the history, and the history is still found: "what was Ana's role in September?" is answered.

What looks like a secret — a password, an API key or token, a card number — is never kept: extraction leaves it out (and says so), and keeping it by hand is refused (FACT_SENSITIVE).

See, correct and delete facts#

Metis ▸ Memory, the memory: facts grouped by subject, each with its date and source. show what was replaced adds what they replaced. A fact's Edit corrects it (its history is kept); Forget deletes it — with and the N older facts it replaced, everything kept about it. Add a fact keeps one by hand.

$ astra metis memory team --history
$ astra metis forget team f_9b2c4d6e8f0a1b3c --history

GET …/memory?history=true, PUT …/memory/<id>, DELETE …/memory/<id>?history=true — see the Metis API.

Each fact is a note of the memory (notes/memory/<id>.md, its history in notes/memory/history/), written on the memory's machine. Deleting the memory deletes every fact.

Which conversations are read#

Only the ones you choose, when you choose. The app keeps its chats on your phone and the Playground in your browser; Remember this conversation sends that one conversation, once, to the memory's machine, where the extractor reads it and nothing of it is kept but the facts you choose. Memory does not read your conversations by itself: there is no automatic extraction to turn on yet.

Troubleshooting#

Symptom Cause Fix
409 NO_EXTRACTOR The memory has no extractor model Set spec.extractor (step 2), or keep facts by hand
503 EXTRACTOR_UNAVAILABLE The extractor deployment does not answer Check it in Eos → Deployments; keep it at one replica
502 EXTRACTOR_UNREADABLE The model did not answer with facts Try again; a larger chat model is steadier
No facts proposed Nothing durable was said (small talk, questions) Keep a fact by hand