PSA/ee/docs/plans/2026-04-07-ai-chat-history-search/SCRATCHPAD.md

Scratchpad — AI Chat History Search

• Plan slug: 2026-04-07-ai-chat-history-search
• Created: 2026-04-07

What This Is

Working memory for adding searchable AI chat history to the existing enterprise chat sidebar.

Decisions

• (2026-04-07) Search scope is chat-level only. Results should return matching chats, not individual matching messages or snippets.
• (2026-04-07) A match should come from either chat titles or persisted message body content.
• (2026-04-07) Use Postgres full-text search over the existing chats and messages tables rather than vector search or a denormalized search document.
• (2026-04-07) Keep the feature inside the existing history card in RightSidebarContent.tsx; do not add a separate page or modal.
• (2026-04-07) Keep preview_text behavior unchanged: show the latest persisted message preview, not the matched text excerpt.
• (2026-04-07) Minimum query length is assumed to be 2 characters unless product scope changes during review.

Discoveries / Constraints

• (2026-04-07) Current persistence lives in ee/server/src/lib/chat-actions/chatActions.tsx, with Chat.getRecentByUser(...) in ee/server/src/models/chat.ts and Message.getByChatId(...) in ee/server/src/models/message.ts.
• (2026-04-07) The history sidebar already uses one server-action seam for recent history and one for full-chat load, so search can slot into that pattern with a new action instead of a new API route.
• (2026-04-07) The existing AI schema migration already creates process_large_lexemes(...) and uses generated tsvector columns elsewhere, so chat search can reuse that pattern.
• (2026-04-07) Chat.tsx persists chats/messages during the existing SSE flow; search should avoid changing that write path.
• (2026-04-07) The current history list is capped at 20 rows and uses latest persisted message content as preview_text; search should preserve both unless scope changes.
• (2026-04-07) Existing sidebar tests live in server/src/test/unit/RightSidebar.historyToggle.test.tsx; DB-backed persistence tests already exist in server/src/test/integration/chatPersistenceExecution.integration.test.ts.

Commands / Runbooks

• (2026-04-07) Locate relevant chat history flow: rg -n "RightSidebarContent|listCurrentUserChatsAction|getChatMessagesAction|createNewChatAction|addMessageToChatAction" .
• (2026-04-07) Inspect current chat actions: sed -n '1,280p' ee/server/src/lib/chat-actions/chatActions.tsx
• (2026-04-07) Inspect chat persistence query shape: sed -n '1,260p' ee/server/src/models/chat.ts
• (2026-04-07) Inspect current history sidebar behavior: sed -n '1,760p' ee/server/src/components/layout/RightSidebarContent.tsx
• (2026-04-07) Inspect AI schema migration: sed -n '1,180p' ee/server/migrations/202410291100_create_ai_schema.cjs
• (2026-04-07) Validate the plan artifacts: python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-04-07-ai-chat-history-search

Links / References

• ee/server/src/components/layout/RightSidebarContent.tsx
• ee/server/src/components/chat/Chat.tsx
• ee/server/src/lib/chat-actions/chatActions.tsx
• ee/server/src/models/chat.ts
• ee/server/src/models/message.ts
• ee/server/migrations/202410291100_create_ai_schema.cjs
• server/src/test/unit/RightSidebar.historyToggle.test.tsx
• server/src/test/integration/chatPersistenceExecution.integration.test.ts

Open Questions

• No blocking product questions remain after confirming:
  • chat-level results only
  • match on titles and message content
  • Postgres full-text search path

Implementation Log

• (2026-04-07) Completed F001: Added migration ee/server/migrations/20260407163000_add_chat_history_search_indexes.cjs to create chats.title_index as a stored generated tsvector from coalesce(title_text, '').
• (2026-04-07) Completed F002: Added chats_title_index_idx GIN index on chats.title_index in the same migration.
• (2026-04-07) Completed F003: Added messages.content_index as a stored generated tsvector using process_large_lexemes(coalesce(content, '')) in the same migration.
• (2026-04-07) Completed F004: Added messages_content_index_idx GIN index on messages.content_index in the same migration.
• (2026-04-07) Completed F005: Added Chat.searchByUser(userId, query, limit) in ee/server/src/models/chat.ts returning ChatHistoryItem[].
• (2026-04-07) Completed F006: Chat.searchByUser matches chats by chats.title_index OR related messages.content_index using websearch_to_tsquery.
• (2026-04-07) Completed F007: Chat.searchByUser keeps one row per chat (chat-driven query with exists) and orders by relevance rank then recency (coalesce(updated_at, created_at) desc).
• (2026-04-07) Completed F008: Chat.searchByUser preserves preview_text from the latest persisted message (message_order desc, fallback id desc).
• (2026-04-07) Completed F009: Added searchCurrentUserChatsAction(query, limit) in ee/server/src/lib/chat-actions/chatActions.tsx with trim + minimum length (2) guard.
• (2026-04-07) Completed F010: Search action fails closed for unavailable persistence and rollout schema gaps (42P01, 42703) by returning [] and not breaking sidebar behavior.
• (2026-04-07) Completed F011: Added chat-history search input and local query state in ee/server/src/components/layout/RightSidebarContent.tsx.
• (2026-04-07) Completed F012: Empty search query path now explicitly loads recent chats via listCurrentUserChatsAction(HISTORY_LIMIT) and keeps “Recent Chats” mode.
• (2026-04-07) Completed F013: Added debounced search (250ms) for trimmed queries with length >= 2 and “Search Results” labeling.
• (2026-04-07) Completed F014: One-character queries show helper state and skip server search calls.
• (2026-04-07) Completed F015: Search result rows continue to reuse existing row rendering (title, timestamp, preview, rename/delete).
• (2026-04-07) Completed F016: Selecting search result row reuses existing getChatMessagesAction(chatId) load flow.
• (2026-04-07) Completed F017: Added explicit search states for loading, query-too-short, no-results (and preserved no-saved-chats state for recent mode).
• (2026-04-07) Completed F018: Rename/delete now refresh the currently active dataset (recent or current search query) via refreshActiveHistoryDataset.
• (2026-04-07) Completed F019: Clearing query immediately restores recent dataset (no sidebar close/reopen required).
• (2026-04-07) Completed T001/T002: Added DB-backed integration coverage in server/src/test/integration/chatHistorySearch.integration.test.ts for title+message matching, dedupe, preview behavior, relevance+recency ordering, user scoping, and non-match guard.
• (2026-04-07) Completed T003/T004/T005/T006: Added sidebar unit coverage in server/src/test/unit/RightSidebar.historySearch.test.tsx for empty-query recent mode, debounced threshold switching, query-too-short helper, clear-to-recent behavior, no-results state, result selection load, and rename/delete re-search behavior.
• (2026-04-07) Completed T007: Added searchCurrentUserChatsAction fail-closed unit coverage in server/src/test/unit/chatActions.searchCurrentUserChatsAction.test.ts for unavailable persistence and missing-column rollout scenarios.

Additional Gotchas

• Chat search uses cached persistence checks in chatActions.tsx; unit tests that validate fallback behavior should reset modules or isolate imports to avoid cross-test cache effects.
• Search refresh after mutations is tied to current trimmed query state to keep mode consistency between recent/search datasets.