feat: persistent chat

backend/main.py

@@ -241,6 +241,14 @@ async def list_files(_: None = Depends(auth.require_admin)) -> dict:
     return {"files": hf_sync.list_remote_pdfs()}
 
 
+@app.get("/documents")
+async def list_documents() -> dict:
+    """Public read-only list of uploaded course materials."""
+    if not hf_sync.is_configured():
+        return {"files": []}
+    return {"files": hf_sync.list_remote_pdfs()}
+
+
 # ---------------- Admin auth ----------------
 @app.post("/admin/login")
 async def admin_login(body: LoginRequest, response: Response) -> dict:

frontend/components/chat-interface.tsx

@@ -1,20 +1,31 @@
 "use client";
 import { useState, useRef, useEffect } from "react";
-import { Send, Loader2, BookOpen } from "lucide-react";
+import { BookOpen, FileText, Loader2, Plus, RefreshCw, Send, Trash2 } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Card, CardContent } from "@/components/ui/card";
 import { PersonaSelector } from "@/components/persona-selector";
 import { TemperatureSlider } from "@/components/temperature-slider";
-import { DEFAULT_PERSONAS, DEFAULT_PERSONA_ID, fetchPersonas, type Persona } from "@/lib/personas";
+import {
+  createConversation,
+  loadChatPreferences,
+  loadChatStore,
+  removeConversation,
+  saveChatPreferences,
+  saveChatStore,
+  titleFromMessages,
+  upsertConversation,
+  type ChatConversation,
+  type ChatMessage,
+} from "@/lib/chat-storage";
+import {
+  DEFAULT_PERSONAS,
+  DEFAULT_PERSONA_ID,
+  fetchPersonas,
+  type Persona,
+} from "@/lib/personas";
 
-type Msg = {
-  role: "user" | "assistant";
-  content: string;
-  reasoning?: string;
-  sources?: string[];
-  status?: string;
-};
+const DEFAULT_TEMPERATURE = 0.4;
 
 function latestThinkingPreview(reasoning: string) {
   const text = reasoning.trim();
@@ -22,40 +33,249 @@ function latestThinkingPreview(reasoning: string) {
   return text.length > 420 ? `...${text.slice(-420)}` : text;
 }
 
+function displayDate(value: string) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
+  return date.toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
 export function ChatInterface() {
   const [personas, setPersonas] = useState<Persona[]>(DEFAULT_PERSONAS);
-  const [persona, setPersona] = useState<Persona>(
-    DEFAULT_PERSONAS.find((p) => p.id === DEFAULT_PERSONA_ID) ?? DEFAULT_PERSONAS[0]
-  );
-  const [temperature, setTemperature] = useState(0.4);
-  const [messages, setMessages] = useState<Msg[]>([]);
+  const [documents, setDocuments] = useState<string[] | null>(null);
+  const [documentsError, setDocumentsError] = useState<string | null>(null);
+  const [activePersonaId, setActivePersonaId] = useState(DEFAULT_PERSONA_ID);
+  const [temperature, setTemperature] = useState(DEFAULT_TEMPERATURE);
+  const [conversations, setConversations] = useState<ChatConversation[]>([]);
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
   const [input, setInput] = useState("");
   const [busy, setBusy] = useState(false);
+  const [hydrated, setHydrated] = useState(false);
+
   const scrollRef = useRef<HTMLDivElement>(null);
+  const activeIdRef = useRef<string | null>(null);
+  const personaIdRef = useRef(activePersonaId);
+  const temperatureRef = useRef(temperature);
+
+  const persona =
+    personas.find((p) => p.id === activePersonaId) ??
+    personas.find((p) => p.id === DEFAULT_PERSONA_ID) ??
+    personas[0] ??
+    DEFAULT_PERSONAS[0];
+
+  useEffect(() => {
+    const store = loadChatStore();
+    const preferences = loadChatPreferences();
+    const active = store.conversations.find((conversation) => conversation.id === store.activeId);
+    const personaId = active?.personaId ?? preferences.personaId ?? DEFAULT_PERSONA_ID;
+    const nextTemperature = active?.temperature ?? preferences.temperature ?? DEFAULT_TEMPERATURE;
+
+    setConversations(store.conversations);
+    setActiveId(store.activeId);
+    setMessages(active?.messages ?? []);
+    setActivePersonaId(personaId);
+    setTemperature(nextTemperature);
+    activeIdRef.current = store.activeId;
+    personaIdRef.current = personaId;
+    temperatureRef.current = nextTemperature;
+    setHydrated(true);
+  }, []);
 
-  // Load live personas on mount
   useEffect(() => {
     fetchPersonas().then((list) => {
       setPersonas(list);
-      // Re-select same id if it still exists, otherwise pick default
-      setPersona((prev) => list.find((p) => p.id === prev.id) ?? list[0] ?? prev);
     });
   }, []);
 
+  async function loadDocuments() {
+    setDocumentsError(null);
+    try {
+      const response = await fetch("/api/documents");
+      if (!response.ok) throw new Error(await response.text());
+      const data = await response.json();
+      setDocuments(Array.isArray(data.files) ? data.files : []);
+    } catch (error) {
+      setDocuments([]);
+      setDocumentsError((error as Error).message);
+    }
+  }
+
+  useEffect(() => {
+    loadDocuments();
+  }, []);
+
+  useEffect(() => {
+    activeIdRef.current = activeId;
+  }, [activeId]);
+
+  useEffect(() => {
+    personaIdRef.current = activePersonaId;
+  }, [activePersonaId]);
+
+  useEffect(() => {
+    temperatureRef.current = temperature;
+  }, [temperature]);
+
+  useEffect(() => {
+    if (hydrated) saveChatStore({ activeId, conversations });
+  }, [activeId, conversations, hydrated]);
+
   useEffect(() => {
     scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight });
   }, [messages, busy]);
 
