feat!: Fix timeline parameter passing with SearchManager alignment

BREAKING CHANGE: Timeline MCP tools now use standardized parameter names
- anchor_id → anchor
- before → depth_before
- after → depth_after
- obs_type → type (timeline tool only)

Fixes timeline endpoint failures caused by parameter name mismatch between
MCP layer and SearchManager. Adds new SessionStore methods for fetching
prompts and session summaries by ID.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [8.0.0] - 2025-12-14
+
+### BREAKING CHANGES
+
+**Timeline MCP Tools Parameter Rename**
+
+Timeline MCP tools now use parameter names matching SearchManager:
+- `anchor_id` → `anchor`
+- `before` → `depth_before`
+- `after` → `depth_after`
+- `obs_type` → `type` (timeline tool only)
+
+**Migration Example:**
+```typescript
+// Old:
+timeline(anchor_id=123, before=10, after=10)
+
+// New:
+timeline(anchor=123, depth_before=10, depth_after=10)
+```
+
+**Affected Tools:** `timeline`, `get_context_timeline`, `get_timeline_by_query`
+
+**Rationale:** Fixes parameter passing bug where timeline tools failed due to name mismatch between MCP layer and SearchManager.
+
+### Fixed
+- Timeline tools now work correctly with proper parameter passing
+- Resolved "Cannot read properties of undefined (reading 'length')" errors in timeline endpoints
+
+---
+
 ## [7.2.1] - 2025-12-14
 
 ## Translation Script Enhancements
@@ -2392,12 +2423,12 @@ None (patch version)
 
 ## [4.3.0] - 2025-10-25
 
-## What's Changed
-* feat: Enhanced context hook with session observations and cross-platform improvements by @thedotmack in https://github.com/thedotmack/claude-mem/pull/25
-
-## New Contributors
-* @thedotmack made their first contribution in https://github.com/thedotmack/claude-mem/pull/25
-
+## What's Changed
+* feat: Enhanced context hook with session observations and cross-platform improvements by @thedotmack in https://github.com/thedotmack/claude-mem/pull/25
+
+## New Contributors
+* @thedotmack made their first contribution in https://github.com/thedotmack/claude-mem/pull/25
+
 **Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v4.2.11...v4.3.0
 
 ## [4.2.10] - 2025-10-25

docs/context/agent-sdk-v2-preview.md

