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