Engagement memory.

Why memory

A consultant without memory is a chatbot. What distinguishes Aria's experience from an ordinary chat is that she remembers the shape of the engagement — the hypotheses she's working through, the unknowns she's still chasing, the findings she's promoted out of earlier turns, and what week of the engagement this is.

That memory lives in Postgres in the EngagementState table. Every live chat request loads the caller org's row and composes it into the L8 layer of the system prompt. If no row exists, Aria treats the engagement as Week 1 and opens with orientation.

Schema

The state is one row per organization. The shape:

export interface EngagementStateData {
  weekNumber: number;            // 1-indexed engagement week
  hypotheses: Hypothesis[];      // active beliefs with evidence and confidence
  unknowns: Unknown[];           // open questions Aria is chasing
  findings: Finding[];           // hypotheses promoted into substantive findings
}

export interface Hypothesis {
  statement: string;             // the claim itself
  confidence: number;            // 0 .. 1
  evidence: string[];            // why we believe it so far
}

export interface Unknown {
  question: string;              // the open question
  whyItMatters: string;          // why answering it changes Aria's recommendation
}

export interface Finding {
  statement: string;             // the claim, now load-bearing
  source: string;                // who said it, on what date
  recordedAt: string;            // ISO timestamp
}

Hypothesis lifecycle

A hypothesis moves through four stages:

1. Form. Aria forms a falsifiable claim — "The largest unresolved dollar lever is in sales-to-ops handoffs, not inside Manufacturing." Initial confidence is seeded from the conversation that produced it.
2. Collect. Over subsequent turns, Aria accumulates evidence for or against. Each piece of evidence is a short attributable line ("user cited $4.1M on deal-approval handoffs in session 2").
3. Revise. Confidence rises or falls as evidence lands. Aria explicitly flags when evidence is mixed and names what would resolve it.
4. Promote or archive. When confidence exceeds a threshold and no contradicting evidence is outstanding, the hypothesis is promoted to a finding. If disconfirming evidence lands, the hypothesis is archived with a short note on why.

Week counter

weekNumber is the engagement's shape, not a calendar week. It starts at 1 when the EngagementState row is created and advances when the week's work is substantively complete — orientation, hypothesis collection, synthesis, and so on. The advance is governed by Aria's judgment during reflection, not by a cron.

A low week number biases Aria toward orientation questions and tight framings. A high week number biases toward synthesis, recommendation, and explicit uncertainty about what remains.

Mutation

Reading engagement state

The planned GET /api/engagement returns the caller org's row:

{
  "data": {
    "weekNumber": 4,
    "hypotheses": [
      {
        "statement": "The largest dollar lever is in Sales→Ops handoffs, not inside Manufacturing.",
        "confidence": 0.72,
        "evidence": [
          "User cited $4.1M on deal-approval handoffs in session 2.",
          "Diane Ortiz interview surfaced a structural coordination gap."
        ]
      }
    ],
    "unknowns": [
      {
        "question": "Is the Mfg Ops slowdown cultural or structural?",
        "whyItMatters": "Determines whether the fix is a process change or a comms rollout."
      }
    ],
    "findings": [
      {
        "statement": "Three new KPIs rolled out to the line floor without briefing.",
        "source": "Diane Ortiz, 2026-04-12",
        "recordedAt": "2026-04-12T15:22:00Z"
      }
    ]
  },
  "meta": { "requestId": "req_01HW…" }
}

Privacy posture

• Engagement state is scoped by orgId. A user cannot read or write another organization's state, by construction.
• Aria does not echo engagement state verbatim into responses; the layer is used to calibrate her reasoning, not recited.
• Evidence lines are stored as short prose; numeric claims follow the 3-tier benchmark discipline (L3) — user-shared numbers are attributed back, typical-range language is hedged, and no unsourced precise figure can enter the state.

Empty state

When EngagementState is null for an organization, the L8 layer emits a short "this is the first session" preamble and Aria begins with orientation. The first hypothesis is not formed until enough context has been gathered to state one that is falsifiable — a guardrail against rushing to judgment in Week 1.

Back to Agent architecture.