Skip to main content

Slice 11 — AI Conversation Memory

The in-app AI Support bubble. Operator clicks the bottom-right bubble and asks any question. Helm answers using the bible (this site), the shop's D1, and the operator's recent conversation history. Per-customer opt-out, per-shop budget cap, audit-logged.

Status: Schema done. Claude API integration not wired.

Drafted from planning · v0.1

Scope​

  • ai_conversations, ai_messages
  • AI Support bubble UI (always-present bottom-right)
  • Claude adapter (src/lib/claude.js)
  • Grounding builder (Worker)
  • Bible RAG (lexical search against bible chunks; vector later)
  • Per-customer opt-out enforcement
  • Per-shop budget cap enforcement
  • Audit logging of conversations

Schema​

  • ai_conversations(id, staff_id, customer_id?, started_at, last_at, total_tokens, total_cost_cents)
  • ai_messages(id, conversation_id, role, content_json, tokens_in, tokens_out, cost_cents, at)

role is user, assistant, or tool. content_json includes text + tool calls + tool results.

Endpoints​

  • POST /api/ai/query — start or continue a conversation
  • GET /api/ai/conversations — list (operator's recent)
  • GET /api/ai/conversations/:id — full transcript
  • DELETE /api/ai/conversations/:id — delete (right-to-erase)

UI​

AI Support bubble:

  • Always present at bottom-right of every screen
  • Click to expand a conversation pane
  • Type a question; streamed response appears
  • Citations link back to bible pages
  • "New conversation" button

In customer profile:

  • "AI: opted out" badge if customers.ai_optout = 1
  • Toggle clickable in edit mode

In Settings → Shop:

  • AI budget per month (default $25)
  • Current month's spend
  • "Pause AI" toggle

Grounding payload (per query)​

{
  current_screen: 'service',
  customer: customer_id ? safeFields(customer) : null,
  ticket: ticket_id ? fetchTicket(ticket_id) : null,
  recent_transactions: customer_id ? fetchRecent(10) : [],
  bible_chunks: searchBible(question, 20),
  conversation_history: lastMessages(8)
}

safeFields strips PII when customer.ai_optout = 1.

Tool use​

Claude can request d1_query tool calls for arbitrary structured queries. Worker validates SQL (no DDL, no DML, parameterized only, capped 1000 rows) before executing. Tool-use loops bounded to 5 iterations.

What's not yet built​

  • Claude adapter
  • Grounding builder
  • Bible chunking pipeline + KV index
  • Bubble UI
  • Budget cap enforcement
  • Daily spend tracker

Acceptance criteria​

  • Operator asks "what did Bob buy last spring?" → answer with citations within 3s
  • Question about Helm itself ("how does the kanban work?") answered from bible
  • Per-customer opt-out is enforced (test: opt out, ask, verify no PII in payload)
  • Budget cap pauses AI for the rest of the month with a polite UI message

See also​