From 584a5116f3f12fea66666632d46d990baf4da993 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 16 Jul 2026 01:19:13 +0000
Subject: [PATCH 1/2] Add usage instrumentation for feature/command adoption
 reporting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every keep-vs-cut decision on the roadmap so far has been a guess. Adds
an append-only usage_events table + record_usage() helper, logged from
every agent tool call (agent/main.py's _run_tools) and every UI-only
mutation that bypasses the agent entirely (expense/income edit/delete,
CSV export, budget set/delete in api/server.py).

Chat requests now carry an optional `source` tag (chip:<label>,
command:<cmd>, or omitted for freeform typing) threaded from Chat.jsx,
so a suggestion-chip click is distinguishable from someone typing the
same words — the two are identical server-side otherwise.

No third-party analytics vendor: this is household financial data, so
the log stays in our own Postgres, records only structural event names/
sources, and never message content or expense/income descriptions.
scripts/usage_report.py gives a simple breakdown for periodic review
instead of building a dashboard UI nobody's asked for yet.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qz6JBNFwhgem5GY3i2BEMY
---
 agent/db.py                      | 55 ++++++++++++++++++++++++++++++++
 agent/main.py                    | 12 ++++---
 api/server.py                    | 16 +++++++++-
 frontend/src/components/Chat.jsx | 10 +++---
 scripts/seed_e2e_data.py         |  2 +-
 scripts/usage_report.py          | 41 ++++++++++++++++++++++++
 tests/conftest.py                |  2 +-
 tests/test_api.py                | 20 ++++++++++--
 tests/test_db.py                 | 42 ++++++++++++++++++++++++
 9 files changed, 185 insertions(+), 15 deletions(-)
 create mode 100644 scripts/usage_report.py

diff --git a/agent/db.py b/agent/db.py
index e41af26..bee8b0b 100644
--- a/agent/db.py
+++ b/agent/db.py
@@ -119,6 +119,23 @@ def _row(r: dict) -> dict:
     )
 """)
 
+# Append-only usage log for feature/command adoption reporting (see
+# scripts/usage_report.py) — deliberately no event payload beyond a
+# structural name/source, never message content or expense/income
+# descriptions, since this is financial household data.
+_run("""
+    CREATE TABLE IF NOT EXISTS usage_events (
+        id         SERIAL PRIMARY KEY,
+        user_id    INTEGER REFERENCES users(id),
+        event_type TEXT NOT NULL,
+        event_name TEXT NOT NULL,
+        source     TEXT,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+    )
+""")
+
+_run("CREATE INDEX IF NOT EXISTS usage_events_name_idx ON usage_events (event_name)")
+
 
 def get_user_by_username(username: str) -> dict | None:
     cur = _run("SELECT * FROM users WHERE username = %s", (username,))
@@ -898,3 +915,41 @@ def increment_api_call_count(user_id: int, date: str) -> None:
         """,
         (user_id, date),
     )
+
+
+def record_usage(user_id: int | None, event_type: str, event_name: str, source: str | None = None) -> None:
+    """Best-effort usage logging — never let a logging failure break the
+    actual request it's attached to (an edit/delete/tool-call succeeding
+    is what matters; the analytics record is secondary)."""
+    try:
+        _run(
+            "INSERT INTO usage_events (user_id, event_type, event_name, source) VALUES (%s, %s, %s, %s)",
+            (user_id, event_type, event_name, source),
+        )
+    except Exception:
+        pass
+
+
+def get_usage_summary(since: str | None = None) -> list[dict]:
+    """Event counts grouped by type/name/source, for scripts/usage_report.py."""
+    if since:
+        cur = _run(
+            """
+            SELECT event_type, event_name, source, COUNT(*) AS count
+            FROM usage_events
+            WHERE created_at >= %s
+            GROUP BY event_type, event_name, source
+            ORDER BY count DESC
+            """,
+            (since,),
+        )
+    else:
+        cur = _run(
+            """
+            SELECT event_type, event_name, source, COUNT(*) AS count
+            FROM usage_events
+            GROUP BY event_type, event_name, source
+            ORDER BY count DESC
+            """
+        )
+    return [dict(r) for r in cur.fetchall()]
diff --git a/agent/main.py b/agent/main.py
index 1c60167..1a47adb 100644
--- a/agent/main.py
+++ b/agent/main.py
@@ -6,6 +6,7 @@
 import anthropic
 from dotenv import load_dotenv
 
+from agent import db
 from agent.categories import CATEGORY_HINTS, INCOME_CATEGORY_HINTS
 from agent.tools import TOOL_DEFINITIONS, TOOL_HANDLERS
 
@@ -192,7 +193,7 @@ def _build_user_content(user_input: str, images: list[dict] | None) -> str:
     return "\n\n".join(parts)
 
 
-def _run_tools(response_content: list, user_id: int, on_result=None) -> list:
+def _run_tools(response_content: list, user_id: int, on_result=None, source: str | None = None) -> list:
     # Every tool_use block below MUST produce a tool_result, even if the
     # handler raises. The assistant message containing these tool_use blocks
     # is already appended to the persistent session history by the caller
@@ -215,6 +216,7 @@ def _run_tools(response_content: list, user_id: int, on_result=None) -> list:
             except Exception:
                 logger.error("tool %s(%s) failed:\n%s", block.name, kwargs, traceback.format_exc())
                 result = {"status": "error", "message": f"{block.name} failed unexpectedly — tell the user and don't retry automatically."}
+            db.record_usage(user_id, "tool", block.name, source)
             print(f"[tool] {block.name}({kwargs}) -> {result}")
             if on_result:
                 on_result(block.name, result)
@@ -230,7 +232,7 @@ def clear_session(user_id: int) -> None:
     _sessions.pop(str(user_id), None)
 
 
-def chat(user_input: str, user_id: int, username: str = "user", images: list[dict] | None = None) -> str:
+def chat(user_input: str, user_id: int, username: str = "user", images: list[dict] | None = None, source: str | None = None) -> str:
     messages = _sessions.setdefault(str(user_id), [])
     _repair_dangling_tool_use(messages)
     content = _build_user_content(user_input, images)
