Skip to content

Models

emotional_memory.models.Memory

Bases: BaseModel

A stored experience with its full affective fingerprint.

emotional_memory.models.EmotionalTag

Bases: BaseModel

Full affective fingerprint of a memory at encoding time.

Captures all five AFT layers as snapshots

Layer 1: core_affect — where the system was Layer 2: momentum — where it was heading Layer 3: mood_snapshot — global mood background Layer 4: appraisal — why this emotion arose (if computed) Layer 5: resonance_links — associative cluster membership

consolidation_strength modulates decay rate (McGaugh, 2004): high arousal → strong consolidation → slow decay → high retrieval priority

Reconsolidation (Nader & Schiller, 2000): every retrieval may update the tag. reconsolidation_count tracks how many times this occurred. reconsolidation_window is managed at runtime via last_retrieved + window_seconds — not stored as a boolean flag.

Frozen like all other value objects — use model_copy(update=...) to derive modified versions.

emotion_label: EmotionLabel | None = None class-attribute instance-attribute

Discrete Plutchik emotion label, set when auto_categorize=True.

expected_affect: CoreAffect | None = None class-attribute instance-attribute

EMA prediction of core_affect, updated by update_prediction() on retrieval.

pending_appraisal: bool = False class-attribute instance-attribute

True when fast-path encoding was used; appraisal is deferred to elaborate().

prediction_learning_rate: float = 0.2 class-attribute instance-attribute

Adaptive learning rate for expected_affect EMA. Clamped to [0.05, 0.80].

window_opened_at: datetime | None = None class-attribute instance-attribute

Timestamp when the reconsolidation lability window was opened (APE-gated).

Bases: BaseModel

A directed affective-associative link between two memories.

link_type encodes the dominant associative principle (Aristotle's laws of association + Bower's affective network theory): semantic — similar content emotional — similar core_affect at encoding temporal — close in time causal — perceived causal relationship contrastive — opposing affective valence (anxiety ↔ relief)

emotional_memory.models.make_emotional_tag(core_affect: CoreAffect, momentum: AffectiveMomentum, mood: MoodField, consolidation_strength: float, appraisal: AppraisalVector | None = None) -> EmotionalTag

Convenience constructor for EmotionalTag with sensible defaults.

Source code in src/emotional_memory/models.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def make_emotional_tag(
    core_affect: CoreAffect,
    momentum: AffectiveMomentum,
    mood: MoodField,
    consolidation_strength: float,
    appraisal: AppraisalVector | None = None,
) -> EmotionalTag:
    """Convenience constructor for EmotionalTag with sensible defaults."""
    return EmotionalTag(
        core_affect=core_affect,
        momentum=momentum,
        mood_snapshot=mood,
        appraisal=appraisal,
        timestamp=_now(),
        consolidation_strength=max(0.0, min(1.0, consolidation_strength)),
    )