Memory, Conversation & Workflows

1 The Memory Problem — LLMs Are Stateless

As noted in Guide 01: an LLM has no memory between calls. Every call to CompleteAsync() is independent. If a user tells the agent "My name is Alice" in turn 1, and then asks "What is my name?" in turn 5, Claude will not know the answer — unless the earlier turns are included in the prompt.

This project handles state in two separate ways:

The problem, made concrete — a 5-turn conversation without memory

Imagine a user has this conversation with the agent (no memory management). Notice what happens:

2 IMemoryStore — Storing Agent Knowledge

What kind of "knowledge" does an agent store? Not the full conversation — that is IConversationStore's job. IMemoryStore stores distilled facts that the agent has learned and wants to remember across many conversations. Think of it as the agent's notebook: short bullet points like "Alice prefers FedEx for international orders", "SKU-B often runs low in Q4", "This tenant's SLA allows 7 days, not 5".

Before the agent answers a question, it can call SearchAsync to pull the most relevant facts from its notebook and include them in the prompt. The agent gets smarter over time without retraining.

public interface IMemoryStore
{
    Task AddAsync(MemoryEntry entry, CancellationToken ct = default);
    Task<IReadOnlyList<MemoryEntry>> SearchAsync(string query, int topK = 5, ...);
    Task<IReadOnlyList<MemoryEntry>> GetAllAsync(...);
    Task<bool> DeleteAsync(string id, ...);
    Task<string> SummarizeAsync(...);
}

public class MemoryEntry
{
    public string   Id        { get; set; }  // unique ID (auto-generated)
    public string   Content   { get; set; }  // the fact being stored
    public string   Source    { get; set; }  // "agent", "user", "system"
    public string[] Keywords  { get; set; }  // used for similarity matching
    public DateTime CreatedAt { get; set; }
}

SearchAsync returns the most relevant memories for a given query, sorted by keyword overlap. An agent can call this before reasoning to pull in relevant context from past interactions.

3 MemoryConsolidator — Deduplicating Memories

If an agent stores many related facts ("SKU-A is low", "Stock for SKU-A is at 30 units", "SKU-A needs reorder"), the memory store fills up with near-duplicates. MemoryConsolidator merges entries that are too similar.

It uses Jaccard similarity on keywords: two entries with 50%+ keyword overlap are considered duplicates. The pivot entry absorbs the content of the duplicate:

// Jaccard similarity: size of intersection / size of union
public static double JaccardSimilarity(string[] a, string[] b)
{
    var setA        = new HashSet<string>(a, StringComparer.OrdinalIgnoreCase);
    var setB        = new HashSet<string>(b, StringComparer.OrdinalIgnoreCase);
    var intersection = setA.Intersect(setB).Count();
    var union        = setA.Union(setB).Count();
    return union == 0 ? 0 : (double)intersection / union;
}

Step-by-step Jaccard calculation — worked example

Say the agent has stored these two memory entries about the same situation:

// Entry A — stored from iteration 2:
Keywords: ["SKU-A", "low", "stock", "reorder"]
Content:  "SKU-A is running low and may need to be reordered"

// Entry B — stored from iteration 5:
Keywords: ["SKU-A", "stock", "threshold", "reorder"]
Content:  "SKU-A stock has fallen below the reorder threshold"

// Jaccard similarity:
setA        = { SKU-A, low, stock, reorder }
setB        = { SKU-A, stock, threshold, reorder }
intersection = { SKU-A, stock, reorder }         // 3 words in common
union        = { SKU-A, low, stock, reorder, threshold }  // 5 unique words total
score        = 3 / 5 = 0.60   // > 0.5 threshold → entries are merged

// After merge: Entry A absorbs B's content. Entry B is deleted.
// Result: one entry instead of two near-identical ones, saving memory and tokens.

4 IConversationStore — Multi-Turn Chat History

When a user has a multi-turn conversation with the agent, each turn must be stored so that on the next request, the agent can reload the history and send it all to Claude (remember: LLMs are stateless).

public interface IConversationStore
{
    // Start a new session (returns a GUID session ID)
    Task<string> CreateSessionAsync(string userId, string tenantId, ...);

    // Append a turn (user message or agent reply)
    Task AddTurnAsync(string sessionId, string role, string content, ...);

    // Reload the full history for a session
    Task<IReadOnlyList<ConversationTurn>> GetTurnsAsync(string sessionId, ...);
}

Two implementations

• InMemoryConversationStore — fast, no setup, data lost on restart. Used by default (Persistence.UseInMemory = true).
• SqliteConversationStore — persists to a SQLite file (nexaflow.db). Switch by setting Persistence.UseInMemory = false in appsettings.json. Data survives restarts.

SqliteConversationStore uses raw ADO.NET (not EF Core) and creates its own schema at startup if the tables do not exist. Two tables: Sessions and Turns.

When does switching to SQLite actually matter?

5 Workflows — Event-Driven Automation