@@ -0,0 +1,390 @@
+# TypeScript SDK V2 interface (preview)
+
+Preview of the simplified V2 TypeScript Agent SDK, with session-based send/receive patterns for multi-turn conversations.
+
+---
+
+<Warning>
+The V2 interface is an **unstable preview**. APIs may change based on feedback before becoming stable. Some features like session forking are only available in the [V1 SDK](/docs/en/agent-sdk/typescript).
+</Warning>
+
+The V2 Claude Agent TypeScript SDK removes the need for async generators and yield coordination. This makes multi-turn conversations simpler—instead of managing generator state across turns, each turn is a separate `send()`/`receive()` cycle. The API surface reduces to three concepts:
+
+- `createSession()` / `resumeSession()`: Start or continue a conversation
+- `session.send()`: Send a message
+- `session.receive()`: Get the response
+
+## Installation
+
+The V2 interface is included in the existing SDK package:
+
+```bash
+npm install @anthropic-ai/claude-agent-sdk
+```
+
+## Quick start
+
+### One-shot prompt
+
+For simple single-turn queries where you don't need to maintain a session, use `unstable_v2_prompt()`. This example sends a math question and logs the answer:
+
+```typescript
+import { unstable_v2_prompt } from '@anthropic-ai/claude-agent-sdk'
+
+const result = await unstable_v2_prompt('What is 2 + 2?', {
+  model: 'claude-sonnet-4-5-20250929'
+})
+console.log(result.result)
+```
+
+<details>
+<summary>See the same operation in V1</summary>
+
+```typescript
+import { query } from '@anthropic-ai/claude-agent-sdk'
+
+const q = query({
+  prompt: 'What is 2 + 2?',
+  options: { model: 'claude-sonnet-4-5-20250929' }
+})
+
+for await (const msg of q) {
+  if (msg.type === 'result') {
+    console.log(msg.result)
+  }
+}
+```
+
+</details>
+
+### Basic session
+
+For interactions beyond a single prompt, create a session. V2 separates sending and receiving into distinct steps:
+- `send()` dispatches your message
+- `receive()` streams back the response
+
+This explicit separation makes it easier to add logic between turns (like processing responses before sending follow-ups).
+
+The example below creates a session, sends "Hello!" to Claude, and prints the text response. It uses [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management) (TypeScript 5.2+) to automatically close the session when the block exits. You can also call `session.close()` manually.
+
+```typescript
+import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'
+
+await using session = unstable_v2_createSession({
+  model: 'claude-sonnet-4-5-20250929'
+})
+
+await session.send('Hello!')
+for await (const msg of session.receive()) {
+  // Filter for assistant messages to get human-readable output
+  if (msg.type === 'assistant') {
+    const text = msg.message.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    console.log(text)
+  }
+}
+```
+
+<details>
+<summary>See the same operation in V1</summary>
+
+In V1, both input and output flow through a single async generator. For a basic prompt this looks similar, but adding multi-turn logic requires restructuring to use an input generator.
+
+```typescript
+import { query } from '@anthropic-ai/claude-agent-sdk'
+
+const q = query({
+  prompt: 'Hello!',
+  options: { model: 'claude-sonnet-4-5-20250929' }
+})
+
+for await (const msg of q) {
+  if (msg.type === 'assistant') {
+    const text = msg.message.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    console.log(text)
+  }
+}
+```
+
+</details>
+
+### Multi-turn conversation
+
+Sessions persist context across multiple exchanges. To continue a conversation, call `send()` again on the same session. Claude remembers the previous turns.
+
+This example asks a math question, then asks a follow-up that references the previous answer:
+
+```typescript
+import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'
+
+await using session = unstable_v2_createSession({
+  model: 'claude-sonnet-4-5-20250929'
+})
+
+// Turn 1
+await session.send('What is 5 + 3?')
+for await (const msg of session.receive()) {
+  // Filter for assistant messages to get human-readable output
+  if (msg.type === 'assistant') {
+    const text = msg.message.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    console.log(text)
+  }
+}
+
+// Turn 2
+await session.send('Multiply that by 2')
+for await (const msg of session.receive()) {
+  if (msg.type === 'assistant') {
+    const text = msg.message.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    console.log(text)
+  }
+}
+```
+
+<details>
+<summary>See the same operation in V1</summary>
+
+```typescript
+import { query } from '@anthropic-ai/claude-agent-sdk'
+
+// Must create an async iterable to feed messages
+async function* createInputStream() {
+  yield {
+    type: 'user',
+    session_id: '',
+    message: { role: 'user', content: [{ type: 'text', text: 'What is 5 + 3?' }] },
+    parent_tool_use_id: null
+  }
+  // Must coordinate when to yield next message
+  yield {
+    type: 'user',
+    session_id: '',
+    message: { role: 'user', content: [{ type: 'text', text: 'Multiply by 2' }] },
+    parent_tool_use_id: null
+  }
+}
+
+const q = query({
+  prompt: createInputStream(),
+  options: { model: 'claude-sonnet-4-5-20250929' }
+})
+
+for await (const msg of q) {
+  if (msg.type === 'assistant') {
+    const text = msg.message.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    console.log(text)
+  }
+}
+```
+
+</details>
+
+### Session resume
+
+If you have a session ID from a previous interaction, you can resume it later. This is useful for long-running workflows or when you need to persist conversations across application restarts.
+
+This example creates a session, stores its ID, closes it, then resumes the conversation:
+
+```typescript
+import {
+  unstable_v2_createSession,
+  unstable_v2_resumeSession,
+  type SDKMessage
+} from '@anthropic-ai/claude-agent-sdk'
+
+// Helper to extract text from assistant messages
+function getAssistantText(msg: SDKMessage): string | null {
+  if (msg.type !== 'assistant') return null
+  return msg.message.content
+    .filter(block => block.type === 'text')
+    .map(block => block.text)
+    .join('')
+}
+
+// Create initial session and have a conversation
+const session = unstable_v2_createSession({
+  model: 'claude-sonnet-4-5-20250929'
+})
+
+await session.send('Remember this number: 42')
+
+// Get the session ID from any received message
+let sessionId: string | undefined
+for await (const msg of session.receive()) {
+  sessionId = msg.session_id
+  const text = getAssistantText(msg)
+  if (text) console.log('Initial response:', text)
+}
+
+console.log('Session ID:', sessionId)
+session.close()
+
+// Later: resume the session using the stored ID
+await using resumedSession = unstable_v2_resumeSession(sessionId!, {
+  model: 'claude-sonnet-4-5-20250929'
+})
+
+await resumedSession.send('What number did I ask you to remember?')
+for await (const msg of resumedSession.receive()) {
+  const text = getAssistantText(msg)
+  if (text) console.log('Resumed response:', text)
+}
+```
+
+<details>
+<summary>See the same operation in V1</summary>
+
+```typescript
+import { query } from '@anthropic-ai/claude-agent-sdk'
+
+// Create initial session
+const initialQuery = query({
+  prompt: 'Remember this number: 42',
+  options: { model: 'claude-sonnet-4-5-20250929' }
+})
+
+// Get session ID from any message
+let sessionId: string | undefined
+for await (const msg of initialQuery) {
+  sessionId = msg.session_id
+  if (msg.type === 'assistant') {
+    const text = msg.message.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    console.log('Initial response:', text)
+  }
+}
+
+console.log('Session ID:', sessionId)
+
+// Later: resume the session
+const resumedQuery = query({
+  prompt: 'What number did I ask you to remember?',
+  options: {
+    model: 'claude-sonnet-4-5-20250929',
+    resume: sessionId
+  }
+})
+
+for await (const msg of resumedQuery) {
+  if (msg.type === 'assistant') {
+    const text = msg.message.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    console.log('Resumed response:', text)
+  }
+}
+```
+
+</details>
+
+### Cleanup
+
+Sessions can be closed manually or automatically using [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management), a TypeScript 5.2+ feature for automatic resource cleanup. If you're using an older TypeScript version or encounter compatibility issues, use manual cleanup instead.
+
+**Automatic cleanup (TypeScript 5.2+):**
+
+```typescript
+import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'
+
+await using session = unstable_v2_createSession({
+  model: 'claude-sonnet-4-5-20250929'
+})
+// Session closes automatically when the block exits
+```
+
+**Manual cleanup:**
+
+```typescript
+import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'
+
+const session = unstable_v2_createSession({
+  model: 'claude-sonnet-4-5-20250929'
+})
+// ... use the session ...
+session.close()
+```
+
+## API reference
+
+### `unstable_v2_createSession()`
+
+Creates a new session for multi-turn conversations.
+
+```typescript
+function unstable_v2_createSession(options: {
+  model: string;
+  // Additional options supported
+}): Session
+```
+
+### `unstable_v2_resumeSession()`
+
+Resumes an existing session by ID.
+
+```typescript
+function unstable_v2_resumeSession(
+  sessionId: string,
+  options: {
+    model: string;
+    // Additional options supported
+  }
+): Session
+```
+
+### `unstable_v2_prompt()`
+
+One-shot convenience function for single-turn queries.
+
+```typescript
+function unstable_v2_prompt(
+  prompt: string,
+  options: {
+    model: string;
+    // Additional options supported
+  }
+): Promise<Result>
+```
+
+### Session interface
+
+```typescript
+interface Session {
+  send(message: string): Promise<void>;
+  receive(): AsyncGenerator<SDKMessage>;
+  close(): void;
+}
+```
+
+## Feature availability
+
+Not all V1 features are available in V2 yet. The following require using the [V1 SDK](/docs/en/agent-sdk/typescript):
+
+- Session forking (`forkSession` option)
+- Some advanced streaming input patterns
+
+## Feedback
+
+Share your feedback on the V2 interface before it becomes stable. Report issues and suggestions through [GitHub Issues](https://github.com/anthropics/claude-code/issues).
+
+## See also
+
+- [TypeScript SDK reference (V1)](/docs/en/agent-sdk/typescript) - Full V1 SDK documentation
+- [SDK overview](/docs/en/agent-sdk/overview) - General SDK concepts
+- [V2 examples on GitHub](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world-v2) - Working code examples

plugin/skills/mem-search/SKILL.md

@@ -10,6 +10,7 @@ Search past work across all sessions. Simple workflow: search → get IDs → fe
 ## When to Use
 
 Use when users ask about PREVIOUS sessions (not current conversation):
+
 - "Did we already fix this?"
 - "How did we solve X last time?"
 - "What happened last week?"
@@ -25,16 +26,23 @@ Use when users ask about PREVIOUS sessions (not current conversation):
 
 ### Step 1: Search Everything
 
-```bash
-curl "http://localhost:37777/api/search?query=authentication&format=index&limit=40"
-```
+Use the `search` MCP tool:
 
 **Required parameters:**
+
 - `query` - Search term
-- `format=index` - ALWAYS start with index (lightweight)
-- `limit=40` - You can request large indexes as necessary
+- `format: "index"` - ALWAYS start with index (lightweight)
+- `limit: 30` - You can request large indexes as necessary
+- `project` - Project name (required)
+
+**Example:**
+
+```
+search(query="authentication", format="index", limit=30, project="my-project")
+```
 
 **Returns:**
+
 ```
 1. [feature] Added JWT authentication
    Date: 11/17/2025, 3:48:45 PM
@@ -47,19 +55,26 @@ curl "http://localhost:37777/api/search?query=authentication&format=index&limit=
 
 ### Step 2: Get Timeline Context
 
-You MUST understand "what was happening" around a result:
+You MUST understand "what was happening" around a result.
 
-```bash
-# Get timeline around an observation ID
-curl "http://localhost:37777/api/timeline?anchor=11131&depth_before=3&depth_after=3"
+Use the `timeline` MCP tool:
 
-# Or use query to find + get timeline in one step
-curl "http://localhost:37777/api/timeline?query=authentication&depth_before=3&depth_after=3"
+**Example with observation ID:**
+
+```
+timeline(anchor=11131, depth_before=3, depth_after=3, project="my-project")
+```
+
+**Example with query (finds anchor automatically):**
+
+```
+timeline(query="authentication", depth_before=3, depth_after=3, project="my-project")
 ```
 
 **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
@@ -70,52 +85,66 @@ Review the index results (and timeline if used). Identify which IDs are actually
 
 ### Step 4: Fetch by ID
 
-For each relevant ID, fetch full details:
+For each relevant ID, fetch full details using MCP tools:
 
-```bash
-# Fetch single observation
-curl "http://localhost:37777/api/observation/11131"
+**Fetch single observation:**
 
-# Fetch multiple observations in one request (more efficient)
-curl -X POST "http://localhost:37777/api/observations/batch" \
-  -H "Content-Type: application/json" \
-  -d '{"ids": [11131, 10942, 10855]}'
-
-# Fetch session
-curl "http://localhost:37777/api/session/2005"
-
-# Fetch prompt
-curl "http://localhost:37777/api/prompt/5421"
+```
+get_observation(id=11131)
 ```
 
-**Batch fetch options:**
-```bash
-# With ordering and limit
-curl -X POST "http://localhost:37777/api/observations/batch" \
-  -H "Content-Type: application/json" \
-  -d '{"ids": [11131, 10942], "orderBy": "date_desc", "limit": 10}'
+**Fetch multiple observations (recommended for 2+ IDs):**
+
+```
+get_batch_observations(ids=[11131, 10942, 10855])
+```
+
+**With ordering and limit:**
+
+```
+get_batch_observations(
+  ids=[11131, 10942, 10855],
+  orderBy="date_desc",
+  limit=10
+)
+```
+
+**Fetch session:**
+
+```
+get_session(id=2005)  # Just the number from S2005
+```
+
+**Fetch prompt:**
+
+```
+get_prompt(id=5421)
 ```
 
 **ID formats:**
+
 - Observations: Just the number (11131)
 - Sessions: Just the number (2005) from "S2005"
 - Prompts: Just the number (5421)
 
 **When to use batch:**
-- Always use batch when fetching 2+ observations
+
+- Always use `get_batch_observations` when fetching 2+ observations
 - More efficient: one request vs multiple
 - Returns all observations in a single response
 
 ## Search Parameters
 
 **Basic:**
+
 - `query` - What to search for (required)
 - `format` - "index" or "full" (always use "index" first)
-- `limit` - How many results (default 5, max 100)
+- `limit` - How many results (default 30)
+- `project` - Filter by project name (required)
 
 **Filters (optional):**
+
 - `type` - Filter to "observations", "sessions", or "prompts"
-- `project` - Filter by project name
 - `dateStart` - Start date (YYYY-MM-DD or epoch timestamp)
 - `dateEnd` - End date (YYYY-MM-DD or epoch timestamp)
 - `obs_type` - Filter observations by type (comma-separated): bugfix, feature, decision, discovery, change
@@ -123,39 +152,54 @@ curl -X POST "http://localhost:37777/api/observations/batch" \
 ## Examples
 
 **Find recent bug fixes:**
-```bash
-curl "http://localhost:37777/api/search?query=bug&type=observations&obs_type=bugfix&format=index&limit=5"
+
+Use the `search` MCP tool with filters:
+
+```
+search(query="bug", type="observations", obs_type="bugfix", format="index", limit=30, project="my-project")
 ```
 
 **Find what happened last week:**
-```bash
-curl "http://localhost:37777/api/search?query=&type=observations&dateStart=2025-11-11&format=index&limit=10"
+
+Use date filters:
+
+```
+search(type="observations", dateStart="2025-11-11", format="index", limit=30, project="my-project")
 ```
 
 **Search everything:**
-```bash
-curl "http://localhost:37777/api/search?query=database+migration&format=index&limit=5"
+
+Simple query search:
+
+```
+search(query="database migration", format="index", limit=30, project="my-project")
+```
+
+**Get detailed instructions:**
+
+Use the `progressive_ix` tool to load full instructions on-demand:
+
+```
+progressive_ix(topic="workflow")  # Get 4-step workflow
+progressive_ix(topic="search_params")  # Get parameters reference
+progressive_ix(topic="examples")  # Get usage examples
+progressive_ix(topic="all")  # Get complete guide
 ```
 
 ## Why This Workflow?
 
 **Token efficiency:**
+
 - Index format: ~50-100 tokens per result
 - Full format: ~500-1000 tokens per result
 - **10x difference** - only fetch full when you know it's relevant
 
 **Clarity:**
+
 - See everything first
 - Pick what matters
 - Get details only for what you need
 
-## Error Handling
-
-If search fails, tell the user the worker isn't available and suggest:
-```bash
-pm2 list  # Check if worker is running
-```
-
 ---
 
-**Remember:** ALWAYS search with format=index first. ALWAYS fetch by ID for details. The IDs are there for a reason - USE THEM.
+**Remember:** ALWAYS search with format=index first. ALWAYS get timeline context for observations you're interested in. ALWAYS fetch by ID for details. The IDs are there for a reason - use them.

src/servers/mcp-server.ts

@@ -41,7 +41,8 @@ const TOOL_ENDPOINT_MAP: Record<string, string> = {
   'find_by_type': '/api/search/by-type',
   'get_recent_context': '/api/context/recent',
   'get_context_timeline': '/api/context/timeline',
-  'get_timeline_by_query': '/api/timeline/by-query'
+  'get_timeline_by_query': '/api/timeline/by-query',
+  'progressive_ix': '/api/instructions'
 };
 
 /**
@@ -89,6 +90,94 @@ async function callWorkerAPI(
   }
 }
 
+/**
+ * Call Worker HTTP API with path parameter (GET)
+ */
+async function callWorkerAPIWithPath(
+  endpoint: string,
+  id: number
+): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
+  happy_path_error__with_fallback('[mcp-server] → Worker API (path)', { endpoint, id });
+
+  try {
+    const url = `${WORKER_BASE_URL}${endpoint}/${id}`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Worker API error (${response.status}): ${errorText}`);
+    }
+
+    const data = await response.json();
+
+    happy_path_error__with_fallback('[mcp-server] ← Worker API success (path)', { endpoint, id });
+
+    // Wrap raw data in MCP format
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(data, null, 2)
+      }]
+    };
+  } catch (error: any) {
+    happy_path_error__with_fallback('[mcp-server] ← Worker API error (path)', { endpoint, id, error: error.message });
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Error calling Worker API: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+}
+
+/**
+ * Call Worker HTTP API with POST body
+ */
+async function callWorkerAPIPost(
+  endpoint: string,
+  body: Record<string, any>
+): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
+  happy_path_error__with_fallback('[mcp-server] → Worker API (POST)', { endpoint, body });
+
+  try {
+    const url = `${WORKER_BASE_URL}${endpoint}`;
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Worker API error (${response.status}): ${errorText}`);
+    }
+
+    const data = await response.json();
+
+    happy_path_error__with_fallback('[mcp-server] ← Worker API success (POST)', { endpoint });
+
+    // Wrap raw data in MCP format
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(data, null, 2)
+      }]
+    };
+  } catch (error: any) {
+    happy_path_error__with_fallback('[mcp-server] ← Worker API error (POST)', { endpoint, error: error.message });
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Error calling Worker API: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+}
+
 /**
  * Verify Worker is accessible
  */
@@ -107,7 +196,7 @@ async function verifyWorkerConnection(): Promise<boolean> {
 const tools = [
   {
     name: 'search',
-    description: 'Unified search across all memory types (observations, sessions, and user prompts) using vector-first semantic search (ChromaDB). Returns combined results from all document types. IMPORTANT: Always use index format first (default) to get an overview with minimal token usage, then use format: "full" only for specific items of interest.',
+    description: 'Search observations, sessions, and prompts',
     inputSchema: z.object({
       query: z.string().optional().describe('Natural language search query for semantic ranking via ChromaDB vector search. Optional - omit for date-filtered queries only (Chroma cannot filter by date, requires direct SQLite).'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED for initial search), "full" for complete details (use only after reviewing index results)'),
@@ -129,14 +218,14 @@ const tools = [
   },
   {
     name: 'timeline',
-    description: 'Fetch timeline of observations around a specific point in time. Supports two modes: anchor-based (fetch observations before/after a specific observation ID) and query-based (semantic search for anchor point). IMPORTANT: Use anchor_id when you know the specific observation, or query to find an anchor point first.',
+    description: 'Get timeline around observation ID or query',
     inputSchema: z.object({
-      query: z.string().optional().describe('Natural language query to find anchor observation (query-based mode). Mutually exclusive with anchor_id.'),
-      anchor_id: z.number().optional().describe('Observation ID to use as anchor (anchor-based mode). Mutually exclusive with query.'),
-      before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
-      after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
+      query: z.string().optional().describe('Natural language query to find anchor observation (query-based mode). Mutually exclusive with anchor.'),
+      anchor: z.number().optional().describe('Observation ID to use as anchor (anchor-based mode). Mutually exclusive with query.'),
+      depth_before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
+      depth_after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
-      obs_type: z.string().optional().describe('Filter observations by type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      type: z.string().optional().describe('Filter observations by type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
       concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
       files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match)'),
       project: z.string().optional().describe('Filter by project name')
@@ -148,7 +237,7 @@ const tools = [
   },
   {
     name: 'decisions',
-    description: 'Semantic shortcut for finding architectural, design, and implementation decisions. Optimized for decision-type observations with relevant keyword boosting.',
+    description: 'Find architectural and design decisions',
     inputSchema: z.object({
       query: z.string().describe('Natural language query for finding decisions'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -163,7 +252,7 @@ const tools = [
   },
   {
     name: 'changes',
-    description: 'Semantic shortcut for finding code changes, refactorings, and modifications. Optimized for change-type observations with relevant keyword boosting.',
+    description: 'Find code changes and refactorings',
     inputSchema: z.object({
       query: z.string().describe('Natural language query for finding changes'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -178,7 +267,7 @@ const tools = [
   },
   {
     name: 'how_it_works',
-    description: 'Semantic shortcut for understanding system architecture, design patterns, and implementation details. Optimized for discovery-type observations with architecture/design keyword boosting.',
+    description: 'Understand system architecture',
     inputSchema: z.object({
       query: z.string().describe('Natural language query for understanding how something works'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -193,7 +282,7 @@ const tools = [
   },
   {
     name: 'search_observations',
-    description: '[DEPRECATED - Use "search" with type="observations" instead] Search observations (facts/narratives) using FTS5 full-text search. Supports filtering by type, concepts, files, and date range.',
+    description: '[DEPRECATED] Search observations only',
     inputSchema: z.object({
       query: z.string().optional().describe('Full-text search query (FTS5)'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -214,7 +303,7 @@ const tools = [
   },
   {
     name: 'search_sessions',
-    description: '[DEPRECATED - Use "search" with type="sessions" instead] Search session summaries using FTS5 full-text search. Returns both request_summary and learned_summary fields.',
+    description: '[DEPRECATED] Search sessions only',
     inputSchema: z.object({
       query: z.string().optional().describe('Full-text search query (FTS5)'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -232,7 +321,7 @@ const tools = [
   },
   {
     name: 'search_user_prompts',
-    description: '[DEPRECATED - Use "search" with type="prompts" instead] Search user prompts using FTS5 full-text search. Searches prompt text only.',
+    description: '[DEPRECATED] Search prompts only',
     inputSchema: z.object({
       query: z.string().optional().describe('Full-text search query (FTS5)'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -250,7 +339,7 @@ const tools = [
   },
   {
     name: 'find_by_concept',
-    description: 'Find observations tagged with specific concepts. Returns observations that match any of the provided concept tags.',
+    description: 'Find observations by concept tags',
     inputSchema: z.object({
       concepts: z.string().describe('Concept tag(s) to filter by (single value or comma-separated list)'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -270,7 +359,7 @@ const tools = [
   },
   {
     name: 'find_by_file',
-    description: 'Find observations related to specific file paths. Uses partial matching - searches for file paths containing the provided string.',
+    description: 'Find observations by file paths',
     inputSchema: z.object({
       files: z.string().describe('File path(s) to filter by (single value or comma-separated list for partial match)'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -290,7 +379,7 @@ const tools = [
   },
   {
     name: 'find_by_type',
-    description: 'Find observations of specific types. Returns observations matching any of the provided observation types.',
+    description: 'Find observations by type',
     inputSchema: z.object({
       type: z.string().describe('Observation type(s) to filter by (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -310,7 +399,7 @@ const tools = [
   },
   {
     name: 'get_recent_context',
-    description: 'Get recent session context for timeline display. Returns recent observations, sessions, and user prompts with metadata for building timeline UI.',
+    description: 'Get recent timeline items',
     inputSchema: z.object({
       limit: z.number().min(1).max(100).default(30).describe('Maximum number of timeline items to return'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
@@ -328,11 +417,11 @@ const tools = [
   },
   {
     name: 'get_context_timeline',
-    description: 'Get timeline of observations around a specific observation ID. Returns observations before and after the anchor point with metadata for timeline display.',
+    description: 'Get timeline around specific observation',
     inputSchema: z.object({
-      anchor_id: z.number().describe('Observation ID to use as anchor point'),
-      before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
-      after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
+      anchor: z.number().describe('Observation ID to use as anchor point'),
+      depth_before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
+      depth_after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
       type: z.string().optional().describe('Filter by observation type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
       concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
@@ -346,11 +435,11 @@ const tools = [
   },
   {
     name: 'get_timeline_by_query',
-    description: 'Combined search + timeline tool. First searches for observations matching the query, then returns timeline around the best match. Useful for finding specific observations and viewing their context.',
+    description: 'Search and get timeline in one call',
     inputSchema: z.object({
       query: z.string().describe('Natural language query to find anchor observation'),
-      before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
-      after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
+      depth_before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
+      depth_after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
       format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
       type: z.string().optional().describe('Filter by observation type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
       concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
@@ -363,6 +452,62 @@ const tools = [
       const endpoint = TOOL_ENDPOINT_MAP['get_timeline_by_query'];
       return await callWorkerAPI(endpoint, args);
     }
+  },
+  {
+    name: 'progressive_ix',
+    description: 'Load detailed instructions for mem-search tools',
+    inputSchema: z.object({
+      topic: z.enum(['workflow', 'search_params', 'examples', 'all'])
+        .default('all')
+        .describe('Which instruction section to load: workflow (4-step process), search_params (parameters reference), examples (usage examples), all (complete guide)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['progressive_ix'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'get_observation',
+    description: 'Get full details for a single observation by ID',
+    inputSchema: z.object({
+      id: z.number().describe('Observation ID from search/timeline results')
+    }),
+    handler: async (args: any) => {
+      return await callWorkerAPIWithPath('/api/observation', args.id);
+    }
+  },
+  {
+    name: 'get_batch_observations',
+    description: 'Get full details for multiple observations by IDs in one request',
+    inputSchema: z.object({
+      ids: z.array(z.number()).describe('Array of observation IDs to fetch'),
+      orderBy: z.enum(['date_desc', 'date_asc']).optional().describe('Sort order for results'),
+      limit: z.number().optional().describe('Maximum number of results to return'),
+      project: z.string().optional().describe('Filter by project name')
+    }),
+    handler: async (args: any) => {
+      return await callWorkerAPIPost('/api/observations/batch', args);
+    }
+  },
+  {
+    name: 'get_session',
+    description: 'Get full session summary by ID',
+    inputSchema: z.object({
+      id: z.number().describe('Session ID (just the number from S1234)')
+    }),
+    handler: async (args: any) => {
+      return await callWorkerAPIWithPath('/api/session', args.id);
+    }
+  },
+  {
+    name: 'get_prompt',
+    description: 'Get user prompt by ID',
+    inputSchema: z.object({
+      id: z.number().describe('Prompt ID from search results')
+    }),
+    handler: async (args: any) => {
+      return await callWorkerAPIWithPath('/api/prompt', args.id);
+    }
   }
 ];
 

src/services/sqlite/SessionStore.ts

@@ -1614,8 +1614,9 @@ export class SessionStore {
         prompts: prompts.map(p => ({
           id: p.id,
           claude_session_id: p.claude_session_id,
+          prompt_number: p.prompt_number,
+          prompt_text: p.prompt_text,
           project: p.project,
-          prompt: p.prompt_text,
           created_at: p.created_at,
           created_at_epoch: p.created_at_epoch
         }))
@@ -1626,6 +1627,112 @@ export class SessionStore {
     }
   }
 
+  /**
+   * Get a single user prompt by ID
+   */
+  getPromptById(id: number): {
+    id: number;
+    claude_session_id: string;
+    prompt_number: number;
+    prompt_text: string;
+    project: string;
+    created_at: string;
+    created_at_epoch: number;
+  } | null {
+    const stmt = this.db.prepare(`
+      SELECT
+        p.id,
+        p.claude_session_id,
+        p.prompt_number,
+        p.prompt_text,
+        s.project,
+        p.created_at,
+        p.created_at_epoch
+      FROM user_prompts p
+      LEFT JOIN sdk_sessions s ON p.claude_session_id = s.claude_session_id
+      WHERE p.id = ?
+      LIMIT 1
+    `);
+
+    return stmt.get(id) || null;
+  }
+
+  /**
+   * Get multiple user prompts by IDs
+   */
+  getPromptsByIds(ids: number[]): Array<{
+    id: number;
+    claude_session_id: string;
+    prompt_number: number;
+    prompt_text: string;
+    project: string;
+    created_at: string;
+    created_at_epoch: number;
+  }> {
+    if (ids.length === 0) return [];
+
+    const placeholders = ids.map(() => '?').join(',');
+    const stmt = this.db.prepare(`
+      SELECT
+        p.id,
+        p.claude_session_id,
+        p.prompt_number,
+        p.prompt_text,
+        s.project,
+        p.created_at,
+        p.created_at_epoch
+      FROM user_prompts p
+      LEFT JOIN sdk_sessions s ON p.claude_session_id = s.claude_session_id
+      WHERE p.id IN (${placeholders})
+      ORDER BY p.created_at_epoch DESC
+    `);
+
+    return stmt.all(...ids) as Array<{
+      id: number;
+      claude_session_id: string;
+      prompt_number: number;
+      prompt_text: string;
+      project: string;
+      created_at: string;
+      created_at_epoch: number;
+    }>;
+  }
+
+  /**
+   * Get full session summary by ID (includes request_summary and learned_summary)
+   */
+  getSessionSummaryById(id: number): {
+    id: number;
+    sdk_session_id: string | null;
+    claude_session_id: string;
+    project: string;
+    user_prompt: string;
+    request_summary: string | null;
+    learned_summary: string | null;
+    status: string;
+    created_at: string;
+    created_at_epoch: number;
+  } | null {
+    const stmt = this.db.prepare(`
+      SELECT
+        id,
+        sdk_session_id,
+        claude_session_id,
+        project,
+        user_prompt,
+        request_summary,
+        learned_summary,
+        status,
+        created_at,
+        created_at_epoch
+      FROM sdk_sessions
+      WHERE id = ?
+      LIMIT 1
+    `);
+
+    return stmt.get(id) || null;
+  }
+
   /**
    * Close the database connection
    */

src/services/worker-service.ts

@@ -9,6 +9,7 @@
 import express from 'express';
 import http from 'http';
 import path from 'path';
+import * as fs from 'fs';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { getWorkerPort, getWorkerHost } from '../shared/worker-utils.js';
@@ -142,6 +143,39 @@ export class WorkerService {
       }
     });
 
+    // Instructions endpoint - loads SKILL.md sections on-demand for progressive instruction loading
+    this.app.get('/api/instructions', async (req, res) => {
+      const topic = (req.query.topic as string) || 'all';
+
+      try {
+        // Read SKILL.md from plugin directory
+        // Path resolution: __dirname is build output directory (plugin/scripts/)
+        // SKILL.md is at plugin/skills/mem-search/SKILL.md
+        const skillPath = path.join(__dirname, '../skills/mem-search/SKILL.md');
+        const fullContent = await fs.promises.readFile(skillPath, 'utf-8');
+
+        // Extract section based on topic
+        const section = this.extractInstructionSection(fullContent, topic);
+
+        // Return in MCP format
+        res.json({
+          content: [{
+            type: 'text',
+            text: section
+          }]
+        });
+      } catch (error) {
+        logger.error('WORKER', 'Failed to load instructions', { topic, skillPath }, error as Error);
+        res.status(500).json({
+          content: [{
+            type: 'text',
+            text: `Error loading instructions: ${error instanceof Error ? error.message : 'Unknown error'}`
+          }],
+          isError: true
+        });
+      }
+    });
+
     // Admin endpoints for process management
     this.app.post('/api/admin/restart', async (_req, res) => {
       res.json({ status: 'restarting' });
@@ -334,6 +368,35 @@ export class WorkerService {
     }
   }
 
+  /**
+   * Extract a specific section from instruction content
+   * Used by /api/instructions endpoint for progressive instruction loading
+   */
+  private extractInstructionSection(content: string, topic: string): string {
+    const sections: Record<string, string> = {
+      'workflow': this.extractBetween(content, '## The Workflow', '## Search Parameters'),
+      'search_params': this.extractBetween(content, '## Search Parameters', '## Examples'),
+      'examples': this.extractBetween(content, '## Examples', '## Why This Workflow'),
+      'all': content
+    };
+
+    return sections[topic] || sections['all'];
+  }
+
+  /**
+   * Extract text between two markers
+   * Helper for extractInstructionSection
+   */
+  private extractBetween(content: string, startMarker: string, endMarker: string): string {
+    const startIdx = content.indexOf(startMarker);
+    const endIdx = content.indexOf(endMarker);
+
+    if (startIdx === -1) return content;
+    if (endIdx === -1) return content.substring(startIdx);
+
+    return content.substring(startIdx, endIdx).trim();
+  }
+
   /**
    * Shutdown the worker service
    */