flynn/docs/plans/phase2-pr3-history-index-checklist.md

Phase 2 PR #3 Checklist: History Index and Topic Search

Created: 2026-02-12 Owner: Flynn core Status: ready to implement

Goal

Add lightweight session history indexing to support topic/keyword search and improve future routing/context decisions.

Scope

In scope:

• message metadata indexing (keywords/topics)
• search API over indexed history
• optional routing confidence boost hook
• gateway handlers for search and reindex

Out of scope:

• heavyweight semantic/vector history search
• UI redesign for history explorer

Files

New:

• src/session/indexer.ts
• src/session/search.ts
• src/session/indexer.test.ts
• src/session/search.test.ts
• src/gateway/handlers/history.ts

Modified:

• src/config/schema.ts
• src/session/store.ts
• src/session/manager.ts
• src/daemon/index.ts
• src/daemon/routing.ts
• src/gateway/handlers/index.ts

Implementation Steps

1. Add history_index config section (enabled, max_keywords, search_limit, etc.).
2. Extend session persistence with metadata field (migration-safe).
3. Implement indexer:
   • tokenize + stopword filtering
   • extract top keywords/topics
   • attach metadata when messages are written
4. Implement searcher:
   • query keyword overlap
   • rank by relevance + recency
5. Wire into session manager lifecycle.
6. Add gateway handlers:
   • history.search
   • history.reindex
7. Add optional routing hook to boost confidence when query overlaps strong historical topics.

Validation Commands

pnpm typecheck
pnpm test:run src/session/indexer.test.ts
pnpm test:run src/session/search.test.ts
pnpm test:run src/session/store.test.ts
pnpm test:run src/session/manager.test.ts
pnpm test:run src/daemon/routing.test.ts
pnpm test:run
pnpm lint
pnpm build

Acceptance Criteria

• Metadata indexing persists without breaking existing sessions.
• History search returns ranked, relevant results.
• Reindex operation is safe and idempotent.
• Existing session behavior remains unchanged when feature disabled.
• Routing boost path is optional and bounded.

Risks

• DB migration regressions on existing data.
  • Mitigation: additive migration + migration tests.
• Search noise (low precision).
  • Mitigation: score threshold + max result cap.

Commit Message

feat(session): add history indexing and topic search metadata