commit 7ad6af0a780ef7a7f3f7d413673920ef81b130ca Author: Zhongwei Li Date: Sun Nov 30 09:01:40 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..cc99d56 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "claude-mem", + "description": "Persistent memory system for Claude Code - seamlessly preserve context across sessions", + "version": "6.3.2", + "author": { + "name": "Alex Newman" + }, + "skills": [ + "./skills" + ], + "hooks": [ + "./hooks" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..cae6eb6 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# claude-mem + +Persistent memory system for Claude Code - seamlessly preserve context across sessions diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..99a3a8e --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,67 @@ +{ + "description": "Claude-mem memory system hooks", + "hooks": { + "SessionStart": [ + { + "matcher": "startup|clear|compact", + "hooks": [ + { + "type": "command", + "command": "node \"${CLAUDE_PLUGIN_ROOT}/../scripts/smart-install.js\" && node ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js", + "timeout": 300 + }, + { + "type": "command", + "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/user-message-hook.js", + "timeout": 10 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js", + "timeout": 120 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js", + "timeout": 120 + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js", + "timeout": 120 + } + ] + } + ], + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js", + "timeout": 120 + } + ] + } + ] + } +} diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..f60223e --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,141 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:thedotmack/claude-mem:plugin", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "1c728c6aeca699bae22dcd6faf6487d1637ef288", + "treeHash": "83b4ff66cb9db59f61944ef222dfdafed3e163348e3e104142ed1f58632f21ac", + "generatedAt": "2025-11-28T10:28:39.695972Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "claude-mem", + "description": "Persistent memory system for Claude Code - seamlessly preserve context across sessions", + "version": "6.3.2" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "4f60c1d3f064907a0503c1c52c14a919d382bc5ecf3a567e616718dff7f43608" + }, + { + "path": "hooks/hooks.json", + "sha256": "c46910e1ed08e26f887ad1a188f79c83898352f1eb83210276162493c77b225a" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "e04e7b6701b813a9cd454ba1a655f8298d3ae289eca19793a281ca4229223b52" + }, + { + "path": "skills/troubleshoot/SKILL.md", + "sha256": "2703b624ba522d670be12817efc6abdd020344561f73706a1532f3622e848eca" + }, + { + "path": "skills/troubleshoot/operations/reference.md", + "sha256": "d29baec58936eab6fe5d395d704a6550d96f0b0e8284592685a0d1c236e3f1d3" + }, + { + "path": "skills/troubleshoot/operations/common-issues.md", + "sha256": "d95bb2dece7c301addc0ee2ba42bd2e1eab61e69c2a2a1c15d2c873f16b4639b" + }, + { + "path": "skills/troubleshoot/operations/automated-fixes.md", + "sha256": "48e38b54ce075d0c78c25009125aa6ce7a55f1b310da94787cfd8bb4786645e3" + }, + { + "path": "skills/troubleshoot/operations/worker.md", + "sha256": "7f06c8eb9e2aa3c037da51399447dcfd68449a5f929522d47b651dc35bf55284" + }, + { + "path": "skills/troubleshoot/operations/diagnostics.md", + "sha256": "1c141af5ea6c18ea5eb42d143475e0a79356c0a9a60cdfe7fcf77899a830b051" + }, + { + "path": "skills/troubleshoot/operations/database.md", + "sha256": "446efd961ab94df8a9cbcecc929b1aa4cf34c1d44e80691e2a5fb09d9d738618" + }, + { + "path": "skills/mem-search/SKILL.md", + "sha256": "f01e450464b5231ce54803911fa4623fadbefd9872c66e982078d98a0a8654ec" + }, + { + "path": "skills/mem-search/operations/common-workflows.md", + "sha256": "a585b75d97768470d44d5fd8479317231fa5e47150ceb864ae7d1ded5b184d57" + }, + { + "path": "skills/mem-search/operations/by-type.md", + "sha256": "1f8379f562fbf1bcefa836acb07669002c99fd7b84c16edd30b2a102ddd88dc9" + }, + { + "path": "skills/mem-search/operations/.gitkeep", + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" + }, + { + "path": "skills/mem-search/operations/help.md", + "sha256": "ecfeeae6093f5931fdb96dc2847363b5ea831e76af766208e9a137c94f8e8427" + }, + { + "path": "skills/mem-search/operations/recent-context.md", + "sha256": "bdd107cced02b022231718ce1a33f1d9fd31206663bb845b8f1438812c05a2bb" + }, + { + "path": "skills/mem-search/operations/timeline-by-query.md", + "sha256": "5bf7d5c2c2375d467792dc4e9d065c12560315ecb30bd68b77754b6ab3d23fdb" + }, + { + "path": "skills/mem-search/operations/timeline.md", + "sha256": "9156aa4a65b15a3112fb0f6d673f725bcbf21ccfa22bb3cc9bf38b89a7d91de2" + }, + { + "path": "skills/mem-search/operations/by-concept.md", + "sha256": "d20e61e35ca8e099f4ced0fa059d3b92592694331f4e621667793f51a9620051" + }, + { + "path": "skills/mem-search/operations/sessions.md", + "sha256": "bc310f0ced293045bf4ebf7109ec84be95bd72bd68146211636743d1a795efdb" + }, + { + "path": "skills/mem-search/operations/by-file.md", + "sha256": "ff9cd17a33f59a1b35a99a2a34f711935fc0aa7c850547e877823b08b2796e30" + }, + { + "path": "skills/mem-search/operations/prompts.md", + "sha256": "00dd792f040611c6f370ee9360f986c2743ee4ee48c664208a81f0b24b3e9b96" + }, + { + "path": "skills/mem-search/operations/formatting.md", + "sha256": "abfe656a004fecac86ed6313dc41ab5752a9ab948fa636e15261a4d7dfc4b1d1" + }, + { + "path": "skills/mem-search/operations/observations.md", + "sha256": "c3cd330be9336852569df58a39b4ee496f35a2ef99b3c591d2e7b42d011dd59f" + }, + { + "path": "skills/mem-search/principles/progressive-disclosure.md", + "sha256": "2a04559a22ec1b9d8311d97297b13e65d186d79340f859cf663d63c6d2ec84f4" + }, + { + "path": "skills/mem-search/principles/.gitkeep", + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" + }, + { + "path": "skills/mem-search/principles/anti-patterns.md", + "sha256": "9c9b47c038b120efebd75bd0989a28781ac34db4fee91f155b2f1fc97f75f48c" + } + ], + "dirSha256": "83b4ff66cb9db59f61944ef222dfdafed3e163348e3e104142ed1f58632f21ac" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/mem-search/SKILL.md b/skills/mem-search/SKILL.md new file mode 100644 index 0000000..affb896 --- /dev/null +++ b/skills/mem-search/SKILL.md @@ -0,0 +1,123 @@ +--- +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. +--- + +# 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. **Review** - Look at titles/dates, pick relevant IDs +3. **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" +``` + +**Required parameters:** +- `query` - Search term +- `format=index` - ALWAYS start with index (lightweight) +- `limit=5` - Start small (3-5 results) + +**Returns:** +``` +1. [feature] Added JWT authentication + Date: 11/17/2025, 3:48:45 PM + ID: 11131 + +2. [bugfix] Fixed auth token expiration + Date: 11/16/2025, 2:15:22 PM + ID: 10942 +``` + +### Step 2: Pick IDs + +Review the index results. Identify which IDs are actually relevant. Discard the rest. + +### Step 3: Fetch by ID + +For each relevant ID, fetch full details: + +```bash +# Fetch observation +curl "http://localhost:37777/api/observation/11131" + +# Fetch session +curl "http://localhost:37777/api/session/2005" + +# Fetch prompt +curl "http://localhost:37777/api/prompt/5421" +``` + +**ID formats:** +- Observations: Just the number (11131) +- Sessions: Just the number (2005) from "S2005" +- Prompts: Just the number (5421) + +## Search Parameters + +**Basic:** +- `query` - What to search for (required) +- `format` - "index" or "full" (always use "index" first) +- `limit` - How many results (default 5, max 100) + +**Filters (optional):** +- `type` - Filter to "observations", "sessions", or "prompts" +- `project` - Filter by project name +- `dateRange[start]` - Start date (YYYY-MM-DD) +- `dateRange[end]` - End date (YYYY-MM-DD) +- `obs_type` - Filter observations by: bugfix, feature, decision, discovery, change + +## Examples + +**Find recent bug fixes:** +```bash +curl "http://localhost:37777/api/search?query=bug&type=observations&obs_type=bugfix&format=index&limit=5" +``` + +**Find what happened last week:** +```bash +curl "http://localhost:37777/api/search?query=&type=observations&dateRange[start]=2025-11-11&format=index&limit=10" +``` + +**Search everything:** +```bash +curl "http://localhost:37777/api/search?query=database+migration&format=index&limit=5" +``` + +## Why This Workflow? + +**Token efficiency:** +- Index format: ~50-100 tokens per result +- Full format: ~500-1000 tokens per result +- **10x difference** - only fetch full when you know it's relevant + +**Clarity:** +- See everything first +- Pick what matters +- Get details only for what you need + +## Error Handling + +If search fails, tell the user the worker isn't available and suggest: +```bash +pm2 list # Check if worker is running +``` + +--- + +**Remember:** ALWAYS search with format=index first. ALWAYS fetch by ID for details. The IDs are there for a reason - USE THEM. diff --git a/skills/mem-search/operations/.gitkeep b/skills/mem-search/operations/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/mem-search/operations/by-concept.md b/skills/mem-search/operations/by-concept.md new file mode 100644 index 0000000..37d9564 --- /dev/null +++ b/skills/mem-search/operations/by-concept.md @@ -0,0 +1,124 @@ +# 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) +- **dateRange**: 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/skills/mem-search/operations/by-file.md b/skills/mem-search/operations/by-file.md new file mode 100644 index 0000000..bdd0cfa --- /dev/null +++ b/skills/mem-search/operations/by-file.md @@ -0,0 +1,127 @@ +# 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) +- **dateRange**: 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 dateRange to see recent changes: `?filePath=worker.ts&dateRange[start]=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/skills/mem-search/operations/by-type.md b/skills/mem-search/operations/by-type.md new file mode 100644 index 0000000..f5de613 --- /dev/null +++ b/skills/mem-search/operations/by-type.md @@ -0,0 +1,123 @@ +# 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) +- **dateRange**: 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 dateRange for recent work: `?type=bugfix&dateRange[start]=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/skills/mem-search/operations/common-workflows.md b/skills/mem-search/operations/common-workflows.md new file mode 100644 index 0000000..163d3a5 --- /dev/null +++ b/skills/mem-search/operations/common-workflows.md @@ -0,0 +1,251 @@ +# 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&dateRange[start]=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 + dateRange = 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, dateRange, 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/skills/mem-search/operations/formatting.md b/skills/mem-search/operations/formatting.md new file mode 100644 index 0000000..9e09577 --- /dev/null +++ b/skills/mem-search/operations/formatting.md @@ -0,0 +1,403 @@ +# 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 +pm2 list +``` + +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/skills/mem-search/operations/help.md b/skills/mem-search/operations/help.md new file mode 100644 index 0000000..7092c7a --- /dev/null +++ b/skills/mem-search/operations/help.md @@ -0,0 +1,175 @@ +# 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": "5.4.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 (v5.4.0) + +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 +- **dateRange**: Filter by date range + - `dateRange[start]`: Start date (ISO string or epoch) + - `dateRange[end]`: End date (ISO string or epoch) + +## Error Handling + +**Worker not running:** +Connection refused error. Response: "The search API isn't available. Check if worker is running: `pm2 list`" + +**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": "5.4.0", + "skill_migration": true, + "deprecated": { + "mcp_tools": "Replaced by HTTP API in v5.4.0" + } +} +``` + +Check version to ensure compatibility with documentation. diff --git a/skills/mem-search/operations/observations.md b/skills/mem-search/operations/observations.md new file mode 100644 index 0000000..97b65bf --- /dev/null +++ b/skills/mem-search/operations/observations.md @@ -0,0 +1,124 @@ +# 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) +- **dateRange**: Filter by date range (optional) - `dateRange[start]` and/or `dateRange[end]` +- **obs_type**: Filter by observation type: bugfix, feature, refactor, decision, discovery, change (optional) +- **concepts**: Filter by concept tags (optional) +- **files**: Filter by file paths (optional) + +**Important**: When omitting `query`, you MUST provide at least one filter (project, dateRange, 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&dateRange[start]=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&dateRange[start]=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, dateRange, 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/skills/mem-search/operations/prompts.md b/skills/mem-search/operations/prompts.md new file mode 100644 index 0000000..55d285d --- /dev/null +++ b/skills/mem-search/operations/prompts.md @@ -0,0 +1,125 @@ +# 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) +- **dateRange**: 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 dateRange to find recent questions: `?query=bug&dateRange[start]=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/skills/mem-search/operations/recent-context.md b/skills/mem-search/operations/recent-context.md new file mode 100644 index 0000000..69f3524 --- /dev/null +++ b/skills/mem-search/operations/recent-context.md @@ -0,0 +1,134 @@ +# 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: `pm2 list` + +## 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/skills/mem-search/operations/sessions.md b/skills/mem-search/operations/sessions.md new file mode 100644 index 0000000..7da9a04 --- /dev/null +++ b/skills/mem-search/operations/sessions.md @@ -0,0 +1,124 @@ +# 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) +- **dateRange**: 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 dateRange for recent sessions: `?query=auth&dateRange[start]=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/skills/mem-search/operations/timeline-by-query.md b/skills/mem-search/operations/timeline-by-query.md new file mode 100644 index 0000000..5ecf0a7 --- /dev/null +++ b/skills/mem-search/operations/timeline-by-query.md @@ -0,0 +1,192 @@ +# 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 + +## Command + +```bash +# Auto mode: Uses top search result as timeline anchor +curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=auto&depth_before=10&depth_after=10" + +# Interactive mode: Shows top N search results for manual selection +curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=interactive&limit=5" +``` + +## 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: + +```bash +curl -s "http://localhost:37777/api/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: + +```bash +curl -s "http://localhost:37777/api/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 /api/timeline/context?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/skills/mem-search/operations/timeline.md b/skills/mem-search/operations/timeline.md new file mode 100644 index 0000000..d909c18 --- /dev/null +++ b/skills/mem-search/operations/timeline.md @@ -0,0 +1,174 @@ +# 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 + +## Command + +```bash +# Using observation ID as anchor +curl -s "http://localhost:37777/api/timeline/context?anchor=1234&depth_before=10&depth_after=10" + +# Using session ID as anchor +curl -s "http://localhost:37777/api/timeline/context?anchor=S545&depth_before=10&depth_after=10" + +# Using ISO timestamp as anchor +curl -s "http://localhost:37777/api/timeline/context?anchor=2024-11-09T12:00:00Z&depth_before=10&depth_after=10" +``` + +## 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/skills/mem-search/principles/.gitkeep b/skills/mem-search/principles/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/mem-search/principles/anti-patterns.md b/skills/mem-search/principles/anti-patterns.md new file mode 100644 index 0000000..acd3b1c --- /dev/null +++ b/skills/mem-search/principles/anti-patterns.md @@ -0,0 +1,176 @@ +# 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/skills/mem-search/principles/progressive-disclosure.md b/skills/mem-search/principles/progressive-disclosure.md new file mode 100644 index 0000000..2de4f29 --- /dev/null +++ b/skills/mem-search/principles/progressive-disclosure.md @@ -0,0 +1,120 @@ +# 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`, `dateRange`, `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/skills/troubleshoot/SKILL.md b/skills/troubleshoot/SKILL.md new file mode 100644 index 0000000..616e20a --- /dev/null +++ b/skills/troubleshoot/SKILL.md @@ -0,0 +1,89 @@ +--- +name: troubleshoot +description: Diagnose and fix claude-mem installation issues. Checks PM2 worker status, database integrity, service health, dependencies, and provides automated fixes for common problems. +--- + +# Claude-Mem Troubleshooting Skill + +Diagnose and resolve installation and operational issues with the claude-mem plugin. + +## When to Use This Skill + +**Invoke this skill when:** +- Memory not persisting after `/clear` +- Viewer UI empty or not loading +- Worker service not running +- Database missing or corrupted +- Port conflicts +- Missing dependencies +- "Nothing is remembered" complaints +- Search results empty when they shouldn't be + +**Do NOT invoke** for feature requests or usage questions (use regular documentation for that). + +## Quick Decision Guide + +Once the skill is loaded, choose the appropriate operation: + +**What's the problem?** + +- "Nothing is being remembered" → [operations/common-issues.md](operations/common-issues.md#nothing-remembered) +- "Viewer is empty" → [operations/common-issues.md](operations/common-issues.md#viewer-empty) +- "Worker won't start" → [operations/common-issues.md](operations/common-issues.md#worker-not-starting) +- "Want to run full diagnostics" → [operations/diagnostics.md](operations/diagnostics.md) +- "Need automated fix" → [operations/automated-fixes.md](operations/automated-fixes.md) + +## Available Operations + +Choose the appropriate operation file for detailed instructions: + +### Diagnostic Workflows +1. **[Full System Diagnostics](operations/diagnostics.md)** - Comprehensive step-by-step diagnostic workflow +2. **[Worker Diagnostics](operations/worker.md)** - PM2 worker-specific troubleshooting +3. **[Database Diagnostics](operations/database.md)** - Database integrity and data checks + +### Issue Resolution +4. **[Common Issues](operations/common-issues.md)** - Quick fixes for frequently encountered problems +5. **[Automated Fixes](operations/automated-fixes.md)** - One-command fix sequences + +### Reference +6. **[Quick Commands](operations/reference.md)** - Essential commands for troubleshooting + +## Quick Start + +**Fast automated fix (try this first):** +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ && \ +pm2 delete claude-mem-worker 2>/dev/null; \ +npm install && \ +node_modules/.bin/pm2 start ecosystem.config.cjs && \ +sleep 3 && \ +curl -s http://127.0.0.1:37777/health +``` + +Expected output: `{"status":"ok"}` + +If that doesn't work, proceed to detailed diagnostics. + +## Response Format + +When troubleshooting: +1. **Identify the symptom** - What's the user reporting? +2. **Choose operation file** - Use the decision guide above +3. **Follow steps systematically** - Don't skip diagnostic steps +4. **Report findings** - Tell user what you found and what was fixed +5. **Verify resolution** - Confirm the issue is resolved + +## Technical Notes + +- **Worker port:** Default 37777 (configurable via `CLAUDE_MEM_WORKER_PORT`) +- **Database location:** `~/.claude-mem/claude-mem.db` +- **Plugin location:** `~/.claude/plugins/marketplaces/thedotmack/` +- **PM2 process name:** `claude-mem-worker` + +## Error Reporting + +If troubleshooting doesn't resolve the issue, collect diagnostic data and direct user to: +https://github.com/thedotmack/claude-mem/issues + +See [operations/diagnostics.md](operations/diagnostics.md#reporting-issues) for details on what to collect. diff --git a/skills/troubleshoot/operations/automated-fixes.md b/skills/troubleshoot/operations/automated-fixes.md new file mode 100644 index 0000000..baab150 --- /dev/null +++ b/skills/troubleshoot/operations/automated-fixes.md @@ -0,0 +1,151 @@ +# Automated Fix Sequences + +One-command fix sequences for common claude-mem issues. + +## Quick Fix: Complete Reset and Restart + +**Use when:** General issues, worker not responding, after updates + +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ && \ +pm2 delete claude-mem-worker 2>/dev/null; \ +npm install && \ +node_modules/.bin/pm2 start ecosystem.config.cjs && \ +sleep 3 && \ +curl -s http://127.0.0.1:37777/health +``` + +**Expected output:** `{"status":"ok"}` + +**What it does:** +1. Stops the worker (if running) +2. Ensures dependencies are installed +3. Starts worker with local PM2 +4. Waits for startup +5. Verifies health + +## Fix: Worker Not Running + +**Use when:** PM2 shows worker as stopped or not listed + +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ && \ +node_modules/.bin/pm2 start ecosystem.config.cjs && \ +sleep 2 && \ +pm2 status +``` + +**Expected output:** Worker shows as "online" + +## Fix: Dependencies Missing + +**Use when:** Worker won't start due to missing packages + +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ && \ +npm install && \ +pm2 restart claude-mem-worker +``` + +## Fix: Port Conflict + +**Use when:** Error shows port already in use + +```bash +# Change to port 37778 +mkdir -p ~/.claude-mem && \ +echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json && \ +pm2 restart claude-mem-worker && \ +sleep 2 && \ +curl -s http://127.0.0.1:37778/health +``` + +**Expected output:** `{"status":"ok"}` + +## Fix: Database Issues + +**Use when:** Database appears corrupted or out of sync + +```bash +# Backup and test integrity +cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup && \ +sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;" && \ +pm2 restart claude-mem-worker +``` + +**If integrity check fails, recreate database:** +```bash +# WARNING: This deletes all memory data +mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.old && \ +pm2 restart claude-mem-worker +``` + +## Fix: Clean Reinstall + +**Use when:** All else fails, nuclear option + +```bash +# Backup data first +cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup 2>/dev/null + +# Stop and remove worker +pm2 delete claude-mem-worker 2>/dev/null + +# Reinstall dependencies +cd ~/.claude/plugins/marketplaces/thedotmack/ && \ +rm -rf node_modules && \ +npm install + +# Start worker +node_modules/.bin/pm2 start ecosystem.config.cjs && \ +sleep 3 && \ +curl -s http://127.0.0.1:37777/health +``` + +## Fix: Clear PM2 Logs + +**Use when:** Logs are too large, want fresh start + +```bash +pm2 flush claude-mem-worker && \ +pm2 restart claude-mem-worker +``` + +## Verification Commands + +**After running any fix, verify with these:** + +```bash +# Check worker status +pm2 status | grep claude-mem-worker + +# Check health +curl -s http://127.0.0.1:37777/health + +# Check database +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;" + +# Check viewer +curl -s http://127.0.0.1:37777/api/stats + +# Check logs for errors +pm2 logs claude-mem-worker --lines 20 --nostream | grep -i error +``` + +**All checks should pass:** +- Worker status: "online" +- Health: `{"status":"ok"}` +- Database: Shows count (may be 0 if new) +- Stats: Returns JSON with counts +- Logs: No recent errors + +## Troubleshooting the Fixes + +**If automated fix fails:** +1. Run the diagnostic script from [diagnostics.md](diagnostics.md) +2. Check specific error in PM2 logs +3. Try manual worker start to see detailed error: + ```bash + cd ~/.claude/plugins/marketplaces/thedotmack/ + node plugin/scripts/worker-service.cjs + ``` diff --git a/skills/troubleshoot/operations/common-issues.md b/skills/troubleshoot/operations/common-issues.md new file mode 100644 index 0000000..d6dc444 --- /dev/null +++ b/skills/troubleshoot/operations/common-issues.md @@ -0,0 +1,232 @@ +# Common Issue Resolutions + +Quick fixes for frequently encountered claude-mem problems. + +## Issue: Nothing is Remembered After `/clear` {#nothing-remembered} + +**Symptoms:** +- Data doesn't persist across sessions +- Context is empty after `/clear` +- Search returns no results for past work + +**Root cause:** Sessions are marked complete but data should persist. This suggests: +- Worker not processing observations +- Database not being written to +- Context hook not reading from database + +**Fix:** +1. Verify worker is running: + ```bash + pm2 jlist | grep claude-mem-worker + ``` + +2. Check database has recent observations: + ```bash + sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations WHERE created_at > datetime('now', '-1 day');" + ``` + +3. Restart worker and start new session: + ```bash + pm2 restart claude-mem-worker + ``` + +4. Create a test observation: `/skill version-bump` then cancel + +5. Check if observation appears in viewer: + ```bash + open http://127.0.0.1:37777 + # Or manually check database: + sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM observations ORDER BY created_at DESC LIMIT 1;" + ``` + +## Issue: Viewer Empty After Every Claude Restart {#viewer-empty} + +**Symptoms:** +- Viewer shows no data at http://127.0.0.1:37777 +- Stats endpoint returns all zeros +- Database appears empty in UI + +**Root cause:** +- Database being recreated on startup (shouldn't happen) +- Worker reading from wrong database location +- Database permissions issue + +**Fix:** +1. Check database file exists and has data: + ```bash + ls -lh ~/.claude-mem/claude-mem.db + sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;" + ``` + +2. Check file permissions: + ```bash + ls -la ~/.claude-mem/claude-mem.db + # Should be readable/writable by your user + ``` + +3. Verify worker is using correct database path in logs: + ```bash + pm2 logs claude-mem-worker --lines 50 --nostream | grep "Database" + ``` + +4. Test viewer connection manually: + ```bash + curl -s http://127.0.0.1:37777/api/stats + # Should show non-zero counts if data exists + ``` + +## Issue: Old Memory in Claude {#old-memory} + +**Symptoms:** +- Context contains outdated observations +- Irrelevant past work appearing in sessions +- Context feels stale + +**Root cause:** Context hook injecting stale observations + +**Fix:** +1. Check the observation count setting: + ```bash + grep CLAUDE_MEM_CONTEXT_OBSERVATIONS ~/.claude/settings.json + ``` + +2. Default is 50 observations - you can adjust this: + ```json + { + "env": { + "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25" + } + } + ``` + +3. Check database for actual observation dates: + ```bash + sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, project, title FROM observations ORDER BY created_at DESC LIMIT 10;" + ``` + +4. Consider filtering by project if working on multiple codebases + +## Issue: Worker Not Starting {#worker-not-starting} + +**Symptoms:** +- PM2 shows worker as "stopped" or "errored" +- Health check fails +- Viewer not accessible + +**Root cause:** +- Port already in use +- PM2 not installed or not in PATH +- Missing dependencies + +**Fix:** +1. Try manual worker start to see error: + ```bash + cd ~/.claude/plugins/marketplaces/thedotmack/ + node plugin/scripts/worker-service.cjs + # Should start server on port 37777 or show error + ``` + +2. If port in use, change it: + ```bash + mkdir -p ~/.claude-mem + echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json + ``` + +3. If dependencies missing: + ```bash + cd ~/.claude/plugins/marketplaces/thedotmack/ + npm install + pm2 start ecosystem.config.cjs + ``` + +## Issue: Search Results Empty + +**Symptoms:** +- Search skill returns no results +- API endpoints return empty arrays +- Know there's data but can't find it + +**Root cause:** +- FTS5 tables not synchronized +- Wrong project filter +- Database not being queried correctly + +**Fix:** +1. Check if observations exist in database: + ```bash + sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;" + ``` + +2. Check FTS5 table sync: + ```bash + sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;" + # Should match observation count + ``` + +3. Try search via API directly: + ```bash + curl "http://127.0.0.1:37777/api/search/observations?q=test&format=index" + ``` + +4. If FTS5 out of sync, restart worker (triggers reindex): + ```bash + pm2 restart claude-mem-worker + ``` + +## Issue: Port Conflicts + +**Symptoms:** +- Worker won't start +- Error: "EADDRINUSE: address already in use" +- Health check fails + +**Fix:** +1. Check what's using port 37777: + ```bash + lsof -i :37777 + ``` + +2. Either kill the conflicting process or change claude-mem port: + ```bash + mkdir -p ~/.claude-mem + echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json + pm2 restart claude-mem-worker + ``` + +## Issue: Database Corrupted + +**Symptoms:** +- SQLite errors in logs +- Worker crashes on startup +- Queries fail + +**Fix:** +1. Backup the database: + ```bash + cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup + ``` + +2. Try to repair: + ```bash + sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;" + ``` + +3. If repair fails, recreate (loses data): + ```bash + rm ~/.claude-mem/claude-mem.db + pm2 restart claude-mem-worker + # Worker will create new database + ``` + +## Prevention Tips + +**Keep claude-mem healthy:** +- Regularly check viewer UI to see if observations are being captured +- Monitor database size (shouldn't grow unbounded) +- Update plugin when new versions are released +- Keep Claude Code updated + +**Performance tuning:** +- Adjust `CLAUDE_MEM_CONTEXT_OBSERVATIONS` if context is too large/small +- Use `/clear` to mark sessions complete and start fresh +- Use search skill to query specific memories instead of loading everything diff --git a/skills/troubleshoot/operations/database.md b/skills/troubleshoot/operations/database.md new file mode 100644 index 0000000..d57c736 --- /dev/null +++ b/skills/troubleshoot/operations/database.md @@ -0,0 +1,403 @@ +# Database Diagnostics + +SQLite database troubleshooting for claude-mem. + +## Database Overview + +Claude-mem uses SQLite3 for persistent storage: +- **Location:** `~/.claude-mem/claude-mem.db` +- **Library:** better-sqlite3 (synchronous, not bun:sqlite) +- **Features:** FTS5 full-text search, triggers, indexes +- **Tables:** observations, sessions, user_prompts, observations_fts, sessions_fts, prompts_fts + +## Basic Database Checks + +### Check Database Exists + +```bash +# Check file exists +ls -lh ~/.claude-mem/claude-mem.db + +# Check file size +du -h ~/.claude-mem/claude-mem.db + +# Check permissions +ls -la ~/.claude-mem/claude-mem.db +``` + +**Expected:** +- File exists +- Size: 100KB - 10MB+ (depends on usage) +- Permissions: Readable/writable by your user + +### Check Database Integrity + +```bash +# Run integrity check +sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;" +``` + +**Expected output:** `ok` + +**If errors appear:** +- Database corrupted +- Backup immediately: `cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup` +- Consider recreating (data loss) + +## Data Inspection + +### Count Records + +```bash +# Observation count +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;" + +# Session count +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM sessions;" + +# User prompt count +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM user_prompts;" + +# FTS5 table counts (should match main tables) +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;" +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM sessions_fts;" +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM prompts_fts;" +``` + +### View Recent Records + +```bash +# Recent observations +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT + created_at, + type, + title, + project +FROM observations +ORDER BY created_at DESC +LIMIT 10; +" + +# Recent sessions +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT + created_at, + request, + project +FROM sessions +ORDER BY created_at DESC +LIMIT 5; +" + +# Recent user prompts +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT + created_at, + prompt +FROM user_prompts +ORDER BY created_at DESC +LIMIT 10; +" +``` + +### Check Projects + +```bash +# List all projects +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT DISTINCT project +FROM observations +ORDER BY project; +" + +# Count observations per project +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT + project, + COUNT(*) as count +FROM observations +GROUP BY project +ORDER BY count DESC; +" +``` + +## Database Schema + +### View Table Structure + +```bash +# List all tables +sqlite3 ~/.claude-mem/claude-mem.db ".tables" + +# Show observations table schema +sqlite3 ~/.claude-mem/claude-mem.db ".schema observations" + +# Show all schemas +sqlite3 ~/.claude-mem/claude-mem.db ".schema" +``` + +### Expected Tables + +- `observations` - Main observation records +- `observations_fts` - FTS5 virtual table for full-text search +- `sessions` - Session summary records +- `sessions_fts` - FTS5 virtual table for session search +- `user_prompts` - User prompt records +- `prompts_fts` - FTS5 virtual table for prompt search + +## FTS5 Synchronization + +The FTS5 tables should stay synchronized with main tables via triggers. + +### Check FTS5 Sync + +```bash +# Compare counts +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT + (SELECT COUNT(*) FROM observations) as observations, + (SELECT COUNT(*) FROM observations_fts) as observations_fts, + (SELECT COUNT(*) FROM sessions) as sessions, + (SELECT COUNT(*) FROM sessions_fts) as sessions_fts, + (SELECT COUNT(*) FROM user_prompts) as prompts, + (SELECT COUNT(*) FROM prompts_fts) as prompts_fts; +" +``` + +**Expected:** All pairs should match (observations = observations_fts, etc.) + +### Fix FTS5 Desync + +If FTS5 counts don't match, triggers may have failed. Restart worker to rebuild: + +```bash +pm2 restart claude-mem-worker +``` + +The worker will rebuild FTS5 indexes on startup if they're out of sync. + +## Common Database Issues + +### Issue: Database Doesn't Exist + +**Cause:** First run, or database was deleted + +**Fix:** Database will be created automatically on first observation. No action needed. + +### Issue: Database is Empty (0 Records) + +**Cause:** +- New installation (normal) +- Data was deleted +- Worker not processing observations + +**Fix:** +1. Create test observation (use any skill and cancel) +2. Check worker logs for errors: + ```bash + pm2 logs claude-mem-worker --lines 50 --nostream + ``` +3. Verify observation appears in database + +### Issue: Database Permission Denied + +**Cause:** File permissions wrong, database owned by different user + +**Fix:** +```bash +# Check ownership +ls -la ~/.claude-mem/claude-mem.db + +# Fix permissions (if needed) +chmod 644 ~/.claude-mem/claude-mem.db +chown $USER ~/.claude-mem/claude-mem.db +``` + +### Issue: Database Locked + +**Cause:** +- Multiple processes accessing database +- Crash left lock file +- Long-running transaction + +**Fix:** +```bash +# Check for lock file +ls -la ~/.claude-mem/claude-mem.db-wal +ls -la ~/.claude-mem/claude-mem.db-shm + +# Remove lock files (only if worker is stopped!) +pm2 stop claude-mem-worker +rm ~/.claude-mem/claude-mem.db-wal ~/.claude-mem/claude-mem.db-shm +pm2 start claude-mem-worker +``` + +### Issue: Database Growing Too Large + +**Cause:** Too many observations accumulated + +**Check size:** +```bash +du -h ~/.claude-mem/claude-mem.db +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;" +``` + +**Options:** +1. Delete old observations (manual cleanup): + ```bash + sqlite3 ~/.claude-mem/claude-mem.db " + DELETE FROM observations + WHERE created_at < datetime('now', '-90 days'); + " + ``` + +2. Vacuum to reclaim space: + ```bash + sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;" + ``` + +3. Archive and start fresh: + ```bash + mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.archive + pm2 restart claude-mem-worker + ``` + +## Database Recovery + +### Backup Database + +**Before any destructive operations:** +```bash +cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup +``` + +### Restore from Backup + +```bash +pm2 stop claude-mem-worker +cp ~/.claude-mem/claude-mem.db.backup ~/.claude-mem/claude-mem.db +pm2 start claude-mem-worker +``` + +### Export Data + +Export to JSON for safekeeping: + +```bash +# Export observations +sqlite3 ~/.claude-mem/claude-mem.db -json "SELECT * FROM observations;" > observations.json + +# Export sessions +sqlite3 ~/.claude-mem/claude-mem.db -json "SELECT * FROM sessions;" > sessions.json + +# Export prompts +sqlite3 ~/.claude-mem/claude-mem.db -json "SELECT * FROM user_prompts;" > prompts.json +``` + +### Recreate Database + +**WARNING: Data loss. Backup first!** + +```bash +# Stop worker +pm2 stop claude-mem-worker + +# Backup current database +cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.old + +# Delete database +rm ~/.claude-mem/claude-mem.db + +# Start worker (creates new database) +pm2 start claude-mem-worker +``` + +## Database Statistics + +### Storage Analysis + +```bash +# Database file size +du -h ~/.claude-mem/claude-mem.db + +# Record counts by type +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT + type, + COUNT(*) as count +FROM observations +GROUP BY type +ORDER BY count DESC; +" + +# Observations per month +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT + strftime('%Y-%m', created_at) as month, + COUNT(*) as count +FROM observations +GROUP BY month +ORDER BY month DESC; +" + +# Average observation size (characters) +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT + AVG(LENGTH(content)) as avg_content_length, + MAX(LENGTH(content)) as max_content_length +FROM observations; +" +``` + +## Advanced Queries + +### Find Specific Observations + +```bash +# Search by keyword (FTS5) +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT title, created_at +FROM observations_fts +WHERE observations_fts MATCH 'authentication' +ORDER BY created_at DESC; +" + +# Find by type +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT title, created_at +FROM observations +WHERE type = 'bugfix' +ORDER BY created_at DESC +LIMIT 10; +" + +# Find by file path +sqlite3 ~/.claude-mem/claude-mem.db " +SELECT title, created_at +FROM observations +WHERE file_path LIKE '%auth%' +ORDER BY created_at DESC; +" +``` + +## Database Maintenance + +### Regular Maintenance Tasks + +```bash +# Analyze for query optimization +sqlite3 ~/.claude-mem/claude-mem.db "ANALYZE;" + +# Rebuild FTS5 indexes +sqlite3 ~/.claude-mem/claude-mem.db " +INSERT INTO observations_fts(observations_fts) VALUES('rebuild'); +INSERT INTO sessions_fts(sessions_fts) VALUES('rebuild'); +INSERT INTO prompts_fts(prompts_fts) VALUES('rebuild'); +" + +# Vacuum to reclaim space +sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;" +``` + +**Run monthly to keep database healthy.** diff --git a/skills/troubleshoot/operations/diagnostics.md b/skills/troubleshoot/operations/diagnostics.md new file mode 100644 index 0000000..fbb4ac2 --- /dev/null +++ b/skills/troubleshoot/operations/diagnostics.md @@ -0,0 +1,219 @@ +# Full System Diagnostics + +Comprehensive step-by-step diagnostic workflow for claude-mem issues. + +## Diagnostic Workflow + +Run these checks systematically to identify the root cause: + +### 1. Check PM2 Worker Status + +First, verify if the worker service is running: + +```bash +# Check if PM2 is available +which pm2 || echo "PM2 not found in PATH" + +# List PM2 processes +pm2 jlist 2>&1 + +# If pm2 is not found, try the local installation +~/.claude/plugins/marketplaces/thedotmack/node_modules/.bin/pm2 jlist 2>&1 +``` + +**Expected output:** JSON array with `claude-mem-worker` process showing `"status": "online"` + +**If worker not running or status is not "online":** +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ +pm2 start ecosystem.config.cjs +# Or use local pm2: +node_modules/.bin/pm2 start ecosystem.config.cjs +``` + +### 2. Check Worker Service Health + +Test if the worker service responds to HTTP requests: + +```bash +# Default port is 37777 +curl -s http://127.0.0.1:37777/health + +# Check custom port from settings +PORT=$(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_WORKER_PORT | grep -o '[0-9]\+' || echo "37777") +curl -s http://127.0.0.1:$PORT/health +``` + +**Expected output:** `{"status":"ok"}` + +**If connection refused:** +- Worker not running → Go back to step 1 +- Port conflict → Check what's using the port: + ```bash + lsof -i :37777 || netstat -tlnp | grep 37777 + ``` + +### 3. Check Database + +Verify the database exists and contains data: + +```bash +# Check if database file exists +ls -lh ~/.claude-mem/claude-mem.db + +# Check database size (should be > 0 bytes) +du -h ~/.claude-mem/claude-mem.db + +# Query database for observation count (requires sqlite3) +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) as observation_count FROM observations;" 2>&1 + +# Query for session count +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) as session_count FROM sessions;" 2>&1 + +# Check recent observations +sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, type, title FROM observations ORDER BY created_at DESC LIMIT 5;" 2>&1 +``` + +**Expected:** +- Database file exists (typically 100KB - 10MB+) +- Contains observations and sessions +- Recent observations visible + +**If database missing or empty:** +- New installation - this is normal, database will populate as you work +- After `/clear` - sessions are marked complete but not deleted, data should persist +- Corrupted database - backup and recreate: + ```bash + cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup + # Worker will recreate on next observation + ``` + +### 4. Check Dependencies Installation + +Verify all required npm packages are installed: + +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ + +# Check for critical packages +ls node_modules/@anthropic-ai/claude-agent-sdk 2>&1 | head -1 +ls node_modules/better-sqlite3 2>&1 | head -1 +ls node_modules/express 2>&1 | head -1 +ls node_modules/pm2 2>&1 | head -1 +``` + +**Expected:** All critical packages present + +**If dependencies missing:** +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ +npm install +``` + +### 5. Check Worker Logs + +Review recent worker logs for errors: + +```bash +# View last 50 lines of worker logs +pm2 logs claude-mem-worker --lines 50 --nostream + +# Or use local pm2: +cd ~/.claude/plugins/marketplaces/thedotmack/ +node_modules/.bin/pm2 logs claude-mem-worker --lines 50 --nostream + +# Check for specific errors +pm2 logs claude-mem-worker --lines 100 --nostream | grep -i "error\|exception\|failed" +``` + +### 6. Test Viewer UI + +Check if the web viewer is accessible: + +```bash +# Test viewer endpoint +curl -s http://127.0.0.1:37777/ | head -20 + +# Test stats endpoint +curl -s http://127.0.0.1:37777/api/stats +``` + +**Expected:** +- `/` returns HTML page with React viewer +- `/api/stats` returns JSON with database counts + +### 7. Check Port Configuration + +Verify port settings and availability: + +```bash +# Check if custom port is configured +cat ~/.claude-mem/settings.json 2>/dev/null +cat ~/.claude/settings.json 2>/dev/null + +# Check what's listening on default port +lsof -i :37777 2>&1 || netstat -tlnp 2>&1 | grep 37777 + +# Test connectivity +nc -zv 127.0.0.1 37777 2>&1 +``` + +## Full System Diagnosis Script + +Run this comprehensive diagnostic script to collect all information: + +```bash +#!/bin/bash +echo "=== Claude-Mem Troubleshooting Report ===" +echo "" +echo "1. Environment" +echo " OS: $(uname -s)" +echo "" +echo "2. Plugin Installation" +echo " Plugin directory exists: $([ -d ~/.claude/plugins/marketplaces/thedotmack ] && echo 'YES' || echo 'NO')" +echo " Package version: $(grep '"version"' ~/.claude/plugins/marketplaces/thedotmack/package.json 2>/dev/null | head -1)" +echo "" +echo "3. Database" +echo " Database exists: $([ -f ~/.claude-mem/claude-mem.db ] && echo 'YES' || echo 'NO')" +echo " Database size: $(du -h ~/.claude-mem/claude-mem.db 2>/dev/null | cut -f1)" +echo " Observation count: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM observations;' 2>/dev/null || echo 'N/A')" +echo " Session count: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM sessions;' 2>/dev/null || echo 'N/A')" +echo "" +echo "4. Worker Service" +PM2_PATH=$(which pm2 2>/dev/null || echo "~/.claude/plugins/marketplaces/thedotmack/node_modules/.bin/pm2") +echo " PM2 path: $PM2_PATH" +WORKER_STATUS=$($PM2_PATH jlist 2>/dev/null | grep -o '"name":"claude-mem-worker".*"status":"[^"]*"' | grep -o 'status":"[^"]*"' | cut -d'"' -f3 || echo 'not running') +echo " Worker status: $WORKER_STATUS" +echo " Health check: $(curl -s http://127.0.0.1:37777/health 2>/dev/null || echo 'FAILED')" +echo "" +echo "5. Configuration" +echo " Port setting: $(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_WORKER_PORT || echo 'default (37777)')" +echo " Observation count: $(cat ~/.claude/settings.json 2>/dev/null | grep CLAUDE_MEM_CONTEXT_OBSERVATIONS || echo 'default (50)')" +echo "" +echo "6. Recent Activity" +echo " Latest observation: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT created_at FROM observations ORDER BY created_at DESC LIMIT 1;' 2>/dev/null || echo 'N/A')" +echo " Latest session: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT created_at FROM sessions ORDER BY created_at DESC LIMIT 1;' 2>/dev/null || echo 'N/A')" +echo "" +echo "=== End Report ===" +``` + +Save this as `/tmp/claude-mem-diagnostics.sh` and run: +```bash +bash /tmp/claude-mem-diagnostics.sh +``` + +## Reporting Issues + +If troubleshooting doesn't resolve the issue, collect this information for a bug report: + +1. Full diagnostic report (run script above) +2. Worker logs: `pm2 logs claude-mem-worker --lines 100 --nostream` +3. Your setup: + - Claude version: Check with Claude + - OS: `uname -a` + - Node version: `node --version` + - Plugin version: In package.json +4. Steps to reproduce the issue +5. Expected vs actual behavior + +Post to: https://github.com/thedotmack/claude-mem/issues diff --git a/skills/troubleshoot/operations/reference.md b/skills/troubleshoot/operations/reference.md new file mode 100644 index 0000000..5664ef5 --- /dev/null +++ b/skills/troubleshoot/operations/reference.md @@ -0,0 +1,190 @@ +# Quick Commands Reference + +Essential commands for troubleshooting claude-mem. + +## Worker Management + +```bash +# Check worker status +pm2 status | grep claude-mem-worker +pm2 jlist | grep claude-mem-worker # JSON format + +# Start worker +cd ~/.claude/plugins/marketplaces/thedotmack/ +pm2 start ecosystem.config.cjs + +# Restart worker +pm2 restart claude-mem-worker + +# Stop worker +pm2 stop claude-mem-worker + +# Delete worker (for clean restart) +pm2 delete claude-mem-worker + +# View logs +pm2 logs claude-mem-worker + +# View last N lines +pm2 logs claude-mem-worker --lines 50 --nostream + +# Clear logs +pm2 flush claude-mem-worker +``` + +## Health Checks + +```bash +# Check worker health (default port) +curl -s http://127.0.0.1:37777/health + +# Check viewer stats +curl -s http://127.0.0.1:37777/api/stats + +# Open viewer in browser +open http://127.0.0.1:37777 + +# Test custom port +PORT=37778 +curl -s http://127.0.0.1:$PORT/health +``` + +## Database Queries + +```bash +# Observation count +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;" + +# Session count +sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM sessions;" + +# Recent observations +sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, type, title FROM observations ORDER BY created_at DESC LIMIT 10;" + +# Recent sessions +sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, request FROM sessions ORDER BY created_at DESC LIMIT 5;" + +# Database size +du -h ~/.claude-mem/claude-mem.db + +# Database integrity check +sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;" + +# Projects in database +sqlite3 ~/.claude-mem/claude-mem.db "SELECT DISTINCT project FROM observations ORDER BY project;" +``` + +## Configuration + +```bash +# View current settings +cat ~/.claude-mem/settings.json +cat ~/.claude/settings.json + +# Change worker port +echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json + +# Change context observation count +# Edit ~/.claude/settings.json and add: +{ + "env": { + "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25" + } +} + +# Change AI model +{ + "env": { + "CLAUDE_MEM_MODEL": "claude-haiku-4-5" + } +} +``` + +## Plugin Management + +```bash +# Navigate to plugin directory +cd ~/.claude/plugins/marketplaces/thedotmack/ + +# Check plugin version +grep '"version"' package.json + +# Reinstall dependencies +npm install + +# View package.json +cat package.json +``` + +## Port Diagnostics + +```bash +# Check what's using port 37777 +lsof -i :37777 +netstat -tlnp | grep 37777 + +# Test port connectivity +nc -zv 127.0.0.1 37777 +curl -v http://127.0.0.1:37777/health +``` + +## Log Analysis + +```bash +# Search logs for errors +pm2 logs claude-mem-worker --lines 100 --nostream | grep -i "error" + +# Search for specific keyword +pm2 logs claude-mem-worker --lines 100 --nostream | grep "keyword" + +# Follow logs in real-time +pm2 logs claude-mem-worker + +# Show only error logs +pm2 logs claude-mem-worker --err +``` + +## File Locations + +```bash +# Plugin directory +~/.claude/plugins/marketplaces/thedotmack/ + +# Database +~/.claude-mem/claude-mem.db + +# Settings +~/.claude-mem/settings.json +~/.claude/settings.json + +# Chroma vector database +~/.claude-mem/chroma/ + +# Usage logs +~/.claude-mem/usage-logs/ + +# PM2 logs +~/.pm2/logs/ +``` + +## System Information + +```bash +# OS version +uname -a + +# Node version +node --version + +# NPM version +npm --version + +# PM2 version +pm2 --version + +# SQLite version +sqlite3 --version + +# Check disk space +df -h ~/.claude-mem/ +``` diff --git a/skills/troubleshoot/operations/worker.md b/skills/troubleshoot/operations/worker.md new file mode 100644 index 0000000..894db91 --- /dev/null +++ b/skills/troubleshoot/operations/worker.md @@ -0,0 +1,308 @@ +# Worker Service Diagnostics + +PM2 worker-specific troubleshooting for claude-mem. + +## PM2 Worker Overview + +The claude-mem worker is a persistent background service managed by PM2. It: +- Runs Express.js server on port 37777 (default) +- Processes observations asynchronously +- Serves the viewer UI +- Provides search API endpoints + +## Check Worker Status + +### Basic Status Check + +```bash +# List all PM2 processes +pm2 list + +# JSON format (parseable) +pm2 jlist + +# Filter for claude-mem-worker +pm2 status | grep claude-mem-worker +``` + +**Expected output:** +``` +│ claude-mem-worker │ online │ 12345 │ 0 │ 45m │ 0% │ 85.6mb │ +``` + +**Status meanings:** +- `online` - Worker running correctly +- `stopped` - Worker stopped (normal shutdown) +- `errored` - Worker crashed (check logs) +- `stopping` - Worker shutting down +- Not listed - Worker never started + +### Detailed Worker Info + +```bash +# Show detailed information +pm2 show claude-mem-worker + +# JSON format +pm2 jlist | grep -A 20 '"name":"claude-mem-worker"' +``` + +## Worker Health Endpoint + +The worker exposes a health endpoint at `/health`: + +```bash +# Check health (default port) +curl -s http://127.0.0.1:37777/health + +# With custom port +PORT=$(grep CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json | grep -o '[0-9]\+' || echo "37777") +curl -s http://127.0.0.1:$PORT/health +``` + +**Expected response:** `{"status":"ok"}` + +**Error responses:** +- Connection refused - Worker not running +- Timeout - Worker hung (restart needed) +- Empty response - Worker crashed mid-request + +## Worker Logs + +### View Recent Logs + +```bash +# Last 50 lines +pm2 logs claude-mem-worker --lines 50 --nostream + +# Last 200 lines +pm2 logs claude-mem-worker --lines 200 --nostream + +# Follow logs in real-time +pm2 logs claude-mem-worker +``` + +### Search Logs for Errors + +```bash +# Find errors +pm2 logs claude-mem-worker --lines 500 --nostream | grep -i "error" + +# Find exceptions +pm2 logs claude-mem-worker --lines 500 --nostream | grep -i "exception" + +# Find failed requests +pm2 logs claude-mem-worker --lines 500 --nostream | grep -i "failed" + +# All error patterns +pm2 logs claude-mem-worker --lines 500 --nostream | grep -iE "error|exception|failed|crash" +``` + +### Common Log Patterns + +**Good startup:** +``` +Worker service started on port 37777 +Database initialized +Express server listening +``` + +**Database errors:** +``` +Error: SQLITE_ERROR +Error initializing database +Database locked +``` + +**Port conflicts:** +``` +Error: listen EADDRINUSE +Port 37777 already in use +``` + +**Crashes:** +``` +PM2 | App [claude-mem-worker] exited with code [1] +PM2 | App [claude-mem-worker] will restart in 100ms +``` + +## Starting the Worker + +### Basic Start + +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ +pm2 start ecosystem.config.cjs +``` + +### Start with Local PM2 + +If `pm2` command not in PATH: + +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ +node_modules/.bin/pm2 start ecosystem.config.cjs +``` + +### Force Restart + +```bash +# Restart if already running +pm2 restart claude-mem-worker + +# Delete and start fresh +pm2 delete claude-mem-worker +pm2 start ecosystem.config.cjs +``` + +## Stopping the Worker + +```bash +# Graceful stop +pm2 stop claude-mem-worker + +# Delete completely (also removes from PM2 list) +pm2 delete claude-mem-worker +``` + +## Worker Not Starting + +### Diagnostic Steps + +1. **Try manual start to see error:** + ```bash + cd ~/.claude/plugins/marketplaces/thedotmack/ + node plugin/scripts/worker-service.cjs + ``` + This runs the worker directly without PM2, showing full error output. + +2. **Check PM2 itself:** + ```bash + which pm2 + pm2 --version + ``` + If PM2 not found, dependencies not installed. + +3. **Check dependencies:** + ```bash + cd ~/.claude/plugins/marketplaces/thedotmack/ + ls node_modules/@anthropic-ai/claude-agent-sdk + ls node_modules/better-sqlite3 + ls node_modules/express + ls node_modules/pm2 + ``` + +4. **Check port availability:** + ```bash + lsof -i :37777 + ``` + If port in use, either kill that process or change claude-mem port. + +### Common Fixes + +**Dependencies missing:** +```bash +cd ~/.claude/plugins/marketplaces/thedotmack/ +npm install +pm2 start ecosystem.config.cjs +``` + +**Port conflict:** +```bash +echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json +pm2 restart claude-mem-worker +``` + +**Corrupted PM2:** +```bash +pm2 kill # Stop PM2 daemon +cd ~/.claude/plugins/marketplaces/thedotmack/ +pm2 start ecosystem.config.cjs +``` + +## Worker Crashing Repeatedly + +If worker keeps restarting (check with `pm2 status` showing high restart count): + +### Find the Cause + +1. **Check error logs:** + ```bash + pm2 logs claude-mem-worker --err --lines 100 --nostream + ``` + +2. **Look for crash pattern:** + ```bash + pm2 logs claude-mem-worker --lines 200 --nostream | grep -A 5 "exited with code" + ``` + +### Common Crash Causes + +**Database corruption:** +```bash +sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;" +``` +If fails, backup and recreate database. + +**Out of memory:** +Check if database is too large or memory leak. Restart: +```bash +pm2 restart claude-mem-worker +``` + +**Port conflict race condition:** +Another process grabbing port intermittently. Change port: +```bash +echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json +pm2 restart claude-mem-worker +``` + +## PM2 Management Commands + +```bash +# List processes +pm2 list +pm2 jlist # JSON format + +# Show detailed info +pm2 show claude-mem-worker + +# Monitor resources +pm2 monit + +# Clear logs +pm2 flush claude-mem-worker + +# Restart PM2 daemon +pm2 kill +pm2 resurrect # Restore saved processes + +# Save current process list +pm2 save + +# Update PM2 +npm install -g pm2 +``` + +## Testing Worker Endpoints + +Once worker is running, test all endpoints: + +```bash +# Health check +curl -s http://127.0.0.1:37777/health + +# Viewer HTML +curl -s http://127.0.0.1:37777/ | head -20 + +# Stats API +curl -s http://127.0.0.1:37777/api/stats + +# Search API +curl -s "http://127.0.0.1:37777/api/search/observations?q=test&format=index" + +# Prompts API +curl -s "http://127.0.0.1:37777/api/prompts?limit=5" +``` + +All should return appropriate responses (HTML for viewer, JSON for APIs).