feat: Add batch fetching for observations and update documentation

- Implemented a new endpoint for fetching multiple observations by IDs in a single request.
- Updated the DataRoutes to include a POST /api/observations/batch endpoint.
- Enhanced SKILL.md documentation to reflect changes in the search process and batch fetching capabilities.
- Increased the default limit for search results from 5 to 40 for better usability.

plugin/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "claude-mem-plugin",
+  "version": "7.2.1",
+  "private": true,
+  "description": "Runtime dependencies for claude-mem bundled hooks",
+  "type": "module",
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  }
+}

plugin/skills/mem-search/SKILL.md

@@ -19,20 +19,20 @@ 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. **Timeline** (optional) - Get context around top results to understand what was happening
+2. **Timeline** - 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
 
 ```bash
-curl "http://localhost:37777/api/search?query=authentication&format=index&limit=5"
+curl "http://localhost:37777/api/search?query=authentication&format=index&limit=40"
 ```
 
 **Required parameters:**
 - `query` - Search term
 - `format=index` - ALWAYS start with index (lightweight)
-- `limit=5` - Start small (3-5 results)
+- `limit=40` - You can request large indexes as necessary
 
 **Returns:**
 ```
@@ -45,9 +45,9 @@ curl "http://localhost:37777/api/search?query=authentication&format=index&limit=
    ID: 10942
 ```
 
-### Step 2: Get Timeline Context (Optional)
+### Step 2: Get Timeline Context
 
-When you need to understand "what was happening" around a result:
+You MUST understand "what was happening" around a result:
 
 ```bash
 # Get timeline around an observation ID
@@ -73,9 +73,14 @@ Review the index results (and timeline if used). Identify which IDs are actually
 For each relevant ID, fetch full details:
 
 ```bash
-# Fetch observation
+# Fetch single observation
 curl "http://localhost:37777/api/observation/11131"
 
+# 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"
 
@@ -83,11 +88,24 @@ curl "http://localhost:37777/api/session/2005"
 curl "http://localhost:37777/api/prompt/5421"
 ```
 
+**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}'
+```
+
 **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
+- More efficient: one request vs multiple
+- Returns all observations in a single response
+
 ## Search Parameters
 
 **Basic:**

src/services/worker/http/routes/DataRoutes.ts

@@ -38,6 +38,7 @@ export class DataRoutes extends BaseRouteHandler {
 
     // Fetch by ID endpoints
     app.get('/api/observation/:id', this.handleGetObservationById.bind(this));
+    app.post('/api/observations/batch', this.handleGetObservationsByIds.bind(this));
     app.get('/api/session/:id', this.handleGetSessionById.bind(this));
     app.get('/api/prompt/:id', this.handleGetPromptById.bind(this));
 
@@ -96,6 +97,36 @@ export class DataRoutes extends BaseRouteHandler {
     res.json(observation);
   });
 
+  /**
+   * Get observations by array of IDs
+   * POST /api/observations/batch
+   * Body: { ids: number[], orderBy?: 'date_desc' | 'date_asc', limit?: number, project?: string }
+   */
+  private handleGetObservationsByIds = this.wrapHandler((req: Request, res: Response): void => {
+    const { ids, orderBy, limit, project } = req.body;
+
+    if (!ids || !Array.isArray(ids)) {
+      this.badRequest(res, 'ids must be an array of numbers');
+      return;
+    }
+
+    if (ids.length === 0) {
+      res.json([]);
+      return;
+    }
+
+    // Validate all IDs are numbers
+    if (!ids.every(id => typeof id === 'number' && Number.isInteger(id))) {
+      this.badRequest(res, 'All ids must be integers');
+      return;
+    }
+
+    const store = this.dbManager.getSessionStore();
+    const observations = store.getObservationsByIds(ids, { orderBy, limit, project });
+
+    res.json(observations);
+  });
+
   /**
    * Get session by ID
    * GET /api/session/:id