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

Created: 2026-02-12
Owner: Flynn core
Status: completed

## 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

```bash
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`

## Completion Notes (2026-02-13)

- Implemented `history_index` config with defaults and bounds.
- Added migration-safe message metadata persistence in SQLite.
- Implemented indexing/tokenization and ranked history search with recency weighting.
- Wired indexing/search lifecycle in `SessionManager` and routing boost hook in daemon routing.
- Added gateway handlers for `history.search` and `history.reindex`.
- Verified with full suite: `pnpm test:run` (`1593/1593`), plus `pnpm typecheck` and `pnpm build`.