┌─────────────────────────────────────────────────────────────────┐
│                  RECALLMEM MEMORY ARCHITECTURE                  │
│                  The LLM proposes, TypeScript decides.          │
│                  Retrieval is deterministic. Always.            │
└─────────────────────────────────────────────────────────────────┘

  YOU SEND A MESSAGE                READ PATH (deterministic)
  ──────────────────►       ┌──────────────────────────────┐
                            │  SQL pulls profile summary   │
                            │                              │
                            │  Smart fact selection:       │
                            │    1. Pinned identity/family │
                            │       facts (always included)│
                            │    2. Vector search on facts │
                            │       for what's relevant to │
                            │       your message           │
                            │    3. Recent facts fill the  │
                            │       remaining slots        │
                            │                              │
                            │  EmbeddingGemma converts     │
                            │    your message to a vector  │
                            │  pgvector cosine similarity  │
                            │    ranks past transcript     │
                            │    chunks (up to 8)          │
                            │                              │
                            │  TypeScript template builds  │
                            │    the system prompt         │
                            └──────────────┬───────────────┘
                                           │
                                           ▼
                            ┌──────────────────────────────┐
                            │   Your chosen LLM            │
                            │   (Gemma / Claude / GPT /    │
                            │    Grok / any compatible)    │
                            │   sees a fully-assembled     │
                            │   prompt with dated memory   │
                            └──────────────────────────────┘

  The LLM never queries the database. It cannot "decide" to
  retrieve something. It cannot hallucinate a memory that
  isn't there — if it's not in the prompt, it doesn't exist
  for the model.

═══════════════════════════════════════════════════════════════════
  AFTER EVERY ASSISTANT REPLY — LIVE FACT EXTRACTION
═══════════════════════════════════════════════════════════════════

  Stream closes
       │
       ▼  fire-and-forget, user never waits
  The same LLM you're chatting with reads the transcript
  AND the existing active facts. Returns a JSON object:
       {
         facts: ["new fact 1", "new fact 2"],
         supersedes: ["uuid-of-old-fact-that-no-longer-true"]
       }
       │
       ▼
  TypeScript validator (6 gates)
       │
       ├──► garbage filter (meta-observations,
       │    AI behavior notes, "hasn't shared", etc)
       ├──► JSON parse + type validation
       ├──► length / quality bar
       ├──► dedupe against entire facts table
       ├──► category routing (keyword + inflection,
       │    no LLM)
       └──► insert OR retire
              │
              ▼
  New facts are embedded (768-dim vector) for future
  semantic search. Old facts get is_active=false,
  valid_to=NOW(). History preserved. Active set always
  reflects current truth.
       │
       ▼
  recategorizeAllFacts() re-runs the router on every fact.
  Categories self-heal as the logic improves.
       │
       ▼
  rebuildProfile() synthesizes a structured profile from
  active facts. Each fact stamped with its valid_from date.

═══════════════════════════════════════════════════════════════════
  TEMPORAL CONTEXT — SOLVES THE COLLAPSE PROBLEM
═══════════════════════════════════════════════════════════════════

  Across conversations:  every active fact in the prompt is
                         stamped [YYYY-MM-DD]. Newer facts
                         override older ones if they conflict.

  Resumed conversations: chat last touched > 2 hours ago?
                         single system marker injected:
                         [Conversation resumed 6 days later]

  Retrieved chunks:      vector search results prefixed with
                         [from conversation on YYYY-MM-DD]
                         so the model can tell history from now.