Skip to content

Cognitive Features

CMM implements multiple cognitive features that model aspects of human memory. These features work together during retrieval to surface the most relevant memories.

Temporal Decay

Memories decay over time, but with a realistic model:

  • Grace period: No decay for 2 weeks after last access. Memories are at full strength during this window.
  • Exponential decay: After the grace period, e^(-lambda_eff * age) where age = time since last access (not creation). Default lambda = 5e-7.
  • Rehearsal effect: Frequently accessed memories decay slower via lambda_eff = lambda / (1 + freq_weight * access_frequency_per_week).
  • Lock threshold: Memories accessed >= 0.5 times/week become permanent and never decay. Like birthdays -- the access interval is shorter than the decay timescale.

Decay is a last-resort maintenance operation, not an active scoring feature. It cleans up genuinely neglected information, not recent memories.

Spreading Activation

Dual-path expansion from seed retrieval results:

  1. FAISS embedding neighbors -- finds memories with similar vector representations
  2. Entity-linked memories -- traverses named entity connections via the entity index

Score decays per hop via spread_factor (default 0.5). This enables cross-domain association -- for example, "Industrial Way" connects a warehouse inspection to a hospital report, even when their embedding similarity is only 0.18.

Spreading Activation

Entity Linking

spaCy NER + regex extracts named entities (people, places, organizations) at storage time. An entity index maps entity -> [memory_ids]. Spreading activation traverses both embedding proximity AND entity links, enabling associations that pure embedding similarity cannot capture.

Priming

Recently activated memories get a turn-decaying boost:

boost = 1 + boost_strength * e^(-decay_rate * turns_since_activation)

Default: 1.3x boost at activation, decaying over subsequent turns. This models the psychological finding that recently encountered concepts are easier to recall.

Importance Weighting

Memories are auto-scored at storage time based on content type:

Content Type Importance Score
Corrections / instructions 2.0x
Novel information 1.5x
Normal conversation 1.0x
Routine exchanges 0.5x

Importance scoring turned a 0.12-similarity allergy memory into a life-saving recall during a food ordering query.

Importance Scoring

Emotional Valence

Each memory is tagged with:

  • Valence: -1 (negative) to +1 (positive)
  • Arousal: 0 (calm) to 1 (intense)
  • Emotion label: e.g., "frustration", "excitement", "neutral"

Emotional context is surfaced during retrieval, enabling empathetic recall -- when the user hits a similar bug, the system can recall the previous frustration.

Metamemory

Confidence levels on retrieved memories:

  • HIGH -- strong match, high confidence
  • MODERATE -- reasonable match
  • LOW -- weak match, uncertain
  • NONE -- no relevant memories found

"Tip of the tongue" partial match hints are surfaced via recall_with_metamemory(). When a memory scores below the retrieval threshold but is still a plausible partial match, it is reported as a hint rather than discarded.

Working Memory

A fixed-size buffer (default 10) of recently activated memories with turn-based TTL (default 5 turns). Items in working memory are re-scored against the current query on each retrieval, keeping contextually relevant memories available across consecutive turns.

Consolidation

Episodic-to-semantic memory consolidation, mirroring human memory:

  1. Turn-level gists cluster into session summaries at end-of-session
  2. Similar episodic memories cluster into semantic memories via consolidation
  3. Consolidation runs automatically after a configurable number of turns (default 50) or can be triggered manually

This produces increasingly compressed representations over time -- recent memories are detailed episodes, older memories are generalized knowledge.