Module memory_api 

A high-level memory API over the document engine: remember, recall, forget and explain, with temporal validity, supersession, and opt-in consolidation and forgetting.

Design

A fact is an ordinary document. Its memory fields live in one reserved metadata key (_mem, see stamp), so the API adds no persisted structure: stores written before it open unchanged, and journaling, replay and encryption apply as for any document. The engine’s documents, vectors and raw search stay reachable through Memory::core; nothing here is required to use them.

Two time axes are kept apart. Valid time is when a fact holds (valid_from, valid_to, and the event time it describes); knowledge time is when the store ingested it. Recall evaluates validity “as of” a time and, optionally, what was known_at an ingest time.

Supersession links are written once, on the superseding fact, and never edit the old one, so history is never rewritten or lost. The reverse links live in a derived in-memory index that is rebuilt from the documents whenever the store changes behind the API’s back.

Every policy is a trait with a default that changes nothing: supersession is explicit, recency does not rescale scores, nothing is forgotten, nothing is consolidated. Each has a serde spec in MemoryConfig for bindings and may be replaced with any implementation through the with_* builders.

Structs

CapabilitiesRequest

ChainLink

CollapseDuplicates

Merges current facts whose text is identical after trimming and case folding (and that share a subject) into one fact superseding all of them.

ConsolidateOptions

ConsolidationAction

One consolidation step: a new fact that supersedes sources.

ConsolidationReport

What a consolidation run did or would do.

ExpiredFor

Forgets facts whose validity ended more than grace_ms ago.

Explanation

Why a fact matched and how it was adjusted.

ExplicitOnly

Supersession happens only where the caller names it. Default.

ExponentialRecency

0.5^(age / half_life), never below floor. Facts without a time, and facts newer than the evaluation time, are not decayed.

FactRecord

A stored fact with its history links, as get and history return it.

FactSummary

A stored fact as maintenance policies see it.

FactView

A fact as supersession policies see it.

ForgetOptions

ForgetReport

KeepAll

Never forgets. Default.

LatestBySubject

Treats a subject as a single-valued slot on the valid-time axis: a fact supersedes the latest earlier-or-equal fact of its subject, and is itself superseded by the earliest later one. Arrival order does not matter, so a late-ingested older fact becomes history instead of overriding newer knowledge. Use subjects that name one slot (“alice/city”), not a topic that holds several facts.

ManualClock

A clock that only moves when told to; for deterministic runs and tests.

MaxFacts

Keeps at most limit facts: forgets the non-current ones first, oldest ingested first, then the oldest current ones.

Memory

The memory API over one engine.

MemoryCapabilities

MemoryConfig

Plain-data configuration; every field has a default that changes no behavior.

NoConsolidation

Plans nothing. Default.

NoRecency

RecallOptions

Recalled

One fact returned by recall.

RecencyContext

What a recency policy sees of a fact.

RememberInput

One fact to remember.

Remembered

What remember did with one fact.

Resolution

The links a policy asks for.

SupersededFor

Forgets superseded facts whose superseder took effect more than age_ms ago: prunes old history while current facts are untouched.

SystemClock

The system clock. Default.

Enums

ChainRelation

ConsolidationSpec

FactStatus

A fact’s standing at the time recall evaluates it.

ForgetScope

What forget removes.

ForgettingSpec

HistoryMode

Which facts recall returns.

IdConflict

What remember does when an id exists with different content.

MemoryError

An error the caller can act on. Anything that is not one of these (journal I/O, a poisoned invariant) reaches the caller as a plain anyhow error; downcast with error.downcast_ref::<MemoryError>() to tell the two apart.

RecencyBasis

Which time a recency decay measures from.

RecencySpec

SupersessionSpec

Built-in supersession policies by name.

Constants

OPERATIONS

The operations Memory::call accepts.

Traits

Clock

The source of “now” for ingest times and for recall without as_of.

ConsolidationPolicy

Plans merges of related facts. Default: NoConsolidation. A plan only ever adds facts that supersede their sources, so history survives unless the caller opts into removal.

EntityExtractor

Finds the entities a fact mentions. Optional; default none. The result is stored with the fact and matched exactly by RecallOptions::entities. This and MemoryObserver are the extension points for a graph or entity layer; nothing in the store requires one.

ForgettingPolicy

Chooses facts to remove. Default: KeepAll.

MemoryObserver

Receives memory events after they are durable. Default: none. Callbacks run on the calling thread and must not call back into the same Memory’s writers.

RecencyPolicy

Multiplies a result’s retrieval score. Default: NoRecency, which leaves scores exactly as document search returned them.

SupersessionPolicy

Decides, when a fact with a subject is remembered, which stored facts about the same subject it supersedes or is superseded by. Explicit supersedes ids on the input always apply in addition. Ids returned must come from same_subject; others are an error.

Type Aliases

Millis

Unix time in milliseconds.