Enhance memory search functionality with timeline context retrieval (#151)

- Introduced optional timeline context retrieval step in memory search flow to provide users with better understanding of previous sessions.
- Updated SKILL.md to reflect new flow, including timeline context commands and usage scenarios.
- Refactored timeline retrieval commands in timeline-by-query.md and timeline.md to utilize new MCP tools for streamlined access.
- Implemented filtering logic in search-server.ts to respect depth_before and depth_after parameters when displaying timeline items.
- Improved response formatting to include filtered item counts and enhanced user guidance for timeline queries.

plugin/skills/mem-search/SKILL.md

@@ -19,8 +19,9 @@ Use when users ask about PREVIOUS sessions (not current conversation):
 **ALWAYS follow this exact flow:**
 
 1. **Search** - Get an index of results with IDs
-2. **Review** - Look at titles/dates, pick relevant IDs
-3. **Fetch** - Get full details ONLY for those IDs
+2. **Timeline** (optional) - Get context around top results to understand what was happening
+3. **Review** - Look at titles/dates/context, pick relevant IDs
+4. **Fetch** - Get full details ONLY for those IDs
 
 ### Step 1: Search Everything
 
@@ -44,11 +45,30 @@ curl "http://localhost:37777/api/search?query=authentication&format=index&limit=
    ID: 10942
 ```
 
-### Step 2: Pick IDs
+### Step 2: Get Timeline Context (Optional)
 
-Review the index results. Identify which IDs are actually relevant. Discard the rest.
+When you need to understand "what was happening" around a result:
 
-### Step 3: Fetch by ID
+```bash
+# Get timeline around an observation ID
+curl "http://localhost:37777/api/timeline?anchor=11131&depth_before=3&depth_after=3"
+
+# Or use query to find + get timeline in one step
+curl "http://localhost:37777/api/timeline?query=authentication&depth_before=3&depth_after=3"
+```
+
+**Returns exactly `depth_before + 1 + depth_after` items** - observations, sessions, and prompts interleaved chronologically around the anchor.
+
+**When to use:**
+- User asks "what was happening when..."
+- Need to understand sequence of events
+- Want broader context around a specific observation
+
+### Step 3: Pick IDs
+
+Review the index results (and timeline if used). Identify which IDs are actually relevant. Discard the rest.
+
+### Step 4: Fetch by ID
 
 For each relevant ID, fetch full details:
 

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

@@ -9,14 +9,16 @@ Search for observations and get timeline context in a single request. Combines s
 - User asks: "Timeline of database work"
 - Need to find something then see temporal context
 
-## Command
+## MCP Tool
 
-```bash
+Use the `get_timeline_by_query` MCP tool:
+
+```
 # 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"
+get_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"
+get_timeline_by_query(query="authentication", mode="interactive", limit=5)
 ```
 
 ## Parameters
@@ -34,8 +36,8 @@ curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=
 
 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"
+```
+get_timeline_by_query(query="JWT authentication", mode="auto", depth_before=10, depth_after=10)
 ```
 
 **Response:**
@@ -64,8 +66,8 @@ curl -s "http://localhost:37777/api/timeline/by-query?query=JWT+authentication&m
 
 Shows top search results for manual review:
 
-```bash
-curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=interactive&limit=5"
+```
+get_timeline_by_query(query="authentication", mode="interactive", limit=5)
 ```
 
 **Response:**
@@ -89,7 +91,7 @@ curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=
       "score": 0.87
     }
   ],
-  "next_step": "Use /api/timeline/context?anchor=<id>&depth_before=10&depth_after=10"
+  "next_step": "Use get_context_timeline(anchor=<id>, depth_before=10, depth_after=10)"
 }
 ```
 

plugin/skills/mem-search/operations/timeline.md

@@ -9,17 +9,14 @@ Get a chronological timeline of observations, sessions, and prompts around a spe
 - User asks: "What happened before and after that change?"
 - Need temporal context around an event
 
-## Command
+## MCP Tool
 
-```bash
-# Using observation ID as anchor
-curl -s "http://localhost:37777/api/timeline/context?anchor=1234&depth_before=10&depth_after=10"
+Use the `get_context_timeline` MCP tool:
 
-# Using session ID as anchor
-curl -s "http://localhost:37777/api/timeline/context?anchor=S545&depth_before=10&depth_after=10"
-
-# Using ISO timestamp as anchor
-curl -s "http://localhost:37777/api/timeline/context?anchor=2024-11-09T12:00:00Z&depth_before=10&depth_after=10"
+```
+get_context_timeline(anchor=1234, depth_before=10, depth_after=10)
+get_context_timeline(anchor="S545", depth_before=10, depth_after=10)
+get_context_timeline(anchor="2024-11-09T12:00:00Z", depth_before=10, depth_after=10)
 ```
 
 ## Parameters