+  function ensureActiveConversation() {
+    const existing = conversations.find((conversation) => conversation.id === activeIdRef.current);
+    if (existing) return existing.id;
+
+    const conversation = createConversation(personaIdRef.current, temperatureRef.current);
+    activeIdRef.current = conversation.id;
+    setActiveId(conversation.id);
+    setConversations((prev) => upsertConversation(prev, conversation));
+    return conversation.id;
+  }
+
+  function commitMessages(conversationId: string, nextMessages: ChatMessage[]) {
+    setMessages(nextMessages);
+    setConversations((prev) => {
+      const existing =
+        prev.find((conversation) => conversation.id === conversationId) ??
+        createConversation(personaIdRef.current, temperatureRef.current);
+      return upsertConversation(prev, {
+        ...existing,
+        id: conversationId,
+        title: titleFromMessages(nextMessages),
+        updatedAt: new Date().toISOString(),
+        personaId: personaIdRef.current,
+        temperature: temperatureRef.current,
+        messages: nextMessages,
+      });
+    });
+  }
+
+  function updateActiveSettings(personaId: string, nextTemperature: number) {
+    if (!activeIdRef.current) return;
+    setConversations((prev) =>
+      prev.map((conversation) =>
+        conversation.id === activeIdRef.current
+          ? {
+              ...conversation,
+              personaId,
+              temperature: nextTemperature,
+              updatedAt: new Date().toISOString(),
+            }
+          : conversation
+      )
+    );
+  }
+
+  function handlePersonaChange(nextPersona: Persona) {
+    setActivePersonaId(nextPersona.id);
+    personaIdRef.current = nextPersona.id;
+    saveChatPreferences({ personaId: nextPersona.id, temperature: temperatureRef.current });
+    updateActiveSettings(nextPersona.id, temperatureRef.current);
+  }
+
+  function handleTemperatureChange(nextTemperature: number) {
+    setTemperature(nextTemperature);
+    temperatureRef.current = nextTemperature;
+    saveChatPreferences({ personaId: personaIdRef.current, temperature: nextTemperature });
+    updateActiveSettings(personaIdRef.current, nextTemperature);
+  }
+
+  function newChat() {
+    if (busy) return;
+    activeIdRef.current = null;
+    setActiveId(null);
+    setMessages([]);
+    setInput("");
+    const preferences = loadChatPreferences();
+    const personaId = preferences.personaId ?? personaIdRef.current;
+    const nextTemperature = preferences.temperature ?? temperatureRef.current;
+    setActivePersonaId(personaId);
+    setTemperature(nextTemperature);
+    personaIdRef.current = personaId;
+    temperatureRef.current = nextTemperature;
+  }
+
+  function openConversation(conversation: ChatConversation) {
+    if (busy) return;
+    activeIdRef.current = conversation.id;
+    setActiveId(conversation.id);
+    setMessages(conversation.messages);
+    setActivePersonaId(conversation.personaId);
+    setTemperature(conversation.temperature);
+    personaIdRef.current = conversation.personaId;
+    temperatureRef.current = conversation.temperature;
+    saveChatPreferences({
+      personaId: conversation.personaId,
+      temperature: conversation.temperature,
+    });
+    setInput("");
+  }
+
+  function deleteConversation(id: string) {
+    if (busy) return;
+    const remaining = removeConversation(conversations, id);
+    const nextActive = activeId === id ? remaining[0] : conversations.find((item) => item.id === activeId);
+
+    setConversations(remaining);
+    if (nextActive) {
+      activeIdRef.current = nextActive.id;
+      setActiveId(nextActive.id);
+      setMessages(nextActive.messages);
+      setActivePersonaId(nextActive.personaId);
+      setTemperature(nextActive.temperature);
+      personaIdRef.current = nextActive.personaId;
+      temperatureRef.current = nextActive.temperature;
+    } else {
+      activeIdRef.current = null;
+      setActiveId(null);
+      setMessages([]);
+      const preferences = loadChatPreferences();
+      const personaId = preferences.personaId ?? personaIdRef.current;
+      const nextTemperature = preferences.temperature ?? temperatureRef.current;
+      setActivePersonaId(personaId);
+      setTemperature(nextTemperature);
+      personaIdRef.current = personaId;
+      temperatureRef.current = nextTemperature;
+    }
+  }
+
+  function clearHistory() {
+    if (busy) return;
+    setConversations([]);
+    activeIdRef.current = null;
+    setActiveId(null);
+    setMessages([]);
+    setInput("");
+    const preferences = loadChatPreferences();
+    const personaId = preferences.personaId ?? personaIdRef.current;
+    const nextTemperature = preferences.temperature ?? temperatureRef.current;
+    setActivePersonaId(personaId);
+    setTemperature(nextTemperature);
+    personaIdRef.current = personaId;
+    temperatureRef.current = nextTemperature;
+  }
+
   async function send() {
     const text = input.trim();
     if (!text || busy) return;
+
+    const conversationId = ensureActiveConversation();
     setInput("");
-    const next: Msg[] = [
+
+    let currentMessages: ChatMessage[] = [
       ...messages,
       { role: "user", content: text },
       { role: "assistant", content: "" },
     ];
-    setMessages(next);
+    commitMessages(conversationId, currentMessages);
     setBusy(true);
 
     try {
@@ -63,11 +283,11 @@ export function ChatInterface() {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          messages: next
+          messages: currentMessages
             .slice(0, -1)
             .map(({ role, content }) => ({ role, content })),
           persona_prompt: persona.prompt,
-          temperature,
+          temperature: temperatureRef.current,
         }),
       });
 
