Skip to main content

Memory Concepts — Interactive Walkthrough

AiMOneHealth's clinical reasoning sits on top of a three-tier memory model: Episodic, Short-Term, and Long-Term. Functional teams need to know what each tier does; technical teams need to know how data moves between them. This page covers both with two interactive walkthroughs — click Next to advance one step at a time, or hit Play for slower autoplay.

Controls — ◀ / ▶ buttons step manually · ▶ Play autoplays (default 3.5s/frame; pick from the Speed menu, slowest is 6s) · click any dot to jump · keyboard ← / → / Space when the panel has focus.

For the formal specification (collections, schemas, retention windows, the 19-flow legal-transition matrix), see memory-hierarchy. For the agent-loop view, see reasoning-flow.

Walkthrough 1 — How a single patient question touches all three tiers​

Dr. Vance asks her assistant: "What is the latest evidence for this patient's chemo regimen?" Step through to see how that single ask ripples across the memory model.

A single patient question — step by step
Step 1 of 5 — The question lands at the agent. No memory tier has been touched yet.Step 2 of 5 — Short-Term Memory captures the working set: patient_id scope, current question, prior turn. This is the agent's scratchpad for this turn.Step 3 of 5 — Long-Term Memory is consulted. Claims come back ranked by composite_k = confidence × freshness × evidence-tier.Step 4 of 5 — Episodic Memory records the access trail: WHO read WHAT, WHEN, under WHAT consent. Tamper-evident hash chain.Step 5 of 5 — Answer returned with evidence trail. Each tier keeps its own lifetime: Episodic = forever · STM = TTL · LTM = decays-as-it-ages.

Step 1 of 5 — The question lands at the agent. No memory tier has been touched yet.

Prefer an auto-looping GIF? Download the animated GIF. Use the buttons above (or ←/→/Space) to scrub frame-by-frame at your own pace.

Plain-English summary (functional team)​

  • Short-Term = the agent's working memory for this conversation. Forgotten on TTL.
  • Long-Term = what the system has learned — clinical claims with sources and confidence. Kept indefinitely while still relevant.
  • Episodic = the paper trail of every access. Auditors replay history from this; nothing else can.

Schema hooks (technical team)​

TierBacking collectionPHI handlingLifetime
Episodicaudit_eventsseq + prevHash + eventHash (RFC 8785 JCS + SHA-256); patient/user IDs only — never narrative6 years (HIPAA floor)
Short-Termmemory_short_term@phi_repository envelope encryption; pii_fields per row; patient_id scope requiredTTL via Mongo TTL index on expires_at
Long-Termmemory_claims, memory_entities, memory_relationshipsEnvelope-encrypted at the repository boundary; supersession on update; decay_at anonymization in placeIndefinite while Active

Walkthrough 2 — How data moves between the tiers​

The interesting part isn't the tiers themselves — it's the legal transitions. Five steps cover the four movements you'll see in production: write, consolidate, supersede, decay.

Data movement between tiers — step by step
Frame 1 of 5 — A new piece of evidence shows up (e.g., Researcher discovers an NCCN update). Nothing has been written yet.Frame 2 of 5 — Write to STM. Working observation lands with patient_id scope + TTL. Audit event recorded synchronously. PHI fields envelope-encrypted at the repository boundary.Frame 3 of 5 — STM → LTM consolidation. The observation graduates into a durable claim. Three triggers, one rule-set: explicit MemoryClient.consolidate() · age threshold · Critic-promote signal.Frame 4 of 5 — Supersession. Critic rejects an old claim. A new claim is created with supersedes=<old_id>; the old one flips Active → Superseded. Never an in-place rewrite.Frame 5 of 5 — Decay. STM rows expire on TTL. LTM claims that pass decay_at are anonymized in place (IDs stripped, content kept). Audit chain captures every transition — auditors replay history without ever rewriting it.

Frame 1 of 5 — A new piece of evidence shows up (e.g., Researcher discovers an NCCN update). Nothing has been written yet.

Prefer an auto-looping GIF? Download the animated GIF. Use the buttons above (or ←/→/Space) to scrub frame-by-frame at your own pace.

Why this design? (balanced view)​

PropertyBenefitTrade-off
Three tiers, separate storesLifetimes can differ — Episodic forever, STM minutes, LTM indefinite-but-decaying — without one tier's policy bleeding into anotherMore moving pieces; consolidation paths must be explicitly designed (and they are: 19-flow matrix in memory-hierarchy)
Append-only Episodic with hash chainTamper-evident; auditors replay rather than trustStorage grows monotonically; offsets via the 6-year retention window
Supersession instead of in-place editsEvery fact has a version history; no fact is silently rewrittenReads must filter state=Active; supersession chains add one indirection
Anonymization-in-place at decay_atLTM keeps the content (e.g., "metformin first-line for T2D") even after the patient/source identifiers are stripped, so the system gets smarter over timeAnonymization rule must be conservative — over-anonymize and the claim becomes useless

Illegal transitions (fail-closed)​

These will refuse to execute:

  • ❌ Source → Episodic bypassing the originating tier (every episodic event names a source tier).
  • ❌ STM → STM cross-scope (admin-only override).
  • ❌ LTM → LTM in-place content rewrite — corrections route through supersede, never PATCH.
  • ❌ Episodic → any writable tier — replay produces derived data, never mutates the chain.

Where this is implemented​

  • Spec 08 — Episodic + LTM original specification.
  • Spec 065 — STM tier + consolidation pipeline.
  • Spec 063 — Freshness + confidence scoring (drives composite_k).
  • Spec 064 — Numeric freshness scorer (drives decay_at).
  • Spec 066 — Self-improvement loop that ties Critic verdicts back to LTM supersession.