Initial commit

2025-11-30 09:01:43 +08:00
commit 7de5fc7545
28 changed files with 4312 additions and 0 deletions
--- a/skills/mem-search/operations/timeline-by-query.md
+++ b/skills/mem-search/operations/timeline-by-query.md
@@ -0,0 +1,192 @@
+# Timeline by Query
+
+Search for observations and get timeline context in a single request. Combines search + timeline into one operation.
+
+## When to Use
+
+- User asks: "What was happening when we worked on authentication?"
+- User asks: "Show me context around bug fixes"
+- User asks: "Timeline of database work"
+- Need to find something then see temporal context
+
+## Command
+
+```bash
+# Auto mode: Uses top search result as timeline anchor
+curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=auto&depth_before=10&depth_after=10"
+
+# Interactive mode: Shows top N search results for manual selection
+curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=interactive&limit=5"
+```
+
+## Parameters
+
+- **query** (required): Search terms (e.g., "authentication", "bug fix", "database")
+- **mode**: Search mode
+  - `auto` (default): Automatically uses top search result as timeline anchor
+  - `interactive`: Returns top N search results for manual anchor selection
+- **depth_before**: Records before anchor (default: 10, max: 50) - for auto mode
+- **depth_after**: Records after anchor (default: 10, max: 50) - for auto mode
+- **limit**: Number of search results (default: 5, max: 20) - for interactive mode
+- **project**: Filter by project name (optional)
+
+## Auto Mode (Recommended)
+
+Automatically gets timeline around best match:
+
+```bash
+curl -s "http://localhost:37777/api/timeline/by-query?query=JWT+authentication&mode=auto&depth_before=10&depth_after=10"
+```
+
+**Response:**
+```json
+{
+  "query": "JWT authentication",
+  "mode": "auto",
+  "best_match": {
+    "id": 1234,
+    "type": "feature",
+    "title": "Implemented JWT authentication",
+    "score": 0.95
+  },
+  "timeline": [
+    // ... timeline records around observation #1234
+  ]
+}
+```
+
+**When to use auto mode:**
+- You're confident the top result is what you want
+- Want fastest path to timeline context
+- Query is specific enough for accurate top result
+
+## Interactive Mode
+
+Shows top search results for manual review:
+
+```bash
+curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=interactive&limit=5"
+```
+
+**Response:**
+```json
+{
+  "query": "authentication",
+  "mode": "interactive",
+  "top_matches": [
+    {
+      "id": 1234,
+      "type": "feature",
+      "title": "Implemented JWT authentication",
+      "subtitle": "Added token-based auth with refresh tokens",
+      "score": 0.95
+    },
+    {
+      "id": 1240,
+      "type": "bugfix",
+      "title": "Fixed authentication token expiration",
+      "subtitle": "Resolved race condition in refresh flow",
+      "score": 0.87
+    }
+  ],
+  "next_step": "Use /api/timeline/context?anchor=<id>&depth_before=10&depth_after=10"
+}
+```
+
+**When to use interactive mode:**
+- Query is broad and may have multiple relevant results
+- Want to review options before getting timeline
+- Not sure which result is most relevant
+
+## How to Present Results
+
+**For auto mode:**
+
+```markdown
+## Timeline: JWT authentication
+
+**Best Match:** 🟣 Observation #1234 - Implemented JWT authentication (score: 0.95)
+
+### Before (10 records)
+**2:45 PM** - 🟣 Added authentication middleware
+
+### ⭐ Anchor Point (2:55 PM)
+🟣 **Observation #1234**: Implemented JWT authentication
+
+### After (10 records)
+**3:00 PM** - 🎯 Session completed: JWT authentication system
+```
+
+**For interactive mode:**
+
+```markdown
+Found 5 matches for "authentication":
+
+1. 🟣 **#1234** Implemented JWT authentication (score: 0.95)
+   > Added token-based auth with refresh tokens
+
+2. 🔴 **#1240** Fixed authentication token expiration (score: 0.87)
+   > Resolved race condition in refresh flow
+
+To see timeline context, use observation ID with timeline operation.
+```
+
+For complete formatting guidelines, see [formatting.md](formatting.md).
+
+## Error Handling
+
+**Missing query parameter:**
+```json
+{"error": "Missing required parameter: query"}
+```
+Fix: Add the query parameter
+
+**No results found:**
+```json
+{"query": "foobar", "top_matches": []}
+```
+Response: "No results found for 'foobar'. Try different search terms."
+
+## Tips
+
+1. **Use auto mode** for specific queries: "JWT authentication implementation"
+2. **Use interactive mode** for broad queries: "authentication"
+3. Start with depth 10/10 for balanced context
+4. Be specific in queries for better auto mode accuracy
+5. This is fastest way to find + explore context in one request
+
+**Token Efficiency:**
+- Auto mode: ~3,000-4,000 tokens (search + timeline)
+- Interactive mode: ~500-1,000 tokens (search results only)
+- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md)
+
+## Workflow Comparison
+
+**timeline-by-query (auto):**
+1. One request → get timeline around best match
+2. ~3,000 tokens
+
+**timeline-by-query (interactive) → timeline:**
+1. First request → see top matches (~500 tokens)
+2. Second request → get timeline for chosen match (~3,000 tokens)
+3. Total: ~3,500 tokens
+
+**observations search → timeline:**
+1. Search observations (~500 tokens)
+2. Get timeline for chosen result (~3,000 tokens)
+3. Total: ~3,500 tokens
+
+Use auto mode when you're confident about the query. Use interactive mode or separate search when you want more control.
+
+## When to Use Timeline-by-Query
+
+**Use timeline-by-query when:**
+- Need to find something AND see temporal context
+- Want one-request convenience (auto mode)
+- Investigating "what was happening when we worked on X?"
+- Don't have observation ID already
+
+**Don't use timeline-by-query when:**
+- Already have observation ID (use timeline instead)
+- Just need search results (use observations search)
+- Need recent work overview (use recent-context)