A memory is not just a sentence. It carries who wrote it, what kind of thing it is, how much it matters, and what it relates to. Send more of that and recall gets better. This page is the full list, with the rules that actually bind.
Talking to your assistant in plain English works, and it fills most of these in for you. This page is for when you want to drive the save yourself, or you are writing something that saves on your behalf.
One memory, in full
Everything Korium can hold about a single memory. Five fields are required. The rest are there when you have them, and skipping one costs nothing.
{
// required
"content": "Postgres over DynamoDB for the ledger: we need joins.",
"thought_type": "decision",
"source_agent": "architect",
"source_phase": "design",
"importance": 0.8,
// optional, and worth sending
"scope": ["billing.ledger"],
"confidence": 0.9,
"trigger_event": "ledger design review",
"relations": [{ "target_id": "<uuid>", "relation_type": "supersedes" }],
// optional, free-form
"evidence": ["benchmark run 2026-07-14"],
"alternatives_rejected": ["DynamoDB", "single-table Mongo"],
"decided_by": { "name": "Dana", "role": "staff engineer" },
"metadata": { "ticket": "BILL-204" },
// optional, who is involved
"captured_by": "dana",
"actor_id": "dana",
"actor_type": "human"
}The five you must send
Leave any of these out and the save is refused, with a message saying which one and why.
| Field | What it is | The rule |
|---|---|---|
content |
The memory itself. Write it so it makes sense to someone who was not there. | Any text, any language. Must not be empty. Up to 8 KB. |
thought_type |
What kind of thing this is. Decides how long it lives and how it is weighted. | One of the eleven below. Nothing else is accepted. |
source_agent |
Who wrote it. Use a role, not a person or a product name. | Lowercase letters, digits, _ or -. Starts with a letter. 2 to 64 characters. |
source_phase |
What kind of work produced it: research, build, review. |
Same shape as source_agent. |
importance |
How much this should count when Korium decides what to bring back. | A number from 0 to 1. |
Korium will never reject source_agent or source_phase for being unfamiliar. Only the shape is checked. Invent the names that match how you work, and if you misspell one, fix what is displayed later rather than editing the memory. See naming your agents.
The eleven kinds of memory
The type is not a label for tidiness. It sets how long the memory stays in normal recall and how heavily it counts by default, so it is worth picking the right one.
| Type | Use it for | Default weight | Stays current for |
|---|---|---|---|
decision | A choice that is now settled, ideally with the reason. | 0.80 | Always |
preference | How someone wants things done. | 0.70 | Always |
reflection | A look back that pulls several things together. | 0.75 | Always |
handoff | What the next person needs to pick this up. | 0.60 | Always |
seed | Background you loaded in to get started. | 0.50 | Always |
lesson | Something learned the hard way. | 0.70 | 1 year |
pattern | Something that keeps happening. | 0.70 | 1 year |
insight | A finding that was not obvious. | 0.70 | 6 months |
rejection | An option you looked at and said no to. Keeps the no. | 0.60 | 6 months |
correction | A fix to something recorded wrongly before. | 0.60 | 3 months |
drift | Something that has slid away from what was agreed. | 0.40 | 3 months |
rejection is the most under-used type and the most valuable. Recording what you decided against, and why, is what stops the same bad idea coming back in six months wearing a different hat.
How long a memory lives
The "stays current for" column above is a soft expiry, and the word soft is doing real work.
When a memory passes its window, Korium marks it as expired and stops bringing it back in ordinary searches. It is not deleted. It is still there, still counts toward your room, and still comes back if you ask for expired memories on purpose. Nothing you save is ever thrown away to make space or to tidy up.
The five types marked Always never expire at all. That is why a settled decision should be filed as a decision and not as an insight: one is still answering questions in two years, the other quietly steps out of the way after six months.
Alongside expiry, a memory carries a status:
- active
- superseded
- invalidated
- expired
- conflicted
superseded means something newer replaced it. conflicted means Korium noticed it disagrees with something else you saved, which is the system telling you two of your own records cannot both be true.
Importance and confidence
Two numbers from 0 to 1 that look similar and mean completely different things.
importance: how much it should count
Required. This feeds ranking, so it changes what comes back first. If you leave everything at the same number you have told Korium nothing, and ranking falls back to text matching alone. A rough scale that works:
- 0.8 to 1.0 is a decision that binds, something that would be expensive to get wrong.
- 0.5 to 0.7 is ordinary working knowledge. Most memories live here.
- 0.2 to 0.4 is background you would like kept but would not want surfacing first.
confidence: how sure you are
Optional. This is about the claim, not about its weight. "The migration takes about four hours" saved at confidence: 0.4 is honest bookkeeping: important to remember, not yet proven. Somebody reading it later can see it was a guess rather than a measurement.
Scope: filing it away
Scope is a dotted path that works like a folder, so you can later ask for everything under one project in a single question. A memory can carry more than one.
"scope": ["billing.ledger", "q3.launch"]The format is strict, because the path becomes a real index rather than a tag. Each part may use only plain ASCII letters, digits, underscore or hyphen, joined with dots. No spaces, no slashes, no accents.
| Works | Refused |
|---|---|
billing | billing ledger space |
billing.ledger.v2 | billing/ledger slash |
deploiement.hydra | déploiement.hydra accent |
If a scope breaks the rule, nothing is saved and you get an error naming the rule, so an assistant can correct the path and try again. The memory text itself has no such limit and can be written in any language.
Searching by scope is a different thing
When you save, a scope is an exact path. When you search, it is a pattern, so you can ask for a whole branch at once:
| Search scope | Brings back |
|---|---|
* | Everything. |
billing | Only memories filed exactly at billing. |
billing.* | Everything underneath billing. |
This is the payoff for filing consistently. A scope you invent once and use everywhere turns into "show me everything we know about billing" a year later.
The extra fields
All optional, all free-form. They cost nothing when skipped, and they are what turns a note into a record.
| Field | What to put in it |
|---|---|
trigger_event | What prompted this. A short phrase: "ledger design review", "incident 412". |
evidence | A list of what backs the claim. Benchmark names, ticket numbers, file paths, links. |
alternatives_rejected | A list of what you looked at and did not choose. Pairs well with a decision. |
decided_by | Who made the call, as an object. Whatever shape suits you. |
metadata | Anything else, as an object. Ticket ids, environment, build number. |
These are stored as you send them and come back with the memory. Korium does not impose a schema on them, so use them for the things your own work needs.
Who wrote it, and who it is about
These two get mixed up, so it is worth being blunt about the difference.
| Field | Answers | Notes |
|---|---|---|
source_agent | Which agent wrote this? | Required. A role name. |
captured_by | Who was at the keyboard? | Optional. Filled in from your sign-in when you leave it out. |
actor_id | Who is this memory about? | Optional. The subject, not the author. |
actor_type | What kind of actor that is. | Optional. human, agent or system. Nothing else. |
A memory written by your reviewer agent about a decision Dana made has source_agent: "reviewer" and actor_id: "dana". Getting this right is what lets you ask "what has Dana decided" separately from "what has the reviewer noticed".
Linking memories together
Links are what make this a memory rather than a pile of notes. There are two ways to make one.
While you save
Pass relations with the memory. Each entry names the memory you are pointing at and how the two relate. Four link types are available at save time:
- supersedes
- contradicts
- supports
- synthesized_from
"relations": [
{ "target_id": "3f9a...", "relation_type": "supersedes" }
]supersedes is the one to reach for most. It is how you change your mind without losing the record of what you used to think: the old memory is marked superseded, stays readable, and stops crowding your results.
Afterwards
Use the linking tool (korium_relation) to connect two memories that already exist. It accepts a wider set:
- mentions
- produced_by
- occurred_during
- supersedes
- derives_from
- contradicts
- caused
- part_of
- instance_of
- associates
- applies_to
- advances
- synthesized_from
- supports
Three of these go both ways on their own: associates, contradicts and supports. Link A to B and B is linked to A. The rest point one way, so the direction you choose is the direction it reads.
When you search, Korium does not stop at the memories that match your words. It walks two steps out along these links and brings back what is connected. A well-linked memory pulls its neighbours in with it, which is how you get an answer instead of a search result.
How big a memory can be
One memory holds up to 8 KB of text, which is roughly 8,000 characters. The same on every self-serve plan.
That is not a plan feature and it is not something you can buy more of. It is the definition of what counts as one memory, and since your room is counted in memories, one has to mean the same thing on every plan.
In practice it is generous. The longest memories in real use run around 1,300 characters, and those are end-of-session summaries. Ordinary ones sit between 600 and 850. Aim under 500. Not because of the ceiling, but because a memory that says one thing clearly is one that comes back cleanly; a memory that says nine things comes back for all nine and answers none of them.
Do not. Split it into the claims it contains and save those, linked together. A pasted page counts as one memory against your room but behaves badly on recall, because the useful sentence is buried among a thousand that are not.
What happens after you save
The save returns almost immediately, in about a thousandth of a second. The interesting work happens quietly afterwards.
Korium reads what you wrote and pulls out the things in it, sorting each one into one of ten kinds:
- Actor
- Artifact
- Claim
- Concept
- Decision
- Entity
- Event
- Goal
- Period
- Rule
Those become points on a graph, joined by the link types above. A person named in one memory and in another is the same point on the graph, which is how a question about Dana finds work she did that never mentioned her by name.
On the paid plans it goes further: noticing when two memories are about the same thing, spotting when something you saved today contradicts something from last month, and writing short summaries that pull several memories together.
Teaching it your own words
Those ten kinds are the built-in set, and you can extend them. If your work has Contracts or Studies or Runs, you can register them as your own kinds hanging off the built-in ones, and Korium will start sorting things into them. That is the korium_register_vocabulary tool on the capabilities page.
Where to go next
Everything Korium can do
All fourteen tools, what each is for, and when to reach for it.
Make it automatic
Stop asking. Set it up so your assistant searches and saves on its own.