Module semantic 

B4 (v0.22.4): two-tier semantic memory — a unified MemoryStore abstraction (namespaced key-value + semantic recall) with a short-/long-term split and weighted-decay ranking.

Why a second memory abstraction

crate::BaseMemory manages conversation history (messages injected into the next prompt). The types in this module manage knowledge: durable facts about the user / task extracted from completed turns, addressable by namespace (e.g. one per user or session) and retrievable by meaning rather than by recency in a transcript.

The two tiers

• ShortTermMemory is the in-thread working tier: bounded per namespace (capacity, FIFO eviction), exact key-value lookups plus semantic search purely by similarity. Nothing is persisted; a dropped store is a forgotten store.
• LongTermMemory is unbounded and ranks candidates the way generative-agent systems do: score = w_similarity · sim + w_recency · 2^(−age/half_life) + w_importance · importance (DecayWeights). Frequently re-accessed memories stay fresh; old, unimportant ones naturally sink — nothing is deleted on the read path.
• TwoTierMemory wires the two together: writes land in the short tier; consolidate promotes entries that clear the PromotionPolicy (high importance or enough re-accesses). Recall searches both tiers with one uniform weighted formula and de-duplicates by key (short tier wins on collision).

Semantics without a mandatory embedding dependency

SemanticScorer is a pluggable trait; the always-available LexicalScorer ranks by cosine over term-frequency vectors (Unicode-aware tokenization), so the whole abstraction and its tests run offline with zero extra dependencies. An embedding-backed scorer can be supplied with with_scorer without touching the stores.

All time-dependent logic takes an injected clock, so decay/consolidation tests are pure — no sleeps.

Structs

DecayWeights

Weights and half-life of the long-term ranking formula.

LexicalScorer

Dependency-free scorer: cosine similarity over Unicode word term-frequency vectors.

LongTermMemory

Unbounded long-term memory with weighted-decay ranking.

MemoryHit

A recall result.

MemoryItem

A storable unit of knowledge.

MemoryQuery

A semantic recall query against one namespace.

PromotionPolicy

Policy deciding which short-term entries consolidate into long-term memory.

ShortTermMemory

Bounded in-thread working memory (one FIFO queue per namespace).

StoredMemory

A memory with its lifecycle bookkeeping.

TwoTierMemory

Two-tier memory: bounded short-term working store + decayed long-term store.

Enums

MemoryTier

Which tier a recall hit came from.

Traits

MemoryExtractor

Turns a completed conversation turn into durable memories.

MemoryStore

Namespaced key-value store with semantic recall.

SemanticScorer

Pluggable semantic similarity between two texts.

Type Aliases

Clock

Injectable wall clock (defaults to SystemTime::now).