conversation-search

SKILL.md

---
name: conversation-search
description: >-
  Search Polly conversation history by keyword to recall what was previously discussed.
  Use when the user asks what was said before, references a prior conversation, wants to
  look up a past decision or discussion, or when context from a previous session would
  help answer a question. Keywords: we discussed, last time, previously, earlier
  conversation, do you remember, look back, find the conversation where.
---

# Conversation Search

Searches conversation history across sessions and task chats, returns a compact match index and saves full context windows as temp files.

## Storage Layout

```
/home/polly/sessions/s_{provider}_{channel_id}_{conv_id}_assistant/
    session_data.json       # metadata: created_at, updated_at, provider, message_count
    conversation.jsonl      # active messages
    archive/compact_*.jsonl # compacted older messages (same JSONL format — search both)
    archive/message_*.json  # externalized large messages (script follows these pointers)

/home/polly/tasks/{task_id}/
    task_context.jsonl      # user↔Polly task chat (INCLUDE by default)
    task_data.json          # task metadata: task_name, created_at
    runs/{run_id}/
        messages.jsonl      # automated agent run (EXCLUDE by default)
        run_data.json       # run metadata
```

Providers: `web` (main UI), `slack`, `imessage`, `task_chat`

**Important:** Sessions can run for weeks. A session created on March 16 may still contain April 17 messages. The date filter matches sessions that were ACTIVE during the range (created_at before end AND updated_at after start), not just sessions whose updated_at falls within the range.

## Script

```
/home/polly/skills/installed/conversation-search/scripts/search_conversations.py
```

```bash
python3 <script> "<query>" [options]

Key options:
  --session SESSION_ID      Search only this specific session (partial ID match ok)
  --provider web|slack|imessage|task_chat|all   (default: all)
  --after YYYY-MM-DD        Sessions active after this date
  --before YYYY-MM-DD       Sessions active before this date
  --context-turns N         Turns captured around each match (default: 4)
  --max-matches N           (default: 10)
  --output-dir PATH         Where temp JSON files are saved (default: /tmp)
  --no-task-chat            Exclude task-scoped chats
  --include-runs            Include automated task run messages
```

## Output

The script prints a JSON object:
```json
{
  "query": "...",
  "total_matches": N,
  "index": [
    {
      "match_index": 0,
      "match_timestamp": "2026-04-17T...",
      "match_role": "user",
      "snippet": "first 150 chars of matching message",
      "source_type": "session|task_chat|task_run",
      "provider": "web|slack|...",
      "session_or_task_id": "s_web_...",
      "label": "human-readable session or task name",
      "source_file": "/home/polly/sessions/.../conversation.jsonl"
    }
  ],
  "saved_context_files": ["/tmp/conv_search_match_00.json", ...]
}
```

Each `conv_search_match_NN.json` contains:
- `match_text`: the matching message text (from externalized file if applicable)
- `match_timestamp`: ISO timestamp
- `context`: array of ±N compact turns around the match
- `source`: full source metadata including raw file path

## Workflow

1. Run the script with `exec_bash`.
2. Present the **index** to the user as a compact summary: timestamp, source, snippet.
3. Do NOT automatically load all context files — only load specific ones if:
   - The user asks for details from a specific match
   - You need more context to answer the current question
4. To load a context file: `cat /tmp/conv_search_match_NN.json` or `exec_bash`.
5. Provide the `source_file` path if the user wants the full raw transcript.

## Key Workflow Rules (learned from failure)

- **Never declare content "lost to compaction"** — compact archives ARE the original messages. The script follows externalized message pointers automatically.
- **Long-running sessions span date ranges** — if a session was created March 16 and updated April 17, searching for "April 17" WILL find it. Don't assume a session was the wrong one based on its creation date.
- **Use `--session` for targeted search** — if you know the session ID, go directly to it rather than scanning all sessions.
- **Keyword absence ≠ content absence** — if a keyword search returns zero matches in a session, try broader terms. The actual words used may differ from what you expect.

## Context Budget

- Default `--context-turns 4` gives ±4 messages (8 total) per match.
- For deeper context on a specific match: re-run with `--session <id> --context-turns 10`.
- Avoid loading more than 2-3 full context files in one turn.