feat: Add search skill with progressive disclosure and refactor existing skills
Enhancements: - Added search skill with 10 HTTP API endpoints for memory queries - Refactored version-bump and troubleshoot skills using progressive disclosure pattern - Added operations/ subdirectories for detailed skill documentation - Updated CLAUDE.md with skill-based search architecture - Enhanced worker service with search API endpoints - Updated CHANGELOG.md with v5.4.0 migration details Technical changes: - New plugin/skills/search/ directory with SKILL.md - New .claude/skills/version-bump/operations/ (workflow.md, scenarios.md) - New plugin/skills/troubleshoot/operations/ (common-issues.md, worker.md) - Modified src/services/worker-service.ts (added search endpoints) - Modified plugin/scripts/worker-service.cjs (rebuilt with search API) - Reduced main skill files by 89% using progressive disclosure - Token savings: ~2,250 tokens per session start 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alex Newman
+1
-6
@@ -1,8 +1,3 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"claude-mem-search": {
|
||||
"type": "stdio",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/search-server.mjs"
|
||||
}
|
||||
}
|
||||
"mcpServers": {}
|
||||
}
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,96 @@
|
||||
---
|
||||
name: search
|
||||
description: Search claude-mem persistent memory for past sessions, observations, bugs fixed, features implemented, decisions made, code changes, and previous work. Use when answering questions about history, finding past decisions, or researching previous implementations.
|
||||
---
|
||||
|
||||
# Claude-Mem Search Skill
|
||||
|
||||
Access claude-mem's persistent memory through a comprehensive HTTP API. Search for past work, understand context, and learn from previous decisions.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Invoke this skill when users ask about:**
|
||||
- Past work: "What did we do last session?"
|
||||
- Bug fixes: "Did we fix this before?" or "What bugs did we fix?"
|
||||
- Features: "How did we implement authentication?"
|
||||
- Decisions: "Why did we choose this approach?"
|
||||
- Code changes: "What files were modified in that refactor?"
|
||||
- File history: "What changes to auth/login.ts?"
|
||||
- Timeline context: "What was happening around that time?"
|
||||
- Recent activity: "What have we been working on?"
|
||||
|
||||
**Do NOT invoke** for current session work or future planning (use regular tools for that).
|
||||
|
||||
## Quick Decision Guide
|
||||
|
||||
Once the skill is loaded, choose the appropriate operation:
|
||||
|
||||
**What are you looking for?**
|
||||
|
||||
- "What did we do last session?" → [operations/recent-context.md](operations/recent-context.md)
|
||||
- "Did we fix this bug before?" → [operations/by-type.md](operations/by-type.md) (type=bugfix)
|
||||
- "How did we implement X?" → [operations/observations.md](operations/observations.md)
|
||||
- "What changes to file.ts?" → [operations/by-file.md](operations/by-file.md)
|
||||
- "What was happening then?" → [operations/timeline.md](operations/timeline.md)
|
||||
- "Why did we choose X?" → [operations/observations.md](operations/observations.md) (search for decisions)
|
||||
|
||||
## Available Operations
|
||||
|
||||
Choose the appropriate operation file for detailed instructions:
|
||||
|
||||
### Full-Text Search
|
||||
1. **[Search Observations](operations/observations.md)** - Find observations by keyword (bugs, features, decisions, etc.)
|
||||
2. **[Search Sessions](operations/sessions.md)** - Search session summaries to understand what was accomplished
|
||||
3. **[Search Prompts](operations/prompts.md)** - Find what users have asked about in the past
|
||||
|
||||
### Filtered Search
|
||||
4. **[Search by Type](operations/by-type.md)** - Find bugfix, feature, refactor, decision, or discovery observations
|
||||
5. **[Search by Concept](operations/by-concept.md)** - Find observations tagged with specific concepts
|
||||
6. **[Search by File](operations/by-file.md)** - Find all work related to a specific file path
|
||||
|
||||
### Context Retrieval
|
||||
7. **[Get Recent Context](operations/recent-context.md)** - Get recent session summaries and observations for a project
|
||||
8. **[Get Timeline](operations/timeline.md)** - Get chronological timeline around a specific point in time
|
||||
9. **[Timeline by Query](operations/timeline-by-query.md)** - Search then get timeline around the best match
|
||||
|
||||
### Utilities
|
||||
10. **[API Help](operations/help.md)** - Get API documentation
|
||||
|
||||
## Common Workflows
|
||||
|
||||
For step-by-step guides on typical user requests, see [operations/common-workflows.md](operations/common-workflows.md):
|
||||
- Understanding past work
|
||||
- Finding specific bug fixes
|
||||
- Understanding file history
|
||||
- Timeline investigation
|
||||
|
||||
## Response Formatting
|
||||
|
||||
For guidelines on how to present search results to users, see [operations/formatting.md](operations/formatting.md):
|
||||
- Format=index responses (compact lists)
|
||||
- Format=full responses (complete details)
|
||||
- Timeline responses (chronologically grouped)
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- **Port:** Default 37777 (configurable via `CLAUDE_MEM_WORKER_PORT`)
|
||||
- **Response format:** Always JSON
|
||||
- **Search type:** FTS5 full-text search + structured filters
|
||||
- **All operations use HTTP GET** with query parameters
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. Use **format=index** first for overviews, then **format=full** for details
|
||||
2. Start with **limit=5-10**, expand if needed
|
||||
3. Use **project filtering** when working on one codebase
|
||||
4. Use **timeline depth** of 5-10 for focused context
|
||||
5. Be specific in search queries: "authentication JWT" > "auth"
|
||||
|
||||
## Error Handling
|
||||
|
||||
If HTTP request fails:
|
||||
1. Inform user the search service isn't available
|
||||
2. Suggest checking if worker is running: `pm2 list`
|
||||
3. Offer to help troubleshoot
|
||||
|
||||
For detailed error handling, see the specific operation files.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Search by Concept
|
||||
|
||||
Find observations tagged with specific concepts.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Looking for observations about a specific concept
|
||||
- Understanding patterns across the codebase
|
||||
- Finding related learnings
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-concept?concept=discovery&limit=5&format=index"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **concept** (required): Concept tag to search for
|
||||
- **format**: "index" or "full" (default: "full")
|
||||
- **limit**: Number of results (default: 10, max: 100)
|
||||
- **project**: Filter by project name (optional)
|
||||
|
||||
## Common Concepts
|
||||
|
||||
- **discovery**: Learnings and findings
|
||||
- **decision**: Choices and rationale
|
||||
- **architecture**: System design
|
||||
- **performance**: Speed and optimization
|
||||
- **security**: Security considerations
|
||||
- **testing**: Test-related work
|
||||
- **how-it-works**: Implementation details
|
||||
- **why-it-exists**: Rationale and context
|
||||
- **gotcha**: Tricky issues or edge cases
|
||||
- **pattern**: Reusable patterns
|
||||
|
||||
## Use Case
|
||||
|
||||
"What have we learned about the database?" → Search concept=discovery + keyword search for "database"
|
||||
|
||||
You can combine concept search with keyword search:
|
||||
```bash
|
||||
# First get observations with concept=discovery
|
||||
curl -s "http://localhost:37777/api/search/by-concept?concept=discovery&limit=20&format=index"
|
||||
# Then filter results for "database" mentions
|
||||
```
|
||||
|
||||
## How to Present Results
|
||||
|
||||
```markdown
|
||||
Found 5 discoveries:
|
||||
|
||||
1. 🔵 **#1230** Database connection pooling best practices
|
||||
> Learned that pool size should match CPU cores * 2
|
||||
> Nov 8, 2024 • api-server
|
||||
|
||||
2. 🔵 **#1231** JWT library comparison
|
||||
> Evaluated 3 libraries: jsonwebtoken, jose, passport-jwt
|
||||
> Nov 8, 2024 • api-server
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. Concepts provide semantic grouping beyond full-text search
|
||||
2. Useful for finding patterns across different parts of work
|
||||
3. Combine with full-text search for precise results
|
||||
@@ -0,0 +1,83 @@
|
||||
# Search by File Path
|
||||
|
||||
Find all work related to a specific file.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks: "What changes did we make to auth/login.ts?"
|
||||
- Understanding the history of a specific file
|
||||
- Finding all observations that touched a file
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&limit=10&format=index"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **filePath** (required): Full or partial file path
|
||||
- Examples: "auth/", "login.ts", "src/components/Button.tsx"
|
||||
- **format**: "index" or "full" (default: "full")
|
||||
- **limit**: Number of results per type (default: 10, max: 100)
|
||||
- **project**: Filter by project name (optional)
|
||||
|
||||
## Response Structure
|
||||
|
||||
Returns both observations and sessions that touched the file:
|
||||
|
||||
```json
|
||||
{
|
||||
"filePath": "auth/login.ts",
|
||||
"count": 5,
|
||||
"format": "index",
|
||||
"results": {
|
||||
"observations": [...],
|
||||
"sessions": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Full file path:**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-file?filePath=src/auth/login.ts&limit=10"
|
||||
```
|
||||
|
||||
**Partial path (matches all files in directory):**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-file?filePath=auth/&limit=10"
|
||||
```
|
||||
|
||||
**Filename only (matches across directories):**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-file?filePath=login.ts&limit=10"
|
||||
```
|
||||
|
||||
## How to Present Results
|
||||
|
||||
```markdown
|
||||
Found 5 changes to auth/login.ts:
|
||||
|
||||
**Observations:**
|
||||
1. 🟣 **#1234** Implemented JWT authentication
|
||||
> Added token-based auth with refresh tokens
|
||||
> Nov 9, 2024
|
||||
|
||||
2. 🔴 **#1235** Fixed token expiration edge case
|
||||
> Handled race condition in refresh flow
|
||||
> Nov 9, 2024
|
||||
|
||||
**Sessions:**
|
||||
1. **Session #123** (Nov 8, 2024)
|
||||
> Add user authentication
|
||||
> Completed: Implemented JWT auth, added middleware
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. Partial paths are powerful for finding all work in a directory
|
||||
2. Use this before modifying a file to understand its history
|
||||
3. Helps identify who/when/why changes were made
|
||||
4. Combine observations + sessions for complete file history
|
||||
@@ -0,0 +1,72 @@
|
||||
# Search by Type
|
||||
|
||||
Find observations by their classification (bugfix, feature, refactor, decision, discovery, 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&limit=10&format=index"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **type** (required): Observation type
|
||||
- **format**: "index" or "full" (default: "full")
|
||||
- **limit**: Number of results (default: 10, max: 100)
|
||||
- **project**: Filter by project name (optional)
|
||||
|
||||
## Valid Types
|
||||
|
||||
- **bugfix**: Bug fixes and error resolutions 🔴
|
||||
- **feature**: New features and capabilities 🟣
|
||||
- **refactor**: Code restructuring and improvements 🔄
|
||||
- **decision**: Architectural or design decisions 🧠
|
||||
- **discovery**: Learnings about the codebase 🔵
|
||||
- **change**: General changes and updates ✅
|
||||
|
||||
## Use Cases
|
||||
|
||||
**"Show me recent bugs we fixed"**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-type?type=bugfix&limit=10&format=index"
|
||||
```
|
||||
|
||||
**"What features did we add this week?"**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-type?type=feature&limit=20&format=index"
|
||||
```
|
||||
|
||||
**"What architectural decisions have we made?"**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-type?type=decision&limit=10&format=full"
|
||||
```
|
||||
|
||||
## How to Present Results
|
||||
|
||||
```markdown
|
||||
Found 5 recent bugfixes:
|
||||
|
||||
1. 🔴 **#1234** Fixed token expiration edge case
|
||||
> Handled race condition in refresh flow
|
||||
> Nov 9, 2024 • api-server
|
||||
|
||||
2. 🔴 **#1235** Resolved database connection pooling issue
|
||||
> Fixed connection leak in long-running queries
|
||||
> Nov 8, 2024 • api-server
|
||||
```
|
||||
|
||||
Use type-specific emojis for visual clarity.
|
||||
|
||||
## Tips
|
||||
|
||||
1. type=bugfix is great for understanding what issues were resolved
|
||||
2. type=decision helps understand architectural choices
|
||||
3. type=discovery reveals learnings about the codebase
|
||||
4. Combine with project filtering for focused results
|
||||
@@ -0,0 +1,166 @@
|
||||
# Common Workflows
|
||||
|
||||
Step-by-step guides for typical user requests.
|
||||
|
||||
## Workflow 1: Understanding Past Work
|
||||
|
||||
**User asks:** "What did we do last session?"
|
||||
|
||||
**Steps:**
|
||||
1. Use [recent-context.md](recent-context.md) to get last 3 sessions
|
||||
2. Parse and format the summary, observations, and outcomes
|
||||
3. Present in readable markdown
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
RESULT=$(curl -s "http://localhost:37777/api/context/recent?limit=3")
|
||||
# Parse JSON and format for user
|
||||
```
|
||||
|
||||
**Present as:**
|
||||
- Show session request
|
||||
- List key accomplishments
|
||||
- Highlight important observations
|
||||
- Note any next steps
|
||||
|
||||
---
|
||||
|
||||
## Workflow 2: Finding a Specific Bug Fix
|
||||
|
||||
**User asks:** "Did we fix the login timeout issue?"
|
||||
|
||||
**Steps:**
|
||||
1. Search observations with [by-type.md](by-type.md): `type=bugfix`
|
||||
2. Or use [observations.md](observations.md): `query=login+timeout`
|
||||
3. If results found, show title + subtitle + ID
|
||||
4. Offer to get more details or timeline context
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Option 1: Search by type
|
||||
curl -s "http://localhost:37777/api/search/by-type?type=bugfix&limit=20&format=index"
|
||||
|
||||
# Option 2: Full-text search
|
||||
curl -s "http://localhost:37777/api/search/observations?query=login+timeout&format=index&limit=10"
|
||||
```
|
||||
|
||||
**Present as:**
|
||||
- List matching bugfixes
|
||||
- Include observation ID for follow-up
|
||||
- Offer to show full details or timeline
|
||||
|
||||
---
|
||||
|
||||
## Workflow 3: Understanding File History
|
||||
|
||||
**User asks:** "What changes have we made to auth/login.ts?"
|
||||
|
||||
**Steps:**
|
||||
1. Use [by-file.md](by-file.md) to search by file path
|
||||
2. Get both observations and sessions
|
||||
3. Sort chronologically and present
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&limit=10&format=index"
|
||||
```
|
||||
|
||||
**Present as:**
|
||||
- Chronological list of changes
|
||||
- Separate observations and sessions
|
||||
- Include what changed and when
|
||||
- Highlight recent modifications
|
||||
|
||||
---
|
||||
|
||||
## Workflow 4: Timeline Investigation
|
||||
|
||||
**User asks:** "What were we working on around the time of that deployment?"
|
||||
|
||||
**Steps:**
|
||||
1. Use [timeline-by-query.md](timeline-by-query.md) for one-shot query
|
||||
2. Or two-step: search for "deployment" to get ID, then use [timeline.md](timeline.md)
|
||||
|
||||
**Option 1 (Recommended): One request**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/timeline/by-query?query=deployment&depth_before=10&depth_after=10"
|
||||
```
|
||||
|
||||
**Option 2: Two requests**
|
||||
```bash
|
||||
# Step 1: Find the deployment
|
||||
curl -s "http://localhost:37777/api/search/observations?query=deployment&format=index&limit=5"
|
||||
# Get observation ID (e.g., #1234)
|
||||
|
||||
# Step 2: Get timeline around it
|
||||
curl -s "http://localhost:37777/api/context/timeline?anchor=1234&depth_before=10&depth_after=10"
|
||||
```
|
||||
|
||||
**Present as:**
|
||||
- Show the anchor point (deployment observation)
|
||||
- Chronological timeline grouped by day
|
||||
- Highlight observations, sessions, and prompts
|
||||
- Use emojis for visual clarity
|
||||
|
||||
---
|
||||
|
||||
## Workflow 5: Understanding Decisions
|
||||
|
||||
**User asks:** "Why did we choose PostgreSQL over MySQL?"
|
||||
|
||||
**Steps:**
|
||||
1. Search for decisions using [by-type.md](by-type.md): `type=decision`
|
||||
2. Filter results for "PostgreSQL" or "MySQL"
|
||||
3. Show the decision observation with full context
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/by-type?type=decision&limit=20&format=index"
|
||||
# Then search results for database-related decisions
|
||||
```
|
||||
|
||||
Or use full-text search:
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/observations?query=PostgreSQL+MySQL+decision&format=full&limit=5"
|
||||
```
|
||||
|
||||
**Present as:**
|
||||
- Show the decision with full narrative
|
||||
- Include facts and rationale
|
||||
- Link to related observations if available
|
||||
|
||||
---
|
||||
|
||||
## Workflow 6: Exploring a Topic
|
||||
|
||||
**User asks:** "What have we learned about authentication?"
|
||||
|
||||
**Steps:**
|
||||
1. Use [observations.md](observations.md) for full-text search
|
||||
2. Filter by type=discovery for learnings
|
||||
3. Or use [by-concept.md](by-concept.md) for concept=discovery
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Full-text search
|
||||
curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=20"
|
||||
|
||||
# Or discoveries only
|
||||
curl -s "http://localhost:37777/api/search/by-type?type=discovery&limit=20&format=index"
|
||||
# Then filter for "authentication" in results
|
||||
```
|
||||
|
||||
**Present as:**
|
||||
- Group by type (features, bugs, decisions, discoveries)
|
||||
- Show progression of work over time
|
||||
- Highlight key learnings
|
||||
|
||||
---
|
||||
|
||||
## Tips for All Workflows
|
||||
|
||||
1. **Start with format=index** for overviews, then format=full for details
|
||||
2. **Use limit=5-10** initially, expand if needed
|
||||
3. **Combine operations** for comprehensive answers
|
||||
4. **Offer follow-ups**: "Want more details?" "See timeline context?"
|
||||
5. **Use project filtering** when working on one codebase
|
||||
@@ -0,0 +1,242 @@
|
||||
# Response Formatting Guidelines
|
||||
|
||||
How to present search results to users.
|
||||
|
||||
## Format=Index Responses
|
||||
|
||||
When using `format=index`, present results as a **compact list**.
|
||||
|
||||
### Observations
|
||||
|
||||
```markdown
|
||||
Found 5 results for "authentication":
|
||||
|
||||
1. **#1234** [feature] Implemented JWT authentication
|
||||
> Added token-based auth with refresh tokens
|
||||
> Nov 9, 2024 • claude-mem
|
||||
|
||||
2. **#1235** [bugfix] Fixed token expiration edge case
|
||||
> Handled race condition in refresh flow
|
||||
> Nov 9, 2024 • claude-mem
|
||||
|
||||
3. **#1236** [refactor] Simplified authentication middleware
|
||||
> Reduced code complexity by 40%
|
||||
> Nov 10, 2024 • claude-mem
|
||||
```
|
||||
|
||||
**Include:**
|
||||
- ID (for follow-up queries)
|
||||
- Type with emoji (see below)
|
||||
- Title
|
||||
- Subtitle (one-line summary)
|
||||
- Date and project
|
||||
|
||||
**Type Emojis:**
|
||||
- 🔴 **bugfix**: Bug fixes
|
||||
- 🟣 **feature**: New features
|
||||
- 🔄 **refactor**: Code restructuring
|
||||
- 🧠 **decision**: Architectural decisions
|
||||
- 🔵 **discovery**: Learnings
|
||||
- ✅ **change**: General changes
|
||||
|
||||
### Sessions
|
||||
|
||||
```markdown
|
||||
Found 3 sessions about "deployment":
|
||||
|
||||
1. **Session #123** (Nov 8, 2024)
|
||||
> Deploy Docker container to production
|
||||
> Completed: Set up CI/CD pipeline, configured secrets
|
||||
|
||||
2. **Session #124** (Nov 9, 2024)
|
||||
> Fix deployment rollback issues
|
||||
> Completed: Added health checks, fixed rollback script
|
||||
```
|
||||
|
||||
### Prompts
|
||||
|
||||
```markdown
|
||||
Found 3 past prompts about "docker":
|
||||
|
||||
1. **Prompt #456** (Nov 8, 2024)
|
||||
> "Help me set up Docker for this project"
|
||||
|
||||
2. **Prompt #457** (Nov 9, 2024)
|
||||
> "Fix Docker compose networking issues"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Format=Full Responses
|
||||
|
||||
When using `format=full`, present **complete details**.
|
||||
|
||||
### Observations (Full)
|
||||
|
||||
```markdown
|
||||
### Observation #1234: Implemented JWT authentication
|
||||
|
||||
**Type:** Feature 🟣
|
||||
**Project:** claude-mem
|
||||
**Date:** Nov 9, 2024 3:30 PM
|
||||
|
||||
**Summary:** Added token-based auth with refresh tokens
|
||||
|
||||
**Details:**
|
||||
Implemented a complete JWT authentication system for the API. The system uses
|
||||
short-lived access tokens (15 minutes) combined with longer-lived refresh tokens
|
||||
(7 days) to balance security and user experience. The implementation includes
|
||||
middleware for route protection and automatic token refresh handling.
|
||||
|
||||
**Facts:**
|
||||
- Used jsonwebtoken library (v9.0.2)
|
||||
- Access tokens expire after 15 minutes
|
||||
- Refresh tokens expire after 7 days
|
||||
- Tokens include user ID and role claims
|
||||
- Added rate limiting to auth endpoints
|
||||
|
||||
**Files Modified:**
|
||||
- src/auth/jwt.ts (created, 145 lines)
|
||||
- src/middleware/auth.ts (created, 78 lines)
|
||||
- src/routes/auth.ts (created, 92 lines)
|
||||
- tests/auth.test.ts (created, 234 lines)
|
||||
|
||||
**Concepts:** authentication, security, tokens, middleware
|
||||
```
|
||||
|
||||
### Sessions (Full)
|
||||
|
||||
```markdown
|
||||
### Session #123: Add user authentication (Nov 8, 2024)
|
||||
|
||||
**Request:** Implement JWT-based authentication for the API
|
||||
|
||||
**Completed:**
|
||||
- Implemented JWT authentication system with access and refresh tokens
|
||||
- Created authentication middleware for route protection
|
||||
- Added login, logout, and token refresh endpoints
|
||||
- Wrote comprehensive tests for auth flows
|
||||
- Added rate limiting to prevent brute force attacks
|
||||
|
||||
**Learned:**
|
||||
- JWT refresh token rotation is critical for security
|
||||
- Need to handle token expiration gracefully on client side
|
||||
- Rate limiting should be IP-based for auth endpoints
|
||||
- Token blacklisting adds complexity, short expiration is simpler
|
||||
|
||||
**Next Steps:**
|
||||
- Add password reset functionality
|
||||
- Implement 2FA for admin accounts
|
||||
- Add OAuth integration for social login
|
||||
|
||||
**Files Read:**
|
||||
- docs/authentication-spec.md
|
||||
- src/middleware/existing-auth.ts
|
||||
- tests/integration/auth.test.ts
|
||||
|
||||
**Files Edited:**
|
||||
- src/auth/jwt.ts (created)
|
||||
- src/middleware/auth.ts (created)
|
||||
- src/routes/auth.ts (created)
|
||||
- tests/auth.test.ts (created)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Timeline Responses
|
||||
|
||||
Present timeline results **chronologically grouped by day**.
|
||||
|
||||
```markdown
|
||||
## Timeline around Observation #1234
|
||||
|
||||
**Window:** 10 records before → 10 records after
|
||||
**Total:** 15 items (8 obs, 5 sessions, 2 prompts)
|
||||
|
||||
### Nov 8, 2024
|
||||
|
||||
**4:30 PM** - 🎯 **Session Request:** "Add user authentication"
|
||||
|
||||
**4:45 PM** - 🔵 **Discovery #1230:** "JWT library options compared"
|
||||
> Evaluated 3 libraries: jsonwebtoken, jose, passport-jwt
|
||||
> Chose jsonwebtoken for simplicity and community support
|
||||
|
||||
**5:00 PM** - 🧠 **Decision #1231:** "Chose jsonwebtoken for simplicity"
|
||||
> jsonwebtoken has better TypeScript support and simpler API
|
||||
|
||||
**5:15 PM** - 🟣 **Feature #1232:** "Created JWT utility functions"
|
||||
> Sign, verify, and decode token helpers
|
||||
|
||||
### Nov 9, 2024
|
||||
|
||||
**3:30 PM** - 🟣 **Feature #1234:** "Implemented JWT authentication" ← ANCHOR
|
||||
> Complete auth system with access and refresh tokens
|
||||
|
||||
**4:00 PM** - 🔴 **Bugfix #1235:** "Fixed token expiration edge case"
|
||||
> Handled race condition in refresh flow
|
||||
|
||||
**4:30 PM** - ✅ **Change #1236:** "Updated API documentation"
|
||||
> Added auth endpoint docs to README
|
||||
```
|
||||
|
||||
**Legend:**
|
||||
- 🎯 session-request
|
||||
- 🔴 bugfix
|
||||
- 🟣 feature
|
||||
- 🔄 refactor
|
||||
- ✅ change
|
||||
- 🔵 discovery
|
||||
- 🧠 decision
|
||||
|
||||
**Formatting Rules:**
|
||||
1. Group by day with date headers
|
||||
2. Show time for each item
|
||||
3. Use emoji + type + ID/title
|
||||
4. Indent subtitle/summary with `>`
|
||||
5. Mark anchor point with `← ANCHOR`
|
||||
6. Include legend at bottom
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
### No Results
|
||||
|
||||
```markdown
|
||||
No results found for "foobar". Try different search terms or:
|
||||
- Check spelling
|
||||
- Use broader terms
|
||||
- Try synonyms
|
||||
- Search by type or concept instead
|
||||
```
|
||||
|
||||
### Service Unavailable
|
||||
|
||||
```markdown
|
||||
Search service is not available. The claude-mem worker may not be running.
|
||||
|
||||
To check worker status:
|
||||
\`\`\`bash
|
||||
pm2 list
|
||||
\`\`\`
|
||||
|
||||
To restart the worker:
|
||||
\`\`\`bash
|
||||
pm2 restart claude-mem-worker
|
||||
\`\`\`
|
||||
|
||||
Would you like help troubleshooting?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## General Formatting Tips
|
||||
|
||||
1. **Use markdown formatting**: Bold, headers, code blocks, quotes
|
||||
2. **Be concise**: Users want quick answers, not walls of text
|
||||
3. **Highlight key information**: IDs, dates, types
|
||||
4. **Group related items**: By day, by type, by file
|
||||
5. **Offer follow-ups**: "Want more details?" "See timeline?"
|
||||
6. **Use visual hierarchy**: Headers, lists, indentation
|
||||
7. **Include context**: Project names, dates, related observations
|
||||
8. **Make IDs clickable-ready**: **#1234** stands out for reference
|
||||
@@ -0,0 +1,103 @@
|
||||
# API Help
|
||||
|
||||
Get comprehensive API documentation from the search service.
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/help"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
Returns complete API documentation in JSON format including:
|
||||
- All 10 endpoint paths
|
||||
- HTTP methods (all GET)
|
||||
- Parameter descriptions
|
||||
- Example curl commands
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Claude-Mem Search API",
|
||||
"description": "HTTP API for searching persistent memory",
|
||||
"endpoints": [
|
||||
{
|
||||
"path": "/api/search/observations",
|
||||
"method": "GET",
|
||||
"description": "Search observations using full-text search",
|
||||
"parameters": {
|
||||
"query": "Search query (required)",
|
||||
"format": "Response format: 'index' or 'full' (default: 'full')",
|
||||
"limit": "Number of results (default: 20)",
|
||||
"project": "Filter by project name (optional)"
|
||||
}
|
||||
},
|
||||
// ... 9 more endpoints
|
||||
],
|
||||
"examples": [
|
||||
"curl \"http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5\"",
|
||||
"curl \"http://localhost:37777/api/search/by-type?type=bugfix&limit=10\"",
|
||||
// ... more examples
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks: "How do I use the search API?"
|
||||
- Need to see all available endpoints
|
||||
- Reference for parameter names and formats
|
||||
- Getting started with search
|
||||
|
||||
## How to Present
|
||||
|
||||
```markdown
|
||||
## Claude-Mem Search API Documentation
|
||||
|
||||
**Base URL:** http://localhost:37777
|
||||
**Port:** Configurable via `CLAUDE_MEM_WORKER_PORT` (default: 37777)
|
||||
|
||||
### Available Endpoints
|
||||
|
||||
**Full-Text Search:**
|
||||
1. `GET /api/search/observations` - Search observations by keyword
|
||||
2. `GET /api/search/sessions` - Search session summaries
|
||||
3. `GET /api/search/prompts` - Search user prompts
|
||||
|
||||
**Filtered Search:**
|
||||
4. `GET /api/search/by-type` - Filter by observation type
|
||||
5. `GET /api/search/by-concept` - Filter by concept tags
|
||||
6. `GET /api/search/by-file` - Find work by file path
|
||||
|
||||
**Context Retrieval:**
|
||||
7. `GET /api/context/recent` - Get recent sessions
|
||||
8. `GET /api/context/timeline` - Timeline around a point
|
||||
9. `GET /api/timeline/by-query` - Search + timeline in one call
|
||||
|
||||
**Documentation:**
|
||||
10. `GET /api/search/help` - This help documentation
|
||||
|
||||
### Example Usage
|
||||
|
||||
\`\`\`bash
|
||||
# Search for authentication-related observations
|
||||
curl "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5"
|
||||
|
||||
# Get recent bugfixes
|
||||
curl "http://localhost:37777/api/search/by-type?type=bugfix&limit=10"
|
||||
|
||||
# Get timeline around observation #1234
|
||||
curl "http://localhost:37777/api/context/timeline?anchor=1234&depth_before=5&depth_after=5"
|
||||
\`\`\`
|
||||
|
||||
For detailed information on each endpoint, see the operation-specific documentation files.
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- This endpoint is useful for quick API reference
|
||||
- Most users won't need to use this directly
|
||||
- The router SKILL.md provides better user-facing guidance
|
||||
- Use this when users specifically ask "how do I use the API"
|
||||
@@ -0,0 +1,96 @@
|
||||
# Search Observations (Full-Text)
|
||||
|
||||
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=20"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **query** (required): Search terms (e.g., "authentication", "bug fix", "database migration")
|
||||
- **format**: "index" (summary) or "full" (complete details). Default: "full"
|
||||
- **limit**: Number of results (default: 20, max: 100)
|
||||
- **project**: Filter by project name (optional)
|
||||
|
||||
## When to Use Each Format
|
||||
|
||||
**Use format=index for:**
|
||||
- Quick overviews
|
||||
- Finding IDs for deeper investigation
|
||||
- Listing multiple results
|
||||
|
||||
**Use format=full for:**
|
||||
- Complete details including narrative, facts, files, concepts
|
||||
- Understanding the full context of specific observations
|
||||
|
||||
## 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](formatting.md).
|
||||
|
||||
## 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 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
|
||||
@@ -0,0 +1,64 @@
|
||||
# Search User Prompts
|
||||
|
||||
Find what users have asked about in the past.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks: "Have we worked on Docker before?"
|
||||
- Looking for patterns in user requests
|
||||
- Understanding what topics have been explored
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/prompts?query=docker&format=index&limit=10"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **query** (required): Search terms
|
||||
- **format**: "index" (summary) or "full" (complete details). Default: "full"
|
||||
- **limit**: Number of results (default: 20, max: 100)
|
||||
- **project**: Filter by project name (optional)
|
||||
|
||||
## Use Case
|
||||
|
||||
"Have we worked on Docker before?" → Search prompts to see related user requests
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "docker",
|
||||
"count": 3,
|
||||
"format": "index",
|
||||
"results": [
|
||||
{
|
||||
"id": 456,
|
||||
"claude_session_id": "abc-123",
|
||||
"prompt_number": 1,
|
||||
"prompt_text": "Help me set up Docker for this project",
|
||||
"created_at_epoch": 1699564800000,
|
||||
"score": 0.98
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## How to Present Results
|
||||
|
||||
```markdown
|
||||
Found 3 past prompts about "docker":
|
||||
|
||||
1. **Prompt #456** (Nov 8, 2024)
|
||||
> "Help me set up Docker for this project"
|
||||
|
||||
2. **Prompt #457** (Nov 9, 2024)
|
||||
> "Fix Docker compose networking issues"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. Useful for understanding what users have asked about
|
||||
2. Combine with session search to see both questions and outcomes
|
||||
3. Helps identify recurring topics or pain points
|
||||
@@ -0,0 +1,93 @@
|
||||
# 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?"
|
||||
- Need to understand recent project activity
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/context/recent?project=claude-mem&limit=3"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **project**: Project name (default: current directory basename)
|
||||
- **limit**: Number of recent sessions (default: 3, max: 10)
|
||||
|
||||
## Response Structure
|
||||
|
||||
Returns complete session data including summaries, observations, and status:
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "claude-mem",
|
||||
"limit": 3,
|
||||
"count": 3,
|
||||
"sessions": [
|
||||
{
|
||||
"sdk_session_id": "abc-123",
|
||||
"status": "completed",
|
||||
"has_summary": 1,
|
||||
"summary": {
|
||||
"request": "Add authentication",
|
||||
"completed": "Implemented JWT auth...",
|
||||
"learned": "...",
|
||||
"next_steps": "..."
|
||||
},
|
||||
"observations": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Use Case: "What did we do last session?"
|
||||
|
||||
```bash
|
||||
# Get last 3 sessions
|
||||
RESULT=$(curl -s "http://localhost:37777/api/context/recent?limit=3")
|
||||
|
||||
# Parse and format:
|
||||
# - Show session request
|
||||
# - Show what was completed
|
||||
# - List key observations
|
||||
# - Highlight next steps
|
||||
```
|
||||
|
||||
## How to Present Results
|
||||
|
||||
```markdown
|
||||
## Recent Work on claude-mem
|
||||
|
||||
### Session 1 (Nov 9, 2024 - Completed)
|
||||
**Request:** Add user authentication
|
||||
|
||||
**Completed:**
|
||||
- Implemented JWT authentication with token-based auth
|
||||
- Added middleware for route protection
|
||||
- Created login and refresh token endpoints
|
||||
|
||||
**Key Observations:**
|
||||
1. 🟣 Implemented JWT authentication (#1234)
|
||||
2. 🔴 Fixed token expiration edge case (#1235)
|
||||
|
||||
**Next Steps:**
|
||||
- Add password reset functionality
|
||||
- Implement rate limiting
|
||||
|
||||
---
|
||||
|
||||
### Session 2 (Nov 8, 2024 - Completed)
|
||||
...
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. This is the best operation for "what did we do recently" questions
|
||||
2. Returns complete context including summaries and observations
|
||||
3. Active sessions show current work in progress
|
||||
4. Default limit=3 is usually sufficient for recent context
|
||||
@@ -0,0 +1,63 @@
|
||||
# Search Session Summaries
|
||||
|
||||
Search session-level summaries to understand what was accomplished in past sessions.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks: "What did we accomplish in previous sessions?"
|
||||
- Looking for sessions about a specific topic
|
||||
- Understanding the scope of past work
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/sessions?query=deployment&format=index&limit=10"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **query** (required): Search terms (e.g., "deployment", "bug fix", "refactor")
|
||||
- **format**: "index" (summary) or "full" (complete details). Default: "full"
|
||||
- **limit**: Number of results (default: 20, max: 100)
|
||||
|
||||
## Response Fields
|
||||
|
||||
- **request**: Original user request
|
||||
- **completed**: What was accomplished
|
||||
- **learned**: Technical learnings
|
||||
- **next_steps**: Planned follow-ups
|
||||
- **files_read**: Files that were read
|
||||
- **files_edited**: Files that were modified
|
||||
|
||||
## Example Use Case
|
||||
|
||||
User asks: "Have we worked on deployment before?"
|
||||
|
||||
```bash
|
||||
RESULT=$(curl -s "http://localhost:37777/api/search/sessions?query=deployment&format=index&limit=5")
|
||||
# Parse JSON and present matching sessions
|
||||
```
|
||||
|
||||
## How to Present Results
|
||||
|
||||
For format=index:
|
||||
|
||||
```markdown
|
||||
Found 3 sessions about "deployment":
|
||||
|
||||
1. **Session #123** (Nov 8, 2024)
|
||||
> Deploy Docker container to production
|
||||
> Completed: Set up CI/CD pipeline, configured secrets
|
||||
|
||||
2. **Session #124** (Nov 9, 2024)
|
||||
> Fix deployment rollback issues
|
||||
> Completed: Added health checks, fixed rollback script
|
||||
```
|
||||
|
||||
For format=full, include all fields (request, completed, learned, next_steps, files).
|
||||
|
||||
## Tips
|
||||
|
||||
1. Use format=index to find relevant sessions quickly
|
||||
2. Then fetch format=full for complete details
|
||||
3. Sessions capture high-level accomplishments vs observations (which are granular facts)
|
||||
@@ -0,0 +1,97 @@
|
||||
# Timeline by Query
|
||||
|
||||
Search for something, then automatically get timeline context around the best match.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks: "What led to the authentication refactor?"
|
||||
- Want to find something AND see surrounding context in one request
|
||||
- Understand the full story with minimal requests
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/timeline/by-query?query=authentication+refactor&mode=auto&depth_before=10&depth_after=10"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **query** (required): Search terms
|
||||
- **mode**: Where to search (default: "auto")
|
||||
- `"auto"`: Search both observations and sessions, return best match
|
||||
- `"observations"`: Search only observations
|
||||
- `"sessions"`: Search only sessions
|
||||
- **depth_before**: Records before match (default: 10, max: 50)
|
||||
- **depth_after**: Records after match (default: 10, max: 50)
|
||||
- **project**: Filter by project name (optional)
|
||||
|
||||
## Response Structure
|
||||
|
||||
Returns both the best match AND timeline around it:
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "authentication refactor",
|
||||
"mode": "auto",
|
||||
"match": {
|
||||
"type": "observation",
|
||||
"id": 1234,
|
||||
"title": "Refactored authentication middleware",
|
||||
"score": 0.95,
|
||||
"created_at_epoch": 1699564800000
|
||||
},
|
||||
"depth_before": 10,
|
||||
"depth_after": 10,
|
||||
"timeline": {
|
||||
"observations": [...],
|
||||
"sessions": [...],
|
||||
"prompts": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Use Case: "What led to the authentication refactor?"
|
||||
|
||||
One query gets both:
|
||||
1. The authentication refactor observation (best match)
|
||||
2. Complete timeline before and after showing what led to it
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/timeline/by-query?query=authentication+refactor&depth_before=10&depth_after=10"
|
||||
```
|
||||
|
||||
## How to Present Results
|
||||
|
||||
```markdown
|
||||
## Found: Refactored authentication middleware (Observation #1234)
|
||||
|
||||
**Match score:** 0.95
|
||||
**Date:** Nov 9, 2024 3:30 PM
|
||||
|
||||
### Timeline (10 before → 10 after)
|
||||
|
||||
**Total:** 18 items (11 obs, 5 sessions, 2 prompts)
|
||||
|
||||
### Nov 8, 2024
|
||||
|
||||
**2:00 PM** - 🔴 **Bugfix #1220:** "Fixed token validation bug"
|
||||
> Tokens weren't properly validated
|
||||
|
||||
**3:00 PM** - 🔵 **Discovery #1225:** "Current auth middleware is fragile"
|
||||
> Multiple edge cases not handled
|
||||
|
||||
### Nov 9, 2024
|
||||
|
||||
**3:30 PM** - 🔄 **Refactor #1234:** "Refactored authentication middleware" ← MATCH
|
||||
> Complete rewrite with better error handling
|
||||
|
||||
**4:00 PM** - ✅ **Change #1235:** "Updated all routes to use new middleware"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. This is the most efficient operation for "what led to X" questions
|
||||
2. One request instead of two (search + timeline)
|
||||
3. Use mode="auto" to search both observations and sessions
|
||||
4. Adjust depth based on how much context you need
|
||||
5. Great for understanding causality and sequence
|
||||
@@ -0,0 +1,97 @@
|
||||
# Get Timeline
|
||||
|
||||
Get a chronological timeline around a specific point in time.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks: "What was happening when we fixed that bug?"
|
||||
- Need context around a specific observation or session
|
||||
- Understanding the sequence of events
|
||||
|
||||
## Command
|
||||
|
||||
```bash
|
||||
# Around an observation ID
|
||||
curl -s "http://localhost:37777/api/context/timeline?anchor=1234&depth_before=10&depth_after=10"
|
||||
|
||||
# Around a session ID
|
||||
curl -s "http://localhost:37777/api/context/timeline?anchor=S123&depth_before=10&depth_after=10"
|
||||
|
||||
# Around a timestamp
|
||||
curl -s "http://localhost:37777/api/context/timeline?anchor=2024-11-09T15:30:00Z&depth_before=10&depth_after=10"
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
- **anchor** (required): Observation ID (number), Session ID ("S123"), or ISO timestamp
|
||||
- **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 timeline with observations, sessions, and prompts interleaved chronologically:
|
||||
|
||||
```json
|
||||
{
|
||||
"anchor": "1234",
|
||||
"depth_before": 10,
|
||||
"depth_after": 10,
|
||||
"timeline": {
|
||||
"observations": [...],
|
||||
"sessions": [...],
|
||||
"prompts": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Workflow: "What was happening when we fixed that auth bug?"
|
||||
|
||||
1. First, find the bug observation:
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/search/observations?query=auth+bug&format=index&limit=5"
|
||||
# Get observation ID (e.g., #1234)
|
||||
```
|
||||
|
||||
2. Then get timeline around it:
|
||||
```bash
|
||||
curl -s "http://localhost:37777/api/context/timeline?anchor=1234&depth_before=5&depth_after=5"
|
||||
```
|
||||
|
||||
## How to Present Results
|
||||
|
||||
Present chronologically grouped by day:
|
||||
|
||||
```markdown
|
||||
## Timeline around Observation #1234
|
||||
|
||||
**Window:** 5 records before → 5 records after
|
||||
**Total:** 12 items (7 obs, 3 sessions, 2 prompts)
|
||||
|
||||
### Nov 8, 2024
|
||||
|
||||
**4:30 PM** - 🎯 **Session Request:** "Add user authentication"
|
||||
|
||||
**4:45 PM** - 🔵 **Discovery #1230:** "JWT library options compared"
|
||||
> Evaluated 3 libraries: jsonwebtoken, jose, passport-jwt
|
||||
|
||||
**5:00 PM** - 🧠 **Decision #1231:** "Chose jsonwebtoken for simplicity"
|
||||
|
||||
### Nov 9, 2024
|
||||
|
||||
**3:30 PM** - 🟣 **Feature #1234:** "Implemented JWT authentication" ← ANCHOR
|
||||
|
||||
**4:00 PM** - 🔴 **Bugfix #1235:** "Fixed token expiration edge case"
|
||||
> Handled race condition in refresh flow
|
||||
```
|
||||
|
||||
**Legend:** 🎯 session-request | 🔴 bugfix | 🟣 feature | 🔄 refactor | 🔵 discovery | 🧠 decision
|
||||
|
||||
For complete formatting guidelines, see [formatting.md](formatting.md).
|
||||
|
||||
## Tips
|
||||
|
||||
1. Use depth_before=5, depth_after=5 for focused context
|
||||
2. Increase depth for broader investigation
|
||||
3. Timeline shows the full story around a specific point
|
||||
4. Helps understand causality and sequence of events
|
||||
@@ -5,359 +5,85 @@ description: Diagnose and fix claude-mem installation issues. Checks PM2 worker
|
||||
|
||||
# Claude-Mem Troubleshooting Skill
|
||||
|
||||
This skill diagnoses and resolves common installation and operational issues with the claude-mem plugin.
|
||||
Diagnose and resolve installation and operational issues with the claude-mem plugin.
|
||||
|
||||
## Quick Reference
|
||||
## When to Use This Skill
|
||||
|
||||
**Common Issues:**
|
||||
**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
|
||||
|
||||
## Diagnostic Workflow
|
||||
**Do NOT invoke** for feature requests or usage questions (use regular documentation for that).
|
||||
|
||||
When invoked, follow these steps systematically:
|
||||
## Quick Decision Guide
|
||||
|
||||
### 1. Check PM2 Worker Status
|
||||
Once the skill is loaded, choose the appropriate operation:
|
||||
|
||||
First, verify if the worker service is running:
|
||||
**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
|
||||
# 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
|
||||
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
|
||||
|
||||
# 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"}`
|
||||
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
|
||||
```
|
||||
If that doesn't work, proceed to detailed diagnostics.
|
||||
|
||||
### 3. Check Database
|
||||
## Response Format
|
||||
|
||||
Verify the database exists and contains data:
|
||||
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
|
||||
|
||||
```bash
|
||||
# Check if database file exists
|
||||
ls -lh ~/.claude-mem/claude-mem.db
|
||||
## Technical Notes
|
||||
|
||||
# Check database size (should be > 0 bytes)
|
||||
du -h ~/.claude-mem/claude-mem.db
|
||||
- **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`
|
||||
|
||||
# Query database for observation count (requires sqlite3)
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) as observation_count FROM observations;" 2>&1
|
||||
## Error Reporting
|
||||
|
||||
# Query for session count
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) as session_count FROM sessions;" 2>&1
|
||||
If troubleshooting doesn't resolve the issue, collect diagnostic data and direct user to:
|
||||
https://github.com/thedotmack/claude-mem/issues
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
## Automated Fix Sequence
|
||||
|
||||
If you're seeing issues, try this automated fix sequence:
|
||||
|
||||
```bash
|
||||
# 1. Stop the worker
|
||||
pm2 delete claude-mem-worker 2>/dev/null || true
|
||||
|
||||
# 2. Navigate to plugin directory
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
|
||||
# 3. Ensure dependencies are installed
|
||||
npm install
|
||||
|
||||
# 4. Start worker with local pm2
|
||||
node_modules/.bin/pm2 start ecosystem.config.cjs
|
||||
|
||||
# 5. Wait for health check
|
||||
sleep 3
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
|
||||
# 6. Check logs for any errors
|
||||
node_modules/.bin/pm2 logs claude-mem-worker --lines 20 --nostream
|
||||
```
|
||||
|
||||
## Common Issue Resolutions
|
||||
|
||||
### Issue: "Nothing is remembered after /clear"
|
||||
|
||||
**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 (Step 1)
|
||||
2. Check database has recent observations (Step 3)
|
||||
3. Restart worker and start new session
|
||||
4. Create a test observation: `/skill version-bump` then cancel
|
||||
5. Check if observation appears in viewer: http://127.0.0.1:37777
|
||||
|
||||
### Issue: "Viewer empty after every Claude restart"
|
||||
|
||||
**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 (Step 3)
|
||||
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
|
||||
4. Test viewer connection manually
|
||||
|
||||
### Issue: "Old memory in Claude"
|
||||
|
||||
**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
|
||||
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;"
|
||||
```
|
||||
|
||||
### Issue: "Worker not starting"
|
||||
|
||||
**Root cause:**
|
||||
- Port already in use
|
||||
- PM2 not installed or not in PATH
|
||||
- Missing dependencies
|
||||
|
||||
**Fix:**
|
||||
1. Try manual worker start:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
node plugin/scripts/worker-service.cjs
|
||||
# Should start server on port 37777
|
||||
```
|
||||
2. If port in use, change it:
|
||||
```bash
|
||||
echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json
|
||||
```
|
||||
|
||||
## Full System Diagnosis
|
||||
|
||||
Run this comprehensive diagnostic script:
|
||||
|
||||
```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
|
||||
|
||||
## 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 MCP search tools to query specific memories instead of loading everything
|
||||
|
||||
## Quick Commands Reference
|
||||
|
||||
```bash
|
||||
# Restart worker
|
||||
pm2 restart claude-mem-worker
|
||||
|
||||
# View logs
|
||||
pm2 logs claude-mem-worker
|
||||
|
||||
# Check health
|
||||
curl http://127.0.0.1:37777/health
|
||||
|
||||
# View database stats
|
||||
curl http://127.0.0.1:37777/api/stats
|
||||
|
||||
# Open viewer
|
||||
open http://127.0.0.1:37777
|
||||
|
||||
# Delete and reinstall worker
|
||||
pm2 delete claude-mem-worker
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
pm2 start ecosystem.config.cjs
|
||||
```
|
||||
See [operations/diagnostics.md](operations/diagnostics.md#reporting-issues) for details on what to collect.
|
||||
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
@@ -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.**
|
||||
@@ -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
|
||||
@@ -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/
|
||||
```
|
||||
@@ -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).
|
||||
Reference in New Issue
Block a user