airkjw/claude-mem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update all search API documentation for simplified parameters

Browse Source 
Update all documentation to reflect the new simplified URL parameter format:
- Replace dateRange[start]/dateRange[end] with dateStart/dateEnd
- Clarify that concepts, files, and obs_type accept comma-separated values
- Update all code examples in skill documentation
- Update comments in search-server.ts

Files updated:
- SKILL.md - Main skill documentation
- operations/*.md - 8 operation guides (observations, prompts, sessions,
  by-file, by-type, by-concept, common-workflows, help)
- principles/progressive-disclosure.md - Design pattern doc
- src/servers/search-server.ts - Code comment

All examples now use clean URLs without bracket encoding:
- Old: ?dateRange[start]=2025-11-01&concepts[]=decision
- New: ?dateStart=2025-11-01&concepts=decision

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alex Newman
2025-11-30 19:03:19 -05:00
parent 50535499d9
commit 7fd0f28343
12 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugin/scripts/search-server.cjs
+1 -1
View File
@@ -543,7 +543,7 @@ Search workflow:
1. Initial search: Use default (index) format to see titles, dates, and sources
2. Review results: Identify which items are most relevant to your needs
3. Deep dive: Only then use format: "full" on specific items of interest
4. Narrow down: Use filters (type, dateRange, concepts, files) to refine results
4. Narrow down: Use filters (type, dateStart/dateEnd, concepts, files) to refine results
Other tips:
\u2022 To search by concept: Use find_by_concept tool
plugin/skills/mem-search/SKILL.md
+4 -4
View File
@@ -98,9 +98,9 @@ curl "http://localhost:37777/api/prompt/5421"
**Filters (optional):**
- `type` - Filter to "observations", "sessions", or "prompts"
- `project` - Filter by project name
- `dateRange[start]` - Start date (YYYY-MM-DD)
- `dateRange[end]` - End date (YYYY-MM-DD)
- `obs_type` - Filter observations by: bugfix, feature, decision, discovery, change
- `dateStart` - Start date (YYYY-MM-DD or epoch timestamp)
- `dateEnd` - End date (YYYY-MM-DD or epoch timestamp)
- `obs_type` - Filter observations by type (comma-separated): bugfix, feature, decision, discovery, change
## Examples
@@ -111,7 +111,7 @@ curl "http://localhost:37777/api/search?query=bug&type=observations&obs_type=bug
**Find what happened last week:**
```bash
curl "http://localhost:37777/api/search?query=&type=observations&dateRange[start]=2025-11-11&format=index&limit=10"
curl "http://localhost:37777/api/search?query=&type=observations&dateStart=2025-11-11&format=index&limit=10"
```
**Search everything:**
plugin/skills/mem-search/operations/by-concept.md
+1 -1
View File
@@ -28,7 +28,7 @@ curl -s "http://localhost:37777/api/search/by-concept?concept=discovery&format=i
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
plugin/skills/mem-search/operations/by-file.md
+2 -2
View File
@@ -24,7 +24,7 @@ curl -s "http://localhost:37777/api/search/by-file?filePath=src/services/worker-
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -118,7 +118,7 @@ Response: "No observations found for 'nonexistent.ts'. Try a partial path or che
1. Use format=index first to see overview of all changes
2. Start with partial paths (e.g., filename only) for broader matches
3. Use full paths when you need specific file matches
4. Combine with dateRange to see recent changes: `?filePath=worker.ts&dateRange[start]=2024-11-01`
4. Combine with dateStart to see recent changes: `?filePath=worker.ts&dateStart=2024-11-01`
5. Use directory searches to see all work in a module
**Token Efficiency:**
plugin/skills/mem-search/operations/by-type.md
+2 -2
View File
@@ -27,7 +27,7 @@ curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limi
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -114,7 +114,7 @@ Fix: Use one of the valid type values
1. Use format=index first to see overview
2. Start with limit=5-10 to avoid token overload
3. Combine with dateRange for recent work: `?type=bugfix&dateRange[start]=2024-11-01`
3. Combine with dateStart for recent work: `?type=bugfix&dateStart=2024-11-01`
4. Use project filtering when working on one codebase
**Token Efficiency:**
plugin/skills/mem-search/operations/common-workflows.md
+3 -3
View File
@@ -186,7 +186,7 @@ Then choose anchor manually.
1. **Combine filters** for precision:
```bash
curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&dateRange[start]=2024-11-01&format=index&limit=10"
curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&dateStart=2024-11-01&format=index&limit=10"
```
2. **Review filtered results**
@@ -207,7 +207,7 @@ Found 10 authentication features added in November:
**Why this workflow:**
- Multiple filters narrow results before requesting full details
- Type + query + dateRange = precise targeting
- Type + query + dateStart/dateEnd = precise targeting
- Progressive disclosure: index first, full details selectively
---
@@ -228,7 +228,7 @@ Found 10 authentication features added in November:
1. **Start with index format** - Always use `format=index` first
2. **Use specialized tools** - by-type, by-file, by-concept when applicable
3. **Compose operations** - Combine search + timeline for investigations
4. **Filter early** - Use type, dateRange, project to narrow before expanding
4. **Filter early** - Use type, dateStart/dateEnd, project to narrow before expanding
5. **Progressive disclosure** - Load full details only for relevant items
## Token Budget Awareness
plugin/skills/mem-search/operations/help.md
+3 -3
View File
@@ -106,9 +106,9 @@ Many endpoints share these parameters:
- **limit**: Number of results to return
- **offset**: Number of results to skip (for pagination)
- **project**: Filter by project name
- **dateRange**: Filter by date range
- `dateRange[start]`: Start date (ISO string or epoch)
- `dateRange[end]`: End date (ISO string or epoch)
- **dateStart/dateEnd**: Filter by date range
- `dateStart`: Start date (YYYY-MM-DD or epoch timestamp)
- `dateEnd`: End date (YYYY-MM-DD or epoch timestamp)
## Error Handling
plugin/skills/mem-search/operations/observations.md
+8 -8
View File
@@ -21,12 +21,12 @@ curl -s "http://localhost:37777/api/search/observations?query=authentication&for
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional) - `dateRange[start]` and/or `dateRange[end]`
- **obs_type**: Filter by observation type: bugfix, feature, refactor, decision, discovery, change (optional)
- **concepts**: Filter by concept tags (optional)
- **files**: Filter by file paths (optional)
- **dateStart/dateEnd**: Filter by date range (optional) - `dateStart` and/or `dateEnd` (YYYY-MM-DD format or epoch timestamp)
- **obs_type**: Filter by observation type (comma-separated): bugfix, feature, refactor, decision, discovery, change (optional)
- **concepts**: Filter by concept tags (comma-separated, optional)
- **files**: Filter by file paths (comma-separated, optional)
**Important**: When omitting `query`, you MUST provide at least one filter (project, dateRange, obs_type, concepts, or files)
**Important**: When omitting `query`, you MUST provide at least one filter (project, dateStart/dateEnd, obs_type, concepts, or files)
## When to Use Each Format
@@ -88,13 +88,13 @@ Search without query text (direct SQLite filtering):
```bash
# Get all observations from November 2025
curl -s "http://localhost:37777/api/search?type=observations&dateRange[start]=2025-11-01&format=index"
curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-01&format=index"
# Get all bug fixes from a specific project
curl -s "http://localhost:37777/api/search?type=observations&obs_type=bugfix&project=api-server&format=index"
# Get all observations from last 7 days
curl -s "http://localhost:37777/api/search?type=observations&dateRange[start]=2025-11-11&format=index"
curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-11&format=index"
```
## Error Handling
@@ -103,7 +103,7 @@ curl -s "http://localhost:37777/api/search?type=observations&dateRange[start]=20
```json
{"error": "Either query or filters required for search"}
```
Fix: Provide either a query parameter OR at least one filter (project, dateRange, obs_type, concepts, files)
Fix: Provide either a query parameter OR at least one filter (project, dateStart/dateEnd, obs_type, concepts, files)
**No results found:**
```json
plugin/skills/mem-search/operations/prompts.md
+2 -2
View File
@@ -21,7 +21,7 @@ curl -s "http://localhost:37777/api/search/prompts?query=authentication&format=i
- **format**: "index" (truncated prompts) or "full" (complete prompt text). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -99,7 +99,7 @@ Response: "No user prompts found for 'foobar'. Try different search terms."
1. Use exact phrases in quotes: `?query="how do I"` for precise matches
2. Start with format=index to see preview, then get full text if needed
3. Use dateRange to find recent questions: `?query=bug&dateRange[start]=2024-11-01`
3. Use dateStart to find recent questions: `?query=bug&dateStart=2024-11-01`
4. Prompts show what was asked, sessions/observations show what was done
5. Combine with session search to see both question and answer
plugin/skills/mem-search/operations/sessions.md
+2 -2
View File
@@ -21,7 +21,7 @@ curl -s "http://localhost:37777/api/search/sessions?query=authentication&format=
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -102,7 +102,7 @@ Response: "No sessions found for 'foobar'. Try different search terms."
1. Be specific: "JWT authentication implementation" > "auth"
2. Start with format=index and limit=5-10
3. Use dateRange for recent sessions: `?query=auth&dateRange[start]=2024-11-01`
3. Use dateStart for recent sessions: `?query=auth&dateStart=2024-11-01`
4. Sessions provide high-level overview, observations provide details
5. Use project filtering when working on one codebase
plugin/skills/mem-search/principles/progressive-disclosure.md
+1 -1
View File
@@ -69,7 +69,7 @@ curl -s "http://localhost:37777/api/search/observations?query=authentication&for
### Step 4: Refine with Filters (If Needed)
**Techniques:**
- Use `type`, `dateRange`, `concepts`, `files` filters
- Use `type`, `dateStart`/`dateEnd`, `concepts`, `files` filters
- Narrow scope BEFORE requesting more results
- Use `offset` for pagination instead of large limits