Skip to content

emotional_memory

CI PyPI License: MIT

Emotional memory for LLMs based on Affective Field Theory (AFT) — a 5-layer model that encodes not just what happened, but how it felt, how that feeling was moving, and what mood colored the moment.

Why emotional_memory?

Most LLM memory libraries treat retrieval as semantic-only: vector similarity over text. Real human recall is driven by more:

  • Affective congruence — we remember things that feel like how we feel now (Bower 1981)
  • Arousal-modulated consolidation — emotionally-charged events consolidate more strongly (Cahill & McGaugh 1995; ACT-R power-law with arousal floor, McGaugh 2004)
  • Reconsolidation — retrieved memories become labile and update with prediction error (Nader & Schiller 2000; APE-gated lability window)
  • Dual-path encoding — fast affective signal precedes slow appraisal (LeDoux 1996)
  • 3D affect — perceived control (dominance) discriminates fear from anger (Mehrabian & Russell 1974; PAD)

emotional_memory operationalizes these as a single retrieval pipeline. Checked for intra-theory coherence with 127 fidelity tests across 20 phenomena and studied in a pre-registered evidence programme — including committed negative results.

How it compares

Library Memory model Affective retrieval Reconsolidation Decay model Psychological fidelity tests
emotional_memory 5-layer AFT (semantic + valence/arousal + momentum + mood + appraisal) ✅ mood-congruent + APE-gated ✅ Nader & Schiller 2000 ACT-R power-law + arousal modulation 127 tests, 20 phenomena
mem0 Fact extraction + vector store ❌ ✅ auto update/remove None —
A-MEM Atomic notes + dynamic links ❌ ❌ None —
LangMem Hot/cold memory tiers ❌ ❌ Time-based eviction —
Generative Agents (Park et al.) Importance + recency + relevance Partial (importance only) ❌ Exponential —

✅ means the feature is implemented and theory-faithful — it is not a head-to-head performance result. The measured retrieval advantage is regime-specific to affect-discriminative recall under oracle-affect labeling (see When NOT to use); under end-to-end automatic appraisal it does not transfer. ❌ marks a feature absent, not a quality judgment. mem0's reconsolidation cell quotes comparison.md (✅ auto update/remove).

This is not a replacement for those tools — emotional_memory is a focused primitive that can plug into any of them via the MemoryStore protocol (LangChain adapter included).

When NOT to use

emotional_memory is a focused primitive for affect-discriminative recall, not a general-purpose memory system. Its measured advantage holds only when relevance is itself affect-conditioned and affect is supplied at encode time (oracle affect). Within that regime the ranking advantage does convert end-to-end: in a pre-registered encode→retrieve→generate→judge task (Addendum R, N=200, gpt-5-mini judge) AFT's LLM-judged answer accuracy is 0.595 vs 0.440 for cosine (Δ=+0.155 [0.095, 0.220], p<0.001). But pre-registered studies show it does not help — and can hurt — outside that regime:

  • Factual / open-domain QA — on LoCoMo (1986 QA pairs) AFT underperforms a naive RAG baseline (F1 0.168 vs 0.271; Gate 1 FAIL).
  • End-to-end automatic appraisal — when affect comes from LLMAppraisalEngine rather than oracle labels, AFT does not beat cosine on affect-free queries (Hg1 FAIL, Δ=−0.010; recalibrated re-run Addendum P, Δ=−0.087, p=0.002). The gain has not transferred to automatic appraisal, calibrated or not.
  • Short-turn naturalistic dialogue — on DailyDialog (120 personas, 396 queries) there is no advantage over cosine (Hk1 FAIL, Δ=−0.008; confirmed with retrieve-time query appraisal, Addendum T2A).
  • Query-type routing as a fix — heuristic routing does not close the LoCoMo gap (Addendum L FAIL).
  • Emotional-support recall (counter-congruent) — on the first third-party emotional retrieval benchmark (MADial-Bench, NAACL 2025; Addendum X) cosine is significantly better (nDCG@5 0.304 vs 0.221, Δ=−0.083), even with near-perfect appraisal: supportive assistants are expected to recall positive memories for a distressed user (interpersonal emotion regulation) — the opposite of AFT's mood-congruence prior. If your gold behavior is counter-congruent, AFT's affect channel actively hurts.
  • Content-determined QA over emotional history (affect-orthogonal) — on the second third-party benchmark (ES-MemEval/EvoEmo, WWW 2026; Addendum X2) cosine is again significantly better (nDCG@4 0.284 vs 0.133, Δ=−0.150, powered), with faithful appraisal: the right memory is fixed by content (what was said, when), 45.5% of queries carry no affect, and the affect channel buys ranking variance with no gold-directed signal. If your gold is content-determined, plain cosine wins.

Research use: exploring mood-congruent retrieval under explicit affect assumptions. Utility in journaling, care or deployed conversational agents has not been established. For the full record see the claim-validation matrix and current evidence.

30-second example

from emotional_memory import EmotionalMemory, InMemoryStore, CoreAffect

# MyEmbedder = any object with `.embed(text) -> list[float]` (see Quickstart for a
# real one via the [sentence-transformers] extra).
em = EmotionalMemory(store=InMemoryStore(), embedder=MyEmbedder())

em.set_affect(CoreAffect(valence=-0.6, arousal=0.7))   # stressed
em.encode("The deployment failed at 3am.")
em.encode("Beautiful sunset on the lake.")

em.set_affect(CoreAffect(valence=-0.5, arousal=0.6))   # similar mood later
results = em.retrieve("yesterday", top_k=2)
# → deployment memory ranks higher than sunset, even with equal semantic distance.

Installation & Quickstart

See Getting Started for install recipes (extras, dev setup) and a runnable quickstart — both sourced from the README so they stay in sync with PyPI.

Try it in the browser: Hugging Face demo — a Gradio chat that encodes messages as memories and recalls them with affect-aware ranking (a free Space; it may take a few seconds to wake up). Benchmark dataset on Hugging Face: emotional-memory-benchmarks.

The 5 Layers

Layer Class Theory
CoreAffect CoreAffect Russell-Mehrabian PAD model — continuous (valence, arousal, dominance)
AffectiveMomentum AffectiveMomentum Spinoza — affect as transition (velocity + acceleration)
MoodField MoodField Heidegger §29 — slow-moving global mood with inertia
AppraisalVector AppraisalVector Scherer CPM — emotion from evaluation (5 dimensions)
ResonanceLinks ResonanceLink Aristotle/Bower/Collins & Loftus/Hebb — bidirectional associative graph (5 link types), multi-hop spreading activation + Hebbian co-retrieval strengthening

See Research for full theoretical foundations.

Tutorials

Guides

Research status

  • Current Evidence — what is validated today, what is only early controlled evidence, and what still needs stronger studies
  • Limitations — current empirical and architectural gaps
  • Benchmarks — fidelity, performance tables, appraisal quality