reflections

Search Conversation History

Search past conversations to answer: $ARGUMENTS

Environment

• Plugin directory: ~/.claude/plugins/local-marketplace/plugins/claude-reflections
• Project name formula: strip leading /, replace / with -, prepend -
  • Example: /home/corona/foo → -home-corona-foo

Workflow

1. Check installation:

   ls ~/.claude/plugins/local-marketplace/plugins/claude-reflections/pyproject.toml
   

   If file not found, tell the user: "The reflections system is not installed. Run ./install.sh in the plugin directory at ~/.claude/plugins/local-marketplace/plugins/claude-reflections/."

2. Search conversations:

   cd ~/.claude/plugins/local-marketplace/plugins/claude-reflections
   uv run claude-reflections search "SEARCH_TERMS" --project="PROJECT_NAME" --limit 5
   

   • Extract search terms from the user's question
   • Derive project name from the working directory
   • Search auto-indexes the project incrementally before searching

3. Read matched conversations: For each search result, use Read to examine the JSONL file at the returned line number (±10 lines for context).

4. Synthesize answer: Extract relevant information and provide a clear answer. Cite conversation dates if helpful.

CLI Reference

All commands run from the plugin directory.

PLUGIN_DIR=~/.claude/plugins/local-marketplace/plugins/claude-reflections
cd "$PLUGIN_DIR"

# List all indexed projects
uv run claude-reflections list

# Check indexing status for a project
uv run claude-reflections status --project="-home-corona-foo"

# Search (auto-indexes when --project specified)
uv run claude-reflections search "query terms" --project="-home-corona-foo" --limit 5

# Manual full reindex
uv run claude-reflections index --project="-home-corona-foo" --full --verbose

Search Output Format

1. [assistant] Score: 0.892
   Project: -home-corona-foo
   File: /home/corona/.claude/projects/-home-corona-foo/abc123.jsonl
   Line: 45
   Time: 2025-01-04T10:30:00+00:00
   Preview: We implemented authentication using...

JSONL Format

Conversation files at ~/.claude/projects/<project>/*.jsonl contain one JSON object per line:

{"type":"user","timestamp":"2025-01-04T10:30:00Z","message":{"role":"user","content":"How do we handle auth?"}}
{"type":"assistant","timestamp":"2025-01-04T10:30:15Z","message":{"role":"assistant","content":[{"type":"text","text":"We use JWT..."}]}}

• type: "user" or "assistant"
• timestamp: ISO format
• message.content: text (user) or array of blocks (assistant)

Troubleshooting

Issue	Solution
Plugin not installed	Run ./install.sh in the plugin directory
No search results	Check project is indexed: uv run claude-reflections list
Wrong project name	Verify with pwd | sed 's|^/|-|' | tr '/' '-'
Database error	Delete ~/.claude/reflections/<project>/vectors.db and reindex
CLI errors	See install.md for full troubleshooting

For installation or configuration issues, direct the user to install.md.