Initial commit

skills/mem-search/operations/prompts.md

@@ -0,0 +1,125 @@
+# Search User Prompts (Full-Text)
+
+Search raw user prompts to find what was actually asked across all sessions.
+
+## When to Use
+
+- User asks: "What did I ask about authentication?"
+- User asks: "Find my question about database migrations"
+- User asks: "When did I ask about testing?"
+- Looking for specific user questions or requests
+
+## Command
+
+```bash
+curl -s "http://localhost:37777/api/search/prompts?query=authentication&format=index&limit=5"
+```
+
+## Parameters
+
+- **query** (required): Search terms (e.g., "authentication", "how do I", "bug fix")
+- **format**: "index" (truncated prompts) or "full" (complete prompt text). Default: "full"
+- **limit**: Number of results (default: 20, max: 100)
+- **project**: Filter by project name (optional)
+- **dateRange**: Filter by date range (optional)
+
+## When to Use Each Format
+
+**Use format=index for:**
+- Quick overviews of what was asked
+- Finding prompt IDs for full text
+- Listing multiple prompts
+- **Token cost: ~50-100 per result (truncated to 200 chars)**
+
+**Use format=full for:**
+- Complete prompt text
+- Understanding the full user request
+- **Token cost: Variable (depends on prompt length, typically 100-300 tokens)**
+
+## Example Response (format=index)
+
+```json
+{
+  "query": "authentication",
+  "count": 5,
+  "format": "index",
+  "results": [
+    {
+      "id": 1250,
+      "session_id": "S545",
+      "prompt_preview": "How do I implement JWT authentication with refresh tokens? I need to handle token expiration...",
+      "created_at_epoch": 1699564800000,
+      "project": "api-server"
+    }
+  ]
+}
+```
+
+## How to Present Results
+
+For format=index, present as a compact list:
+
+```markdown
+Found 5 user prompts about "authentication":
+
+💬 **Prompt #1250** (Session #545)
+   > "How do I implement JWT authentication with refresh tokens? I need to handle token expiration..."
+   > Nov 9, 2024 • api-server
+
+💬 **Prompt #1251** (Session #546)
+   > "The auth tokens are expiring too quickly. Can you help debug the refresh flow?"
+   > Nov 8, 2024 • api-server
+```
+
+For complete formatting guidelines, see [formatting.md](formatting.md).
+
+## What Gets Searched
+
+User prompts search covers:
+- All user messages sent to Claude Code
+- Raw text as typed by the user
+- Multi-turn conversations (each message is a separate prompt)
+- Questions, requests, commands, and clarifications
+
+## Error Handling
+
+**Missing query parameter:**
+```json
+{"error": "Missing required parameter: query"}
+```
+Fix: Add the query parameter
+
+**No results found:**
+```json
+{"query": "foobar", "count": 0, "results": []}
+```
+Response: "No user prompts found for 'foobar'. Try different search terms."
+
+## Tips
+
+1. Use exact phrases in quotes: `?query="how do I"` for precise matches
+2. Start with format=index to see preview, then get full text if needed
+3. Use dateRange to find recent questions: `?query=bug&dateRange[start]=2024-11-01`
+4. Prompts show what was asked, sessions/observations show what was done
+5. Combine with session search to see both question and answer
+
+**Token Efficiency:**
+- Start with format=index (~50-100 tokens per result, prompt truncated to 200 chars)
+- Use format=full only for relevant items (100-300 tokens per result)
+- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md)
+
+## When to Use Prompts vs Sessions
+
+**Use prompts search when:**
+- Looking for specific user questions
+- Trying to remember what was asked
+- Finding original request wording
+
+**Use sessions search when:**
+- Looking for what was accomplished
+- Understanding work summaries
+- Getting high-level context
+
+**Combine both when:**
+- Understanding the full conversation (what was asked + what was done)
+- Investigating how a request was interpreted