How memory works

Capture first, then do the background work

A successful capture records the memory and returns its ID. Extraction and indexing continue afterward. The acknowledgment is not a verdict that the contents are true, that every entity is resolved or that every search path is ready.

That separation keeps the initial save from waiting for all the background work. It also means the client needs to distinguish “saved,” “still processing” and “refused.” A tool call that returned an error is not a saved memory.

On plans with Collective Memory, background processing can find that a new record is a copy of an existing memory: the same text, with spacing and punctuation aside. The duplicate path marks that new record no longer current and records which memory it folded into; it does not delete the saved row. No model makes that call, and two memories that are close but not copies are both kept. A long memory saved again with edits is the other case: the edited parts replace the ones stored before. A capture receipt therefore does not guarantee that the same ID will remain in current search.

Use history inspection when a saved record stops appearing. Check the replacement if it is exposed, and do not guess why a record became inactive from its timestamp alone. If the client cannot show the reason or replacement, keep the ID and use the processing checks.

How does it decide what is relevant?

A normal memory query runs keyword and meaning searches and fuses their rankings. Keyword search finds the words you used. Vector search helps find related meaning when the wording differs.

score = 1 / (60 + keyword_rank) + 1 / (60 + vector_rank)

This is reciprocal rank fusion. Each search contributes according to a memory’s position in its list; a memory absent from a list contributes nothing from that list. Fusion settles the candidate ranking, not the entire memory result.

The next stage blends normalized fusion score with the importance recorded for the memory and with how fresh the memory is. The weights come from the tenant’s cognitive policy rather than one hard-coded set of proportions.

final = w_rrf × normalized_fusion
      + w_importance × importance
      - w_fresh × (1 - freshness)

Freshness is 1 for a memory saved today and halves on a schedule set by the memory's type; some types never fade. The weight w_fresh is the Memories Fade strength, 0.2 unless your organization's admin changed it, and it counts as 0 when Memories Fade is off. The last line is what a memory loses for its age: nothing when it was saved today or never fades, and up to the strength when it has faded all the way. Each result carries final_score, the blended number that set the order, and fade_part, that loss as 0 or a negative number. With Memories Fade on, Korium also looks three pages deep in each of the two searches, so a fresher memory from just below the page can take the place of an old one near the bottom of it. Tuning Memories Fade has worked examples.

That is why the same words are not the whole story. What your company considered important, and how recently it was saved, can affect which relevant memories come back. A search answers with a whole page of memories or reports an error; it never hands back part of a page. The related-entity context beside those memories can still be incomplete: when entities_partial is true, that lookup failed, so an empty related_entities list does not mean there are none.

Does being recalled often change the ranking?

No. Korium counts how many times search has returned each memory and when it last did, and the dashboard shows those numbers. They do not move a memory up or down in results.

Ranking used to include a score built from that history. It was removed because search itself decides what gets shown, so the score rewarded a memory for having been rewarded before, and it pushed down the memory someone wrote once and nobody has needed since. That is often the one a company most needs to find.

Importance is a ranking signal, not proof of correctness. A frequently retrieved mistake still needs correction and evidence.

How does something stop being current?

Use a replacement relationship. The new memory says what changed, and a supersedes link from it to the old one keeps the correction from becoming an unlinked sentence. The link can travel with the new memory in the capture's relations, where Korium writes it a few seconds later when the memory is filed, or be made with a separate korium_relation call after the save. A capture that links to a memory Korium can see is not in your account is refused, and nothing is saved.

The supersedes link is what retires the old memory. When the link is saved, the old memory stops being current and search no longer returns it. This happens on every plan, and no model is involved. If the link was a mistake, marking it wrong with korium_relation_correct makes the old memory current again.

Nothing in that correction requires deleting the previous memory. The chain of what replaced what stays available to inspect. A superseded memory is not necessarily wrong; it is no longer current, and those are two different things.

Korium never retires a memory on its own judgment. It does not ask a model whether a new memory replaces an older one. A memory stops being current when a supersedes link says so. On plans with Collective Memory, the text alone decides two other cases: a new save that is an exact copy of a stored memory is the copy that stops being current, and a long memory saved again with edits replaces the parts it edits. On other plans both copies stay current. Only a position replaces a position. A decision, a preference or a rejection is a position: something you committed to. Everything else is a finding: something noticed, learned or reported. A supersedes link from a finding to a position is saved, and the position stays current. To change a position, save a new decision, preference or rejection that supersedes it.

