Design doc: conversation memory layer (#86)

[vahid-ahmadi]

Summary

Design doc (no implementation) for issue #86: persist a structured active scenario (household + reform + comparison baseline) across turns within a conversation, so follow-ups like "what if they were married?" mutate one field instead of forcing the agent to re-derive the whole household from scrollback. The doc is grounded in the current code — the streaming loop and prompt assembly in backend/routes/chatbot.py, the tool dispatch/definitions in backend/agent_tools.py, the chat_conversations persistence in backend/routes/conversations.py, and the input chrome in frontend/src/app/ChatPage.tsx — with file:line references throughout. Tagged needs-design; opening in PR form for discussion before any code.

TL;DR of the recommended approach

• One active_scenario per conversation, owned by the client and resent each turn — mirrors how messages already round-trip (client-owns-state), so no second/racing DB writer.
• Two tools, get_scenario / update_scenario(patch), added to TOOL_DEFINITIONS, but handled in the chat loop (not in execute_tool) because they touch per-conversation state and execute_tool is intentionally stateless. update_scenario shallow-merges (household merged one level deeper).
• Live scenario snapshot injected as a per-turn system block after the cache breakpoints in _build_system_blocks (same pattern as Plan/Charts directives) — the agent sees prior state for free and is robust to a missed write; static behavioural rules go in the cached SYSTEM_PROMPT.
• Persistence: one nullable active_scenario TEXT column on chat_conversations, added via the existing idempotent ensure_table ALTER pattern; round-trips through save/load/share and the done SSE event + chat request.
• UI: a one-line "Active scenario" pill in the existing toggle row beside Plan/Charts, click-through to a modal with the full JSON + reset.
• Schema is advisory (not Pydantic-validated) in v1, keyed to match _build_compiled_policy / typed-tool args so it slots into Register the three dormant typed tools (UK) #55/Add uk_python typed tools (run_economy_simulation) to fix B1 reform failures #97 once those land.
• Shippable in 3 small PRs (backend plumbing → persistence round-trip → pill UI), plus optional polish.

Key open questions flagged for the team

1. Granularity — recommend per-conversation (not per-message); explicit "fork" later.
2. Display — pill one-liner vs full-structure modal.
3. Plan-mode interaction — Plan mode structurally omits tools, so the agent can read but not patch the scenario in Plan mode; argued this is correct, needs only a directive wording tweak.
4. Vs typed tools (Register the three dormant typed tools (UK) #55/Land typed reform tools to short-circuit reform-API guessing (track PR #55) #81/Add uk_python typed tools (run_economy_simulation) to fix B1 reform failures #97) — keep the reform/household shape aligned with the typed-tool args; sequence this after/alongside them so the schema doesn't get redone.

Refs #86

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
policyengine-uk-chat	Ready	Preview, Comment	Jun 8, 2026 8:17am

[github-actions]

Beta preview is ready.

• Frontend: open preview
• Backend: open backend