refactor: break up search_thoughts() into focused helpers

Extract _query_thoughts() and _format_thought_results() from the 73-line
search_thoughts() function, keeping each piece focused on a single
responsibility. Also fix pre-existing F821 lint errors in mcp_tools.py.

Fixes #594

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/dashboard/routes/calm.py

@@ -19,14 +19,17 @@ router = APIRouter(tags=["calm"])
 
 # Helper functions for state machine logic
 def get_now_task(db: Session) -> Task | None:
+    """Return the single active NOW task, or None."""
     return db.query(Task).filter(Task.state == TaskState.NOW).first()
 
 
 def get_next_task(db: Session) -> Task | None:
+    """Return the single queued NEXT task, or None."""
     return db.query(Task).filter(Task.state == TaskState.NEXT).first()
 
 
 def get_later_tasks(db: Session) -> list[Task]:
+    """Return all LATER tasks ordered by MIT flag then sort_order."""
     return (
         db.query(Task)
         .filter(Task.state == TaskState.LATER)
@@ -36,6 +39,12 @@ def get_later_tasks(db: Session) -> list[Task]:
 
 
 def promote_tasks(db: Session):
+    """Enforce the NOW/NEXT/LATER state machine invariants.
+
+    - At most one NOW task (extras demoted to NEXT).
+    - If no NOW, promote NEXT -> NOW.
+    - If no NEXT, promote highest-priority LATER -> NEXT.
+    """
     # Ensure only one NOW task exists. If multiple, demote extras to NEXT.
     now_tasks = db.query(Task).filter(Task.state == TaskState.NOW).all()
     if len(now_tasks) > 1:
@@ -74,6 +83,7 @@ def promote_tasks(db: Session):
 # Endpoints
 @router.get("/calm", response_class=HTMLResponse)
 async def get_calm_view(request: Request, db: Session = Depends(get_db)):
+    """Render the main CALM dashboard with NOW/NEXT/LATER counts."""
     now_task = get_now_task(db)
     next_task = get_next_task(db)
     later_tasks_count = len(get_later_tasks(db))
@@ -90,6 +100,7 @@ async def get_calm_view(request: Request, db: Session = Depends(get_db)):
 
 @router.get("/calm/ritual/morning", response_class=HTMLResponse)
 async def get_morning_ritual_form(request: Request):
+    """Render the morning ritual intake form."""
     return templates.TemplateResponse(request, "calm/morning_ritual_form.html", {})
 
 
@@ -102,6 +113,7 @@ async def post_morning_ritual(
     mit3_title: str = Form(None),
     other_tasks: str = Form(""),
 ):
+    """Process morning ritual: create MITs, other tasks, and set initial states."""
     # Create Journal Entry
     mit_task_ids = []
     journal_entry = JournalEntry(entry_date=date.today())
@@ -173,6 +185,7 @@ async def post_morning_ritual(
 
 @router.get("/calm/ritual/evening", response_class=HTMLResponse)
 async def get_evening_ritual_form(request: Request, db: Session = Depends(get_db)):
+    """Render the evening ritual form for today's journal entry."""
     journal_entry = db.query(JournalEntry).filter(JournalEntry.entry_date == date.today()).first()
     if not journal_entry:
         raise HTTPException(status_code=404, detail="No journal entry for today")
@@ -189,6 +202,7 @@ async def post_evening_ritual(
     gratitude: str = Form(None),
     energy_level: int = Form(None),
 ):
+    """Process evening ritual: save reflection/gratitude, archive active tasks."""
     journal_entry = db.query(JournalEntry).filter(JournalEntry.entry_date == date.today()).first()
     if not journal_entry:
         raise HTTPException(status_code=404, detail="No journal entry for today")
@@ -223,6 +237,7 @@ async def create_new_task(
     is_mit: bool = Form(False),
     certainty: TaskCertainty = Form(TaskCertainty.SOFT),
 ):
+    """Create a new task in LATER state and return updated count."""
     task = Task(
         title=title,
         description=description,
@@ -247,6 +262,7 @@ async def start_task(
     task_id: int,
     db: Session = Depends(get_db),
 ):
+    """Move a task to NOW state, demoting the current NOW to NEXT."""
     current_now_task = get_now_task(db)
     if current_now_task and current_now_task.id != task_id:
         current_now_task.state = TaskState.NEXT  # Demote current NOW to NEXT
@@ -281,6 +297,7 @@ async def complete_task(
     task_id: int,
     db: Session = Depends(get_db),
 ):
+    """Mark a task as DONE and trigger state promotion."""
     task = db.query(Task).filter(Task.id == task_id).first()
     if not task:
         raise HTTPException(status_code=404, detail="Task not found")
@@ -309,6 +326,7 @@ async def defer_task(
     task_id: int,
     db: Session = Depends(get_db),
 ):
+    """Defer a task and trigger state promotion."""
     task = db.query(Task).filter(Task.id == task_id).first()
     if not task:
         raise HTTPException(status_code=404, detail="Task not found")
@@ -333,6 +351,7 @@ async def defer_task(
 
 @router.get("/calm/partials/later_tasks_list", response_class=HTMLResponse)
 async def get_later_tasks_list(request: Request, db: Session = Depends(get_db)):
+    """Render the expandable list of LATER tasks."""
     later_tasks = get_later_tasks(db)
     return templates.TemplateResponse(
         "calm/partials/later_tasks_list.html",
@@ -348,6 +367,7 @@ async def reorder_tasks(
     later_task_ids: str = Form(""),
     next_task_id: int | None = Form(None),
 ):
+    """Reorder LATER tasks and optionally promote one to NEXT."""
     # Reorder LATER tasks
     if later_task_ids:
         ids_in_order = [int(x.strip()) for x in later_task_ids.split(",") if x.strip()]

src/integrations/chat_bridge/vendors/discord.py

@@ -515,25 +515,36 @@ class DiscordVendor(ChatPlatform):
 
     async def _handle_message(self, message) -> None:
         """Process an incoming message and respond via a thread."""
-        # Strip the bot mention from the message content
-        content = message.content
-        if self._client.user:
-            content = content.replace(f"<@{self._client.user.id}>", "").strip()
-
+        content = self._extract_content(message)
         if not content:
             return
 
-        # Create or reuse a thread for this conversation
         thread = await self._get_or_create_thread(message)
         target = thread or message.channel
+        session_id = f"discord_{thread.id}" if thread else f"discord_{message.channel.id}"
 
-        # Derive session_id for per-conversation history via Agno's SQLite
-        if thread:
-            session_id = f"discord_{thread.id}"
-        else:
-            session_id = f"discord_{message.channel.id}"
+        run_output, response = await self._invoke_agent(content, session_id, target)
 
-        # Run Timmy agent with typing indicator and timeout
+        if run_output is not None:
+            await self._handle_paused_run(run_output, target, session_id)
+            raw_content = run_output.content if hasattr(run_output, "content") else ""
+            response = _clean_response(raw_content or "")
+
+        await self._send_response(response, target)
+
+    def _extract_content(self, message) -> str:
+        """Strip the bot mention and return clean message text."""
+        content = message.content
+        if self._client.user:
+            content = content.replace(f"<@{self._client.user.id}>", "").strip()
+        return content
+
+    async def _invoke_agent(self, content: str, session_id: str, target):
+        """Run chat_with_tools with a typing indicator and timeout.
+
+        Returns a (run_output, error_response) tuple.  On success the
+        error_response is ``None``; on failure run_output is ``None``.
+        """
         run_output = None
         response = None
         try:
@@ -548,51 +559,57 @@ class DiscordVendor(ChatPlatform):
         except Exception as exc:
             logger.error("Discord: chat_with_tools() failed: %s", exc)
             response = "I'm having trouble reaching my inference backend right now. Please try again shortly."
+        return run_output, response
 
-        # Check if Agno paused the run for tool confirmation
-        if run_output is not None:
-            status = getattr(run_output, "status", None)
-            is_paused = status == "PAUSED" or str(status) == "RunStatus.paused"
+    async def _handle_paused_run(self, run_output, target, session_id: str) -> None:
+        """If Agno paused the run for tool confirmation, enqueue approvals."""
+        status = getattr(run_output, "status", None)
+        is_paused = status == "PAUSED" or str(status) == "RunStatus.paused"
 
-            if is_paused and getattr(run_output, "active_requirements", None):
-                from config import settings
+        if not (is_paused and getattr(run_output, "active_requirements", None)):
+            return
 
-                if settings.discord_confirm_actions:
-                    for req in run_output.active_requirements:
-                        if getattr(req, "needs_confirmation", False):
-                            te = req.tool_execution
-                            tool_name = getattr(te, "tool_name", "unknown")
-                            tool_args = getattr(te, "tool_args", {}) or {}
+        from config import settings
 
-                            from timmy.approvals import create_item
+        if not settings.discord_confirm_actions:
+            return
 
-                            item = create_item(
-                                title=f"Discord: {tool_name}",
-                                description=_format_action_description(tool_name, tool_args),
-                                proposed_action=json.dumps({"tool": tool_name, "args": tool_args}),
-                                impact=_get_impact_level(tool_name),
-                            )
-                            self._pending_actions[item.id] = {
-                                "run_output": run_output,
-                                "requirement": req,
-                                "tool_name": tool_name,
-                                "tool_args": tool_args,
-                                "target": target,
-                                "session_id": session_id,
-                            }
-                            await self._send_confirmation(target, tool_name, tool_args, item.id)
+        for req in run_output.active_requirements:
+            if not getattr(req, "needs_confirmation", False):
+                continue
+            te = req.tool_execution
+            tool_name = getattr(te, "tool_name", "unknown")
+            tool_args = getattr(te, "tool_args", {}) or {}
 
-            raw_content = run_output.content if hasattr(run_output, "content") else ""
-            response = _clean_response(raw_content or "")
+            from timmy.approvals import create_item
 
-        # Discord has a 2000 character limit — send with error handling
-        if response and response.strip():
-            for chunk in _chunk_message(response, 2000):
-                try:
-                    await target.send(chunk)
-                except Exception as exc:
-                    logger.error("Discord: failed to send message chunk: %s", exc)
-                    break
+            item = create_item(
+                title=f"Discord: {tool_name}",
+                description=_format_action_description(tool_name, tool_args),
+                proposed_action=json.dumps({"tool": tool_name, "args": tool_args}),
+                impact=_get_impact_level(tool_name),
+            )
+            self._pending_actions[item.id] = {
+                "run_output": run_output,
+                "requirement": req,
+                "tool_name": tool_name,
+                "tool_args": tool_args,
+                "target": target,
+                "session_id": session_id,
+            }
+            await self._send_confirmation(target, tool_name, tool_args, item.id)
+
+    @staticmethod
+    async def _send_response(response: str | None, target) -> None:
+        """Send a response to Discord, chunked to the 2000-char limit."""
+        if not response or not response.strip():
+            return
+        for chunk in _chunk_message(response, 2000):
+            try:
+                await target.send(chunk)
+            except Exception as exc:
+                logger.error("Discord: failed to send message chunk: %s", exc)
+                break
 
     async def _get_or_create_thread(self, message):
         """Get the active thread for a channel, or create one.

src/timmy/agents/base.py

@@ -119,75 +119,84 @@ class BaseAgent(ABC):
         """
         pass
 
-    async def run(self, message: str) -> str:
-        """Run the agent with a message.
+    # Transient errors that indicate Ollama contention or temporary
+    # unavailability — these deserve a retry with backoff.
+    _TRANSIENT = (
+        httpx.ConnectError,
+        httpx.ReadError,
+        httpx.ReadTimeout,
+        httpx.ConnectTimeout,
+        ConnectionError,
+        TimeoutError,
+    )
 
-        Retries on transient failures (connection errors, timeouts) with
-        exponential backoff.  GPU contention from concurrent Ollama
-        requests causes ReadError / ReadTimeout — these are transient
-        and should be retried, not raised immediately (#70).
+    async def run(self, message: str, *, max_retries: int = 3) -> str:
+        """Run the agent with a message, retrying on transient failures.
 
-        Returns:
-            Agent response
+        GPU contention from concurrent Ollama requests causes ReadError /
+        ReadTimeout — these are transient and retried with exponential
+        backoff (#70).
         """
-        max_retries = 3
-        last_exception = None
-        # Transient errors that indicate Ollama contention or temporary
-        # unavailability — these deserve a retry with backoff.
-        _transient = (
-            httpx.ConnectError,
-            httpx.ReadError,
-            httpx.ReadTimeout,
-            httpx.ConnectTimeout,
-            ConnectionError,
-            TimeoutError,
-        )
+        response = await self._run_with_retries(message, max_retries)
+        await self._emit_response_event(message, response)
+        return response
 
+    async def _run_with_retries(self, message: str, max_retries: int) -> str:
+        """Execute agent.run() with retry logic for transient errors."""
         for attempt in range(1, max_retries + 1):
             try:
                 result = self.agent.run(message, stream=False)
-                response = result.content if hasattr(result, "content") else str(result)
-                break  # Success, exit the retry loop
-            except _transient as exc:
-                last_exception = exc
-                if attempt < max_retries:
-                    # Contention backoff — longer waits because the GPU
-                    # needs time to finish the other request.
-                    wait = min(2**attempt, 16)
-                    logger.warning(
-                        "Ollama contention on attempt %d/%d: %s. Waiting %ds before retry...",
-                        attempt,
-                        max_retries,
-                        type(exc).__name__,
-                        wait,
-                    )
-                    await asyncio.sleep(wait)
-                else:
-                    logger.error(
-                        "Ollama unreachable after %d attempts: %s",
-                        max_retries,
-                        exc,
-                    )
-                    raise last_exception from exc
+                return result.content if hasattr(result, "content") else str(result)
+            except self._TRANSIENT as exc:
+                self._handle_retry_or_raise(
+                    exc,
+                    attempt,
+                    max_retries,
+                    transient=True,
+                )
+                await asyncio.sleep(min(2**attempt, 16))
             except Exception as exc:
-                last_exception = exc
-                if attempt < max_retries:
-                    logger.warning(
-                        "Agent run failed on attempt %d/%d: %s. Retrying...",
-                        attempt,
-                        max_retries,
-                        exc,
-                    )
-                    await asyncio.sleep(min(2 ** (attempt - 1), 8))
-                else:
-                    logger.error(
-                        "Agent run failed after %d attempts: %s",
-                        max_retries,
-                        exc,
-                    )
-                    raise last_exception from exc
+                self._handle_retry_or_raise(
+                    exc,
+                    attempt,
+                    max_retries,
+                    transient=False,
+                )
+                await asyncio.sleep(min(2 ** (attempt - 1), 8))
+        # Unreachable — _handle_retry_or_raise raises on last attempt.
+        raise RuntimeError("retry loop exited unexpectedly")  # pragma: no cover
 
-        # Emit completion event
+    @staticmethod
+    def _handle_retry_or_raise(
+        exc: Exception,
+        attempt: int,
+        max_retries: int,
+        *,
+        transient: bool,
+    ) -> None:
+        """Log a retry warning or raise after exhausting attempts."""
+        if attempt < max_retries:
+            if transient:
+                logger.warning(
+                    "Ollama contention on attempt %d/%d: %s. Waiting before retry...",
+                    attempt,
+                    max_retries,
+                    type(exc).__name__,
+                )
+            else:
+                logger.warning(
+                    "Agent run failed on attempt %d/%d: %s. Retrying...",
+                    attempt,
+                    max_retries,
+                    exc,
+                )
+        else:
+            label = "Ollama unreachable" if transient else "Agent run failed"
+            logger.error("%s after %d attempts: %s", label, max_retries, exc)
+            raise exc
+
+    async def _emit_response_event(self, message: str, response: str) -> None:
+        """Publish a completion event to the event bus if connected."""
         if self.event_bus:
             await self.event_bus.publish(
                 Event(
@@ -197,8 +206,6 @@ class BaseAgent(ABC):
                 )
             )
 
-        return response
-
     def get_capabilities(self) -> list[str]:
         """Get list of capabilities this agent provides."""
         return self.tools

src/timmy/mcp_tools.py

@@ -270,20 +270,8 @@ async def create_gitea_issue_via_mcp(title: str, body: str = "", labels: str = "
         return f"Failed to create issue via MCP: {exc}"
 
 
-def _generate_avatar_image() -> bytes:
-    """Generate a Timmy-themed avatar image using Pillow.
-
-    Creates a 512x512 wizard-themed avatar with emerald/purple/gold palette.
-    Returns raw PNG bytes. Falls back to a minimal solid-color image if
-    Pillow drawing primitives fail.
-    """
-    from PIL import Image, ImageDraw
-
-    size = 512
-    img = Image.new("RGB", (size, size), (15, 25, 20))
-    draw = ImageDraw.Draw(img)
-
-    # Background gradient effect — concentric circles
+def _draw_background(draw: ImageDraw.ImageDraw, size: int) -> None:  # noqa: F821
+    """Draw radial gradient background with concentric circles."""
     for i in range(size // 2, 0, -4):
         g = int(25 + (i / (size // 2)) * 30)
         draw.ellipse(
@@ -291,33 +279,45 @@ def _generate_avatar_image() -> bytes:
             fill=(10, g, 20),
         )
 
-    # Wizard hat (triangle)
+
+def _draw_wizard(draw: ImageDraw.ImageDraw) -> None:  # noqa: F821
+    """Draw wizard hat, face, eyes, smile, monogram, and robe."""
     hat_color = (100, 50, 160)  # purple
-    draw.polygon(
-        [(256, 40), (160, 220), (352, 220)],
-        fill=hat_color,
-        outline=(180, 130, 255),
-    )
+    hat_outline = (180, 130, 255)
+    gold = (220, 190, 50)
+    pupil = (30, 30, 60)
 
-    # Hat brim
-    draw.ellipse([140, 200, 372, 250], fill=hat_color, outline=(180, 130, 255))
+    # Hat + brim
+    draw.polygon([(256, 40), (160, 220), (352, 220)], fill=hat_color, outline=hat_outline)
+    draw.ellipse([140, 200, 372, 250], fill=hat_color, outline=hat_outline)
 
-    # Face circle
+    # Face
     draw.ellipse([190, 220, 322, 370], fill=(60, 180, 100), outline=(80, 220, 120))
 
-    # Eyes
+    # Eyes (whites + pupils)
     draw.ellipse([220, 275, 248, 310], fill=(255, 255, 255))
     draw.ellipse([264, 275, 292, 310], fill=(255, 255, 255))
-    draw.ellipse([228, 285, 242, 300], fill=(30, 30, 60))
-    draw.ellipse([272, 285, 286, 300], fill=(30, 30, 60))
+    draw.ellipse([228, 285, 242, 300], fill=pupil)
+    draw.ellipse([272, 285, 286, 300], fill=pupil)
 
     # Smile
-    draw.arc([225, 300, 287, 355], start=10, end=170, fill=(30, 30, 60), width=3)
+    draw.arc([225, 300, 287, 355], start=10, end=170, fill=pupil, width=3)
 
-    # Stars around the hat
+    # "T" monogram on hat
+    draw.text((243, 100), "T", fill=gold)
+
+    # Robe
+    draw.polygon(
+        [(180, 370), (140, 500), (372, 500), (332, 370)],
+        fill=(40, 100, 70),
+        outline=(60, 160, 100),
+    )
+
+
+def _draw_stars(draw: ImageDraw.ImageDraw) -> None:  # noqa: F821
+    """Draw decorative gold stars around the wizard hat."""
     gold = (220, 190, 50)
-    star_positions = [(120, 100), (380, 120), (100, 300), (400, 280), (256, 10)]
-    for sx, sy in star_positions:
+    for sx, sy in [(120, 100), (380, 120), (100, 300), (400, 280), (256, 10)]:
         r = 8
         draw.polygon(
             [
@@ -333,18 +333,26 @@ def _generate_avatar_image() -> bytes:
             fill=gold,
         )
 
-    # "T" monogram on the hat
-    draw.text((243, 100), "T", fill=gold)
 
-    # Robe / body
-    draw.polygon(
-        [(180, 370), (140, 500), (372, 500), (332, 370)],
-        fill=(40, 100, 70),
-        outline=(60, 160, 100),
-    )
+def _generate_avatar_image() -> bytes:
+    """Generate a Timmy-themed avatar image using Pillow.
 
+    Creates a 512x512 wizard-themed avatar with emerald/purple/gold palette.
+    Returns raw PNG bytes. Falls back to a minimal solid-color image if
+    Pillow drawing primitives fail.
+    """
     import io
 
+    from PIL import Image, ImageDraw
+
+    size = 512
+    img = Image.new("RGB", (size, size), (15, 25, 20))
+    draw = ImageDraw.Draw(img)
+
+    _draw_background(draw, size)
+    _draw_wizard(draw)
+    _draw_stars(draw)
+
     buf = io.BytesIO()
     img.save(buf, format="PNG")
     return buf.getvalue()

src/timmy/memory/unified.py

@@ -78,83 +78,88 @@ def _migrate_schema(conn: sqlite3.Connection) -> None:
     cursor = conn.execute("SELECT name FROM sqlite_master WHERE type='table'")
     tables = {row[0] for row in cursor.fetchall()}
 
-    has_memories = "memories" in tables
-    has_episodes = "episodes" in tables
-    has_chunks = "chunks" in tables
-    has_facts = "facts" in tables
-
-    # Check if we need to migrate (old schema exists but new one doesn't fully)
-    if not has_memories:
+    if "memories" not in tables:
         logger.info("Migration: Creating unified memories table")
-        # Schema will be created above
-
-    # Migrate episodes -> memories
-    if has_episodes and has_memories:
-        logger.info("Migration: Converting episodes table to memories")
-        try:
-            cols = _get_table_columns(conn, "episodes")
-            context_type_col = "context_type" if "context_type" in cols else "'conversation'"
-
-            conn.execute(f"""
-                INSERT INTO memories (
-                    id, content, memory_type, source, embedding,
-                    metadata, agent_id, task_id, session_id,
-                    created_at, access_count, last_accessed
-                )
-                SELECT 
-                    id, content, 
-                    COALESCE({context_type_col}, 'conversation'),
-                    COALESCE(source, 'agent'),
-                    embedding,
-                    metadata, agent_id, task_id, session_id,
-                    COALESCE(timestamp, datetime('now')), 0, NULL
-                FROM episodes
-            """)
-            conn.execute("DROP TABLE episodes")
-            logger.info("Migration: Migrated episodes to memories")
-        except sqlite3.Error as exc:
-            logger.warning("Migration: Failed to migrate episodes: %s", exc)
-
-    # Migrate chunks -> memories as vault_chunk
-    if has_chunks and has_memories:
-        logger.info("Migration: Converting chunks table to memories")
-        try:
-            cols = _get_table_columns(conn, "chunks")
-
-            id_col = "id" if "id" in cols else "CAST(rowid AS TEXT)"
-            content_col = "content" if "content" in cols else "text"
-            source_col = (
-                "filepath" if "filepath" in cols else ("source" if "source" in cols else "'vault'")
-            )
-            embedding_col = "embedding" if "embedding" in cols else "NULL"
-            created_col = "created_at" if "created_at" in cols else "datetime('now')"
-
-            conn.execute(f"""
-                INSERT INTO memories (
-                    id, content, memory_type, source, embedding,
-                    created_at, access_count
-                )
-                SELECT 
-                    {id_col}, {content_col}, 'vault_chunk', {source_col},
-                    {embedding_col}, {created_col}, 0
-                FROM chunks
-            """)
-            conn.execute("DROP TABLE chunks")
-            logger.info("Migration: Migrated chunks to memories")
-        except sqlite3.Error as exc:
-            logger.warning("Migration: Failed to migrate chunks: %s", exc)
-
-    # Drop old facts table
-    if has_facts:
-        try:
-            conn.execute("DROP TABLE facts")
-            logger.info("Migration: Dropped old facts table")
-        except sqlite3.Error as exc:
-            logger.warning("Migration: Failed to drop facts: %s", exc)
+        # Schema will be created by _ensure_schema above
+        conn.commit()
+        return
 
+    _migrate_episodes(conn, tables)
+    _migrate_chunks(conn, tables)
+    _drop_legacy_tables(conn, tables)
     conn.commit()
 
 
+def _migrate_episodes(conn: sqlite3.Connection, tables: set[str]) -> None:
+    """Migrate episodes table rows into the unified memories table."""
+    if "episodes" not in tables:
+        return
+    logger.info("Migration: Converting episodes table to memories")
+    try:
+        cols = _get_table_columns(conn, "episodes")
+        context_type_col = "context_type" if "context_type" in cols else "'conversation'"
+        conn.execute(f"""
+            INSERT INTO memories (
+                id, content, memory_type, source, embedding,
+                metadata, agent_id, task_id, session_id,
+                created_at, access_count, last_accessed
+            )
+            SELECT
+                id, content,
+                COALESCE({context_type_col}, 'conversation'),
+                COALESCE(source, 'agent'),
+                embedding,
+                metadata, agent_id, task_id, session_id,
+                COALESCE(timestamp, datetime('now')), 0, NULL
+            FROM episodes
+        """)
+        conn.execute("DROP TABLE episodes")
+        logger.info("Migration: Migrated episodes to memories")
+    except sqlite3.Error as exc:
+        logger.warning("Migration: Failed to migrate episodes: %s", exc)
+
+
+def _migrate_chunks(conn: sqlite3.Connection, tables: set[str]) -> None:
+    """Migrate chunks table rows into the unified memories table as vault_chunk."""
+    if "chunks" not in tables:
+        return
+    logger.info("Migration: Converting chunks table to memories")
+    try:
+        cols = _get_table_columns(conn, "chunks")
+        id_col = "id" if "id" in cols else "CAST(rowid AS TEXT)"
+        content_col = "content" if "content" in cols else "text"
+        source_col = (
+            "filepath" if "filepath" in cols else ("source" if "source" in cols else "'vault'")
+        )
+        embedding_col = "embedding" if "embedding" in cols else "NULL"
+        created_col = "created_at" if "created_at" in cols else "datetime('now')"
+        conn.execute(f"""
+            INSERT INTO memories (
+                id, content, memory_type, source, embedding,
+                created_at, access_count
+            )
+            SELECT
+                {id_col}, {content_col}, 'vault_chunk', {source_col},
+                {embedding_col}, {created_col}, 0
+            FROM chunks
+        """)
+        conn.execute("DROP TABLE chunks")
+        logger.info("Migration: Migrated chunks to memories")
+    except sqlite3.Error as exc:
+        logger.warning("Migration: Failed to migrate chunks: %s", exc)
+
+
+def _drop_legacy_tables(conn: sqlite3.Connection, tables: set[str]) -> None:
+    """Drop old facts table if it exists."""
+    if "facts" not in tables:
+        return
+    try:
+        conn.execute("DROP TABLE facts")
+        logger.info("Migration: Dropped old facts table")
+    except sqlite3.Error as exc:
+        logger.warning("Migration: Failed to drop facts: %s", exc)
+
+
 def _get_table_columns(conn: sqlite3.Connection, table_name: str) -> set[str]:
     """Get the column names for a table."""
     cursor = conn.execute(f"PRAGMA table_info({table_name})")

src/timmy/thinking.py

@@ -341,6 +341,11 @@ class ThinkingEngine:
             )
             return None
 
+        # Capture arrival time *before* the LLM call so the thought
+        # timestamp reflects when the cycle started, not when the
+        # (potentially slow) generation finished.  Fixes #582.
+        arrived_at = datetime.now(UTC).isoformat()
+
         memory_context, system_context, recent_thoughts = self._build_thinking_context()
 
         content, seed_type = await self._generate_novel_thought(
@@ -352,7 +357,7 @@ class ThinkingEngine:
         if not content:
             return None
 
-        thought = self._store_thought(content, seed_type)
+        thought = self._store_thought(content, seed_type, arrived_at=arrived_at)
         self._last_thought_id = thought.id
 
         await self._process_thinking_result(thought)
@@ -1173,14 +1178,25 @@ class ThinkingEngine:
         raw = run.content if hasattr(run, "content") else str(run)
         return _THINK_TAG_RE.sub("", raw) if raw else raw
 
-    def _store_thought(self, content: str, seed_type: str) -> Thought:
-        """Persist a thought to SQLite."""
+    def _store_thought(
+        self,
+        content: str,
+        seed_type: str,
+        *,
+        arrived_at: str | None = None,
+    ) -> Thought:
+        """Persist a thought to SQLite.
+
+        Args:
+            arrived_at: ISO-8601 timestamp captured when the thinking cycle
+                started.  Falls back to now() for callers that don't supply it.
+        """
         thought = Thought(
             id=str(uuid.uuid4()),
             content=content,
             seed_type=seed_type,
             parent_id=self._last_thought_id,
-            created_at=datetime.now(UTC).isoformat(),
+            created_at=arrived_at or datetime.now(UTC).isoformat(),
         )
 
         with _get_conn(self._db_path) as conn:
@@ -1261,6 +1277,52 @@ class ThinkingEngine:
             logger.debug("Failed to broadcast thought: %s", exc)
 
 
+def _query_thoughts(
+    db_path: Path, query: str, seed_type: str | None, limit: int
+) -> list[sqlite3.Row]:
+    """Fetch thought rows matching *query* with optional *seed_type* filter."""
+    with _get_conn(db_path) as conn:
+        if seed_type:
+            return conn.execute(
+                """
+                SELECT id, content, seed_type, created_at
+                FROM thoughts
+                WHERE content LIKE ? AND seed_type = ?
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (f"%{query}%", seed_type, limit),
+            ).fetchall()
+        return conn.execute(
+            """
+            SELECT id, content, seed_type, created_at
+            FROM thoughts
+            WHERE content LIKE ?
+            ORDER BY created_at DESC
+            LIMIT ?
+            """,
+            (f"%{query}%", limit),
+        ).fetchall()
+
+
+def _format_thought_results(rows: list[sqlite3.Row], query: str, seed_type: str | None) -> str:
+    """Format thought rows into a human-readable summary string."""
+    lines = [f'Found {len(rows)} thought(s) matching "{query}":']
+    if seed_type:
+        lines[0] += f' [seed_type="{seed_type}"]'
+    lines.append("")
+
+    for row in rows:
+        ts = datetime.fromisoformat(row["created_at"])
+        local_ts = ts.astimezone()
+        time_str = local_ts.strftime("%Y-%m-%d %I:%M %p").lstrip("0")
+        seed = row["seed_type"]
+        content = row["content"].replace("\n", " ")  # Flatten newlines for display
+        lines.append(f"[{time_str}] ({seed}) {content[:150]}")
+
+    return "\n".join(lines)
+
+
 def search_thoughts(query: str, seed_type: str | None = None, limit: int = 10) -> str:
     """Search Timmy's thought history for reflections matching a query.
 
@@ -1278,58 +1340,17 @@ def search_thoughts(query: str, seed_type: str | None = None, limit: int = 10) -
         Formatted string with matching thoughts, newest first, including
         timestamps and seed types. Returns a helpful message if no matches found.
     """
-    # Clamp limit to reasonable bounds
     limit = max(1, min(limit, 50))
 
     try:
-        engine = thinking_engine
-        db_path = engine._db_path
-
-        # Build query with optional seed_type filter
-        with _get_conn(db_path) as conn:
-            if seed_type:
-                rows = conn.execute(
-                    """
-                    SELECT id, content, seed_type, created_at
-                    FROM thoughts
-                    WHERE content LIKE ? AND seed_type = ?
-                    ORDER BY created_at DESC
-                    LIMIT ?
-                    """,
-                    (f"%{query}%", seed_type, limit),
-                ).fetchall()
-            else:
-                rows = conn.execute(
-                    """
-                    SELECT id, content, seed_type, created_at
-                    FROM thoughts
-                    WHERE content LIKE ?
-                    ORDER BY created_at DESC
-                    LIMIT ?
-                    """,
-                    (f"%{query}%", limit),
-                ).fetchall()
+        rows = _query_thoughts(thinking_engine._db_path, query, seed_type, limit)
 
         if not rows:
             if seed_type:
                 return f'No thoughts found matching "{query}" with seed_type="{seed_type}".'
             return f'No thoughts found matching "{query}".'
 
-        # Format results
-        lines = [f'Found {len(rows)} thought(s) matching "{query}":']
-        if seed_type:
-            lines[0] += f' [seed_type="{seed_type}"]'
-        lines.append("")
-
-        for row in rows:
-            ts = datetime.fromisoformat(row["created_at"])
-            local_ts = ts.astimezone()
-            time_str = local_ts.strftime("%Y-%m-%d %I:%M %p").lstrip("0")
-            seed = row["seed_type"]
-            content = row["content"].replace("\n", " ")  # Flatten newlines for display
-            lines.append(f"[{time_str}] ({seed}) {content[:150]}")
-
-        return "\n".join(lines)
+        return _format_thought_results(rows, query, seed_type)
 
     except Exception as exc:
         logger.warning("Thought search failed: %s", exc)

src/timmy/voice_loop.py

@@ -78,6 +78,11 @@ DEFAULT_MAX_UTTERANCE = 30.0  # safety cap — don't record forever
 DEFAULT_SESSION_ID = "voice"
 
 
+def _rms(block: np.ndarray) -> float:
+    """Compute root-mean-square energy of an audio block."""
+    return float(np.sqrt(np.mean(block.astype(np.float32) ** 2)))
+
+
 @dataclass
 class VoiceConfig:
     """Configuration for the voice loop."""
@@ -161,13 +166,6 @@ class VoiceLoop:
         min_blocks = int(self.config.min_utterance / 0.1)
         max_blocks = int(self.config.max_utterance / 0.1)
 
-        audio_chunks: list[np.ndarray] = []
-        silent_count = 0
-        recording = False
-
-        def _rms(block: np.ndarray) -> float:
-            return float(np.sqrt(np.mean(block.astype(np.float32) ** 2)))
-
         sys.stdout.write("\n  🎤 Listening... (speak now)\n")
         sys.stdout.flush()
 
@@ -177,42 +175,69 @@ class VoiceLoop:
             dtype="float32",
             blocksize=block_size,
         ) as stream:
-            while self._running:
-                block, overflowed = stream.read(block_size)
-                if overflowed:
-                    logger.debug("Audio buffer overflowed")
+            chunks = self._capture_audio_blocks(stream, block_size, silence_blocks, max_blocks)
 
-                rms = _rms(block)
+        return self._finalize_utterance(chunks, min_blocks, sr)
 
-                if not recording:
-                    if rms > self.config.silence_threshold:
-                        recording = True
-                        silent_count = 0
-                        audio_chunks.append(block.copy())
-                        sys.stdout.write("  📢 Recording...\r")
-                        sys.stdout.flush()
+    def _capture_audio_blocks(
+        self,
+        stream,
+        block_size: int,
+        silence_blocks: int,
+        max_blocks: int,
+    ) -> list[np.ndarray]:
+        """Read audio blocks from *stream* until silence or max length.
+
+        Returns the list of captured audio chunks (may be empty).
+        """
+        chunks: list[np.ndarray] = []
+        silent_count = 0
+        recording = False
+
+        while self._running:
+            block, overflowed = stream.read(block_size)
+            if overflowed:
+                logger.debug("Audio buffer overflowed")
+
+            rms = _rms(block)
+
+            if not recording:
+                if rms > self.config.silence_threshold:
+                    recording = True
+                    silent_count = 0
+                    chunks.append(block.copy())
+                    sys.stdout.write("  📢 Recording...\r")
+                    sys.stdout.flush()
+            else:
+                chunks.append(block.copy())
+
+                if rms < self.config.silence_threshold:
+                    silent_count += 1
                 else:
-                    audio_chunks.append(block.copy())
+                    silent_count = 0
 
-                    if rms < self.config.silence_threshold:
-                        silent_count += 1
-                    else:
-                        silent_count = 0
+                if silent_count >= silence_blocks:
+                    break
 
-                    # End of utterance
-                    if silent_count >= silence_blocks:
-                        break
+                if len(chunks) >= max_blocks:
+                    logger.info("Max utterance length reached, stopping.")
+                    break
 
-                    # Safety cap
-                    if len(audio_chunks) >= max_blocks:
-                        logger.info("Max utterance length reached, stopping.")
-                        break
+        return chunks
 
-        if not audio_chunks or len(audio_chunks) < min_blocks:
+    @staticmethod
+    def _finalize_utterance(
+        chunks: list[np.ndarray], min_blocks: int, sample_rate: int
+    ) -> np.ndarray | None:
+        """Concatenate recorded chunks and report duration.
+
+        Returns ``None`` if the utterance is too short to be meaningful.
+        """
+        if not chunks or len(chunks) < min_blocks:
             return None
 
-        audio = np.concatenate(audio_chunks, axis=0).flatten()
-        duration = len(audio) / sr
+        audio = np.concatenate(chunks, axis=0).flatten()
+        duration = len(audio) / sample_rate
         sys.stdout.write(f"  ✂️  Captured {duration:.1f}s of audio\n")
         sys.stdout.flush()
         return audio

tests/integrations/test_discord_vendor.py

@@ -174,6 +174,103 @@ class TestDiscordVendor:
         assert result is False
 
 
+class TestExtractContent:
+    def test_strips_bot_mention(self):
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
+
+        vendor = DiscordVendor()
+        vendor._client = MagicMock()
+        vendor._client.user.id = 12345
+        msg = MagicMock()
+        msg.content = "<@12345> hello there"
+        assert vendor._extract_content(msg) == "hello there"
+
+    def test_no_client_user(self):
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
+
+        vendor = DiscordVendor()
+        vendor._client = MagicMock()
+        vendor._client.user = None
+        msg = MagicMock()
+        msg.content = "hello"
+        assert vendor._extract_content(msg) == "hello"
+
+    def test_empty_after_strip(self):
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
+
+        vendor = DiscordVendor()
+        vendor._client = MagicMock()
+        vendor._client.user.id = 99
+        msg = MagicMock()
+        msg.content = "<@99>"
+        assert vendor._extract_content(msg) == ""
+
+
+class TestInvokeAgent:
+    @staticmethod
+    def _make_typing_target():
+        """Build a mock target whose .typing() is an async context manager."""
+        from contextlib import asynccontextmanager
+
+        target = AsyncMock()
+
+        @asynccontextmanager
+        async def _typing():
+            yield
+
+        target.typing = _typing
+        return target
+
+    @pytest.mark.asyncio
+    async def test_timeout_returns_error(self):
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
+
+        vendor = DiscordVendor()
+        target = self._make_typing_target()
+
+        with patch(
+            "integrations.chat_bridge.vendors.discord.chat_with_tools", side_effect=TimeoutError
+        ):
+            run_output, response = await vendor._invoke_agent("hi", "sess", target)
+        assert run_output is None
+        assert "too long" in response
+
+    @pytest.mark.asyncio
+    async def test_exception_returns_error(self):
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
+
+        vendor = DiscordVendor()
+        target = self._make_typing_target()
+
+        with patch(
+            "integrations.chat_bridge.vendors.discord.chat_with_tools",
+            side_effect=RuntimeError("boom"),
+        ):
+            run_output, response = await vendor._invoke_agent("hi", "sess", target)
+        assert run_output is None
+        assert "trouble" in response
+
+
+class TestSendResponse:
+    @pytest.mark.asyncio
+    async def test_skips_empty(self):
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
+
+        target = AsyncMock()
+        await DiscordVendor._send_response(None, target)
+        target.send.assert_not_called()
+        await DiscordVendor._send_response("", target)
+        target.send.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_sends_short_message(self):
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
+
+        target = AsyncMock()
+        await DiscordVendor._send_response("hello", target)
+        target.send.assert_called_once_with("hello")
+
+
 class TestChunkMessage:
     def test_short_message(self):
         from integrations.chat_bridge.vendors.discord import _chunk_message

tests/timmy/test_agents_base.py

@@ -361,6 +361,53 @@ class TestRun:
         assert response == "ok"
 
 
+# ── _handle_retry_or_raise ────────────────────────────────────────────────
+
+
+class TestHandleRetryOrRaise:
+    def test_raises_on_last_attempt(self):
+        BaseAgent = _make_base_class()
+        with pytest.raises(ValueError, match="boom"):
+            BaseAgent._handle_retry_or_raise(
+                ValueError("boom"),
+                attempt=3,
+                max_retries=3,
+                transient=False,
+            )
+
+    def test_raises_on_last_attempt_transient(self):
+        BaseAgent = _make_base_class()
+        exc = httpx.ConnectError("down")
+        with pytest.raises(httpx.ConnectError):
+            BaseAgent._handle_retry_or_raise(
+                exc,
+                attempt=3,
+                max_retries=3,
+                transient=True,
+            )
+
+    def test_no_raise_on_early_attempt(self):
+        BaseAgent = _make_base_class()
+        # Should return None (no raise) on non-final attempt
+        result = BaseAgent._handle_retry_or_raise(
+            ValueError("retry me"),
+            attempt=1,
+            max_retries=3,
+            transient=False,
+        )
+        assert result is None
+
+    def test_no_raise_on_early_transient(self):
+        BaseAgent = _make_base_class()
+        result = BaseAgent._handle_retry_or_raise(
+            httpx.ReadTimeout("busy"),
+            attempt=2,
+            max_retries=3,
+            transient=True,
+        )
+        assert result is None
+
+
 # ── get_capabilities / get_status ────────────────────────────────────────────
 
 

tests/timmy/test_voice_loop.py

@@ -15,7 +15,7 @@ except ImportError:
     np = None
 
 try:
-    from timmy.voice_loop import VoiceConfig, VoiceLoop, _strip_markdown
+    from timmy.voice_loop import VoiceConfig, VoiceLoop, _rms, _strip_markdown
 except ImportError:
     pass  # pytestmark will skip all tests anyway
 
@@ -147,6 +147,31 @@ class TestStripMarkdown:
         assert "*" not in result
 
 
+class TestRms:
+    def test_silent_block(self):
+        block = np.zeros(1600, dtype=np.float32)
+        assert _rms(block) == pytest.approx(0.0, abs=1e-7)
+
+    def test_loud_block(self):
+        block = np.ones(1600, dtype=np.float32)
+        assert _rms(block) == pytest.approx(1.0, abs=1e-5)
+
+
+class TestFinalizeUtterance:
+    def test_returns_none_for_empty(self):
+        assert VoiceLoop._finalize_utterance([], min_blocks=5, sample_rate=16000) is None
+
+    def test_returns_none_for_too_short(self):
+        chunks = [np.zeros(1600, dtype=np.float32) for _ in range(3)]
+        assert VoiceLoop._finalize_utterance(chunks, min_blocks=5, sample_rate=16000) is None
+
+    def test_returns_audio_for_sufficient_chunks(self):
+        chunks = [np.ones(1600, dtype=np.float32) for _ in range(6)]
+        result = VoiceLoop._finalize_utterance(chunks, min_blocks=5, sample_rate=16000)
+        assert result is not None
+        assert len(result) == 6 * 1600
+
+
 class TestThink:
     def test_think_returns_response(self):
         loop = VoiceLoop()