@@ -107,31 +327,28 @@ export function ChatInterface() {
             } else if (evt.type === "error") {
               acc += `\n\n*[error: ${evt.message}]*`;
             }
-            setMessages((prev) => {
-              const copy = [...prev];
-              copy[copy.length - 1] = {
-                role: "assistant",
-                content: acc,
-                reasoning,
-                sources,
-                status,
-              };
-              return copy;
-            });
+
+            currentMessages = [...currentMessages];
+            currentMessages[currentMessages.length - 1] = {
+              role: "assistant",
+              content: acc,
+              reasoning,
+              sources,
+              status,
+            };
+            commitMessages(conversationId, currentMessages);
           } catch {
             // partial JSON, ignore
           }
         }
       }
     } catch (e) {
-      setMessages((prev) => {
-        const copy = [...prev];
-        copy[copy.length - 1] = {
-          role: "assistant",
-          content: `*Failed to reach the model: ${(e as Error).message}*`,
-        };
-        return copy;
-      });
+      currentMessages = [...currentMessages];
+      currentMessages[currentMessages.length - 1] = {
+        role: "assistant",
+        content: `*Failed to reach the model: ${(e as Error).message}*`,
+      };
+      commitMessages(conversationId, currentMessages);
     } finally {
       setBusy(false);
     }
