claude-mem/plugin/skills/search/operations/timeline-by-query.md

Timeline by Query

Search for something, then automatically get timeline context around the best match.

When to Use

• User asks: "What led to the authentication refactor?"
• Want to find something AND see surrounding context in one request
• Understand the full story with minimal requests

Command

curl -s "http://localhost:37777/api/timeline/by-query?query=authentication+refactor&mode=auto&depth_before=10&depth_after=10"

Parameters

• query (required): Search terms
• mode: Where to search (default: "auto")
  • "auto": Search both observations and sessions, return best match
  • "observations": Search only observations
  • "sessions": Search only sessions
• depth_before: Records before match (default: 10, max: 50)
• depth_after: Records after match (default: 10, max: 50)
• project: Filter by project name (optional)

Response Structure

Returns both the best match AND timeline around it:

{
  "query": "authentication refactor",
  "mode": "auto",
  "match": {
    "type": "observation",
    "id": 1234,
    "title": "Refactored authentication middleware",
    "score": 0.95,
    "created_at_epoch": 1699564800000
  },
  "depth_before": 10,
  "depth_after": 10,
  "timeline": {
    "observations": [...],
    "sessions": [...],
    "prompts": [...]
  }
}

Use Case: "What led to the authentication refactor?"

One query gets both:

1. The authentication refactor observation (best match)
2. Complete timeline before and after showing what led to it

curl -s "http://localhost:37777/api/timeline/by-query?query=authentication+refactor&depth_before=10&depth_after=10"

How to Present Results

## Found: Refactored authentication middleware (Observation #1234)

**Match score:** 0.95
**Date:** Nov 9, 2024 3:30 PM

### Timeline (10 before → 10 after)

**Total:** 18 items (11 obs, 5 sessions, 2 prompts)

### Nov 8, 2024

**2:00 PM** - 🔴 **Bugfix #1220:** "Fixed token validation bug"
> Tokens weren't properly validated

**3:00 PM** - 🔵 **Discovery #1225:** "Current auth middleware is fragile"
> Multiple edge cases not handled

### Nov 9, 2024

**3:30 PM** - 🔄 **Refactor #1234:** "Refactored authentication middleware"  ← MATCH
> Complete rewrite with better error handling

**4:00 PM** - ✅ **Change #1235:** "Updated all routes to use new middleware"

Tips

1. This is the most efficient operation for "what led to X" questions
2. One request instead of two (search + timeline)
3. Use mode="auto" to search both observations and sessions
4. Adjust depth based on how much context you need
5. Great for understanding causality and sequence