Remembering Conversations

# Remembering Conversations

Search archived conversations using semantic similarity or exact text matching.

**Core principle:** Search before reinventing.

**Announce:** "I'm searching previous conversations for [topic]."

**Setup:** See INDEXING.md

## When to Use

**Search when:**
- Your human partner mentions "we discussed this before"
- Debugging similar issues
- Looking for architectural decisions or patterns
- Before implementing something familiar

**Don't search when:**
- Info in current conversation
- Question about current codebase (use Grep/Read)

## In-Session Use

**Always use subagents** (50-100x context savings). See skills/using-skills for workflow.

**Manual/CLI use:** Direct search (below) for humans outside Claude Code sessions.

## Direct Search (Manual/CLI)

**Tool:** `${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/remembering-conversations/tool/search-conversations`

**Modes:**
```bash
search-conversations "query"              # Vector similarity (default)
search-conversations --text "exact"       # Exact string match
search-conversations --both "query"       # Both modes
```

**Flags:**
```bash
--after YYYY-MM-DD    # Filter by date
--before YYYY-MM-DD   # Filter by date
--limit N             # Max results (default: 10)
--help                # Full usage
```

**Examples:**
```bash
# Semantic search
search-conversations "React Router authentication errors"

# Find git SHA
search-conversations --text "a1b2c3d4"

# Time range
search-conversations --after 2025-09-01 "refactoring"
```

Returns: project, date, conversation summary, matched exchange, similarity %, file path.

**For details:** Run `search-conversations --help`


node_modules/
dist/
*.log
.DS_Store

# Local data (database and archives are at ~/.config/superpowers/, not in repo)
*.sqlite*
.cache/


# Managing Conversation Index

Index, archive, and maintain conversations for search.

## Quick Start

**Install auto-indexing hook:**
```bash
~/.claude/skills/collaboration/remembering-conversations/tool/install-hook
```

**Index all conversations:**
```bash
~/.claude/skills/collaboration/remembering-conversations/tool/index-conversations
```

**Process unindexed only:**
```bash
~/.claude/skills/collaboration/remembering-conversations/tool/index-conversations --cleanup
```

## Features

- **Automatic indexing** via sessionEnd hook (install once, forget)
- **Semantic search** across all past conversations
- **AI summaries** (Claude Haiku with Sonnet fallback)
- **Recovery modes** (verify, repair, rebuild)
- **Permanent archive** at `~/.config/superpowers/conversation-archive/`

## Setup

### 1. Install Hook (One-Time)

```bash
cd ~/.claude/skills/collaboration/remembering-conversations/tool
./install-hook
```

Handles existing hooks gracefully (merge or replace). Runs in background after each session.

### 2. Index Existing Conversations

```bash
# Index everything
./index-conversations

# Or just unindexed (faster, cheaper)
./index-conversations --cleanup
```

## Index Modes

```bash
# Index all (first run or full rebuild)
./index-conversations

# Index specific session (used by hook)
./index-conversations --session <uuid>

# Process only unindexed (missing summaries)
./index-conversations --cleanup

# Check index health
./index-conversations --verify

# Fix detected issues
./index-conversations --repair

# Nuclear option (deletes DB, re-indexes everything)
./index-conversations --rebuild
```

## Recovery Scenarios

| Situation | Command |
|-----------|---------|
| Missed conversations | `--cleanup` |
| Hook didn't run | `--cleanup` |
| Updated conversation | `--verify` then `--repair` |
| Corrupted database | `--rebuild` |
| Index