diff --git a/plugin/scripts/mcp-server.cjs b/plugin/scripts/mcp-server.cjs index d25d23ee..8c7adde8 100755 --- a/plugin/scripts/mcp-server.cjs +++ b/plugin/scripts/mcp-server.cjs @@ -29,7 +29,7 @@ NEVER fetch full details without filtering first. 10x token savings.`,inputSchem \`get_observations(ids=[...])\` # ALWAYS batch for 2+ items Returns: Complete details (~500-1000 tokens/result) -**Why:** 10x token savings. Never fetch full details without filtering first.`}]})},{name:"search",description:"Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd",inputSchema:{type:"object",properties:{},additionalProperties:!0},handler:async a=>{let e=di.search;return await fi(e,a)}},{name:"timeline",description:"Step 2: Get context around results. Params: anchor (observation ID), depth_before, depth_after, project",inputSchema:{type:"object",properties:{},additionalProperties:!0},handler:async a=>{let e=di.timeline;return await fi(e,a)}},{name:"get_observations",description:"Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs), project",inputSchema:{type:"object",properties:{ids:{type:"array",items:{type:"number"},description:"Array of observation IDs to fetch (required)"}},required:["ids"],additionalProperties:!0},handler:async a=>await Od("/api/observations/batch",a)}],cs=new oa({name:"mcp-search-server",version:"1.0.0"},{capabilities:{tools:{}}});cs.setRequestHandler(Ca,async()=>({tools:hi.map(a=>({name:a.name,description:a.description,inputSchema:a.inputSchema}))}));cs.setRequestHandler($a,async a=>{let e=hi.find(t=>t.name===a.params.name);if(!e)throw new Error(`Unknown tool: ${a.params.name}`);try{return await e.handler(a.params.arguments||{})}catch(t){return{content:[{type:"text",text:`Tool execution failed: ${t.message}`}],isError:!0}}});async function pi(){_e.info("SYSTEM","MCP server shutting down"),process.exit(0)}process.on("SIGTERM",pi);process.on("SIGINT",pi);async function Ad(){let a=new la;await cs.connect(a),_e.info("SYSTEM","Claude-mem search server started"),setTimeout(async()=>{await Id()?_e.info("SYSTEM","Worker available",void 0,{workerUrl:Pt}):(_e.warn("SYSTEM","Worker not available",void 0,{workerUrl:Pt}),_e.warn("SYSTEM","Tools will fail until Worker is started"),_e.warn("SYSTEM","Start Worker with: npm run worker:restart"))},0)}Ad().catch(a=>{_e.error("SYSTEM","Fatal error",void 0,a),process.exit(1)}); +**Why:** 10x token savings. Never fetch full details without filtering first.`}]})},{name:"search",description:"Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd, offset, orderBy",inputSchema:{type:"object",properties:{},additionalProperties:!0},handler:async a=>{let e=di.search;return await fi(e,a)}},{name:"timeline",description:"Step 2: Get context around results. Params: anchor (observation ID) OR query (finds anchor automatically), depth_before, depth_after, project",inputSchema:{type:"object",properties:{},additionalProperties:!0},handler:async a=>{let e=di.timeline;return await fi(e,a)}},{name:"get_observations",description:"Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs, required), orderBy, limit, project",inputSchema:{type:"object",properties:{ids:{type:"array",items:{type:"number"},description:"Array of observation IDs to fetch (required)"}},required:["ids"],additionalProperties:!0},handler:async a=>await Od("/api/observations/batch",a)}],cs=new oa({name:"mcp-search-server",version:"1.0.0"},{capabilities:{tools:{}}});cs.setRequestHandler(Ca,async()=>({tools:hi.map(a=>({name:a.name,description:a.description,inputSchema:a.inputSchema}))}));cs.setRequestHandler($a,async a=>{let e=hi.find(t=>t.name===a.params.name);if(!e)throw new Error(`Unknown tool: ${a.params.name}`);try{return await e.handler(a.params.arguments||{})}catch(t){return{content:[{type:"text",text:`Tool execution failed: ${t.message}`}],isError:!0}}});async function pi(){_e.info("SYSTEM","MCP server shutting down"),process.exit(0)}process.on("SIGTERM",pi);process.on("SIGINT",pi);async function Ad(){let a=new la;await cs.connect(a),_e.info("SYSTEM","Claude-mem search server started"),setTimeout(async()=>{await Id()?_e.info("SYSTEM","Worker available",void 0,{workerUrl:Pt}):(_e.warn("SYSTEM","Worker not available",void 0,{workerUrl:Pt}),_e.warn("SYSTEM","Tools will fail until Worker is started"),_e.warn("SYSTEM","Start Worker with: npm run worker:restart"))},0)}Ad().catch(a=>{_e.error("SYSTEM","Fatal error",void 0,a),process.exit(1)}); /*! Bundled license information: uri-js/dist/es5/uri.all.js: diff --git a/plugin/skills/mem-search.zip b/plugin/skills/mem-search.zip deleted file mode 100644 index 455c2d47..00000000 Binary files a/plugin/skills/mem-search.zip and /dev/null differ diff --git a/plugin/skills/mem-search/SKILL.md b/plugin/skills/mem-search/SKILL.md deleted file mode 100644 index 61aa0fa6..00000000 --- a/plugin/skills/mem-search/SKILL.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -name: mem-search -description: Search claude-mem's persistent cross-session memory database. Use when user asks "did we already solve this?", "how did we do X last time?", or needs work from previous sessions. ---- - - -## Quick Reference - -**The 3-Layer Pattern (ALWAYS follow this):** - -1. **Search** - Get index of results with IDs - ``` - search(query="...", limit=20, project="...") - ``` - Returns: Table with IDs, titles, dates (~50-100 tokens/result) - -2. **Timeline** - Get context around interesting results - ``` - timeline(anchor=, depth_before=3, depth_after=3, project="...") - ``` - Returns: Chronological context showing what was happening - -3. **Fetch** - Get full details ONLY for relevant IDs - ``` - get_observations(ids=[...]) # ALWAYS batch for 2+ items - ``` - Returns: Complete details (~500-1000 tokens/result) - -**Why:** 10x token savings. Never fetch full details without filtering first. - ---- - -# Memory Search - -Search past work across all sessions. Simple workflow: search ā†’ get IDs ā†’ fetch details by ID. - -## 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?" - -## The Workflow - -**ALWAYS follow this exact flow:** - -1. **Search** - Get an index of results with IDs -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 - -Use the `search` MCP tool: - -**Required parameters:** - -- `query` - Search term -- `limit: 20` - You can request large indexes as necessary -- `project` - Project name (required) - -**Example:** - -``` -search(query="authentication", limit=20, project="my-project") -``` - -**Returns:** - -``` -| ID | Time | T | Title | Read | Work | -|----|------|---|-------|------|------| -| #11131 | 3:48 PM | šŸŸ£ | Added JWT authentication | ~75 | šŸ› ļø 450 | -| #10942 | 2:15 PM | šŸ”“ | Fixed auth token expiration | ~50 | šŸ› ļø 200 | -``` - -### Step 2: Get Timeline Context - -You MUST understand "what was happening" around a result. - -Use the `timeline` MCP tool: - -**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 - -### 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 using MCP tools: - -**Fetch multiple observations (ALWAYS use for 2+ IDs):** - -``` -get_observations(ids=[11131, 10942, 10855]) -``` - -**With ordering and limit:** - -``` -get_observations( - ids=[11131, 10942, 10855], - orderBy="date_desc", - limit=10, - project="my-project" -) -``` - -**Fetch single observation (only when fetching exactly 1):** - -``` -get_observation(id=11131) -``` - -**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) - -**Batch optimization:** - -- **ALWAYS use `get_observations` for 2+ observations** -- 10-100x more efficient than individual fetches -- Single HTTP request vs N requests -- Returns all results in one response -- Supports ordering and filtering - -## Search Parameters - -**Basic:** - -- `query` - What to search for (required) -- `limit` - How many results (default 20) -- `project` - Filter by project name (required) - -**Filters (optional):** - -- `type` - Filter to "observations", "sessions", or "prompts" -- `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 - -## Examples - -**Find recent bug fixes:** - -Use the `search` MCP tool with filters: - -``` -search(query="bug", type="observations", obs_type="bugfix", limit=20, project="my-project") -``` - -**Find what happened last week:** - -Use date filters: - -``` -search(type="observations", dateStart="2025-11-11", limit=20, project="my-project") -``` - -**Search everything:** - -Simple query search: - -``` -search(query="database migration", limit=20, project="my-project") -``` - -**Get detailed instructions:** - -Use the `help` tool to load full instructions on-demand: - -``` -help(topic="workflow") # Get 4-step workflow -help(topic="search_params") # Get parameters reference -help(topic="examples") # Get usage examples -help(topic="all") # Get complete guide -``` - -## Why This Workflow? - -**Token efficiency:** - -- **Search results:** ~50-100 tokens per result (table index) -- **Full observation:** ~500-1000 tokens each -- **10x savings** - only fetch full when you know it's relevant - -**Batch fetching:** - -- **Individual fetches:** 10 HTTP requests, ~5-10s latency -- **Batch fetch:** 1 HTTP request, ~0.5-1s latency -- **10-100x faster** for multi-observation queries - -**Clarity:** - -- See everything first (table index) -- Get timeline context around interesting results -- Pick what matters based on context -- Fetch details only for what you need (batch when possible) - ---- - -**Remember:** - -- ALWAYS get timeline context to understand what was happening -- ALWAYS use `get_observations` when fetching 2+ observations -- The workflow is optimized: search ā†’ timeline ā†’ batch fetch = 10-100x faster - ---- - -## Tool Reference - -Comprehensive parameter documentation for all memory tools. For MCP usage, call `help(topic="search")` to load specific tool docs. - -### search - -Search across all memory types (observations, sessions, prompts). - -**Parameters:** - -- `query` (string, optional) - Search term for full-text search -- `limit` (number, optional) - Maximum results to return. Default: 20, Max: 100 -- `offset` (number, optional) - Number of results to skip. Default: 0 -- `project` (string, required) - Project name to filter by -- `type` (string, optional) - Filter by type: "observations", "sessions", "prompts" -- `dateStart` (string, optional) - Start date filter (YYYY-MM-DD or epoch ms) -- `dateEnd` (string, optional) - End date filter (YYYY-MM-DD or epoch ms) -- `obs_type` (string, optional) - Filter observations by type (comma-separated): bugfix, feature, decision, discovery, change -- `orderBy` (string, optional) - Sort order: "date_desc" (default), "date_asc", "relevance" - -**Returns:** Table of results with IDs, timestamps, types, titles - -### timeline - -Get chronological context around a specific point in time or observation. - -**Parameters:** - -- `anchor` (number, optional) - Observation ID to center timeline around. If not provided, uses most recent result from query -- `query` (string, optional) - Search term to find anchor automatically (if anchor not provided) -- `depth_before` (number, optional) - Items before anchor. Default: 5, Max: 20 -- `depth_after` (number, optional) - Items after anchor. Default: 5, Max: 20 -- `project` (string, required) - Project name to filter by - -**Returns:** Exactly `depth_before + 1 + depth_after` items in chronological order, with observations, sessions, and prompts interleaved - -### get_recent_context - -Get the most recent observations from current or recent sessions. - -**Parameters:** - -- `limit` (number, optional) - Maximum observations to return. Default: 10, Max: 50 -- `project` (string, required) - Project name to filter by - -**Returns:** Recent observations in reverse chronological order - -### get_context_timeline - -Get timeline context around a specific observation ID. - -**Parameters:** - -- `anchor` (number, required) - Observation ID to center timeline around -- `depth_before` (number, optional) - Items before anchor. Default: 5, Max: 20 -- `depth_after` (number, optional) - Items after anchor. Default: 5, Max: 20 -- `project` (string, optional) - Project name to filter by - -**Returns:** Timeline items centered on the anchor observation - -### get_observation - -Fetch a single observation by ID with full details. - -**Parameters:** - -- `id` (number, required) - Observation ID to fetch - -**Returns:** Complete observation object with title, subtitle, narrative, facts, concepts, files, timestamps - -### get_observations - -Batch fetch multiple observations by IDs. Always prefer this over individual fetches for 2+ observations. - -**Parameters:** - -- `ids` (array of numbers, required) - Array of observation IDs to fetch -- `orderBy` (string, optional) - Sort order: "date_desc" (default), "date_asc" -- `limit` (number, optional) - Maximum observations to return. Default: no limit -- `project` (string, optional) - Project name to filter by - -**Returns:** Array of complete observation objects, 10-100x faster than individual fetches - -### get_session - -Fetch a single session by ID with metadata. - -**Parameters:** - -- `id` (number, required) - Session ID to fetch (just the number, not "S2005" format) - -**Returns:** Session object with ID, start time, end time, project, model info - -### get_prompt - -Fetch a single prompt by ID with full text. - -**Parameters:** - -- `id` (number, required) - Prompt ID to fetch - -**Returns:** Prompt object with ID, text, timestamp, session reference - -### help - -Load detailed instructions for specific topics or all documentation. - -**Parameters:** - -- `topic` (string, optional) - Specific topic to load: "workflow", "search", "timeline", "get_recent_context", "get_context_timeline", "get_observation", "get_observations", "get_session", "get_prompt", "all". Default: "all" - -**Returns:** Formatted documentation for the requested topic diff --git a/plugin/skills/mem-search/operations/.gitkeep b/plugin/skills/mem-search/operations/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/plugin/skills/mem-search/operations/by-concept.md b/plugin/skills/mem-search/operations/by-concept.md deleted file mode 100644 index 14f642f3..00000000 --- a/plugin/skills/mem-search/operations/by-concept.md +++ /dev/null @@ -1,124 +0,0 @@ -# Search by Concept - -Find observations tagged with specific concepts. - -## When to Use - -- User asks: "What discoveries did we make?" -- User asks: "What patterns did we identify?" -- User asks: "What gotchas did we encounter?" -- Looking for observations with semantic tags - -## Command - -```bash -curl -s "http://localhost:37777/api/search/by-concept?concept=discovery&format=index&limit=5" -``` - -## Parameters - -- **concept** (required): Concept tag to search for - - `discovery` - New discoveries and insights - - `problem-solution` - Problems and their solutions - - `what-changed` - Change descriptions - - `how-it-works` - Explanations of mechanisms - - `pattern` - Identified patterns - - `gotcha` - Edge cases and gotchas - - `change` - General changes -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of observations by concept -- Finding IDs for deeper investigation -- Listing multiple results -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete details including narrative, facts, files, concepts -- Understanding the full context of specific observations -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "concept": "discovery", - "count": 3, - "format": "index", - "results": [ - { - "id": 1240, - "type": "discovery", - "title": "Worker service uses PM2 for process management", - "subtitle": "Discovered persistent background worker pattern", - "created_at_epoch": 1699564800000, - "project": "claude-mem", - "concepts": ["discovery", "how-it-works"] - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 3 observations tagged with "discovery": - -šŸ”µ **#1240** Worker service uses PM2 for process management - > Discovered persistent background worker pattern - > Nov 9, 2024 ā€¢ claude-mem - > Tags: discovery, how-it-works - -šŸ”µ **#1241** FTS5 full-text search enables instant searches - > SQLite FTS5 virtual tables provide sub-100ms search - > Nov 9, 2024 ā€¢ claude-mem - > Tags: discovery, pattern -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Available Concepts - -| Concept | Description | When to Use | -|---------|-------------|-------------| -| `discovery` | New discoveries and insights | Finding what was learned | -| `problem-solution` | Problems and their solutions | Finding how issues were resolved | -| `what-changed` | Change descriptions | Understanding what changed | -| `how-it-works` | Explanations of mechanisms | Learning how things work | -| `pattern` | Identified patterns | Finding design patterns | -| `gotcha` | Edge cases and gotchas | Learning about pitfalls | -| `change` | General changes | Tracking modifications | - -## Error Handling - -**Missing concept parameter:** -```json -{"error": "Missing required parameter: concept"} -``` -Fix: Add the concept parameter - -**Invalid concept:** -```json -{"error": "Invalid concept: foobar. Valid concepts: discovery, problem-solution, what-changed, how-it-works, pattern, gotcha, change"} -``` -Fix: Use one of the valid concept values - -## Tips - -1. Use format=index first to see overview -2. Start with limit=5-10 to avoid token overload -3. Combine concepts with type filtering for precision -4. Use `discovery` for learning what was found during investigation -5. Use `problem-solution` for finding how past issues were resolved - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) diff --git a/plugin/skills/mem-search/operations/by-file.md b/plugin/skills/mem-search/operations/by-file.md deleted file mode 100644 index d5daa887..00000000 --- a/plugin/skills/mem-search/operations/by-file.md +++ /dev/null @@ -1,127 +0,0 @@ -# Search by File - -Find all work related to a specific file path. - -## When to Use - -- User asks: "What changes to auth/login.ts?" -- User asks: "What work was done on this file?" -- User asks: "Show me the history of src/services/worker.ts" -- Looking for all observations that reference a file - -## Command - -```bash -curl -s "http://localhost:37777/api/search/by-file?filePath=src/services/worker-service.ts&format=index&limit=10" -``` - -## Parameters - -- **filePath** (required): File path to search for (supports partial matching) - - Full path: `src/services/worker-service.ts` - - Partial path: `worker-service.ts` - - Directory: `src/hooks/` -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of work on a file -- Finding IDs for deeper investigation -- Listing multiple changes -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete details including narrative, facts, files, concepts -- Understanding the full context of specific changes -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "filePath": "src/services/worker-service.ts", - "count": 8, - "format": "index", - "results": [ - { - "id": 1245, - "type": "refactor", - "title": "Simplified worker health check logic", - "subtitle": "Removed redundant PM2 status check", - "created_at_epoch": 1699564800000, - "project": "claude-mem", - "files": ["src/services/worker-service.ts", "src/services/worker-utils.ts"] - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 8 observations related to "src/services/worker-service.ts": - -šŸ”„ **#1245** Simplified worker health check logic - > Removed redundant PM2 status check - > Nov 9, 2024 ā€¢ claude-mem - > Files: worker-service.ts, worker-utils.ts - -šŸŸ£ **#1246** Added SSE endpoint for real-time updates - > Implemented Server-Sent Events for viewer UI - > Nov 8, 2024 ā€¢ claude-mem - > Files: worker-service.ts -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Partial Path Matching - -The file path parameter supports partial matching: - -```bash -# These all match "src/services/worker-service.ts" -curl -s "http://localhost:37777/api/search/by-file?filePath=worker-service.ts&format=index" -curl -s "http://localhost:37777/api/search/by-file?filePath=services/worker&format=index" -curl -s "http://localhost:37777/api/search/by-file?filePath=worker-service&format=index" -``` - -## Directory Searches - -Search for all work in a directory: - -```bash -curl -s "http://localhost:37777/api/search/by-file?filePath=src/hooks/&format=index&limit=20" -``` - -## Error Handling - -**Missing filePath parameter:** -```json -{"error": "Missing required parameter: filePath"} -``` -Fix: Add the filePath parameter - -**No results found:** -```json -{"filePath": "nonexistent.ts", "count": 0, "results": []} -``` -Response: "No observations found for 'nonexistent.ts'. Try a partial path or check the spelling." - -## Tips - -1. Use format=index first to see overview of all changes -2. Start with partial paths (e.g., filename only) for broader matches -3. Use full paths when you need specific file matches -4. Combine with dateStart to see recent changes: `?filePath=worker.ts&dateStart=2024-11-01` -5. Use directory searches to see all work in a module - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) diff --git a/plugin/skills/mem-search/operations/by-type.md b/plugin/skills/mem-search/operations/by-type.md deleted file mode 100644 index b659283c..00000000 --- a/plugin/skills/mem-search/operations/by-type.md +++ /dev/null @@ -1,123 +0,0 @@ -# Search by Type - -Find observations by type: bugfix, feature, refactor, decision, discovery, or change. - -## When to Use - -- User asks: "What bugs did we fix?" -- User asks: "What features did we add?" -- User asks: "What decisions did we make?" -- Looking for specific types of work - -## Command - -```bash -curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=5" -``` - -## Parameters - -- **type** (required): One or more types (comma-separated) - - `bugfix` - Bug fixes - - `feature` - New features - - `refactor` - Code refactoring - - `decision` - Architectural/design decisions - - `discovery` - Discoveries and insights - - `change` - General changes -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of work by type -- Finding IDs for deeper investigation -- Listing multiple results -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete details including narrative, facts, files, concepts -- Understanding the full context of specific observations -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "type": "bugfix", - "count": 5, - "format": "index", - "results": [ - { - "id": 1235, - "type": "bugfix", - "title": "Fixed token expiration edge case", - "subtitle": "Handled race condition in refresh flow", - "created_at_epoch": 1699564800000, - "project": "api-server" - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list with type emojis: - -```markdown -Found 5 bugfixes: - -šŸ”“ **#1235** Fixed token expiration edge case - > Handled race condition in refresh flow - > Nov 9, 2024 ā€¢ api-server - -šŸ”“ **#1236** Resolved memory leak in worker - > Fixed event listener cleanup - > Nov 8, 2024 ā€¢ worker-service -``` - -**Type Emojis:** -- šŸ”“ bugfix -- šŸŸ£ feature -- šŸ”„ refactor -- šŸ”µ discovery -- šŸ§  decision -- āœ… change - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Multiple Types - -To search for multiple types: - -```bash -curl -s "http://localhost:37777/api/search/by-type?type=bugfix,feature&format=index&limit=10" -``` - -## Error Handling - -**Missing type parameter:** -```json -{"error": "Missing required parameter: type"} -``` -Fix: Add the type parameter - -**Invalid type:** -```json -{"error": "Invalid type: foobar. Valid types: bugfix, feature, refactor, decision, discovery, change"} -``` -Fix: Use one of the valid type values - -## Tips - -1. Use format=index first to see overview -2. Start with limit=5-10 to avoid token overload -3. Combine with dateStart for recent work: `?type=bugfix&dateStart=2024-11-01` -4. Use project filtering when working on one codebase - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) diff --git a/plugin/skills/mem-search/operations/common-workflows.md b/plugin/skills/mem-search/operations/common-workflows.md deleted file mode 100644 index d6f51419..00000000 --- a/plugin/skills/mem-search/operations/common-workflows.md +++ /dev/null @@ -1,251 +0,0 @@ -# Common Workflows - -Step-by-step guides for typical user requests using the search API. - -## Workflow 1: Understanding Past Work - -**User asks:** "What did we do last session?" or "Catch me up on recent work" - -**Steps:** - -1. **Get recent context** (fastest path): -```bash -curl -s "http://localhost:37777/api/context/recent?limit=3" -``` - -2. **Present as narrative:** -```markdown -## Recent Work - -### Session #545 - Nov 9, 2024 -Implemented JWT authentication system - -**Completed:** -- Added token-based auth with refresh tokens -- Created JWT signing and verification logic - -**Key Learning:** JWT expiration requires careful handling of refresh race conditions -``` - -**Why this workflow:** -- Single request gets both sessions and observations -- Optimized for "catch me up" questions -- ~1,500-2,500 tokens for 3 sessions - ---- - -## Workflow 2: Finding Specific Bug Fixes - -**User asks:** "What bugs did we fix?" or "Show me recent bug fixes" - -**Steps:** - -1. **Search by type** (index format first): -```bash -curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=5" -``` - -2. **Review index results**, identify relevant items - -3. **Get full details** for specific bugs: -```bash -curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=full&limit=1&offset=2" -``` - -4. **Present findings:** -```markdown -Found 5 bug fixes: - -šŸ”“ **#1235** Fixed token expiration edge case - > Handled race condition in refresh flow - > Nov 9, 2024 ā€¢ api-server - -[Click for full details on #1235] -``` - -**Why this workflow:** -- Progressive disclosure: index first, full details selectively -- Type-specific search is more efficient than generic search -- ~250-500 tokens for index, ~750-1000 per full detail - ---- - -## Workflow 3: Understanding File History - -**User asks:** "What changes to auth/login.ts?" or "Show me work on this file" - -**Steps:** - -1. **Search by file** (index format): -```bash -curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&format=index&limit=10" -``` - -2. **Review chronological changes** - -3. **Get full details** for specific changes: -```bash -curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&format=full&limit=1&offset=3" -``` - -4. **Present as file timeline:** -```markdown -## History of auth/login.ts - -šŸŸ£ **#1230** Added JWT authentication (Nov 9) -šŸ”“ **#1235** Fixed token expiration bug (Nov 9) -šŸ”„ **#1240** Refactored auth flow (Nov 8) -``` - -**Why this workflow:** -- File-specific search finds all related work -- Index format shows chronological overview -- Selective full details for deep dives - ---- - -## Workflow 4: Timeline Investigation - -**User asks:** "What was happening when we deployed?" or "Show me context around that bug fix" - -**Steps:** - -1. **Find the event** using search: -```bash -curl -s "http://localhost:37777/api/search/observations?query=deployment&format=index&limit=5" -``` - -2. **Note observation ID** (e.g., #1234) - -3. **Get timeline context**: -```bash -curl -s "http://localhost:37777/api/timeline/context?anchor=1234&depth_before=10&depth_after=10" -``` - -4. **Present as chronological narrative:** -```markdown -## Timeline: Deployment - -### Before (10 records) -**2:45 PM** - šŸŸ£ Prepared deployment scripts -**2:50 PM** - šŸ’¬ User asked: "Are we ready to deploy?" - -### ā­ Anchor Point (2:55 PM) -šŸŽÆ **Observation #1234**: Deployed to production - -### After (10 records) -**3:00 PM** - šŸ”“ Fixed post-deployment routing issue -``` - -**Why this workflow:** -- Timeline shows temporal context (what happened before/after) -- Captures causality between events -- All record types (observations, sessions, prompts) interleaved - ---- - -## Workflow 5: Quick Timeline (One Request) - -**User asks:** "Timeline of authentication work" - -**Steps:** - -1. **Use timeline-by-query** (auto mode): -```bash -curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=auto&depth_before=10&depth_after=10" -``` - -2. **Present timeline directly:** -```markdown -## Timeline: Authentication - -**Best Match:** šŸŸ£ Observation #1234 - Implemented JWT authentication - -### Context (21 records) -[... timeline around best match ...] -``` - -**Why this workflow:** -- Single request combines search + timeline -- Fastest path when query is specific -- Auto mode uses top result as anchor - -**Alternative:** Use interactive mode for broad queries: -```bash -curl -s "http://localhost:37777/api/timeline/by-query?query=auth&mode=interactive&limit=5" -``` -Then choose anchor manually. - ---- - -## Workflow 6: Search Composition - -**User asks:** "What features did we add to the authentication system recently?" - -**Steps:** - -1. **Combine filters** for precision: -```bash -curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&dateStart=2024-11-01&format=index&limit=10" -``` - -2. **Review filtered results** - -3. **Get full details** for relevant features: -```bash -curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&format=full&limit=1&offset=2" -``` - -4. **Present findings:** -```markdown -Found 10 authentication features added in November: - -šŸŸ£ **#1234** Implemented JWT authentication (Nov 9) -šŸŸ£ **#1236** Added refresh token rotation (Nov 9) -šŸŸ£ **#1238** Implemented OAuth2 flow (Nov 7) -``` - -**Why this workflow:** -- Multiple filters narrow results before requesting full details -- Type + query + dateStart/dateEnd = precise targeting -- Progressive disclosure: index first, full details selectively - ---- - -## Workflow Selection Guide - -| User Request | Workflow | Operation | Token Cost | -|--------------|----------|-----------|------------| -| "What did we do last session?" | #1 | recent-context | 1,500-2,500 | -| "What bugs did we fix?" | #2 | by-type | 500-3,000 | -| "What changes to file.ts?" | #3 | by-file | 500-3,000 | -| "What was happening then?" | #4 | search ā†’ timeline | 3,500-6,000 | -| "Timeline of X work" | #5 | timeline-by-query | 3,000-4,000 | -| "Recent features added?" | #6 | observations + filters | 500-3,000 | - -## General Principles - -1. **Start with index format** - Always use `format=index` first -2. **Use specialized tools** - by-type, by-file, by-concept when applicable -3. **Compose operations** - Combine search + timeline for investigations -4. **Filter early** - Use type, dateStart/dateEnd, project to narrow before expanding -5. **Progressive disclosure** - Load full details only for relevant items - -## Token Budget Awareness - -**Quick queries** (500-1,500 tokens): -- Recent context (limit=3) -- Index search (limit=5-10) -- Filtered searches - -**Medium queries** (1,500-4,000 tokens): -- Recent context (limit=5-10) -- Full details (3-5 items) -- Timeline (depth 10/10) - -**Deep queries** (4,000-8,000 tokens): -- Timeline (depth 20/20) -- Full details (10+ items) -- Multiple composed operations - -Always start with minimal token investment, expand only when needed. diff --git a/plugin/skills/mem-search/operations/formatting.md b/plugin/skills/mem-search/operations/formatting.md deleted file mode 100644 index 1b26c502..00000000 --- a/plugin/skills/mem-search/operations/formatting.md +++ /dev/null @@ -1,403 +0,0 @@ -# Response Formatting Guidelines - -How to present search results to users for maximum clarity and usefulness. - -## General Principles - -1. **Progressive disclosure** - Show index results first, full details on demand -2. **Visual hierarchy** - Use emojis, bold, and structure for scannability -3. **Context-aware** - Tailor presentation to user's question -4. **Actionable** - Include IDs for follow-up queries -5. **Token-efficient** - Balance detail with token budget - ---- - -## Format: Index Results - -**When to use:** First response to searches, overviews, multiple results - -**Structure:** -```markdown -Found {count} results for "{query}": - -{emoji} **#{id}** {title} - > {subtitle} - > {date} ā€¢ {project} -``` - -**Example:** -```markdown -Found 5 results for "authentication": - -šŸŸ£ **#1234** Implemented JWT authentication - > Added token-based auth with refresh tokens - > Nov 9, 2024 ā€¢ api-server - -šŸ”“ **#1235** Fixed token expiration edge case - > Handled race condition in refresh flow - > Nov 9, 2024 ā€¢ api-server -``` - -**Type Emojis:** -- šŸ”“ bugfix -- šŸŸ£ feature -- šŸ”„ refactor -- šŸ”µ discovery -- šŸ§  decision -- āœ… change -- šŸŽÆ session -- šŸ’¬ prompt - -**What to include:** -- āœ… ID (for follow-up) -- āœ… Type emoji -- āœ… Title -- āœ… Subtitle (if available) -- āœ… Date (human-readable) -- āœ… Project name -- āŒ Don't include full narrative/facts/files in index format - ---- - -## Format: Full Results - -**When to use:** User requests details, specific items selected from index - -**Structure:** -```markdown -## {emoji} {type} #{id}: {title} - -**Summary:** {subtitle} - -**What happened:** -{narrative} - -**Key Facts:** -- {fact1} -- {fact2} - -**Files modified:** -- {file1} -- {file2} - -**Concepts:** {concepts} - -**Date:** {human_readable_date} -**Project:** {project} -``` - -**Example:** -```markdown -## šŸŸ£ Feature #1234: Implemented JWT authentication - -**Summary:** Added token-based auth with refresh tokens - -**What happened:** -Implemented a complete JWT authentication system with access and refresh tokens. Access tokens expire after 15 minutes, refresh tokens after 7 days. Added token signing with RS256 algorithm and proper key rotation infrastructure. - -**Key Facts:** -- Access tokens use 15-minute expiration -- Refresh tokens stored in httpOnly cookies -- RS256 algorithm with key rotation support -- Token refresh endpoint handles race conditions gracefully - -**Files modified:** -- src/auth/jwt.ts (created) -- src/auth/refresh.ts (created) -- src/middleware/auth.ts (modified) - -**Concepts:** how-it-works, pattern - -**Date:** November 9, 2024 at 2:55 PM -**Project:** api-server -``` - -**What to include:** -- āœ… Full title with emoji and ID -- āœ… Summary/subtitle -- āœ… Complete narrative -- āœ… All key facts -- āœ… All files (with status: created/modified/deleted) -- āœ… Concepts/tags -- āœ… Precise timestamp -- āœ… Project name - ---- - -## Format: Timeline Results - -**When to use:** Temporal investigations, "what was happening" questions - -**Structure:** -```markdown -## Timeline: {anchor_description} - -### Before ({count} records) - -**{time}** - {emoji} {type} #{id}: {title} -**{time}** - {emoji} {type} #{id}: {title} - -### ā­ Anchor Point ({time}) -{emoji} **{type} #{id}**: {title} - -### After ({count} records) - -**{time}** - {emoji} {type} #{id}: {title} -**{time}** - {emoji} {type} #{id}: {title} -``` - -**Example:** -```markdown -## Timeline: Deployment - -### Before (10 records) - -**2:30 PM** - šŸŸ£ #1230: Prepared deployment scripts -**2:45 PM** - šŸ”„ #1232: Updated configuration files -**2:50 PM** - šŸ’¬ User asked: "Are we ready to deploy?" - -### ā­ Anchor Point (2:55 PM) -šŸŽÆ **Session #545**: Deployed to production - -### After (10 records) - -**3:00 PM** - šŸ”“ #1235: Fixed post-deployment routing issue -**3:10 PM** - šŸ”µ #1236: Discovered caching behavior in production -**3:15 PM** - šŸ§  #1237: Decided to add health check endpoint -``` - -**What to include:** -- āœ… Chronological ordering (oldest to newest) -- āœ… Human-readable times (not epochs) -- āœ… Clear anchor point marker (ā­) -- āœ… Mix of all record types (observations, sessions, prompts) -- āœ… Concise titles (not full narratives) -- āœ… Type emojis for quick scanning - ---- - -## Format: Session Summaries - -**When to use:** Recent context, "what did we do" questions - -**Structure:** -```markdown -## Recent Work on {project} - -### šŸŽÆ Session #{id} - {date} - -**Request:** {user_request} - -**Completed:** -- {completion1} -- {completion2} - -**Key Learning:** {learning} - -**Observations:** -- {emoji} **#{obs_id}** {obs_title} - - Files: {file_list} -``` - -**Example:** -```markdown -## Recent Work on api-server - -### šŸŽÆ Session #545 - November 9, 2024 - -**Request:** Add JWT authentication with refresh tokens - -**Completed:** -- Implemented token-based auth with refresh logic -- Added JWT signing and verification -- Created refresh token rotation - -**Key Learning:** JWT expiration requires careful handling of refresh race conditions - -**Observations:** -- šŸŸ£ **#1234** Implemented JWT authentication - - Files: jwt.ts, refresh.ts, middleware/auth.ts -- šŸ”“ **#1235** Fixed token expiration edge case - - Files: refresh.ts -``` - -**What to include:** -- āœ… Session ID and date -- āœ… Original user request -- āœ… What was completed (bulleted list) -- āœ… Key learnings/insights -- āœ… Linked observations with file lists -- āœ… Clear hierarchy (session ā†’ observations) - ---- - -## Format: User Prompts - -**When to use:** "What did I ask" questions, prompt searches - -**Structure:** -```markdown -Found {count} user prompts: - -šŸ’¬ **Prompt #{id}** (Session #{session_id}) - > "{preview_text}" - > {date} ā€¢ {project} -``` - -**Example:** -```markdown -Found 5 user prompts about "authentication": - -šŸ’¬ **Prompt #1250** (Session #545) - > "How do I implement JWT authentication with refresh tokens? I need to handle token expiration..." - > Nov 9, 2024 ā€¢ api-server - -šŸ’¬ **Prompt #1251** (Session #546) - > "The auth tokens are expiring too quickly. Can you help debug the refresh flow?" - > Nov 8, 2024 ā€¢ api-server -``` - -**What to include:** -- āœ… Prompt ID -- āœ… Session ID (for context linking) -- āœ… Preview text (200 chars for index, full text for full format) -- āœ… Date and project -- āœ… Quote formatting for prompt text - ---- - -## Error Responses - -**No results found:** -```markdown -No results found for "{query}". Try: -- Different search terms -- Broader keywords -- Checking spelling -- Using partial paths (for file searches) -``` - -**Service unavailable:** -```markdown -The search service isn't available. Check if the worker is running: - -```bash -npm run worker:status -``` - -If the worker is stopped, restart it: - -```bash -npm run worker:restart -``` -``` - -**Invalid parameters:** -```markdown -Invalid search parameters: -- {parameter}: {error_message} - -See the [API help](help.md) for valid parameter options. -``` - ---- - -## Context-Aware Presentation - -Tailor formatting to user's question: - -**"What bugs did we fix?"** -ā†’ Use index format, emphasize date/type, group by recency - -**"How did we implement X?"** -ā†’ Use full format for best match, include complete narrative and files - -**"What was happening when..."** -ā†’ Use timeline format, emphasize chronology and causality - -**"Catch me up on recent work"** -ā†’ Use session summary format, focus on high-level accomplishments - ---- - -## Token Budget Guidelines - -**Minimal presentation (~100-200 tokens):** -- Index format with 3-5 results -- Compact list structure -- Essential metadata only - -**Standard presentation (~500-1,000 tokens):** -- Index format with 10-15 results -- Include subtitles and context -- Clear formatting and emojis - -**Detailed presentation (~1,500-3,000 tokens):** -- Full format for 2-3 items -- Complete narratives and facts -- Timeline with 20-30 records - -**Comprehensive presentation (~5,000+ tokens):** -- Multiple full results -- Deep timelines (40+ records) -- Session summaries with observations - -Always start minimal, expand only when needed. - ---- - -## Markdown Best Practices - -1. **Use headers (##, ###)** for hierarchy -2. **Bold important elements** (IDs, titles, dates) -3. **Quote user text** (prompts, questions) -4. **Bullet lists** for facts and files -5. **Code blocks** for commands and examples -6. **Emojis** for type indicators -7. **Horizontal rules (---)** for section breaks -8. **Blockquotes (>)** for subtitles and previews - ---- - -## Examples by Use Case - -### Use Case 1: Quick Overview -User: "What did we do last session?" - -```markdown -## Recent Work - -### šŸŽÆ Session #545 - November 9, 2024 -Implemented JWT authentication system - -**Key accomplishment:** Added token-based auth with refresh tokens -**Key learning:** JWT expiration requires careful handling of refresh race conditions -``` - -### Use Case 2: Specific Investigation -User: "How did we implement JWT authentication?" - -```markdown -## šŸŸ£ Feature #1234: Implemented JWT authentication - -**What happened:** -Implemented a complete JWT authentication system with access and refresh tokens. Access tokens expire after 15 minutes, refresh tokens after 7 days. Added token signing with RS256 algorithm. - -**Files:** -- src/auth/jwt.ts (created) -- src/auth/refresh.ts (created) -- src/middleware/auth.ts (modified) - -**Key insight:** Refresh race conditions require atomic token exchange logic. -``` - -### Use Case 3: Timeline Investigation -User: "What was happening around the deployment?" - -```markdown -## Timeline: Deployment - -[... chronological timeline with before/after context ...] -``` - -Choose presentation style based on user's question and information needs. diff --git a/plugin/skills/mem-search/operations/help.md b/plugin/skills/mem-search/operations/help.md deleted file mode 100644 index 7125d0af..00000000 --- a/plugin/skills/mem-search/operations/help.md +++ /dev/null @@ -1,171 +0,0 @@ -# API Help - -Get comprehensive API documentation for all search endpoints. - -## When to Use - -- User asks: "What search operations are available?" -- User asks: "How do I use the search API?" -- Need reference documentation for endpoints -- Want to see all available parameters - -## Command - -```bash -curl -s "http://localhost:37777/api/help" -``` - -## Response Structure - -Returns complete API documentation: - -```json -{ - "version": "6.5.0", - "base_url": "http://localhost:37777/api", - "endpoints": [ - { - "path": "/search/observations", - "method": "GET", - "description": "Search observations using full-text search", - "parameters": [ - { - "name": "query", - "required": true, - "type": "string", - "description": "Search terms" - }, - { - "name": "format", - "required": false, - "type": "string", - "default": "full", - "options": ["index", "full"], - "description": "Response format" - } - ], - "example": "curl -s \"http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5\"" - } - ] -} -``` - -## How to Present Results - -Present as reference documentation: - -```markdown -## claude-mem Search API Reference - -Base URL: `http://localhost:37777/api` - -### Search Operations - -**1. Search Observations** -- **Endpoint:** `GET /search/observations` -- **Description:** Search observations using full-text search -- **Parameters:** - - `query` (required, string): Search terms - - `format` (optional, string): "index" or "full" (default: "full") - - `limit` (optional, number): Max results (default: 20, max: 100) -- **Example:** - ```bash - curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5" - ``` - -[... continue for all endpoints ...] -``` - -## Endpoint Categories - -The API help response organizes endpoints by category: - -1. **Full-Text Search** - - `/search/observations` - - `/search/sessions` - - `/search/prompts` - -2. **Filtered Search** - - `/search/by-type` - - `/search/by-concept` - - `/search/by-file` - -3. **Context Retrieval** - - `/context/recent` - - `/timeline/context` - - `/timeline/by-query` - -4. **Utilities** - - `/help` - -## Common Parameters - -Many endpoints share these parameters: - -- **format**: "index" (summary) or "full" (complete details) -- **limit**: Number of results to return -- **offset**: Number of results to skip (for pagination) -- **project**: Filter by project name -- **dateStart/dateEnd**: Filter by date range - - `dateStart`: Start date (YYYY-MM-DD or epoch timestamp) - - `dateEnd`: End date (YYYY-MM-DD or epoch timestamp) - -## Error Handling - -**Worker not running:** -Connection refused error. Response: "The search API isn't available. Check if worker is running: `npm run worker:status`" - -**Invalid endpoint:** -```json -{"error": "Not found"} -``` -Response: "Invalid API endpoint. Use /api/help to see available endpoints." - -## Tips - -1. Save help response for reference during investigation -2. Use examples as starting point for your queries -3. Check required parameters before making requests -4. Refer to format options for each endpoint -5. All endpoints use GET method with query parameters - -**Token Efficiency:** -- Help response: ~2,000-3,000 tokens (complete API reference) -- Use sparingly - refer to operation-specific docs instead -- Keep help response cached for repeated reference - -## When to Use Help - -**Use help when:** -- Starting to use the search API -- Need complete parameter reference -- Forgot which endpoints are available -- Want to see all options at once - -**Don't use help when:** -- You know which operation you need (use operation-specific docs) -- Just need examples (use common-workflows.md) -- Token budget is limited (help is comprehensive) - -## Alternative to Help Endpoint - -Instead of calling `/api/help`, you can: - -1. **Use SKILL.md** - Quick decision guide with operation links -2. **Use operation docs** - Detailed guides for specific endpoints -3. **Use common-workflows.md** - Step-by-step examples -4. **Use formatting.md** - Response presentation templates - -The help endpoint is most useful when you need complete API reference in one response. - -## API Versioning - -The help response includes version information: - -```json -{ - "version": "6.5.0" -} -``` - -Check version to ensure compatibility with documentation. diff --git a/plugin/skills/mem-search/operations/observations.md b/plugin/skills/mem-search/operations/observations.md deleted file mode 100644 index df5a7e1b..00000000 --- a/plugin/skills/mem-search/operations/observations.md +++ /dev/null @@ -1,124 +0,0 @@ -# Search Observations (Semantic + Full-Text Hybrid) - -Search all observations using natural language queries. - -## When to Use - -- User asks: "How did we implement authentication?" -- User asks: "What bugs did we fix?" -- User asks: "What features did we add?" -- Looking for past work by keyword or topic - -## Command - -```bash -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5" -``` - -## Parameters - -- **query** (optional): Natural language search query - uses semantic search (ChromaDB) for ranking with SQLite FTS5 fallback (e.g., "authentication", "bug fix", "database migration"). Can be omitted for filter-only searches. -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - `dateStart` and/or `dateEnd` (YYYY-MM-DD format or epoch timestamp) -- **obs_type**: Filter by observation type (comma-separated): bugfix, feature, refactor, decision, discovery, change (optional) -- **concepts**: Filter by concept tags (comma-separated, optional) -- **files**: Filter by file paths (comma-separated, optional) - -**Important**: When omitting `query`, you MUST provide at least one filter (project, dateStart/dateEnd, obs_type, concepts, or files) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews -- Finding IDs for deeper investigation -- Listing multiple results -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete details including narrative, facts, files, concepts -- Understanding the full context of specific observations -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "query": "authentication", - "count": 5, - "format": "index", - "results": [ - { - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "subtitle": "Added token-based auth with refresh tokens", - "created_at_epoch": 1699564800000, - "project": "api-server", - "score": 0.95 - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 5 results for "authentication": - -1. **#1234** [feature] Implemented JWT authentication - > Added token-based auth with refresh tokens - > Nov 9, 2024 ā€¢ api-server - -2. **#1235** [bugfix] Fixed token expiration edge case - > Handled race condition in refresh flow - > Nov 9, 2024 ā€¢ api-server -``` - -**Include:** ID (for follow-up), type emoji (šŸ”“ bugfix, šŸŸ£ feature, šŸ”„ refactor, šŸ”µ discovery, šŸ§  decision, āœ… change), title, subtitle, date, project. - -For complete formatting guidelines, see formatting.md (documentation coming soon). - -## Filter-Only Examples - -Search without query text (direct SQLite filtering): - -```bash -# Get all observations from November 2025 -curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-01&format=index" - -# Get all bug fixes from a specific project -curl -s "http://localhost:37777/api/search?type=observations&obs_type=bugfix&project=api-server&format=index" - -# Get all observations from last 7 days -curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-11&format=index" -``` - -## Error Handling - -**Missing query and filters:** -```json -{"error": "Either query or filters required for search"} -``` -Fix: Provide either a query parameter OR at least one filter (project, dateStart/dateEnd, obs_type, concepts, files) - -**No results found:** -```json -{"query": "foobar", "count": 0, "results": []} -``` -Response: "No results found for 'foobar'. Try different search terms." - -## Tips - -1. Be specific: "authentication JWT" > "auth" -2. Start with format=index and limit=5-10 -3. Use project filtering when working on one codebase -4. If no results, try broader terms or check spelling - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) diff --git a/plugin/skills/mem-search/operations/prompts.md b/plugin/skills/mem-search/operations/prompts.md deleted file mode 100644 index 3aa91609..00000000 --- a/plugin/skills/mem-search/operations/prompts.md +++ /dev/null @@ -1,125 +0,0 @@ -# Search User Prompts (Full-Text) - -Search raw user prompts to find what was actually asked across all sessions. - -## When to Use - -- User asks: "What did I ask about authentication?" -- User asks: "Find my question about database migrations" -- User asks: "When did I ask about testing?" -- Looking for specific user questions or requests - -## Command - -```bash -curl -s "http://localhost:37777/api/search/prompts?query=authentication&format=index&limit=5" -``` - -## Parameters - -- **query** (required): Search terms (e.g., "authentication", "how do I", "bug fix") -- **format**: "index" (truncated prompts) or "full" (complete prompt text). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of what was asked -- Finding prompt IDs for full text -- Listing multiple prompts -- **Token cost: ~50-100 per result (truncated to 200 chars)** - -**Use format=full for:** -- Complete prompt text -- Understanding the full user request -- **Token cost: Variable (depends on prompt length, typically 100-300 tokens)** - -## Example Response (format=index) - -```json -{ - "query": "authentication", - "count": 5, - "format": "index", - "results": [ - { - "id": 1250, - "session_id": "S545", - "prompt_preview": "How do I implement JWT authentication with refresh tokens? I need to handle token expiration...", - "created_at_epoch": 1699564800000, - "project": "api-server" - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 5 user prompts about "authentication": - -šŸ’¬ **Prompt #1250** (Session #545) - > "How do I implement JWT authentication with refresh tokens? I need to handle token expiration..." - > Nov 9, 2024 ā€¢ api-server - -šŸ’¬ **Prompt #1251** (Session #546) - > "The auth tokens are expiring too quickly. Can you help debug the refresh flow?" - > Nov 8, 2024 ā€¢ api-server -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## What Gets Searched - -User prompts search covers: -- All user messages sent to Claude Code -- Raw text as typed by the user -- Multi-turn conversations (each message is a separate prompt) -- Questions, requests, commands, and clarifications - -## Error Handling - -**Missing query parameter:** -```json -{"error": "Missing required parameter: query"} -``` -Fix: Add the query parameter - -**No results found:** -```json -{"query": "foobar", "count": 0, "results": []} -``` -Response: "No user prompts found for 'foobar'. Try different search terms." - -## Tips - -1. Use exact phrases in quotes: `?query="how do I"` for precise matches -2. Start with format=index to see preview, then get full text if needed -3. Use dateStart to find recent questions: `?query=bug&dateStart=2024-11-01` -4. Prompts show what was asked, sessions/observations show what was done -5. Combine with session search to see both question and answer - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result, prompt truncated to 200 chars) -- Use format=full only for relevant items (100-300 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## When to Use Prompts vs Sessions - -**Use prompts search when:** -- Looking for specific user questions -- Trying to remember what was asked -- Finding original request wording - -**Use sessions search when:** -- Looking for what was accomplished -- Understanding work summaries -- Getting high-level context - -**Combine both when:** -- Understanding the full conversation (what was asked + what was done) -- Investigating how a request was interpreted diff --git a/plugin/skills/mem-search/operations/recent-context.md b/plugin/skills/mem-search/operations/recent-context.md deleted file mode 100644 index dbf4e4b9..00000000 --- a/plugin/skills/mem-search/operations/recent-context.md +++ /dev/null @@ -1,134 +0,0 @@ -# Get Recent Context - -Get recent session summaries and observations for a project. - -## When to Use - -- User asks: "What did we do last session?" -- User asks: "What have we been working on recently?" -- User asks: "Catch me up on recent work" -- Starting a new session and need context - -## Command - -```bash -curl -s "http://localhost:37777/api/context/recent?project=api-server&limit=3" -``` - -## Parameters - -- **project**: Project name (defaults to current working directory basename) -- **limit**: Number of recent sessions to retrieve (default: 3, max: 10) - -## Response Structure - -Returns combined context from recent sessions: - -```json -{ - "project": "api-server", - "limit": 3, - "sessions": [ - { - "id": 545, - "session_id": "S545", - "title": "Implemented JWT authentication system", - "request": "Add JWT authentication with refresh tokens", - "completion": "Implemented token-based auth with refresh logic", - "learnings": "JWT expiration requires careful handling of refresh race conditions", - "created_at_epoch": 1699564800000, - "observations": [ - { - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "subtitle": "Added token-based auth with refresh tokens", - "files": ["src/auth/jwt.ts", "src/auth/refresh.ts"] - } - ] - } - ] -} -``` - -## How to Present Results - -Present as a chronological narrative: - -```markdown -## Recent Work on api-server - -### Session #545 - Nov 9, 2024 -**Request:** Add JWT authentication with refresh tokens - -**Completed:** -- Implemented token-based auth with refresh logic -- Added JWT signing and verification -- Created refresh token rotation - -**Key Learning:** JWT expiration requires careful handling of refresh race conditions - -**Observations:** -- šŸŸ£ **#1234** Implemented JWT authentication - - Files: jwt.ts, refresh.ts -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Default Project Detection - -If no project parameter is provided, uses current working directory: - -```bash -# Auto-detects project from current directory -curl -s "http://localhost:37777/api/context/recent?limit=3" -``` - -## Error Handling - -**No sessions found:** -```json -{"project": "new-project", "sessions": []} -``` -Response: "No recent sessions found for 'new-project'. This might be a new project." - -**Worker not running:** -Connection refused error. Inform user to check if worker is running: `npm run worker:status` - -## Tips - -1. Start with limit=3 for quick overview (default) -2. Increase to limit=5-10 for deeper context -3. Recent context is perfect for session start -4. Combines both sessions and observations in one request -5. Use this when user asks "what did we do last time?" - -**Token Efficiency:** -- limit=3 sessions: ~1,500-2,500 tokens (includes observations) -- limit=5 sessions: ~2,500-4,000 tokens -- limit=10 sessions: ~5,000-8,000 tokens -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## When to Use Recent Context - -**Use recent-context when:** -- Starting a new session -- User asks about recent work -- Need quick catch-up on project activity -- Want both sessions and observations together - -**Don't use recent-context when:** -- Looking for specific topics (use search instead) -- Need timeline around specific event (use timeline instead) -- Want only observations or only sessions (use search operations) - -## Comparison with Other Operations - -| Operation | Use Case | Token Cost | -|-----------|----------|------------| -| recent-context | Quick catch-up on recent work | 1,500-4,000 | -| sessions search | Find sessions by topic | 50-100 per result (index) | -| observations search | Find specific implementations | 50-100 per result (index) | -| timeline | Context around specific point | 3,000-6,000 | - -Recent context is optimized for "what happened recently?" questions with minimal token usage. diff --git a/plugin/skills/mem-search/operations/sessions.md b/plugin/skills/mem-search/operations/sessions.md deleted file mode 100644 index b69b4765..00000000 --- a/plugin/skills/mem-search/operations/sessions.md +++ /dev/null @@ -1,124 +0,0 @@ -# Search Sessions (Full-Text) - -Search session summaries using natural language queries. - -## When to Use - -- User asks: "What did we work on last week?" -- User asks: "What sessions involved database work?" -- User asks: "Show me sessions where we fixed bugs" -- Looking for past sessions by topic or theme - -## Command - -```bash -curl -s "http://localhost:37777/api/search/sessions?query=authentication&format=index&limit=5" -``` - -## Parameters - -- **query** (required): Search terms (e.g., "authentication", "database migration", "bug fixes") -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of past sessions -- Finding session IDs for deeper investigation -- Listing multiple sessions -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete session summaries with requests, completions, learnings -- Understanding the full context of a session -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "query": "authentication", - "count": 3, - "format": "index", - "results": [ - { - "id": 545, - "session_id": "S545", - "title": "Implemented JWT authentication system", - "subtitle": "Added token-based auth with refresh tokens", - "created_at_epoch": 1699564800000, - "project": "api-server" - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 3 sessions about "authentication": - -šŸŽÆ **Session #545** Implemented JWT authentication system - > Added token-based auth with refresh tokens - > Nov 9, 2024 ā€¢ api-server - -šŸŽÆ **Session #546** Fixed authentication token expiration - > Resolved race condition in token refresh flow - > Nov 8, 2024 ā€¢ api-server -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Session Summary Structure - -Full session summaries include: - -- **Session request**: What the user asked for -- **What was completed**: Summary of work done -- **Key learnings**: Important insights and discoveries -- **Files modified**: List of changed files -- **Observations**: Links to detailed observations - -## Error Handling - -**Missing query parameter:** -```json -{"error": "Missing required parameter: query"} -``` -Fix: Add the query parameter - -**No results found:** -```json -{"query": "foobar", "count": 0, "results": []} -``` -Response: "No sessions found for 'foobar'. Try different search terms." - -## Tips - -1. Be specific: "JWT authentication implementation" > "auth" -2. Start with format=index and limit=5-10 -3. Use dateStart for recent sessions: `?query=auth&dateStart=2024-11-01` -4. Sessions provide high-level overview, observations provide details -5. Use project filtering when working on one codebase - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## When to Use Sessions vs Observations - -**Use sessions search when:** -- Looking for high-level work summaries -- Understanding what was done in past sessions -- Getting overview of recent activity - -**Use observations search when:** -- Looking for specific implementation details -- Finding bugs, features, or decisions -- Need fine-grained context about code changes diff --git a/plugin/skills/mem-search/operations/timeline-by-query.md b/plugin/skills/mem-search/operations/timeline-by-query.md deleted file mode 100644 index 050c76be..00000000 --- a/plugin/skills/mem-search/operations/timeline-by-query.md +++ /dev/null @@ -1,194 +0,0 @@ -# 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 - -## MCP Tool - -Use the `get_timeline_by_query` MCP tool: - -``` -# Auto mode: Uses top search result as timeline anchor -get_timeline_by_query(query="authentication", mode="auto", depth_before=10, depth_after=10) - -# Interactive mode: Shows top N search results for manual selection -get_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: - -``` -get_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: - -``` -get_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 get_context_timeline(anchor=, 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) diff --git a/plugin/skills/mem-search/operations/timeline.md b/plugin/skills/mem-search/operations/timeline.md deleted file mode 100644 index 5c2019d9..00000000 --- a/plugin/skills/mem-search/operations/timeline.md +++ /dev/null @@ -1,171 +0,0 @@ -# Get Context Timeline - -Get a chronological timeline of observations, sessions, and prompts around a specific point in time. - -## When to Use - -- User asks: "What was happening when we deployed?" -- User asks: "Show me context around that bug fix" -- User asks: "What happened before and after that change?" -- Need temporal context around an event - -## MCP Tool - -Use the `get_context_timeline` MCP tool: - -``` -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 - -- **anchor** (required): Point in time to center timeline - - Observation ID: `1234` - - Session ID: `S545` - - ISO timestamp: `2024-11-09T12:00:00Z` -- **depth_before**: Number of records before anchor (default: 10, max: 50) -- **depth_after**: Number of records after anchor (default: 10, max: 50) -- **project**: Filter by project name (optional) - -## Response Structure - -Returns unified chronological timeline: - -```json -{ - "anchor": 1234, - "depth_before": 10, - "depth_after": 10, - "total_records": 21, - "timeline": [ - { - "record_type": "observation", - "id": 1230, - "type": "feature", - "title": "Added authentication middleware", - "created_at_epoch": 1699564700000 - }, - { - "record_type": "prompt", - "id": 1250, - "session_id": "S545", - "prompt_preview": "How do I add JWT authentication?", - "created_at_epoch": 1699564750000 - }, - { - "record_type": "observation", - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "created_at_epoch": 1699564800000, - "is_anchor": true - }, - { - "record_type": "session", - "id": 545, - "session_id": "S545", - "title": "Implemented JWT authentication system", - "created_at_epoch": 1699564900000 - } - ] -} -``` - -## How to Present Results - -Present as chronological narrative with anchor highlighted: - -```markdown -## Timeline around Observation #1234 - -### Before (10 records) - -**2:45 PM** - šŸŸ£ Observation #1230: Added authentication middleware - -**2:50 PM** - šŸ’¬ User asked: "How do I add JWT authentication?" - -### ā­ Anchor Point (2:55 PM) -šŸŸ£ **Observation #1234**: Implemented JWT authentication - -### After (10 records) - -**3:00 PM** - šŸŽÆ Session #545 completed: Implemented JWT authentication system - -**3:05 PM** - šŸ”“ Observation #1235: Fixed token expiration edge case -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Anchor Types - -**Observation ID:** -- Use when you know the specific observation ID -- Example: `anchor=1234` - -**Session ID:** -- Use when you want context around a session -- Example: `anchor=S545` - -**ISO Timestamp:** -- Use when you know approximate time -- Example: `anchor=2024-11-09T14:30:00Z` - -## Error Handling - -**Missing anchor parameter:** -```json -{"error": "Missing required parameter: anchor"} -``` -Fix: Add the anchor parameter - -**Anchor not found:** -```json -{"error": "Anchor not found: 9999"} -``` -Response: "Observation #9999 not found. Check the ID or try a different anchor." - -**Invalid timestamp:** -```json -{"error": "Invalid timestamp format"} -``` -Fix: Use ISO 8601 format: `2024-11-09T14:30:00Z` - -## Tips - -1. Start with depth_before=10, depth_after=10 for balanced context -2. Increase depth for broader investigation (max: 50 each) -3. Use observation IDs from search results as anchors -4. Timelines show all record types interleaved chronologically -5. Perfect for understanding "what was happening when X occurred" - -**Token Efficiency:** -- depth 10/10: ~3,000-4,000 tokens (21 records) -- depth 20/20: ~6,000-8,000 tokens (41 records) -- depth 50/50: ~15,000-20,000 tokens (101 records) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## When to Use Timeline - -**Use timeline when:** -- Need context around specific event -- Understanding sequence of events -- Investigating "what was happening then?" -- Want all record types (observations, sessions, prompts) together - -**Don't use timeline when:** -- Just need recent work (use recent-context) -- Looking for specific topics (use search) -- Don't have an anchor point (use timeline-by-query) - -## Comparison with Timeline-by-Query - -| Feature | timeline | timeline-by-query | -|---------|----------|-------------------| -| Requires anchor | Yes (ID or timestamp) | No (uses search query) | -| Best for | Known event investigation | Finding then exploring context | -| Steps | 1 (direct timeline) | 2 (search + timeline) | -| Use when | You have observation ID | You have search term | - -Timeline is faster when you already know the anchor point. diff --git a/plugin/skills/mem-search/principles/.gitkeep b/plugin/skills/mem-search/principles/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/plugin/skills/mem-search/principles/anti-patterns.md b/plugin/skills/mem-search/principles/anti-patterns.md deleted file mode 100644 index acd3b1cd..00000000 --- a/plugin/skills/mem-search/principles/anti-patterns.md +++ /dev/null @@ -1,176 +0,0 @@ -# Anti-Pattern Catalogue - -Common mistakes to avoid when using the HTTP search API. These anti-patterns address LLM training biases and prevent token-wasting behaviors. - -## Anti-Pattern 1: Skipping Index Format - -**The Mistake:** -```bash -# āŒ Bad: Jump straight to full format -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=full&limit=20" -``` - -**Why It's Wrong:** -- 20 Ɨ 750 tokens = 15,000 tokens -- May hit MCP token limits -- 99% wasted on irrelevant results - -**The Correction:** -```bash -# āœ… Good: Start with index, review, then request full selectively -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5" -# Review results, identify relevant items -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=full&limit=1&offset=2" -``` - -**What It Teaches:** -Progressive disclosure isn't optional - it's essential for scale. - -**LLM Behavior Insight:** -LLMs trained on code examples may have seen `format=full` as "more complete" and default to it. - ---- - -## Anti-Pattern 2: Over-Requesting Results - -**The Mistake:** -```bash -# āŒ Bad: Request limit=20 without reviewing index first -curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=20" -``` - -**Why It's Wrong:** -- Most of 20 results will be irrelevant -- Wastes tokens and time -- Overwhelms review process - -**The Correction:** -```bash -# āœ… Good: Start small, paginate if needed -curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=5" -# If needed, paginate: -curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=5&offset=5" -``` - -**What It Teaches:** -Start small (limit=3-5), review, paginate if needed. - -**LLM Behavior Insight:** -LLMs may think "more results = more thorough" without considering relevance. - ---- - -## Anti-Pattern 3: Ignoring Tool Specialization - -**The Mistake:** -```bash -# āŒ Bad: Use generic search for everything -curl -s "http://localhost:37777/api/search/observations?query=bugfix&format=index&limit=10" -``` - -**Why It's Wrong:** -- Specialized tools (by-type, by-concept, by-file) are more efficient -- Generic search mixes all result types -- Misses filtering optimization - -**The Correction:** -```bash -# āœ… Good: Use specialized endpoint when applicable -curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=10" -``` - -**What It Teaches:** -The decision tree exists for a reason - follow it. - -**LLM Behavior Insight:** -LLMs may gravitate toward "general purpose" tools to avoid decision-making. - ---- - -## Anti-Pattern 4: Loading Full Context Prematurely - -**The Mistake:** -```bash -# āŒ Bad: Request full format before understanding what's relevant -curl -s "http://localhost:37777/api/search/observations?query=database&format=full&limit=10" -``` - -**Why It's Wrong:** -- Can't filter relevance without seeing index first -- Wastes tokens on irrelevant full details -- 10 Ɨ 750 = 7,500 tokens for potentially zero useful results - -**The Correction:** -```bash -# āœ… Good: Index first to identify relevance -curl -s "http://localhost:37777/api/search/observations?query=database&format=index&limit=10" -# Identify relevant: #1234 and #1250 -curl -s "http://localhost:37777/api/search/observations?query=database+1234&format=full&limit=1" -curl -s "http://localhost:37777/api/search/observations?query=database+1250&format=full&limit=1" -``` - -**What It Teaches:** -Filtering is a prerequisite for expansion. - -**LLM Behavior Insight:** -LLMs may try to "get everything at once" to avoid multiple tool calls. - ---- - -## Anti-Pattern 5: Not Using Timeline Tools - -**The Mistake:** -```bash -# āŒ Bad: Search for individual observations separately -curl -s "http://localhost:37777/api/search/observations?query=before+deployment" -curl -s "http://localhost:37777/api/search/observations?query=during+deployment" -curl -s "http://localhost:37777/api/search/observations?query=after+deployment" -``` - -**Why It's Wrong:** -- Misses context around events -- Inefficient (N searches vs 1 timeline) -- Temporal relationships lost - -**The Correction:** -```bash -# āœ… Good: Use timeline tool for contextual investigation -curl -s "http://localhost:37777/api/timeline/by-query?query=deployment&depth_before=10&depth_after=10" -``` - -**What It Teaches:** -Tool composition - some tools are designed to work together. - -**LLM Behavior Insight:** -LLMs may not naturally discover tool composition patterns. - ---- - -## Why These Anti-Patterns Matter - -**Addresses LLM Training Bias:** -LLMs default to "load everything" behavior from web scraping training data where thoroughness was rewarded. - -**Teaches Protocol Awareness:** -HTTP APIs and MCP have real token limits that can break the system. - -**Prevents User Frustration:** -Token limit errors confuse users and break workflows. - -**Builds Good Habits:** -Anti-patterns teach the "why" behind best practices. - -**Makes Implicit Explicit:** -Surfaces mental models that experienced users internalize but novices miss. - ---- - -## What Happens If These Are Ignored - -- **No progressive disclosure**: Every search loads limit=20 in full format ā†’ token exhaustion -- **Over-requesting**: 15,000 token searches for 2 relevant results -- **Wrong tool**: Generic search when specialized filters would be 10x faster -- **Premature expansion**: Load full details before knowing relevance -- **Missing composition**: Single-tool thinking, missing powerful multi-step workflows - -**Bottom Line:** These anti-patterns waste 5-10x more tokens than necessary and frequently cause system failures. diff --git a/plugin/skills/mem-search/principles/progressive-disclosure.md b/plugin/skills/mem-search/principles/progressive-disclosure.md deleted file mode 100644 index 7fcfa968..00000000 --- a/plugin/skills/mem-search/principles/progressive-disclosure.md +++ /dev/null @@ -1,120 +0,0 @@ -# Progressive Disclosure Pattern (MANDATORY) - -**Core Principle**: Find the smallest set of high-signal tokens first (index format), then drill down to full details only for relevant items. - -## The 4-Step Workflow - -### Step 1: Start with Index Format - -**Action:** -- Use `format=index` (default in most operations) -- Set `limit=3-5` (not 20) -- Review titles and dates ONLY - -**Token Cost:** ~50-100 tokens per result - -**Why:** Minimal token investment for maximum signal. Get overview before committing to full details. - -**Example:** -```bash -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5" -``` - -**Response:** -```json -{ - "query": "authentication", - "count": 5, - "format": "index", - "results": [ - { - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "subtitle": "Added token-based auth with refresh tokens", - "created_at_epoch": 1699564800000, - "project": "api-server" - } - ] -} -``` - -### Step 2: Identify Relevant Items - -**Cognitive Task:** -- Scan index results for relevance -- Note which items need full details -- Discard irrelevant items - -**Why:** Human-in-the-loop filtering before expensive operations. Don't load full details for items you'll ignore. - -### Step 3: Request Full Details (Selectively) - -**Action:** -- Use `format=full` ONLY for specific items of interest -- Target by ID or use refined search query - -**Token Cost:** ~500-1000 tokens per result - -**Principle:** Load only what you need - -**Example:** -```bash -# After reviewing index, get full details for observation #1234 -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=full&limit=1&offset=2" -``` - -**Why:** Targeted token expenditure with high ROI. 10x cost difference means selectivity matters. - -### Step 4: Refine with Filters (If Needed) - -**Techniques:** -- Use `type`, `dateStart`/`dateEnd`, `concepts`, `files` filters -- Narrow scope BEFORE requesting more results -- Use `offset` for pagination instead of large limits - -**Why:** Reduce result set first, then expand selectively. Don't load 20 results when filters could narrow to 3. - -## Token Budget Awareness - -**Costs:** -- Index result: ~50-100 tokens -- Full result: ~500-1000 tokens -- 10x cost difference - -**Starting Points:** -- Start with `limit=3-5` (not 20) -- Reduce limit if hitting token errors - -**Savings Example:** -- Naive: 10 items Ɨ 750 tokens (avg full) = 7,500 tokens -- Progressive: (5 items Ɨ 75 tokens index) + (2 items Ɨ 750 tokens full) = 1,875 tokens -- **Savings: 5,625 tokens (75% reduction)** - -## What Problems This Solves - -1. **Token exhaustion**: Without this, LLMs load everything in full format (9,000+ tokens for 10 items) -2. **Poor signal-to-noise**: Loading full details for irrelevant items wastes tokens -3. **MCP limits**: Large payloads hit protocol limits (system failures) -4. **Inefficiency**: Loading 20 full results when only 2 are relevant - -## How It Scales - -**With 10 records:** -- Index (500 tokens) ā†’ Full (2,000 tokens for 2 relevant) = 2,500 tokens -- Without pattern: Full (10,000 tokens for all 10) = 4x more expensive - -**With 1,000 records:** -- Index (500 tokens for top 5) ā†’ Full (1,000 tokens for 1 relevant) = 1,500 tokens -- Without pattern: Would hit MCP limits before seeing relevant data - -## Context Engineering Alignment - -This pattern implements core context engineering principles: - -- **Just-in-time context**: Load data dynamically at runtime -- **Progressive disclosure**: Lightweight identifiers (index) ā†’ full details as needed -- **Token efficiency**: Minimal high-signal tokens first, expand selectively -- **Attention budget**: Treat context as finite resource with diminishing returns - -Always start with the smallest set of high-signal tokens that maximize likelihood of desired outcome. diff --git a/scripts/build-hooks.js b/scripts/build-hooks.js index 6c594cb8..0cbc3071 100644 --- a/scripts/build-hooks.js +++ b/scripts/build-hooks.js @@ -191,28 +191,11 @@ async function buildHooks() { console.log(`āœ“ ${hook.name} built (${sizeInKB} KB)`); } - // Build mem-search skill zip for Claude Desktop - console.log('\nšŸ“¦ Building mem-search skill zip for Claude Desktop...'); - const { execSync } = await import('child_process'); - const zipOutput = 'plugin/skills/mem-search.zip'; - - // Remove old zip if exists - if (fs.existsSync(zipOutput)) { - fs.unlinkSync(zipOutput); - } - - // Create zip from mem-search skill directory - execSync(`cd plugin/skills && zip -r mem-search.zip mem-search/`, { stdio: 'pipe' }); - const zipStats = fs.statSync(zipOutput); - console.log(`āœ“ mem-search.zip built (${(zipStats.size / 1024).toFixed(2)} KB)`); - console.log('\nāœ… All hooks, worker service, and MCP server built successfully!'); console.log(` Output: ${hooksDir}/`); console.log(` - Hooks: *-hook.js`); console.log(` - Worker: worker-service.cjs`); console.log(` - MCP Server: mcp-server.cjs`); - console.log(` - Skills: plugin/skills/`); - console.log(` - Desktop Skill: plugin/skills/mem-search.zip`); console.log('\nšŸ’” Note: Dependencies will be auto-installed on first hook execution'); } catch (error) { diff --git a/src/servers/mcp-server.ts b/src/servers/mcp-server.ts index a1ec67b4..7035af70 100644 --- a/src/servers/mcp-server.ts +++ b/src/servers/mcp-server.ts @@ -185,7 +185,7 @@ NEVER fetch full details without filtering first. 10x token savings.`, }, { name: 'search', - description: 'Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd', + description: 'Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd, offset, orderBy', inputSchema: { type: 'object', properties: {}, @@ -198,7 +198,7 @@ NEVER fetch full details without filtering first. 10x token savings.`, }, { name: 'timeline', - description: 'Step 2: Get context around results. Params: anchor (observation ID), depth_before, depth_after, project', + description: 'Step 2: Get context around results. Params: anchor (observation ID) OR query (finds anchor automatically), depth_before, depth_after, project', inputSchema: { type: 'object', properties: {}, @@ -211,7 +211,7 @@ NEVER fetch full details without filtering first. 10x token savings.`, }, { name: 'get_observations', - description: 'Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs), project', + description: 'Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs, required), orderBy, limit, project', inputSchema: { type: 'object', properties: {