What is event-driven automation? — plain English first

Imagine a warehouse coordinator who sits at a desk all day watching a dashboard. Whenever stock for SKU-A drops below 50 units, they pick up the phone and call the supplier to raise a purchase order. Whenever a delivery is late, they send an email to the account manager and raise a credit note.

Now imagine you replace that coordinator with a system: "Whenever event X happens, automatically run these steps." That is event-driven automation. No human needed to watch and react — the system detects the event and acts.

In this project:

• The event = a named string like "inventory_low" or "sla_breach", fired from anywhere in the code
• The action = a class that implements IWorkflow and says "when you hear inventory_low, run my ExecuteAsync method"
• The coordinator = WorkflowEngine, which holds a list of all workflows and routes events to the matching ones

The IWorkflow interface

public interface IWorkflow
{
    string Name    { get; }  // human-readable, e.g. "ReorderWorkflow"
    string Trigger { get; }  // event that activates this workflow, e.g. "inventory_low"
    Task<WorkflowResult> ExecuteAsync(WorkflowContext context, CancellationToken ct = default);
}

public class WorkflowContext
{
    public string                      TriggerName  { get; set; }
    public Dictionary<string,string> Payload      { get; set; }  // event data (sku, quantity, ...)
    public string?                     TenantId     { get; set; }
    public string?                     UserId       { get; set; }
    public DateTime                    TriggeredAt  { get; set; }
}

6 WorkflowEngine — Dispatching Events

WorkflowEngine receives all registered IWorkflow instances via DI. When TriggerAsync is called, it runs every workflow whose Trigger matches the event name (case-insensitive):

public async Task<List<WorkflowResult>> TriggerAsync(string trigger, WorkflowContext context, ...)
{
    var matching = _workflows
        .Where(w => string.Equals(w.Trigger, trigger, StringComparison.OrdinalIgnoreCase))
        .ToList();

    var results = new List<WorkflowResult>();
    foreach (var workflow in matching)
    {
        try
        {
            var result = await workflow.ExecuteAsync(context, ct);
            results.Add(result);
        }
        catch (Exception ex)
        {
            results.Add(new WorkflowResult { Success = false, Message = ex.Message });
        }
    }
    return results;
}

Adding a new workflow is two steps:

1. Create a class that implements IWorkflow.
2. Register it in Program.cs: builder.Services.AddSingleton<IWorkflow, MyWorkflow>();

7 The Two Built-In Workflows

Why these two specifically? They represent the two most common patterns in supply chain automation:

• ReorderWorkflow = a proactive action triggered by a supply event. Stock runs low → immediately create a PO. No human needs to notice the problem and remember to act.
• SlaBreachWorkflow = a reactive action triggered by a service failure. A delivery is late → automatically escalate and issue a credit. No human needs to monitor every shipment's ETA.

Together they show the two directions: catching problems before they happen (reorder) and responding to problems after they happen (SLA breach).

ReorderWorkflow

• Trigger: inventory_low
• What it does: Creates a simulated purchase order (AUTO-PO-XXXX) for the SKU specified in the event payload.
• Fires from: WebhookController when an order arrives with quantity > 100 (to simulate a large order draining inventory).

// WebhookController fires the trigger:
if (order.TotalQuantity > 100)
{
    await _workflowEngine.TriggerAsync("inventory_low", new WorkflowContext
    {
        TriggerName = "inventory_low",
        Payload     = new() { ["sku"] = firstSku, ["quantity"] = order.TotalQuantity.ToString() }
    });
}
// ReorderWorkflow creates AUTO-PO-0001, AUTO-PO-0002, etc.

SlaBreachWorkflow

• Trigger: sla_breach
• What it does: Creates an escalation ticket (ESC-XXXX) and a credit memo (CR-ESC-XXXX).
• Fires from: WorkflowController via the manual-trigger UI button.

8 Triggering Workflows — Two Ways

1. Automatically via webhook: POST /api/webhooks/orders → WebhookController → checks order quantity → WorkflowEngine.TriggerAsync("inventory_low", ...).
2. Manually via UI: The Workflows page (/Workflow) shows a button per trigger. Clicking it posts to WorkflowController.Trigger(), which calls WorkflowEngine.TriggerAsync().

9 Summary

• LLMs are stateless — you must store conversation history and memory externally, then re-inject them on each call.
• IMemoryStore stores agent-learned facts (searchable by keyword similarity). MemoryConsolidator deduplicates near-duplicate entries using Jaccard similarity.
• IConversationStore stores turn-by-turn chat history. Two implementations: in-memory (default) and SQLite (persistent).
• IWorkflow is a simple interface: a trigger name + an execute method.
• WorkflowEngine is an in-process event dispatcher: fire a trigger name → all matching workflows execute.
• ReorderWorkflow triggers on inventory_low; SlaBreachWorkflow triggers on sla_breach.
• Register new workflows with a single AddSingleton<IWorkflow, YourWorkflow>() line.