@@ -162,44 +379,44 @@ export function ChatInterface() {
                 key={i}
                 className={`flex ${m.role === "user" ? "justify-end" : "justify-start"}`}
               >
-              <div
-                className={`max-w-[85%] rounded-lg px-4 py-2.5 text-sm leading-relaxed ${
-                  m.role === "user"
-                    ? "bg-primary text-primary-foreground"
-                    : "bg-muted text-foreground"
-                }`}
-              >
-                <div className="whitespace-pre-wrap">
-                  {m.content ||
-                    thinkingPreview ||
-                    (isStreamingAssistant ? "Thinking…" : "")}
-                </div>
-                {thinkingPreview && (
-                  <div className="mt-2 text-xs italic opacity-70">
-                    Thinking stream
+                <div
+                  className={`max-w-[85%] rounded-lg px-4 py-2.5 text-sm leading-relaxed ${
+                    m.role === "user"
+                      ? "bg-primary text-primary-foreground"
+                      : "bg-muted text-foreground"
+                  }`}
+                >
+                  <div className="whitespace-pre-wrap">
+                    {m.content ||
+                      thinkingPreview ||
+                      (isStreamingAssistant ? "Thinking..." : "")}
                   </div>
-                )}
-                {m.reasoning && (
-                  <details className="mt-3 rounded-md border border-border/60 bg-background/60 p-3 text-xs text-muted-foreground">
-                    <summary className="cursor-pointer select-none font-medium text-foreground">
-                      Thinking
-                    </summary>
-                    <div className="mt-2 whitespace-pre-wrap leading-relaxed">
-                      {m.reasoning}
+                  {thinkingPreview && (
+                    <div className="mt-2 text-xs italic opacity-70">
+                      Thinking stream
                     </div>
-                  </details>
-                )}
-                {m.status && (
-                  <div className="mt-2 text-xs italic opacity-80">{m.status}</div>
-                )}
-                {m.sources && m.sources.length > 0 && (
-                  <div className="mt-2 border-t border-border/50 pt-2 text-xs opacity-80">
-                    <span className="font-medium">Sources: </span>
-                    {m.sources.join(", ")}
-                  </div>
-                )}
+                  )}
+                  {m.reasoning && (
+                    <details className="mt-3 rounded-md border border-border/60 bg-background/60 p-3 text-xs text-muted-foreground">
+                      <summary className="cursor-pointer select-none font-medium text-foreground">
+                        Thinking
+                      </summary>
+                      <div className="mt-2 whitespace-pre-wrap leading-relaxed">
+                        {m.reasoning}
+                      </div>
+                    </details>
+                  )}
+                  {m.status && (
+                    <div className="mt-2 text-xs italic opacity-80">{m.status}</div>
+                  )}
+                  {m.sources && m.sources.length > 0 && (
+                    <div className="mt-2 border-t border-border/50 pt-2 text-xs opacity-80">
+                      <span className="font-medium">Sources: </span>
+                      {m.sources.join(", ")}
+                    </div>
+                  )}
+                </div>
               </div>
-            </div>
             );
           })}
         </div>
@@ -212,7 +429,7 @@ export function ChatInterface() {
             }}
           >
             <Input
-              placeholder="Ask about the course material…"
+              placeholder="Ask about the course material..."
               value={input}
               onChange={(e) => setInput(e.target.value)}
               disabled={busy}