On plans with Collective Memory, the same long text saved twice is one memory, whatever label the second save carries. When a long memory, such as a transcript, is saved again, an edit replaces the stored text, a copy with nothing new is not stored a second time, and either way the higher-ranked of the two labels stays: a decision saved again as an insight stays a decision, and an insight saved again as a decision becomes a decision. A decision, a preference or a rejection outranks every other label. Between two labels of the same kind, the one with the higher default importance stays, and on a tie the newer label does. Saving a memory again makes it fresh: search counts its age from the day of the newer save, for a short memory and a long one, and whichever label stays. When only part of a long memory is saved again, which of its turns become fresh depends on which label stays; Tuning Memories Fade has the two rules, an example of each, and when they leave turns behind. The date the memory shows does not move. No link is written between the two saves.

Because the link is written after the save is acknowledged, check the capture and the link individually. Use korium_trace to follow the result instead of assuming a successful save established the relationship.

Doesn’t it all go stale?

A stale performance assumption can be dangerous. A year-old explanation of how a team approached a client can still be useful. Age alone does not prove whether either statement is true.

That judgment is different from the rules that decide which records appear in current search. Korium does not hide a memory for its age. It used to: a correction nobody had replaced was gone from search after 90 days, and nobody could see that it had happened. Now a memory leaves current search only when something replaces it, and age changes the order of results instead.

Nothing expires by age. A memory is never hidden or deleted because it is old; it stops being current only when something replaces it. Age lowers a memory's rank instead. A memory saved today is fully fresh, and its freshness then halves on a schedule set by its type.

A faded memory is still current and still found by a search that matches it. Fading only decides which of two memories that match about as well comes first. It does not delete the stored record, prove the statement false or make storage room. A memory that was marked no longer current under the earlier expiry rules stays that way.

Ranking and replacement are separate mechanisms. An organization admin can turn fading off, or change how strong it is, with the Memories Fade setting on the organization's own Settings page, and every workspace in the organization follows it; the Tuning Memories Fade guide in the docs explains how. For an audit, browse the history and inspect the replacement or invalidation information; do not assume an ordinary search includes every old record. Account deletion and contractual retention follow the applicable terms.

Keep the reason and evidence when something changes. Don’t supersede a true memory merely to tidy a result list, and don’t read a low rank as a sign that a memory is wrong.

How are things connected?

There are two different jobs here. One extraction pass identifies kinds of entities, such as a person or project, using the configured entity labels. The role pass uses a fixed list of roles, not your custom relationship names.

Of the predicted roles, only participant and topic are stored, and the others are withheld. Topic comes from the role pass. A participant link means a person spoke a turn of a saved transcript: it comes from the speaker label at the start of the turn, and only when the model also reads that label as a person. A name that is only talked about is recorded as mentioned. Domain vocabulary remains separate from that fixed prompt. Calling a relationship “staffs” or “placed at” can make its meaning clearer to your team, but does not by itself teach the model a new extraction rule.

An explicit link between two saved memories is different from automatically resolving the same person across documents. Check the source and the link you actually received. Do not assume a matching name establishes identity or that saving a correction retrains extraction.

Use specific language such as “staffs,” “credentialed for,” “sourced through” or “placed at” when describing your domain. Verify vocabulary mappings and actual extracted results with examples from your work before relying on them.

Use the setup checklist to verify transcript sources, memory connections and your branch code indexes before automating the work.

What about wrong links and poisoning?

A saved source is evidence, not an instruction with authority over the agent. A transcript or document can contain an error, a quoted command or a deliberate attempt to steer a model. Do not let retrieved text override the user’s instructions or the tool’s permissions.

Separate imported claims from approved decisions. Keep authorship, source, uncertainty and review status. If a link is wrong, correct the record explicitly and verify the chain; simply adding more related text does not fix it.

Use server-side access controls to limit who can write. Review imported batches, and require human approval before a memory triggers a consequential external action. Memory helps an agent decide; it does not create permission to act.

What this does not promise

Korium does not make every old statement true, connect every external tool without setup or replace a person’s approval. A useful result still depends on the source material and the question.

The tool reference explains the callable interfaces. The access guide explains the boundaries around the shared memory.