@@ -260,11 +262,11 @@ def chat(user_input: str, user_id: int, username: str = "user", images: list[dic
                     return block.text
 
         if response.stop_reason == "tool_use":
-            tool_results = _run_tools(response.content, user_id)
+            tool_results = _run_tools(response.content, user_id, source=source)
             messages.append({"role": "user", "content": tool_results})
 
 
-def stream_chat(user_input: str, user_id: int, username: str = "user", images: list[dict] | None = None):
+def stream_chat(user_input: str, user_id: int, username: str = "user", images: list[dict] | None = None, source: str | None = None):
     messages = _sessions.setdefault(str(user_id), [])
     _repair_dangling_tool_use(messages)
     if images:
@@ -320,7 +322,7 @@ def _capture_rich_result(name, result):
                 if name == "get_category_breakdown":
                     rich_events.append({"breakdown": result})
 
-            tool_results = _run_tools(final.content, user_id, on_result=_capture_rich_result)
+            tool_results = _run_tools(final.content, user_id, on_result=_capture_rich_result, source=source)
             messages.append({"role": "user", "content": tool_results})
             yield from rich_events
 
diff --git a/api/server.py b/api/server.py
index 7ab80cb..346a5f8 100644
--- a/api/server.py
+++ b/api/server.py
@@ -26,6 +26,7 @@
     get_recurring_expenses,
     get_user_by_username,
     increment_api_call_count,
+    record_usage,
     set_budget,
     update_expense,
     update_income,
@@ -85,6 +86,12 @@ class ImageInput(BaseModel):
 class ChatRequest(BaseModel):
     message: str
     images: list[ImageInput] | None = None
+    # Where this message came from — a suggested chip, a slash command, or
+    # freeform typing (default). Lets usage reporting tell "clicked /budget"
+    # apart from "typed the same words", which look identical server-side
+    # otherwise. Frontend-supplied and unvalidated (analytics only, never
+    # used for auth/business logic), so no enum constraint here.
+    source: str | None = None
 
 
 def _images_payload(req: ChatRequest) -> list[dict] | None:
@@ -99,7 +106,7 @@ def chat_stream_endpoint(
 ):
     def generate():
         try:
-            for event in stream_chat(req.message, user_id, username, _images_payload(req)):
+            for event in stream_chat(req.message, user_id, username, _images_payload(req), req.source):
                 yield f"data: {json.dumps(event)}\n\n"
         except Exception:
             logger.error("stream_chat error:\n%s", traceback.format_exc())
@@ -167,11 +174,13 @@ def insights_endpoint(user_id: int = Depends(get_current_user)):
 
 @app.put("/budgets/{category}")
 def set_budget_endpoint(category: str, req: BudgetRequest, user_id: int = Depends(get_current_user)):
+    record_usage(user_id, "ui", "set_budget")
     return set_budget(category, req.monthly_limit)
 
 
 @app.delete("/budgets/{category}")
 def delete_budget_endpoint(category: str, user_id: int = Depends(get_current_user)):
+    record_usage(user_id, "ui", "delete_budget")
     return delete_budget(category)
 
 
@@ -202,6 +211,7 @@ def validate_category(cls, v):
 
 @app.patch("/expenses/{id}")
 def update_expense_endpoint(id: int, req: UpdateRequest, user_id: int = Depends(get_current_user)):
+    record_usage(user_id, "ui", "update_expense")
     result = update_expense(id, req.amount, req.category, req.description, req.date, req.flagged)
     if result.get("status") == "not_found":
         raise HTTPException(status_code=404, detail="Expense not found")
@@ -210,6 +220,7 @@ def update_expense_endpoint(id: int, req: UpdateRequest, user_id: int = Depends(
 
 @app.delete("/expenses/{id}")
 def delete_expense_endpoint(id: int, user_id: int = Depends(get_current_user)):
+    record_usage(user_id, "ui", "delete_expense")
     result = delete_expense(id)
     if result.get("status") == "not_found":
         raise HTTPException(status_code=404, detail="Expense not found")
@@ -232,6 +243,7 @@ def validate_category(cls, v):
 
 @app.patch("/income/{id}")
 def update_income_endpoint(id: int, req: IncomeUpdateRequest, user_id: int = Depends(get_current_user)):
+    record_usage(user_id, "ui", "update_income")
     result = update_income(id, req.amount, req.category, req.description, req.date)
     if result.get("status") == "not_found":
         raise HTTPException(status_code=404, detail="Income entry not found")
@@ -240,6 +252,7 @@ def update_income_endpoint(id: int, req: IncomeUpdateRequest, user_id: int = Dep
 
 @app.delete("/income/{id}")
 def delete_income_endpoint(id: int, user_id: int = Depends(get_current_user)):
+    record_usage(user_id, "ui", "delete_income")
     result = delete_income(id)
     if result.get("status") == "not_found":
         raise HTTPException(status_code=404, detail="Income entry not found")
@@ -248,6 +261,7 @@ def delete_income_endpoint(id: int, user_id: int = Depends(get_current_user)):
 
 @app.get("/expenses/export")
 def expenses_export(user_id: int = Depends(get_current_user)):
+    record_usage(user_id, "ui", "export_csv")
     rows = get_expenses()
     output = io.StringIO()
     writer = csv.DictWriter(
diff --git a/frontend/src/components/Chat.jsx b/frontend/src/components/Chat.jsx
index e6949b2..dda7e5a 100644
--- a/frontend/src/components/Chat.jsx
+++ b/frontend/src/components/Chat.jsx
@@ -288,7 +288,7 @@ export default function Chat({ onExpenseChange, className = "", token, username,
     setImages((prev) => prev.filter((_, i) => i !== index));
   };
 
-  const sendMessage = async (text, displayText = null) => {
+  const sendMessage = async (text, displayText = null, source = null) => {
     if (!text || loading) return;
     if (!hasOnboarded) {
       localStorage.setItem(onboardedKey, "1");
@@ -338,6 +338,7 @@ export default function Chat({ onExpenseChange, className = "", token, username,
           images: attachedImages.length
             ? attachedImages.map((img) => ({ data: img.data, media_type: img.mediaType }))
             : null,
+          source,
         }),
         signal: controller.signal,
       });
@@ -404,7 +405,7 @@ export default function Chat({ onExpenseChange, className = "", token, username,
 
   const runCommand = (cmd) => {
     setInput("");
-    sendMessage(cmd.prompt, cmd.label);
+    sendMessage(cmd.prompt, cmd.label, `command:${cmd.command}`);
   };
 
   const send = () => {
@@ -430,7 +431,8 @@ export default function Chat({ onExpenseChange, className = "", token, username,
     const start = `${year}-${String(now.getMonth() + 1).padStart(2, "0")}-01`;
     sendMessage(
       `Summarize my expenses from ${start} to today. Show a breakdown by category with amounts, a total, and one observation about my spending.`,
-      `Summarize ${month} ${year}`
+      `Summarize ${month} ${year}`,
+      "chip:monthly_summary"
     );
   };
 
@@ -643,7 +645,7 @@ export default function Chat({ onExpenseChange, className = "", token, username,
             {suggestions.map((s) => (
               <button
                 key={s.label}
-                onClick={() => sendMessage(s.prompt, s.label)}
+                onClick={() => sendMessage(s.prompt, s.label, `chip:${s.label}`)}
                 className="text-xs px-3 py-1.5 rounded-full border border-input text-foreground hover:bg-muted transition-colors"
               >
                 {s.label}
diff --git a/scripts/seed_e2e_data.py b/scripts/seed_e2e_data.py
index 4546384..a03ade6 100644
--- a/scripts/seed_e2e_data.py
+++ b/scripts/seed_e2e_data.py
@@ -65,7 +65,7 @@ def _today_minus(days: int) -> str:
 
 
 def seed():
-    _run("TRUNCATE expenses, income, budgets, users, api_calls RESTART IDENTITY CASCADE")
+    _run("TRUNCATE expenses, income, budgets, users, api_calls, usage_events RESTART IDENTITY CASCADE")
 
     create_user(E2E_USERNAME, bcrypt.hashpw(E2E_PASSWORD.encode(), bcrypt.gensalt()).decode())
     cur = _run("SELECT id FROM users WHERE username = %s", (E2E_USERNAME,))
diff --git a/scripts/usage_report.py b/scripts/usage_report.py
new file mode 100644
index 0000000..82c07aa
--- /dev/null
+++ b/scripts/usage_report.py
@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+"""Prints a breakdown of usage_events — which tools/commands/UI actions
+actually get used, and which chat messages came from a chip/slash command
+vs freeform typing. Run periodically (e.g. monthly) to inform keep/cut
+decisions instead of guessing. Usage:
+
+    uv run python scripts/usage_report.py            # all-time
+    uv run python scripts/usage_report.py --since 2026-06-01
+"""
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from agent.db import get_usage_summary  # noqa: E402
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--since", help="ISO date (e.g. 2026-06-01) — only include events on/after this date")
+    args = parser.parse_args()
+
+    rows = get_usage_summary(since=args.since)
+    if not rows:
+        print("No usage events recorded" + (f" since {args.since}" if args.since else "") + ".")
+        return
+
+    total = sum(r["count"] for r in rows)
+    print(f"{'EVENT':<28} {'SOURCE':<32} {'COUNT':>6}   %")
+    print("-" * 72)
+    for r in rows:
+        pct = 100 * r["count"] / total
+        source = r["source"] or "(direct)"
+        print(f"{r['event_name']:<28} {source:<32} {r['count']:>6}   {pct:4.1f}%")
+    print("-" * 72)
+    print(f"{'TOTAL':<61} {total:>6}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/conftest.py b/tests/conftest.py
index 70f7502..4dc9ef3 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -11,7 +11,7 @@
 
 @pytest.fixture(autouse=True)
 def clean_db():
-    db._run("TRUNCATE expenses, income, budgets, users, api_calls RESTART IDENTITY CASCADE")
+    db._run("TRUNCATE expenses, income, budgets, users, api_calls, usage_events RESTART IDENTITY CASCADE")
     yield
 
 
diff --git a/tests/test_api.py b/tests/test_api.py
index b57df42..5fd97b1 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -235,7 +235,7 @@ def test_chat_clear_endpoint(auth_headers, user_id):
 
 
 def test_chat_stream_endpoint_streams_chunks(monkeypatch, auth_headers):
-    def fake_stream_chat(message, user_id, username, images):
+    def fake_stream_chat(message, user_id, username, images, source):
         yield {"text": "Hello"}
         yield {"text": " world"}
 
@@ -249,7 +249,7 @@ def fake_stream_chat(message, user_id, username, images):
 
 
 def test_chat_stream_endpoint_forwards_tool_status_events(monkeypatch, auth_headers):
-    def fake_stream_chat(message, user_id, username, images):
+    def fake_stream_chat(message, user_id, username, images, source):
         yield {"status": "Saving expense…"}
         yield {"text": "Done!"}
 
@@ -262,8 +262,22 @@ def fake_stream_chat(message, user_id, username, images):
     assert "Saving expense" in response.text
 
 
+def test_chat_stream_endpoint_forwards_source_to_stream_chat(monkeypatch, auth_headers):
+    captured = {}
+
+    def fake_stream_chat(message, user_id, username, images, source):
+        captured["source"] = source
+        yield {"text": "ok"}
+
+    monkeypatch.setattr(server, "stream_chat", fake_stream_chat)
+
+    client.post("/chat/stream", json={"message": "hi", "source": "command:/budget"}, headers=auth_headers)
+
+    assert captured["source"] == "command:/budget"
+
+
 def test_chat_stream_endpoint_reports_error_on_exception(monkeypatch, auth_headers):
-    def fake_stream_chat(message, user_id, username, images):
+    def fake_stream_chat(message, user_id, username, images, source):
         yield {"text": "partial"}
         raise RuntimeError("boom")
 
diff --git a/tests/test_db.py b/tests/test_db.py
index 070709f..250eeb7 100644
--- a/tests/test_db.py
+++ b/tests/test_db.py
@@ -910,3 +910,45 @@ def test_increment_api_call_count_is_per_day(user_id):
     db.increment_api_call_count(user_id, "2026-06-28")
     assert db.get_api_call_count(user_id, "2026-06-27") == 1
     assert db.get_api_call_count(user_id, "2026-06-28") == 1
+
+
+# --- usage_events / record_usage -------------------------------------------
+
+def test_record_usage_appears_in_summary(user_id):
+    db.record_usage(user_id, "tool", "save_expense", "freeform")
+
+    summary = db.get_usage_summary()
+
+    assert summary == [{"event_type": "tool", "event_name": "save_expense", "source": "freeform", "count": 1}]
+
+
+def test_get_usage_summary_groups_by_type_name_and_source(user_id):
+    db.record_usage(user_id, "tool", "save_expense", "freeform")
+    db.record_usage(user_id, "tool", "save_expense", "freeform")
+    db.record_usage(user_id, "tool", "save_expense", "chip:Summarize this month")
+    db.record_usage(user_id, "ui", "delete_expense", None)
+
+    summary = db.get_usage_summary()
+
+    counts = {(row["event_type"], row["event_name"], row["source"]): row["count"] for row in summary}
+    assert counts[("tool", "save_expense", "freeform")] == 2
+    assert counts[("tool", "save_expense", "chip:Summarize this month")] == 1
+    assert counts[("ui", "delete_expense", None)] == 1
+
+
+def test_get_usage_summary_since_filters_out_older_events(user_id):
+    db.record_usage(user_id, "tool", "save_expense", "freeform")
+    db._run("UPDATE usage_events SET created_at = '2026-01-01' WHERE event_name = 'save_expense'")
+    db.record_usage(user_id, "ui", "delete_expense", None)
+
+    summary = db.get_usage_summary(since="2026-06-01")
+
+    names = {row["event_name"] for row in summary}
+    assert names == {"delete_expense"}
+
+
+def test_record_usage_swallows_errors_instead_of_raising():
+    # A nonexistent user_id violates the FK constraint — record_usage must not
+    # propagate that, since a logging failure should never break the request
+    # it's attached to (e.g. a tool call that otherwise succeeded).
+    db.record_usage(999999, "tool", "save_expense", "freeform")

From fa09249a50bbdd2a4e93f00fdd06c00de5f4ccac Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 16 Jul 2026 01:31:50 +0000
Subject: [PATCH 2/2] Externalize chat session state from process memory to
 Postgres
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Chat history lived in an in-process dict keyed by user_id, so every
redeploy or restart silently dropped every in-progress conversation —
users would just see the agent "forget" everything with no error. Adds
a chat_sessions table (one row per user, messages as JSONB) and
load/save/clear functions in agent/db.py; chat()/stream_chat() now load
at the start of a turn and save after every mutation point, so a crash
mid-turn is recoverable the same way _repair_dangling_tool_use already
recovers in-process failures — now across restarts too, which was the
actual point of this change.

Two things fell out of doing this properly rather than as a drop-in
storage swap:

- Assistant turns previously stored live Anthropic SDK response objects
  directly. Persisting requires plain dicts, so content blocks are now
  normalized via a duck-typed _serialize_block() at append time. That
  also exposed a latent bug in _repair_dangling_tool_use: its type check
  used getattr(), which only ever worked because in-memory sessions were
  never reloaded from a serialized form. Fixed to dict-style access.
- A naive load-then-save round trip can lose messages if the same user
  fires two overlapping requests (double-tap, two tabs) — today's
  in-memory dict can't, since both requests share the same list object.
  Added a per-user threading.Lock around each turn to close the
  same-instance case, which is the actual deployment; true cross-instance
  locking would need a DB-level lock and isn't worth it before this
  scales past a household.

tests/test_agent.py's session-corruption tests previously poked
main._sessions directly and used made-up user_ids; chat_sessions has a
real FK to users like every other user-scoped table, so those are
migrated to a new user_id_factory fixture and to seeding state via
db.save_chat_session instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qz6JBNFwhgem5GY3i2BEMY
---
 agent/db.py         |  34 +++++++
 agent/main.py       | 234 ++++++++++++++++++++++++++------------------
 tests/conftest.py   |  19 +++-
 tests/test_agent.py | 174 ++++++++++++++++++++++----------
 tests/test_api.py   |   5 +-
 5 files changed, 314 insertions(+), 152 deletions(-)

diff --git a/agent/db.py b/agent/db.py
index bee8b0b..c3f21ad 100644
--- a/agent/db.py
+++ b/agent/db.py
@@ -136,6 +136,20 @@ def _row(r: dict) -> dict:
 
 _run("CREATE INDEX IF NOT EXISTS usage_events_name_idx ON usage_events (event_name)")
 
+# Chat session history, externalized from the in-process dict it used to
+# live in (agent/main.py's old _sessions) — that dict silently dropped every
+# in-progress conversation on every redeploy/restart, since nothing survived
+# process memory. One row per user; the whole message list is replaced on
+# every save rather than appended in SQL, since the caller always has the
+# full up-to-date list in hand already.
+_run("""
+    CREATE TABLE IF NOT EXISTS chat_sessions (
+        user_id    INTEGER PRIMARY KEY REFERENCES users(id),
+        messages   JSONB NOT NULL DEFAULT '[]',
+        updated_at TIMESTAMPTZ DEFAULT NOW()
+    )
+""")
+
 
 def get_user_by_username(username: str) -> dict | None:
     cur = _run("SELECT * FROM users WHERE username = %s", (username,))
@@ -930,6 +944,26 @@ def record_usage(user_id: int | None, event_type: str, event_name: str, source:
         pass
 
 
+def load_chat_session(user_id: int) -> list:
+    cur = _run("SELECT messages FROM chat_sessions WHERE user_id = %s", (user_id,))
+    row = cur.fetchone()
+    return row["messages"] if row else []
+
+
+def save_chat_session(user_id: int, messages: list) -> None:
+    _run(
+        """
+        INSERT INTO chat_sessions (user_id, messages, updated_at) VALUES (%s, %s, NOW())
+        ON CONFLICT (user_id) DO UPDATE SET messages = EXCLUDED.messages, updated_at = NOW()
+        """,
+        (user_id, psycopg2.extras.Json(messages)),
+    )
+
+
+def clear_chat_session(user_id: int) -> None:
+    _run("DELETE FROM chat_sessions WHERE user_id = %s", (user_id,))
+
+
 def get_usage_summary(since: str | None = None) -> list[dict]:
     """Event counts grouped by type/name/source, for scripts/usage_report.py."""
     if since:
diff --git a/agent/main.py b/agent/main.py
index 1a47adb..8415923 100644
--- a/agent/main.py
+++ b/agent/main.py
@@ -1,5 +1,6 @@
 import logging
 import os
+import threading
 import traceback
 from datetime import date
 
@@ -76,8 +77,26 @@
 {category_hints}"""
 
 
-# Conversation history keyed by user_id.
-_sessions: dict[str, list] = {}
+# Conversation history is persisted in Postgres (agent/db.py's chat_sessions
+# table), not kept in process memory — an in-memory dict here used to drop
+# every in-progress conversation on every redeploy/restart. One lock per
+# user_id serializes that user's own concurrent requests (e.g. a double-tap,
+# or two tabs) around the load -> mutate -> save round trip, so one request's
+# save can't silently clobber another's; this only guards same-instance
+# concurrency, which is the actual deployment today — true cross-instance
+# locking would need a DB-level lock and isn't worth it at this scale yet.
+_session_locks: dict[str, threading.Lock] = {}
+_session_locks_guard = threading.Lock()
+
+
+def _get_session_lock(user_id: int) -> threading.Lock:
+    key = str(user_id)
+    with _session_locks_guard:
+        if key not in _session_locks:
+            _session_locks[key] = threading.Lock()
+        return _session_locks[key]
+
+
 HISTORY_LIMIT = 30   # max messages passed to the API per turn
 _SESSION_CAP = 120   # trim stored history once it exceeds this to prevent unbounded growth
 API_TIMEOUT = 120.0  # seconds before giving up on a Claude API call
@@ -121,20 +140,35 @@ def _trim_session(messages: list) -> None:
         messages[:] = messages[-HISTORY_LIMIT:]
 
 
+def _serialize_block(block) -> dict:
+    """Normalize one response content block to a plain JSON-serializable
+    dict. In production this is always an Anthropic SDK pydantic object
+    (has model_dump()); test doubles use plain dicts or SimpleNamespace.
+    Required both to persist assistant turns to Postgres and to keep
+    _repair_dangling_tool_use's dict-style access correct now that history
+    can come from a DB reload rather than always being this process's own
+    freshly-returned API response."""
+    if isinstance(block, dict):
+        return block
+    if hasattr(block, "model_dump"):
+        return block.model_dump()
+    return dict(vars(block))
+
+
 def _repair_dangling_tool_use(messages: list) -> None:
     """Drop a trailing assistant tool_use turn that never got its tool_result
     appended. This can only happen from a session that was corrupted by a
     since-fixed bug (a tool handler exception used to abort _run_tools before
-    it appended the matching tool_result) — but since _sessions lives only in
-    memory, any session already in that broken state stays broken forever
-    without this: every future turn would keep failing the same way, since
+    it appended the matching tool_result) — but since sessions are persisted,
+    any session already in that broken state stays broken forever without
+    this: every future turn would keep failing the same way, since
     Anthropic's API rejects a tool_use block with no following tool_result.
     Safe going forward too, in case some other future bug reintroduces the
     same failure mode."""
     if not messages:
         return
     last = messages[-1]
-    if last.get("role") == "assistant" and any(getattr(b, "type", None) == "tool_use" for b in last.get("content", [])):
+    if last.get("role") == "assistant" and any(b.get("type") == "tool_use" for b in last.get("content", [])):
         messages.pop()
 
 
@@ -229,102 +263,110 @@ def _run_tools(response_content: list, user_id: int, on_result=None, source: str
 
 
 def clear_session(user_id: int) -> None:
-    _sessions.pop(str(user_id), None)
+    db.clear_chat_session(user_id)
 
 
 def chat(user_input: str, user_id: int, username: str = "user", images: list[dict] | None = None, source: str | None = None) -> str:
-    messages = _sessions.setdefault(str(user_id), [])
-    _repair_dangling_tool_use(messages)
-    content = _build_user_content(user_input, images)
-    _append_user_turn(messages, content)
-    _trim_session(messages)
-
-    while True:
-        response = client.messages.create(
-            model=MODEL_DEFAULT,
-            max_tokens=2048,
-            timeout=API_TIMEOUT,
-            system=SYSTEM.format(
-                today=date.today().isoformat(),
-                username=username,
-                category_hints=CATEGORY_HINTS,
-                income_category_hints=INCOME_CATEGORY_HINTS,
-            ),
-            tools=TOOL_DEFINITIONS,
-            messages=messages[-HISTORY_LIMIT:],
-        )
-
-        messages.append({"role": "assistant", "content": response.content})
-
-        if response.stop_reason == "end_turn":
-            for block in response.content:
-                if hasattr(block, "text"):
-                    return block.text
-
-        if response.stop_reason == "tool_use":
-            tool_results = _run_tools(response.content, user_id, source=source)
-            messages.append({"role": "user", "content": tool_results})
+    with _get_session_lock(user_id):
+        messages = db.load_chat_session(user_id)
+        _repair_dangling_tool_use(messages)
+        content = _build_user_content(user_input, images)
+        _append_user_turn(messages, content)
+        _trim_session(messages)
+        db.save_chat_session(user_id, messages)
+
+        while True:
+            response = client.messages.create(
+                model=MODEL_DEFAULT,
+                max_tokens=2048,
+                timeout=API_TIMEOUT,
+                system=SYSTEM.format(
+                    today=date.today().isoformat(),
+                    username=username,
+                    category_hints=CATEGORY_HINTS,
+                    income_category_hints=INCOME_CATEGORY_HINTS,
+                ),
+                tools=TOOL_DEFINITIONS,
+                messages=messages[-HISTORY_LIMIT:],
+            )
+
+            messages.append({"role": "assistant", "content": [_serialize_block(b) for b in response.content]})
+            db.save_chat_session(user_id, messages)
+
+            if response.stop_reason == "end_turn":
+                for block in response.content:
+                    if hasattr(block, "text"):
+                        return block.text
+
+            if response.stop_reason == "tool_use":
+                tool_results = _run_tools(response.content, user_id, source=source)
+                messages.append({"role": "user", "content": tool_results})
+                db.save_chat_session(user_id, messages)
 
 
 def stream_chat(user_input: str, user_id: int, username: str = "user", images: list[dict] | None = None, source: str | None = None):
-    messages = _sessions.setdefault(str(user_id), [])
-    _repair_dangling_tool_use(messages)
-    if images:
-        yield {"status": "Reading image…" if len(images) == 1 else "Reading images…"}
-    content = _build_user_content(user_input, images)
-    _append_user_turn(messages, content)
-    _trim_session(messages)
-
-    last_char = ""
-    while True:
-        with client.messages.stream(
-            model=MODEL_DEFAULT,
-            max_tokens=2048,
-            timeout=API_TIMEOUT,
-            system=SYSTEM.format(
-                today=date.today().isoformat(),
-                username=username,
-                category_hints=CATEGORY_HINTS,
-                income_category_hints=INCOME_CATEGORY_HINTS,
-            ),
-            tools=TOOL_DEFINITIONS,
-            messages=messages[-HISTORY_LIMIT:],
-        ) as stream:
-            first_chunk_of_turn = True
-            for chunk in stream.text_stream:
-                if not chunk:
-                    continue
-                # Each turn streams independently, so the model can end one turn
-                # with "...today." and start the next (post-tool_use) with "Done!"
-                # with no space in between. Only check at the turn boundary —
-                # chunks within a single turn are exact slices of one continuous
-                # string and always join up correctly on their own.
-                if first_chunk_of_turn and last_char and not last_char.isspace() and not chunk[0].isspace():
-                    yield {"text": " "}
-                yield {"text": chunk}
-                last_char = chunk[-1]
-                first_chunk_of_turn = False
-            final = stream.get_final_message()
-
-        messages.append({"role": "assistant", "content": final.content})
-
-        if final.stop_reason == "end_turn":
-            break
-
-        if final.stop_reason == "tool_use":
-            for block in final.content:
-                if block.type == "tool_use":
-                    yield {"status": TOOL_STATUS_LABELS.get(block.name, "Working…")}
-
-            rich_events = []
-
-            def _capture_rich_result(name, result):
-                if name == "get_category_breakdown":
-                    rich_events.append({"breakdown": result})
-
-            tool_results = _run_tools(final.content, user_id, on_result=_capture_rich_result, source=source)
-            messages.append({"role": "user", "content": tool_results})
-            yield from rich_events
+    with _get_session_lock(user_id):
+        messages = db.load_chat_session(user_id)
+        _repair_dangling_tool_use(messages)
+        if images:
+            yield {"status": "Reading image…" if len(images) == 1 else "Reading images…"}
+        content = _build_user_content(user_input, images)
+        _append_user_turn(messages, content)
+        _trim_session(messages)
+        db.save_chat_session(user_id, messages)
+
+        last_char = ""
+        while True:
+            with client.messages.stream(
+                model=MODEL_DEFAULT,
+                max_tokens=2048,
+                timeout=API_TIMEOUT,
+                system=SYSTEM.format(
+                    today=date.today().isoformat(),
+                    username=username,
+                    category_hints=CATEGORY_HINTS,
+                    income_category_hints=INCOME_CATEGORY_HINTS,
+                ),
+                tools=TOOL_DEFINITIONS,
+                messages=messages[-HISTORY_LIMIT:],
+            ) as stream:
+                first_chunk_of_turn = True
+                for chunk in stream.text_stream:
+                    if not chunk:
+                        continue
+                    # Each turn streams independently, so the model can end one turn
+                    # with "...today." and start the next (post-tool_use) with "Done!"
+                    # with no space in between. Only check at the turn boundary —
+                    # chunks within a single turn are exact slices of one continuous
+                    # string and always join up correctly on their own.
+                    if first_chunk_of_turn and last_char and not last_char.isspace() and not chunk[0].isspace():
+                        yield {"text": " "}
+                    yield {"text": chunk}
+                    last_char = chunk[-1]
+                    first_chunk_of_turn = False
+                final = stream.get_final_message()
+
+            messages.append({"role": "assistant", "content": [_serialize_block(b) for b in final.content]})
+            db.save_chat_session(user_id, messages)
+
+            if final.stop_reason == "end_turn":
+                break
+
+            if final.stop_reason == "tool_use":
+                for block in final.content:
+                    if block.type == "tool_use":
+                        yield {"status": TOOL_STATUS_LABELS.get(block.name, "Working…")}
+
+                rich_events = []
+
+                def _capture_rich_result(name, result):
+                    if name == "get_category_breakdown":
+                        rich_events.append({"breakdown": result})
+
+                tool_results = _run_tools(final.content, user_id, on_result=_capture_rich_result, source=source)
+                messages.append({"role": "user", "content": tool_results})
+                db.save_chat_session(user_id, messages)
+                yield from rich_events
 
 
 if __name__ == "__main__":
diff --git a/tests/conftest.py b/tests/conftest.py
index 4dc9ef3..b95db4f 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -11,7 +11,7 @@
 
 @pytest.fixture(autouse=True)
 def clean_db():
-    db._run("TRUNCATE expenses, income, budgets, users, api_calls, usage_events RESTART IDENTITY CASCADE")
+    db._run("TRUNCATE expenses, income, budgets, users, api_calls, usage_events, chat_sessions RESTART IDENTITY CASCADE")
     yield
 
 
@@ -19,3 +19,20 @@ def clean_db():
 def user_id():
     db.create_user("testuser", "not-a-real-hash")
     return db.get_user_by_username("testuser")["id"]
+
+
+@pytest.fixture
+def user_id_factory():
+    """Creates a fresh real user per call, returning its id. Use in place of
+    a bare literal int wherever a test needs several distinct isolated
+    user_ids (e.g. separate chat sessions) — chat_sessions.user_id has a real
+    FK to users, so a made-up int would fail to save a session at all."""
+    counter = {"n": 0}
+
+    def _make() -> int:
+        counter["n"] += 1
+        username = f"testuser_{counter['n']}"
+        db.create_user(username, "not-a-real-hash")
+        return db.get_user_by_username(username)["id"]
+
+    return _make
diff --git a/tests/test_agent.py b/tests/test_agent.py
index ba3680a..f8efaf4 100644
--- a/tests/test_agent.py
+++ b/tests/test_agent.py
@@ -1,6 +1,6 @@
 import types
 
-from agent import main
+from agent import db, main
 
 
 def make_block(type_, **kwargs):
@@ -125,12 +125,48 @@ def failing_handler(**kw):
     assert results[2]["content"] == str({"ok": True})
 
 
+# --- _serialize_block --------------------------------------------------------
+# Required for persisting assistant turns to Postgres — a live Anthropic SDK
+# response block in production, but test doubles are plain dicts or
+# SimpleNamespace, so this must handle all three shapes.
+
+def test_serialize_block_passes_through_plain_dicts():
+    block = {"type": "text", "text": "hi"}
+    assert main._serialize_block(block) is block
+
+
+def test_serialize_block_uses_model_dump_when_available():
+    class FakeSdkBlock:
+        def model_dump(self):
+            return {"type": "tool_use", "id": "t1", "name": "save_expense", "input": {}}
+
+    assert main._serialize_block(FakeSdkBlock()) == {"type": "tool_use", "id": "t1", "name": "save_expense", "input": {}}
+
+
+def test_serialize_block_falls_back_to_vars_for_simplenamespace():
+    block = make_block("text", text="hi")
+    assert main._serialize_block(block) == {"type": "text", "text": "hi"}
+
+
+# --- _get_session_lock --------------------------------------------------------
+
+def test_get_session_lock_returns_same_lock_for_same_user_id():
+    assert main._get_session_lock(123) is main._get_session_lock(123)
+
+
+def test_get_session_lock_returns_different_locks_for_different_user_ids():
+    assert main._get_session_lock(123) is not main._get_session_lock(456)
+
+
 # --- _repair_dangling_tool_use ---------------------------------------------
+# Content blocks here are plain dicts, not make_block()/SimpleNamespace —
+# that's what messages actually contain once persisted (see _serialize_block
+# above), and what _repair_dangling_tool_use's dict-style access expects.
 
 def test_repair_dangling_tool_use_drops_unresolved_trailing_assistant_message():
     messages = [
         {"role": "user", "content": "log $5 coffee"},
-        {"role": "assistant", "content": [make_block("tool_use", name="save_expense", input={}, id="tool_1")]},
+        {"role": "assistant", "content": [{"type": "tool_use", "name": "save_expense", "input": {}, "id": "tool_1"}]},
     ]
 
     main._repair_dangling_tool_use(messages)
@@ -141,7 +177,7 @@ def test_repair_dangling_tool_use_drops_unresolved_trailing_assistant_message():
 def test_repair_dangling_tool_use_leaves_resolved_history_untouched():
     messages = [
         {"role": "user", "content": "log $5 coffee"},
-        {"role": "assistant", "content": [make_block("tool_use", name="save_expense", input={}, id="tool_1")]},
+        {"role": "assistant", "content": [{"type": "tool_use", "name": "save_expense", "input": {}, "id": "tool_1"}]},
         {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "tool_1", "content": "{}"}]},
     ]
     original = list(messages)
@@ -154,7 +190,7 @@ def test_repair_dangling_tool_use_leaves_resolved_history_untouched():
 def test_repair_dangling_tool_use_leaves_plain_text_turn_untouched():
     messages = [
         {"role": "user", "content": "hi"},
-        {"role": "assistant", "content": [make_block("text", text="Hello!")]},
+        {"role": "assistant", "content": [{"type": "text", "text": "Hello!"}]},
     ]
     original = list(messages)
 
@@ -170,7 +206,7 @@ def test_repair_dangling_tool_use_on_empty_session_is_a_noop():
 # --- _append_user_turn ------------------------------------------------------
 
 def test_append_user_turn_appends_after_an_assistant_message():
-    messages = [{"role": "assistant", "content": [make_block("text", text="hi")]}]
+    messages = [{"role": "assistant", "content": [{"type": "text", "text": "hi"}]}]
 
     main._append_user_turn(messages, "new message")
 
@@ -221,18 +257,18 @@ def test_append_user_turn_merges_into_a_trailing_tool_results_list_too():
     }]
 
 
-def test_chat_self_heals_a_session_corrupted_mid_multi_round_tool_use(monkeypatch):
+def test_chat_self_heals_a_session_corrupted_mid_multi_round_tool_use(monkeypatch, user_id_factory):
     # The realistic shape of the reported bug: round 1 (lookups) resolved
     # normally, round 2 (saves) is where a handler crashed, leaving a
     # dangling assistant message whose *preceding* user message is a
     # tool_results list from round 1, not a plain string.
-    main.clear_session(10)
-    main._sessions["10"] = [
+    uid = user_id_factory()
+    db.save_chat_session(uid, [
         {"role": "user", "content": "log these 16 transactions"},
-        {"role": "assistant", "content": [make_block("tool_use", name="find_similar_expense", input={}, id="lookup_1")]},
+        {"role": "assistant", "content": [{"type": "tool_use", "name": "find_similar_expense", "input": {}, "id": "lookup_1"}]},
         {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "lookup_1", "content": "[]"}]},
-        {"role": "assistant", "content": [make_block("tool_use", name="save_expense", input={}, id="tool_orphan")]},
-    ]
+        {"role": "assistant", "content": [{"type": "tool_use", "name": "save_expense", "input": {}, "id": "tool_orphan"}]},
+    ])
     captured = {}
 
     def fake_create(**kw):
@@ -241,7 +277,7 @@ def fake_create(**kw):
 
     monkeypatch.setattr(main.client.messages, "create", fake_create)
 
-    result = main.chat("try again", user_id=10)
+    result = main.chat("try again", user_id=uid)
 
     assert result == "Logged it"
     sent = captured["messages"]
@@ -249,7 +285,7 @@ def fake_create(**kw):
     assert sent[-1]["content"][-1] == {"type": "text", "text": "try again"}
 
 
-def test_chat_self_heals_a_session_corrupted_by_the_old_bug(monkeypatch):
+def test_chat_self_heals_a_session_corrupted_by_the_old_bug(monkeypatch, user_id_factory):
     # Simulates a session left over from before _run_tools caught handler
     # exceptions: an assistant tool_use turn with no tool_result ever
     # appended after it, which used to make every future turn fail with
@@ -257,11 +293,11 @@ def test_chat_self_heals_a_session_corrupted_by_the_old_bug(monkeypatch):
     # forever. chat() must drop that dangling turn before sending history,
     # and must not just trade that error for a role-alternation error by
     # leaving two consecutive user messages behind.
-    main.clear_session(9)
-    main._sessions["9"] = [
+    uid = user_id_factory()
+    db.save_chat_session(uid, [
         {"role": "user", "content": "log these 16 transactions"},
-        {"role": "assistant", "content": [make_block("tool_use", name="save_expense", input={}, id="tool_orphan")]},
-    ]
+        {"role": "assistant", "content": [{"type": "tool_use", "name": "save_expense", "input": {}, "id": "tool_orphan"}]},
+    ])
     captured = {}
 
     def fake_create(**kw):
@@ -270,15 +306,15 @@ def fake_create(**kw):
 
     monkeypatch.setattr(main.client.messages, "create", fake_create)
 
-    result = main.chat("try again", user_id=9)
+    result = main.chat("try again", user_id=uid)
 
     assert result == "Logged it"
     sent = captured["messages"]
     # The orphaned assistant tool_use message must not be in what gets sent.
     sent_ids = [
-        b.id for m in sent if m["role"] == "assistant"
+        b["id"] for m in sent if m["role"] == "assistant"
         for b in (m["content"] if isinstance(m["content"], list) else [])
-        if getattr(b, "type", None) == "tool_use"
+        if b.get("type") == "tool_use"
     ]
     assert "tool_orphan" not in sent_ids
     # Roles must strictly alternate — no two consecutive same-role messages.
@@ -289,30 +325,33 @@ def fake_create(**kw):
 
 # --- clear_session ---------------------------------------------------------
 
-def test_clear_session_removes_history():
-    main._sessions["7"] = [{"role": "user", "content": "hi"}]
-    main.clear_session(7)
-    assert "7" not in main._sessions
+def test_clear_session_removes_history(user_id_factory):
+    uid = user_id_factory()
+    db.save_chat_session(uid, [{"role": "user", "content": "hi"}])
+
+    main.clear_session(uid)
+
+    assert db.load_chat_session(uid) == []
 
 
 def test_clear_session_on_unknown_user_is_a_noop():
-    main.clear_session(999999)
+    main.clear_session(999999)  # DELETE on a non-matching row is a no-op, must not raise
 
 
 # --- chat() ------------------------------------------------------------
 
-def test_chat_returns_text_on_end_turn(monkeypatch):
-    main.clear_session(1)
+def test_chat_returns_text_on_end_turn(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     response = make_response([make_block("text", text="Hello there")], "end_turn")
     monkeypatch.setattr(main.client.messages, "create", lambda **kw: response)
 
-    result = main.chat("hi", user_id=1)
+    result = main.chat("hi", user_id=uid)
 
     assert result == "Hello there"
 
 
-def test_chat_runs_tool_then_returns_final_text(monkeypatch):
-    main.clear_session(2)
+def test_chat_runs_tool_then_returns_final_text(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     monkeypatch.setitem(main.TOOL_HANDLERS, "get_expenses", lambda **kw: [])
 
     tool_block = make_block("tool_use", name="get_expenses", input={}, id="tool_1")
@@ -326,12 +365,43 @@ def fake_create(**kw):
 
     monkeypatch.setattr(main.client.messages, "create", fake_create)
 
-    result = main.chat("what did I spend?", user_id=2)
+    result = main.chat("what did I spend?", user_id=uid)
 
     assert result == "No expenses found"
     assert responses == []
 
 
+def test_chat_persists_conversation_to_the_database(monkeypatch, user_id_factory):
+    # The whole point of externalizing session storage: nothing about this
+    # depends on process memory, so it survives a restart between requests.
+    # This test can't simulate an actual restart, but proves the underlying
+    # mechanism — everything chat() needs is read back correctly from what a
+    # prior call wrote, not from anything still sitting in memory.
+    uid = user_id_factory()
+    response = make_response([make_block("text", text="Hello there")], "end_turn")
+    monkeypatch.setattr(main.client.messages, "create", lambda **kw: response)
+
+    main.chat("hi", user_id=uid)
+
+    saved = db.load_chat_session(uid)
+    assert saved[0] == {"role": "user", "content": "hi"}
+    assert saved[1]["role"] == "assistant"
+    assert saved[1]["content"] == [{"type": "text", "text": "Hello there"}]
+
+
+def test_chat_appends_to_previously_persisted_history_across_calls(monkeypatch, user_id_factory):
+    uid = user_id_factory()
+    response = make_response([make_block("text", text="ok")], "end_turn")
+    monkeypatch.setattr(main.client.messages, "create", lambda **kw: response)
+
+    main.chat("first message", user_id=uid)
+    main.chat("second message", user_id=uid)
+
+    saved = db.load_chat_session(uid)
+    user_texts = [m["content"] for m in saved if m["role"] == "user" and isinstance(m["content"], str)]
+    assert user_texts == ["first message", "second message"]
+
+
 # --- stream_chat() -------------------------------------------------------
 
 class FakeStream:
@@ -353,18 +423,18 @@ def __exit__(self, *exc):
         return False
 
 
-def test_stream_chat_yields_text_chunks_on_end_turn(monkeypatch):
-    main.clear_session(3)
+def test_stream_chat_yields_text_chunks_on_end_turn(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     final = make_response([make_block("text", text="Hi!")], "end_turn")
     monkeypatch.setattr(main.client.messages, "stream", lambda **kw: FakeStream(["Hi", "!"], final))
 
-    events = list(main.stream_chat("hello", user_id=3))
+    events = list(main.stream_chat("hello", user_id=uid))
 
     assert events == [{"text": "Hi"}, {"text": "!"}]
 
 
-def test_stream_chat_runs_tool_then_streams_final_text(monkeypatch):
-    main.clear_session(4)
+def test_stream_chat_runs_tool_then_streams_final_text(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     monkeypatch.setitem(main.TOOL_HANDLERS, "get_expenses", lambda **kw: [])
 
     tool_block = make_block("tool_use", name="get_expenses", input={}, id="tool_1")
@@ -378,7 +448,7 @@ def fake_stream(**kw):
 
     monkeypatch.setattr(main.client.messages, "stream", fake_stream)
 
-    events = list(main.stream_chat("what did I spend?", user_id=4))
+    events = list(main.stream_chat("what did I spend?", user_id=uid))
 
     assert events == [
         {"status": "Looking up expenses…"},
@@ -388,8 +458,8 @@ def fake_stream(**kw):
     assert streams == []
 
 
-def test_stream_chat_emits_breakdown_event_for_category_breakdown_tool(monkeypatch):
-    main.clear_session(9)
+def test_stream_chat_emits_breakdown_event_for_category_breakdown_tool(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     breakdown_result = {
         "breakdown": [{"category": "Dining", "total": 42.0, "count": 3, "pct": 100.0}],
         "grand_total": 42.0,
@@ -407,7 +477,7 @@ def fake_stream(**kw):
 
     monkeypatch.setattr(main.client.messages, "stream", fake_stream)
 
-    events = list(main.stream_chat("breakdown please", user_id=9))
+    events = list(main.stream_chat("breakdown please", user_id=uid))
 
     assert events == [
         {"status": "Calculating breakdown…"},
@@ -416,8 +486,8 @@ def fake_stream(**kw):
     ]
 
 
-def test_stream_chat_emits_status_for_unmapped_tool(monkeypatch):
-    main.clear_session(7)
+def test_stream_chat_emits_status_for_unmapped_tool(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     monkeypatch.setitem(main.TOOL_HANDLERS, "some_new_tool", lambda **kw: [])
 
     tool_block = make_block("tool_use", name="some_new_tool", input={}, id="tool_1")
@@ -431,24 +501,24 @@ def fake_stream(**kw):
 
     monkeypatch.setattr(main.client.messages, "stream", fake_stream)
 
-    events = list(main.stream_chat("do something new", user_id=7))
+    events = list(main.stream_chat("do something new", user_id=uid))
 
     assert events[0] == {"status": "Working…"}
 
 
-def test_stream_chat_emits_status_for_images(monkeypatch):
-    main.clear_session(8)
+def test_stream_chat_emits_status_for_images(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     final = make_response([make_block("text", text="Logged!")], "end_turn")
     monkeypatch.setattr(main.client.messages, "stream", lambda **kw: FakeStream(["Logged!"], final))
     monkeypatch.setattr(main, "_ocr_image", lambda data, media_type: "Total: $5")
 
-    events = list(main.stream_chat("log this", user_id=8, images=[{"data": "x", "media_type": "image/png"}]))
+    events = list(main.stream_chat("log this", user_id=uid, images=[{"data": "x", "media_type": "image/png"}]))
 
     assert events[0] == {"status": "Reading image…"}
 
 
-def test_stream_chat_inserts_space_between_turns_missing_one(monkeypatch):
-    main.clear_session(5)
+def test_stream_chat_inserts_space_between_turns_missing_one(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     monkeypatch.setitem(main.TOOL_HANDLERS, "get_expenses", lambda **kw: [])
 
     tool_block = make_block("tool_use", name="get_expenses", input={}, id="tool_1")
@@ -462,14 +532,14 @@ def fake_stream(**kw):
 
     monkeypatch.setattr(main.client.messages, "stream", fake_stream)
 
-    events = list(main.stream_chat("log two expenses", user_id=5))
+    events = list(main.stream_chat("log two expenses", user_id=uid))
     text = "".join(e["text"] for e in events if "text" in e)
 
     assert text == "I'll log both today. Done!"
 
 
-def test_stream_chat_does_not_double_space_when_turn_already_ends_in_space(monkeypatch):
-    main.clear_session(6)
+def test_stream_chat_does_not_double_space_when_turn_already_ends_in_space(monkeypatch, user_id_factory):
+    uid = user_id_factory()
     monkeypatch.setitem(main.TOOL_HANDLERS, "get_expenses", lambda **kw: [])
 
     tool_block = make_block("tool_use", name="get_expenses", input={}, id="tool_2")
@@ -483,7 +553,7 @@ def fake_stream(**kw):
 
     monkeypatch.setattr(main.client.messages, "stream", fake_stream)
 
-    events = list(main.stream_chat("log an expense", user_id=6))
+    events = list(main.stream_chat("log an expense", user_id=uid))
     text = "".join(e["text"] for e in events if "text" in e)
 
     assert text == "Logging it. Done!"
diff --git a/tests/test_api.py b/tests/test_api.py
index 5fd97b1..1b1169d 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -222,13 +222,12 @@ def test_expenses_export_returns_csv(auth_headers, user_id):
 # --- chat/clear -------------------------------------------------------------
 
 def test_chat_clear_endpoint(auth_headers, user_id):
-    from agent import main
-    main._sessions[str(user_id)] = [{"role": "user", "content": "hi"}]
+    db.save_chat_session(user_id, [{"role": "user", "content": "hi"}])
 
     response = client.post("/chat/clear", headers=auth_headers)
 
     assert response.status_code == 200
-    assert str(user_id) not in main._sessions
+    assert db.load_chat_session(user_id) == []
 
 
 # --- /chat, /chat/stream wiring (mocked agent layer) ------------------------