@@ -230,12 +447,108 @@ export function ChatInterface() {
 
       <Card>
         <CardContent className="space-y-6 p-6">
+          <div className="space-y-2">
+            <div className="flex items-center justify-between gap-2">
+              <div className="text-sm font-medium">Conversations</div>
+              <Button variant="outline" size="sm" onClick={newChat} disabled={busy}>
+                <Plus className="h-4 w-4" /> New
+              </Button>
+            </div>
+            <div className="max-h-56 space-y-1 overflow-y-auto rounded-md border bg-background p-1">
+              {conversations.length === 0 ? (
+                <div className="px-2 py-6 text-center text-xs text-muted-foreground">
+                  No saved chats yet.
+                </div>
+              ) : (
+                conversations.map((conversation) => (
+                  <div
+                    key={conversation.id}
+                    className={`group flex items-center gap-1 rounded-md ${
+                      conversation.id === activeId ? "bg-accent" : "hover:bg-accent/60"
+                    }`}
+                  >
+                    <button
+                      type="button"
+                      className="min-w-0 flex-1 px-2 py-2 text-left"
+                      onClick={() => openConversation(conversation)}
+                      disabled={busy}
+                    >
+                      <div className="truncate text-sm font-medium">
+                        {conversation.title}
+                      </div>
+                      <div className="text-xs text-muted-foreground">
+                        {displayDate(conversation.updatedAt)}
+                      </div>
+                    </button>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="icon"
+                      className="h-8 w-8 shrink-0 opacity-70 group-hover:opacity-100"
+                      onClick={() => deleteConversation(conversation.id)}
+                      disabled={busy}
+                      aria-label={`Delete ${conversation.title}`}
+                    >
+                      <Trash2 className="h-4 w-4" />
+                    </Button>
+                  </div>
+                ))
+              )}
+            </div>
+            {conversations.length > 0 && (
+              <Button variant="ghost" size="sm" onClick={clearHistory} disabled={busy}>
+                <Trash2 className="h-4 w-4" /> Clear history
+              </Button>
+            )}
+          </div>
+
+          <div className="space-y-2">
+            <div className="flex items-center justify-between gap-2">
+              <div className="text-sm font-medium">Course Materials</div>
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                onClick={loadDocuments}
+                disabled={documents === null}
+              >
+                <RefreshCw className="h-4 w-4" /> Refresh
+              </Button>
+            </div>
+            <div className="max-h-44 overflow-y-auto rounded-md border bg-background">
+              {documents === null ? (
+                <div className="px-3 py-6 text-center text-xs text-muted-foreground">
+                  Loading materials...
+                </div>
+              ) : documentsError ? (
+                <div className="px-3 py-3 text-xs text-destructive">
+                  {documentsError}
+                </div>
+              ) : documents.length === 0 ? (
+                <div className="px-3 py-6 text-center text-xs text-muted-foreground">
+                  No materials uploaded yet.
+                </div>
+              ) : (
+                <ul className="divide-y">
+                  {documents.map((name) => (
+                    <li key={name} className="flex min-w-0 items-center gap-2 px-3 py-2">
+                      <FileText className="h-4 w-4 shrink-0 text-muted-foreground" />
+                      <span className="truncate text-sm" title={name}>
+                        {name}
+                      </span>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </div>
+          </div>
+
           <div className="space-y-2">
             <div className="text-sm font-medium">Persona</div>
-            <PersonaSelector personas={personas} value={persona.id} onChange={setPersona} />
+            <PersonaSelector personas={personas} value={persona.id} onChange={handlePersonaChange} />
             <p className="text-xs text-muted-foreground">{persona.description}</p>
           </div>
-          <TemperatureSlider value={temperature} onChange={setTemperature} />
+          <TemperatureSlider value={temperature} onChange={handleTemperatureChange} />
         </CardContent>
       </Card>
     </div>

frontend/components/persona-selector.tsx

@@ -4,7 +4,6 @@ import {
   SelectContent,
   SelectItem,
   SelectTrigger,
-  SelectValue,
 } from "@/components/ui/select";
 import { type Persona } from "@/lib/personas";
 
@@ -17,6 +16,8 @@ export function PersonaSelector({
   value: string;
   onChange: (p: Persona) => void;
 }) {
+  const selected = personas.find((p) => p.id === value);
+
   return (
     <Select
       value={value}
@@ -25,8 +26,10 @@ export function PersonaSelector({
         if (p) onChange(p);
       }}
     >
-      <SelectTrigger className="w-full">
-        <SelectValue placeholder="Choose a persona" />
+      <SelectTrigger className="h-11 w-full">
+        <span className="truncate text-left font-medium">
+          {selected?.name ?? "Choose a persona"}
+        </span>
       </SelectTrigger>
       <SelectContent>
         {personas.map((p) => (

frontend/lib/chat-storage.ts

@@ -0,0 +1,192 @@
+export type ChatMessage = {
+  role: "user" | "assistant";
+  content: string;
+  reasoning?: string;
+  sources?: string[];
+  status?: string;
+};
+
+export type ChatConversation = {
+  id: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  personaId: string;
+  temperature: number;
+  messages: ChatMessage[];
+};
+
+type ChatStore = {
+  activeId: string | null;
+  conversations: ChatConversation[];
+};
+
+type ChatPreferences = {
+  personaId?: string;
+  temperature?: number;
+};
+
+const STORAGE_KEY = "iamearth.chat.v1";
+const PREFERENCES_KEY = "iamearth.chat.preferences.v1";
+const MAX_CONVERSATIONS = 20;
+const MAX_MESSAGES_PER_CONVERSATION = 80;
+const MAX_MESSAGE_CHARS = 12000;
+
+const emptyStore: ChatStore = {
+  activeId: null,
+  conversations: [],
+};
+
+function now() {
+  return new Date().toISOString();
+}
+
+function id() {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `chat-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+function isBrowser() {
+  return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+}
+
+function sanitizeMessage(message: ChatMessage): ChatMessage {
+  return {
+    ...message,
+    content: message.content.slice(0, MAX_MESSAGE_CHARS),
+    reasoning: message.reasoning?.slice(0, MAX_MESSAGE_CHARS),
+  };
+}
+
+function sanitizeConversation(conversation: ChatConversation): ChatConversation {
+  return {
+    ...conversation,
+    messages: conversation.messages
+      .slice(-MAX_MESSAGES_PER_CONVERSATION)
+      .map(sanitizeMessage),
+  };
+}
+
+function sorted(conversations: ChatConversation[]) {
+  return [...conversations].sort(
+    (a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt)
+  );
+}
+
+export function titleFromMessages(messages: ChatMessage[]) {
+  const firstUser = messages.find((message) => message.role === "user")?.content.trim();
+  if (!firstUser) return "New chat";
+  return firstUser.length > 48 ? `${firstUser.slice(0, 45)}...` : firstUser;
+}
+
+export function createConversation(personaId: string, temperature: number): ChatConversation {
+  const timestamp = now();
+  return {
+    id: id(),
+    title: "New chat",
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    personaId,
+    temperature,
+    messages: [],
+  };
+}
+
+export function loadChatStore(): ChatStore {
+  if (!isBrowser()) return emptyStore;
+
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return emptyStore;
+    const parsed = JSON.parse(raw) as Partial<ChatStore>;
+    if (!Array.isArray(parsed.conversations)) return emptyStore;
+
+    const conversations = sorted(
+      parsed.conversations
+        .filter((conversation): conversation is ChatConversation => {
+          return Boolean(
+            conversation &&
+              typeof conversation.id === "string" &&
+              typeof conversation.title === "string" &&
+              Array.isArray(conversation.messages)
+          );
+        })
+        .map(sanitizeConversation)
+    ).slice(0, MAX_CONVERSATIONS);
+
+    const activeId =
+      parsed.activeId === null
+        ? null
+        : conversations.find((conversation) => conversation.id === parsed.activeId)?.id ??
+          conversations[0]?.id ??
+          null;
+
+    return { activeId, conversations };
+  } catch {
+    return emptyStore;
+  }
+}
+
+export function saveChatStore(store: ChatStore) {
+  if (!isBrowser()) return;
+
+  try {
+    const conversations = sorted(store.conversations)
+      .map(sanitizeConversation)
+      .slice(0, MAX_CONVERSATIONS);
+    const activeId =
+      store.activeId === null
+        ? null
+        : conversations.find((conversation) => conversation.id === store.activeId)?.id ??
+          conversations[0]?.id ??
+          null;
+
+    window.localStorage.setItem(
+      STORAGE_KEY,
+      JSON.stringify({ activeId, conversations })
+    );
+  } catch {
+    // Storage can fail in private browsing or when the quota is full.
+  }
+}
+
+export function loadChatPreferences(): ChatPreferences {
+  if (!isBrowser()) return {};
+
+  try {
+    const raw = window.localStorage.getItem(PREFERENCES_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as Partial<ChatPreferences>;
+    return {
+      personaId: typeof parsed.personaId === "string" ? parsed.personaId : undefined,
+      temperature: typeof parsed.temperature === "number" ? parsed.temperature : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function saveChatPreferences(preferences: ChatPreferences) {
+  if (!isBrowser()) return;
+
+  try {
+    window.localStorage.setItem(PREFERENCES_KEY, JSON.stringify(preferences));
+  } catch {
+    // Storage can fail in private browsing or when the quota is full.
+  }
+}
+
+export function upsertConversation(
+  conversations: ChatConversation[],
+  conversation: ChatConversation
+) {
+  return sorted([
+    sanitizeConversation(conversation),
+    ...conversations.filter((item) => item.id !== conversation.id),
+  ]).slice(0, MAX_CONVERSATIONS);
+}
+
+export function removeConversation(conversations: ChatConversation[], idToRemove: string) {
+  return conversations.filter((conversation) => conversation.id !== idToRemove);
+}