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
@@ -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
|
||||
Reference in New Issue
Block a user