+-------------------------------------------------------------------------+
|                        2-TIER AGENT MEMORY FLOW                         |
+-------------------------------------------------------------------------+

   User Query ───► [ Ingestion & Token Gate ]
                            │
         ┌──────────────────┴──────────────────┐
         ▼                                     ▼
  [ Tier 1: Working Buffer ]          [ Tier 2: Episodic Store ]
  • Last N raw turns (FIFO)           • Extracted semantic facts
  • Immediate scratchpad              • Entity graph & preferences
  • Strict token budget (< 1.5k)      • pgvector / relational store
         │                                     │
         └──────────────────┬──────────────────┘
                            ▼
               [ Context Synthesis Engine ]
                            │
                            ▼
                  [ LLM Inference Turn ]
                            │
                            ▼
        [ Async Background Worker (Off-Thread) ]
        • Evaluates working buffer token pressure
        • Triggers deterministic compaction
        • Extracts entities -> updates Tier 2

// src/services/agent-memory.ts
import { z } from 'zod';
import { db } from '../db';
import { taskQueue } from '../queue';
import { callLLM } from '../llm';

interface MemoryContext {
  systemPrompt: string;
  longTermFacts: string[];
  workingHistory: Array<{ role: 'user' | 'assistant'; content: string }>;
}

const COMPACTION_THRESHOLD_TOKENS = 2000;
const TARGET_BUFFER_TOKENS = 800;

export class AgentMemoryManager {
  /**
   * Assembles the optimized prompt context within strict token boundaries
   */
  async assembleContext(sessionId: string, userId: string): Promise<MemoryContext> {
    // 1. Fetch persistent long-term entity facts
    const facts = await db.agentFacts.findMany({
      where: { userId },
      select: { fact: true },
      take: 10,
    });

    // 2. Fetch Tier 1 working buffer
    const rawTurns = await db.agentTurns.findMany({
      where: { sessionId },
      orderBy: { createdAt: 'desc' },
      take: 6,
    });

    const workingHistory = rawTurns.reverse().map((t) => ({
      role: t.role as 'user' | 'assistant',
      content: t.content,
    }));

    return {
      systemPrompt: "You are an enterprise operations assistant.",
      longTermFacts: facts.map((f) => f.fact),
      workingHistory,
    };
  }

  /**
   * Post-turn hook: Checks token pressure and delegates compaction off-thread
   */
  async handleTurnCompletion(sessionId: string, userId: string, currentTokenCount: number): Promise<void> {
    if (currentTokenCount > COMPACTION_THRESHOLD_TOKENS) {
      // Enqueue async compaction worker - DO NOT block the client response
      await taskQueue.push('compact-session-memory', {
        sessionId,
        userId,
      });
    }
  }
}

/**
 * Off-Thread Background Compactor Worker
 */
export async function processMemoryCompaction(payload: { sessionId: string; userId: string }) {
  const { sessionId, userId } = payload;

  // 1. Fetch older turns that exceed the active working threshold
  const turnsToCompact = await db.agentTurns.findMany({
    where: { sessionId, isCompacted: false },
    orderBy: { createdAt: 'asc' },
    take: 10,
  });

  if (turnsToCompact.length === 0) return;

  const transcript = turnsToCompact
    .map((t) => `<span class="inline-math px-1"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>t</mi><mi mathvariant="normal">.</mi><mi>r</mi><mi>o</mi><mi>l</mi><mi>e</mi><mi mathvariant="normal">.</mi><mi>t</mi><mi>o</mi><mi>U</mi><mi>p</mi><mi>p</mi><mi>e</mi><mi>r</mi><mi>C</mi><mi>a</mi><mi>s</mi><mi>e</mi><mo stretchy="false">(</mo><mo stretchy="false">)</mo></mrow><mo>:</mo></mrow><annotation encoding="application/x-tex">{t.role.toUpperCase()}:</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="katex-base"><span class="katex-strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord"><span class="mord mathnormal">t</span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.0278em;">r</span><span class="mord mathnormal">o</span><span class="mord mathnormal" style="margin-right:0.0197em;">l</span><span class="mord mathnormal">e</span><span class="mord">.</span><span class="mord mathnormal">t</span><span class="mord mathnormal">o</span><span class="mord mathnormal" style="margin-right:0.109em;">U</span><span class="mord mathnormal">pp</span><span class="mord mathnormal" style="margin-right:0.0278em;">er</span><span class="mord mathnormal" style="margin-right:0.0715em;">C</span><span class="mord mathnormal">a</span><span class="mord mathnormal">se</span><span class="mopen">(</span><span class="mclose">)</span></span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span></span>{t.content}`)
    .join('\n');

  // 2. Extract durable facts & state updates using structured output
  const extractionPrompt = `
Extract critical facts, user preferences, and business constraints from this transcript.
Return ONLY a JSON array of strings.

Transcript:
${transcript}`;

  const response = await callLLM({
    model: 'gpt-4o-mini', // Use low-cost model for compaction
    prompt: extractionPrompt,
    temperature: 0,
  });

  const extractedFacts: string[] = JSON.parse(response.content);

  // 3. Atomically persist facts and flag turns as compacted
  await db.$transaction([
    ...extractedFacts.map((fact) =>
      db.agentFacts.create({ data: { userId, sessionId, fact } })
    ),
    db.agentTurns.updateMany({
      where: { id: { in: turnsToCompact.map((t) => t.id) } },
      data: { isCompacted: true },
    }),
  ]);
}