Summary

Closes #147 (assistant phase 2b). The conversational assistant now reads the user's twin profile (preferences + inferences) and recent episodic memories before composing each reply, so it can answer the two killer use cases that distinguish a personal twin from generic ChatGPT:

• "What did I tell you about X last month?"
• "What's my preference for Y?"

What landed

ContextBuilder in @skytwin/assistant

Composes a compact context block prepended to the system prompt:

```

What I know about you

Trust tier: moderate_autonomy
Preferences:

• email/auto_archive = yes (high)
• calendar/default_meeting_length = 30 (confirmed)
  Inferences (not yet user-confirmed):
• finance/monthly_subscription_threshold = 50 (high) — based on 12 prior approvals

Relevant past episodes

• [2026-04-12] email · Archived a Stripe receipt without asking · auto-archive (approved)
  ```

Two ports keep the @skytwin/assistant package free of @skytwin/db / @skytwin/mempalace deps and unit-testable with stubs:

Design choices:

• Hard cap at 2KB with UTF-8-clean ellipsis truncation. Noisy profile + long memory hits can't dominate the model's token budget.
• Confidence floor — only confirmed / high / moderate surface. Speculative + low entries stay in the twin model but don't broadcast (would make the assistant look unsure of itself).
• Confidence-ranked truncation — highest-confidence wins MAX_PREFERENCES = 12 / MAX_INFERENCES = 6 / MAX_MEMORIES = 5 slots.
• Boolean values render as yes/no instead of true/false. More readable for both the model and anyone debugging via prompt logs.
• Partial-context fallback — if either provider throws, the other still renders. console.warn records which side failed; the request continues with whatever was retrievable.
• No-op on empty — empty result from both providers returns '', which AssistantService treats as "use the default system prompt unchanged" — same behavior as phase 1, no surprises for early bring-up paths without context.

AssistantService.reply() now takes optional enrichment

New optional 2nd param enrichment?: { userId, query }. Backward-compatible: omitting it OR omitting the ctor builder falls back to the bare default system prompt — phase 1 callers compile unchanged.

Wiring

• apps/api/src/routes/assistant.ts constructs a ContextBuilder once per process. enrichment.query is the just-sent user message — that's what the assistant is about to answer, so the most-relevant memories are the ones that match it.
• The memory adapter splits the query into ≥3-char tokens and calls mempalaceRepository.searchEpisodes — same backing as MemoryStack.search L3. Stop-words and short tokens drop so a query like "the plan for X" doesn't ILIKE-match every episode containing "the".
• Episode outcome JSON blobs collapse to a one-line label (kind / status / result field if present, else short stringification) so the rendered context stays compact.

Safety / invariants

• Trust boundary — the rendered context is text only, prepended to the system prompt. No user-controlled strings flow through it: preferences and inferences come from the twin model (which already tracks source and evidence), and episodic memory summary strings are written by the system itself, not by external senders. So even though we expand what the LLM sees, we don't expand the attack surface.
• Information leak — same don't-leak-existence semantics as phase 1; ownership middleware gates userId access; the new context endpoint isn't a thing — context is built server-side per request.
• Cost / latency — the 2KB cap puts a hard ceiling on token cost per request from this feature. Profile + memory fetches happen in parallel with Promise.all.

Test plan

• pnpm build — 20 packages green
• pnpm test — 40 packages green; 15 new tests (12 ContextBuilder + 4 AssistantService enrichment paths) on top of phase-1's 24
• pnpm lint — clean
• Manual: load #/assistant, ask the twin about its preferences (e.g. "do I auto-archive emails?") and verify it answers from the profile, not from generic priors
• Manual: with no profile data, verify the assistant still works (returns generic ChatGPT-style answers)
• Manual: pull the worker log during a request and verify the rendered system prompt contains the expected context block

Phase 2+ still in flight

• Assistant phase 2a: SSE streaming on POST /api/assistant/messages #146 SSE streaming
• Assistant phase 2c: action-intent routing through @skytwin/decision-engine #148 action-intent routing through the decision engine
• Assistant phase 3: multi-turn LlmClient API + drop prompt-flattening workaround #149 native multi-turn LlmClient API

🤖 Generated with Claude Code