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

refactor: update documentation and API references for version bump and search functionalities

Browse Source
This commit is contained in:
Alex Newman
2025-12-14 20:12:39 -05:00
parent 2ec72f948d
commit b97579dfec
10 changed files with 82 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/CLAUDE.md
+1 -1
View File
@@ -19,7 +19,7 @@ This directory contains skills **for developing and maintaining the claude-mem p
## Skills in This Directory ## Skills in This Directory
### version-bump ### version-bump
Manages semantic versioning for the claude-mem project itself. Handles updating all four version files (package.json, marketplace.json, plugin.json, CLAUDE.md), creating git tags, and GitHub releases. Manages semantic versioning for the claude-mem project itself. Handles updating all three version files (package.json, marketplace.json, plugin.json), creating git tags, and GitHub releases.
**Usage**: Only for claude-mem maintainers releasing new versions. **Usage**: Only for claude-mem maintainers releasing new versions.
.claude/skills/version-bump/SKILL.md
+7 -10
View File
@@ -1,6 +1,6 @@
--- ---
name: version-bump name: version-bump
description: Manage semantic version updates for claude-mem project. Handles patch, minor, and major version increments following semantic versioning. Updates package.json, marketplace.json, plugin.json, and CLAUDE.md version number (NOT version history). Creates git tags and GitHub releases. Auto-generates CHANGELOG.md from releases. description: Manage semantic version updates for claude-mem project. Handles patch, minor, and major version increments following semantic versioning. Updates package.json, marketplace.json, and plugin.json. Creates git tags and GitHub releases. Auto-generates CHANGELOG.md from releases.
--- ---
# Version Bump Skill # Version Bump Skill
@@ -9,11 +9,10 @@ Manage semantic versioning across the claude-mem project with consistent updates
## Quick Reference ## Quick Reference
**Files requiring updates (ALL FOUR):** **Files requiring updates (ALL THREE):**
1. `package.json` (line 3) 1. `package.json` (line 3)
2. `.claude-plugin/marketplace.json` (line 13) 2. `.claude-plugin/marketplace.json` (line 13)
3. `plugin/.claude-plugin/plugin.json` (line 3) 3. `plugin/.claude-plugin/plugin.json` (line 3)
4. `CLAUDE.md` (line 9 ONLY - version number, NOT version history)
**Semantic versioning:** **Semantic versioning:**
- **PATCH** (x.y.Z): Bugfixes only - **PATCH** (x.y.Z): Bugfixes only
@@ -37,7 +36,7 @@ See [operations/workflow.md](operations/workflow.md) for detailed step-by-step p
1. Determine version type (PATCH/MINOR/MAJOR) 1. Determine version type (PATCH/MINOR/MAJOR)
2. Calculate new version from current 2. Calculate new version from current
3. Preview changes to user 3. Preview changes to user
4. Update ALL FOUR files 4. Update ALL THREE files
5. Verify consistency 5. Verify consistency
6. Build and test 6. Build and test
7. Commit and create git tag 7. Commit and create git tag
@@ -54,29 +53,27 @@ See [operations/scenarios.md](operations/scenarios.md) for examples:
## Critical Rules ## Critical Rules
**ALWAYS:** **ALWAYS:**
- Update ALL FOUR files with matching version numbers - Update ALL THREE files with matching version numbers
- Create git tag with format `vX.Y.Z` - Create git tag with format `vX.Y.Z`
- Create GitHub release from the tag - Create GitHub release from the tag
- Generate CHANGELOG.md from releases after creating release - Generate CHANGELOG.md from releases after creating release
- Ask user if version type is unclear - Ask user if version type is unclear
**NEVER:** **NEVER:**
- Update only one, two, or three files - Update only one or two files
- Skip the verification step - Skip the verification step
- Forget to create git tag or GitHub release - Forget to create git tag or GitHub release
- Add version history entries to CLAUDE.md (that's managed separately)
## Verification Checklist ## Verification Checklist
Before considering the task complete: Before considering the task complete:
- [ ] All FOUR files have matching version numbers - [ ] All THREE files have matching version numbers
- [ ] `npm run build` succeeds - [ ] `npm run build` succeeds
- [ ] Git commit created with all version files - [ ] Git commit created with all version files
- [ ] Git tag created (format: vX.Y.Z) - [ ] Git tag created (format: vX.Y.Z)
- [ ] Commit and tags pushed to remote - [ ] Commit and tags pushed to remote
- [ ] GitHub release created from the tag - [ ] GitHub release created from the tag
- [ ] CHANGELOG.md generated and committed - [ ] CHANGELOG.md generated and committed
- [ ] CLAUDE.md: ONLY line 9 updated (version number), NOT version history
## Reference Commands ## Reference Commands
@@ -92,7 +89,7 @@ git tag -l -n1
# Check what will be committed # Check what will be committed
git status git status
git diff package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json CLAUDE.md git diff package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
``` ```
For more commands, see [operations/reference.md](operations/reference.md). For more commands, see [operations/reference.md](operations/reference.md).
.claude/skills/version-bump/operations/reference.md
+8 -18
View File
@@ -4,7 +4,7 @@ Quick reference for version bump commands and file locations.
## File Locations ## File Locations
### Version-Tracked Files (ALL FOUR) ### Version-Tracked Files (ALL THREE)
1. **package.json** 1. **package.json**
- Path: `package.json` - Path: `package.json`
@@ -21,11 +21,6 @@ Quick reference for version bump commands and file locations.
- Line: 3 - Line: 3
- Format: `"version": "X.Y.Z",` - Format: `"version": "X.Y.Z",`
4. **CLAUDE.md**
- Path: `CLAUDE.md`
- Line: 9
- Format: `**Current Version**: X.Y.Z`
## Essential Commands ## Essential Commands
### View Current Version ### View Current Version
@@ -39,7 +34,6 @@ grep '"version"' package.json | head -1 | sed 's/.*"version": "\(.*\)".*/\1/'
# From all version files # From all version files
grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
grep "Current Version" CLAUDE.md
``` ```
### Verify Version Consistency ### Verify Version Consistency
@@ -52,10 +46,6 @@ grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plu
# package.json:3: "version": "5.3.0", # package.json:3: "version": "5.3.0",
# .claude-plugin/marketplace.json:13: "version": "5.3.0", # .claude-plugin/marketplace.json:13: "version": "5.3.0",
# plugin/.claude-plugin/plugin.json:3: "version": "5.3.0", # plugin/.claude-plugin/plugin.json:3: "version": "5.3.0",
# Check CLAUDE.md
grep "Current Version" CLAUDE.md
# Should output: **Current Version**: 5.3.0
``` ```
### Git Commands ### Git Commands
@@ -96,7 +86,7 @@ npm test
```bash ```bash
# Stage version files # Stage version files
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json CLAUDE.md plugin/scripts/ git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
# Commit # Commit
git commit -m "Release vX.Y.Z: [Description]" git commit -m "Release vX.Y.Z: [Description]"
@@ -163,11 +153,11 @@ MAJOR: 5.3.2 → 6.0.0 (resets minor and patch)
```bash ```bash
# Example: 5.3.0 → 5.3.1 # Example: 5.3.0 → 5.3.1
# 1. Update all four files to 5.3.1 # 1. Update all three files to 5.3.1
# 2. Build and test # 2. Build and test
npm run build npm run build
# 3. Commit and tag # 3. Commit and tag
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json CLAUDE.md plugin/scripts/ git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
git commit -m "Release v5.3.1: Fixed observer crash" git commit -m "Release v5.3.1: Fixed observer crash"
git tag v5.3.1 -m "Release v5.3.1: Fixed observer crash" git tag v5.3.1 -m "Release v5.3.1: Fixed observer crash"
git push && git push --tags git push && git push --tags
@@ -179,11 +169,11 @@ gh release create v5.3.1 --title "v5.3.1" --notes "Fixed observer crash on empty
```bash ```bash
# Example: 5.3.0 → 5.4.0 # Example: 5.3.0 → 5.4.0
# 1. Update all four files to 5.4.0 # 1. Update all three files to 5.4.0
# 2. Build and test # 2. Build and test
npm run build npm run build
# 3. Commit and tag # 3. Commit and tag
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json CLAUDE.md plugin/scripts/ git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
git commit -m "Release v5.4.0: Added dark mode support" git commit -m "Release v5.4.0: Added dark mode support"
git tag v5.4.0 -m "Release v5.4.0: Added dark mode support" git tag v5.4.0 -m "Release v5.4.0: Added dark mode support"
git push && git push --tags git push && git push --tags
@@ -195,11 +185,11 @@ gh release create v5.4.0 --title "v5.4.0" --generate-notes
```bash ```bash
# Example: 5.3.0 → 6.0.0 # Example: 5.3.0 → 6.0.0
# 1. Update all four files to 6.0.0 # 1. Update all three files to 6.0.0
# 2. Build and test # 2. Build and test
npm run build npm run build
# 3. Commit and tag # 3. Commit and tag
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json CLAUDE.md plugin/scripts/ git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
git commit -m "Release v6.0.0: Storage layer redesign" git commit -m "Release v6.0.0: Storage layer redesign"
git tag v6.0.0 -m "Release v6.0.0: Storage layer redesign" git tag v6.0.0 -m "Release v6.0.0: Storage layer redesign"
git push && git push --tags git push && git push --tags
.claude/skills/version-bump/operations/scenarios.md
+5 -5
View File
@@ -19,7 +19,7 @@ Current: 4.2.8
New: 4.2.9 (PATCH) New: 4.2.9 (PATCH)
Steps: Steps:
1. Update all four files to 4.2.9 1. Update all three files to 4.2.9
2. npm run build 2. npm run build
3. git commit -m "Release v4.2.9: Fixed memory leak in search" 3. git commit -m "Release v4.2.9: Fixed memory leak in search"
4. git tag v4.2.9 -m "Release v4.2.9: Fixed memory leak in search" 4. git tag v4.2.9 -m "Release v4.2.9: Fixed memory leak in search"
@@ -44,7 +44,7 @@ Current: 4.2.8
New: 4.3.0 (MINOR - reset patch to 0) New: 4.3.0 (MINOR - reset patch to 0)
Steps: Steps:
1. Update all four files to 4.3.0 1. Update all three files to 4.3.0
2. npm run build 2. npm run build
3. git commit -m "Release v4.3.0: Added web search MCP integration" 3. git commit -m "Release v4.3.0: Added web search MCP integration"
4. git tag v4.3.0 -m "Release v4.3.0: Added web search MCP integration" 4. git tag v4.3.0 -m "Release v4.3.0: Added web search MCP integration"
@@ -69,7 +69,7 @@ Current: 4.2.8
New: 5.0.0 (MAJOR - reset minor and patch to 0) New: 5.0.0 (MAJOR - reset minor and patch to 0)
Steps: Steps:
1. Update all four files to 5.0.0 1. Update all three files to 5.0.0
2. npm run build 2. npm run build
3. git commit -m "Release v5.0.0: Storage layer redesign with migration required" 3. git commit -m "Release v5.0.0: Storage layer redesign with migration required"
4. git tag v5.0.0 -m "Release v5.0.0: Storage layer redesign" 4. git tag v5.0.0 -m "Release v5.0.0: Storage layer redesign"
@@ -94,7 +94,7 @@ Current: 4.2.8
New: 4.2.9 (PATCH) New: 4.2.9 (PATCH)
Steps: Steps:
1. Update all four files to 4.2.9 1. Update all three files to 4.2.9
2. npm run build 2. npm run build
3. git commit -m "Release v4.2.9: Multiple bug fixes 3. git commit -m "Release v4.2.9: Multiple bug fixes
@@ -122,7 +122,7 @@ Current: 5.1.0
New: 5.2.0 (MINOR) New: 5.2.0 (MINOR)
Steps: Steps:
1. Update all four files to 5.2.0 1. Update all three files to 5.2.0
2. npm run build 2. npm run build
3. git commit -m "Release v5.2.0: Dark mode support + bug fixes 3. git commit -m "Release v5.2.0: Dark mode support + bug fixes
.claude/skills/version-bump/operations/workflow.md
+1 -14
View File
@@ -64,7 +64,6 @@ Files to update:
- package.json: "version": "4.2.9" - package.json: "version": "4.2.9"
- marketplace.json: "version": "4.2.9" - marketplace.json: "version": "4.2.9"
- plugin.json: "version": "4.2.9" - plugin.json: "version": "4.2.9"
- CLAUDE.md line 9: "**Current Version**: 4.2.9" (version number ONLY)
- Git tag: v4.2.9 - Git tag: v4.2.9
Proceed? (yes/no) Proceed? (yes/no)
@@ -116,18 +115,6 @@ File: `plugin/.claude-plugin/plugin.json`
Update line 3 with new version. Update line 3 with new version.
### Update CLAUDE.md
File: `CLAUDE.md`
**ONLY update line 9 with the version number:**
```markdown
**Current Version**: 4.2.9
```
**CRITICAL:** DO NOT add version history entries to CLAUDE.md. Version history is managed separately outside this skill.
## Step 6: Verify Consistency ## Step 6: Verify Consistency
```bash ```bash
@@ -155,7 +142,7 @@ Build must succeed before proceeding.
```bash ```bash
# Stage all version files # Stage all version files
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json CLAUDE.md plugin/scripts/ git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
# Commit with descriptive message # Commit with descriptive message
git commit -m "Release vX.Y.Z: [Brief description] git commit -m "Release vX.Y.Z: [Brief description]
CLAUDE.md
+12 -36
View File
@@ -6,8 +6,6 @@
Claude-mem is a Claude Code plugin providing persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions. Claude-mem is a Claude Code plugin providing persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions.
**Current Version**: 7.2.1
## Architecture ## Architecture
**5 Lifecycle Hooks**: SessionStart → UserPromptSubmit → PostToolUse → Summary → SessionEnd **5 Lifecycle Hooks**: SessionStart → UserPromptSubmit → PostToolUse → Summary → SessionEnd
@@ -34,13 +32,16 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.
## Build Commands ## Build Commands
**Hooks only**: `npm run build && npm run sync-marketplace` ```bash
npm run build-and-sync # Build, sync to marketplace, restart worker (most common)
npm run build # Compile TypeScript only
npm run sync-marketplace # Copy to ~/.claude/plugins only
npm run worker:restart # Restart worker service only
npm run worker:status # Check worker status
npm run worker:logs # View worker logs
```
**Worker changes**: `npm run build && npm run sync-marketplace && npm run worker:restart` **Viewer UI**: http://localhost:37777
**Skills only**: `npm run sync-marketplace`
**Viewer UI**: `npm run build && npm run sync-marketplace && npm run worker:restart`
## Configuration ## Configuration
@@ -48,23 +49,13 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
**Core Settings:** **Core Settings:**
- `CLAUDE_MEM_MODEL` - Model for observations/summaries (default: claude-haiku-4-5) - `CLAUDE_MEM_MODEL` - Model for observations/summaries (default: claude-haiku-4-5)
- `CLAUDE_MEM_CONTEXT_OBSERVATIONS` - Observations injected at SessionStart (default: 50) - `CLAUDE_MEM_CONTEXT_OBSERVATIONS` - Observations injected at SessionStart
- `CLAUDE_MEM_WORKER_PORT` - Worker service port (default: 37777) - `CLAUDE_MEM_WORKER_PORT` - Worker service port (default: 37777)
- `CLAUDE_MEM_WORKER_HOST` - Worker bind address (default: 127.0.0.1, use 0.0.0.0 for remote access) - `CLAUDE_MEM_WORKER_HOST` - Worker bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)
**System Configuration:** **System Configuration:**
- `CLAUDE_MEM_DATA_DIR` - Data directory location (default: ~/.claude-mem) - `CLAUDE_MEM_DATA_DIR` - Data directory location (default: ~/.claude-mem)
- `CLAUDE_MEM_LOG_LEVEL` - Log verbosity: DEBUG, INFO, WARN, ERROR, SILENT (default: INFO) - `CLAUDE_MEM_LOG_LEVEL` - Log verbosity: DEBUG, INFO, WARN, ERROR, SILENT (default: INFO)
- `CLAUDE_MEM_PYTHON_VERSION` - Python version for uvx/chroma-mcp (default: 3.13, avoids onnxruntime compatibility issues with Python 3.14+)
- `CLAUDE_CODE_PATH` - Path to Claude executable (default: auto-detect via 'which claude')
**Settings File Format:**
```json
{
"CLAUDE_MEM_MODEL": "claude-haiku-4-5",
"CLAUDE_MEM_WORKER_PORT": "37777"
}
```
## File Locations ## File Locations
@@ -73,30 +64,15 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
- **Installed Plugin**: `~/.claude/plugins/marketplaces/thedotmack/` - **Installed Plugin**: `~/.claude/plugins/marketplaces/thedotmack/`
- **Database**: `~/.claude-mem/claude-mem.db` - **Database**: `~/.claude-mem/claude-mem.db`
- **Chroma**: `~/.claude-mem/chroma/` - **Chroma**: `~/.claude-mem/chroma/`
- **Usage Logs**: `~/.claude-mem/usage-logs/usage-YYYY-MM-DD.jsonl`
## Requirements ## Requirements
- **Bun** >= 1.0 (all platforms - auto-installed if missing) - **Bun** (all platforms - auto-installed if missing)
- **uv** (all platforms - auto-installed if missing, provides Python for Chroma) - **uv** (all platforms - auto-installed if missing, provides Python for Chroma)
- Node.js >= 18 (build tools only) - Node.js (build tools only)
## Quick Reference
```bash
npm run build # Compile TypeScript
npm run sync-marketplace # Copy to ~/.claude/plugins
npm run worker:restart # Restart worker service
npm run worker:status # Check worker status
npm run worker:logs # View worker logs
```
**Viewer UI**: http://localhost:37777
**Worker Logs**: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
## Documentation ## Documentation
**Public Docs**: https://docs.claude-mem.ai (Mintlify) **Public Docs**: https://docs.claude-mem.ai (Mintlify)
**Source**: `docs/public/` - MDX files, edit `docs.json` for navigation **Source**: `docs/public/` - MDX files, edit `docs.json` for navigation
**Deploy**: Auto-deploys from GitHub on push to main **Deploy**: Auto-deploys from GitHub on push to main
**Local Dev**: `cd docs/public && npx mintlify dev`
package.json
+1
View File
@@ -32,6 +32,7 @@
}, },
"scripts": { "scripts": {
"build": "node scripts/build-hooks.js", "build": "node scripts/build-hooks.js",
"build-and-sync": "npm run build && npm run sync-marketplace && sleep 1 && cd ~/.claude/plugins/marketplaces/thedotmack && npm run worker:restart",
"test": "vitest", "test": "vitest",
"test:parser": "npx tsx src/sdk/parser.test.ts", "test:parser": "npx tsx src/sdk/parser.test.ts",
"test:context": "echo '{\"session_id\":\"test-'$(date +%s)'\",\"cwd\":\"'$(pwd)'\",\"source\":\"startup\"}' | node plugin/scripts/context-hook.js 2>/dev/null", "test:context": "echo '{\"session_id\":\"test-'$(date +%s)'\",\"cwd\":\"'$(pwd)'\",\"source\":\"startup\"}' | node plugin/scripts/context-hook.js 2>/dev/null",
plugin/skills/mem-search/SKILL.md
+23 -29
View File
@@ -31,26 +31,22 @@ Use the `search` MCP tool:
**Required parameters:** **Required parameters:**
- `query` - Search term - `query` - Search term
- `format: "index"` - ALWAYS start with index (lightweight) - `limit: 20` - You can request large indexes as necessary
- `limit: 30` - You can request large indexes as necessary
- `project` - Project name (required) - `project` - Project name (required)
**Example:** **Example:**
``` ```
search(query="authentication", format="index", limit=30, project="my-project") search(query="authentication", limit=20, project="my-project")
``` ```
**Returns:** **Returns:**
``` ```
1. [feature] Added JWT authentication | ID | Time | T | Title | Read | Work |
Date: 11/17/2025, 3:48:45 PM |----|------|---|-------|------|------|
ID: 11131 | #11131 | 3:48 PM | 🟣 | Added JWT authentication | ~75 | 🛠️ 450 |
| #10942 | 2:15 PM | 🔴 | Fixed auth token expiration | ~50 | 🛠️ 200 |
2. [bugfix] Fixed auth token expiration
Date: 11/16/2025, 2:15:22 PM
ID: 10942
``` ```
### Step 2: Get Timeline Context ### Step 2: Get Timeline Context
@@ -141,8 +137,7 @@ get_prompt(id=5421)
**Basic:** **Basic:**
- `query` - What to search for (required) - `query` - What to search for (required)
- `format` - "index" (NEVER USE FULL) - `limit` - How many results (default 20)
- `limit` - How many results (default 30)
- `project` - Filter by project name (required) - `project` - Filter by project name (required)
**Filters (optional):** **Filters (optional):**
@@ -159,7 +154,7 @@ get_prompt(id=5421)
Use the `search` MCP tool with filters: Use the `search` MCP tool with filters:
``` ```
search(query="bug", type="observations", obs_type="bugfix", format="index", limit=30, project="my-project") search(query="bug", type="observations", obs_type="bugfix", limit=20, project="my-project")
``` ```
**Find what happened last week:** **Find what happened last week:**
@@ -167,7 +162,7 @@ search(query="bug", type="observations", obs_type="bugfix", format="index", limi
Use date filters: Use date filters:
``` ```
search(type="observations", dateStart="2025-11-11", format="index", limit=30, project="my-project") search(type="observations", dateStart="2025-11-11", limit=20, project="my-project")
``` ```
**Search everything:** **Search everything:**
@@ -175,37 +170,37 @@ search(type="observations", dateStart="2025-11-11", format="index", limit=30, pr
Simple query search: Simple query search:
``` ```
search(query="database migration", format="index", limit=30, project="my-project") search(query="database migration", limit=20, project="my-project")
``` ```
**Get detailed instructions:** **Get detailed instructions:**
Use the `progressive_ix` tool to load full instructions on-demand: Use the `progressive_description` tool to load full instructions on-demand:
``` ```
progressive_ix(topic="workflow") # Get 4-step workflow progressive_description(topic="workflow") # Get 4-step workflow
progressive_ix(topic="search_params") # Get parameters reference progressive_description(topic="search_params") # Get parameters reference
progressive_ix(topic="examples") # Get usage examples progressive_description(topic="examples") # Get usage examples
progressive_ix(topic="all") # Get complete guide progressive_description(topic="all") # Get complete guide
``` ```
## Why This Workflow? ## Why This Workflow?
**Massive performance gains:** **Token efficiency:**
- **Index format:** ~50-100 tokens per result - **Search results:** ~50-100 tokens per result (table index)
- **Full format:** ~500-1000 tokens per result - **Full observation:** ~500-1000 tokens each
- **10x token savings** - only fetch full when you know it's relevant - **10x savings** - only fetch full when you know it's relevant
**Batch fetching optimization:** **Batch fetching:**
- **Fetching 10 observations individually:** 10 HTTP requests, ~5-10s latency - **Individual fetches:** 10 HTTP requests, ~5-10s latency
- **Batch fetch:** 1 HTTP request, ~0.5-1s latency - **Batch fetch:** 1 HTTP request, ~0.5-1s latency
- **10-100x faster** for multi-observation queries - **10-100x faster** for multi-observation queries
**Clarity:** **Clarity:**
- See everything first (index) - See everything first (table index)
- Get timeline context around interesting results - Get timeline context around interesting results
- Pick what matters based on context - Pick what matters based on context
- Fetch details only for what you need (batch when possible) - Fetch details only for what you need (batch when possible)
@@ -214,7 +209,6 @@ progressive_ix(topic="all") # Get complete guide
**Remember:** **Remember:**
- ALWAYS search with `format="index"` first for token efficiency
- ALWAYS get timeline context to understand what was happening - ALWAYS get timeline context to understand what was happening
- ALWAYS use `get_batch_observations` when fetching 2+ observations - ALWAYS use `get_batch_observations` when fetching 2+ observations
- The workflow is optimized: index → timeline → batch fetch = 10-100x faster - The workflow is optimized: search → timeline → batch fetch = 10-100x faster
src/servers/mcp-server.ts
+13 -17
View File
@@ -32,7 +32,7 @@ const TOOL_ENDPOINT_MAP: Record<string, string> = {
'timeline': '/api/timeline', 'timeline': '/api/timeline',
'get_recent_context': '/api/context/recent', 'get_recent_context': '/api/context/recent',
'get_context_timeline': '/api/context/timeline', 'get_context_timeline': '/api/context/timeline',
'progressive_ix': '/api/instructions' 'progressive_description': '/api/instructions'
}; };
/** /**
@@ -182,15 +182,14 @@ async function verifyWorkerConnection(): Promise<boolean> {
/** /**
* Tool definitions with HTTP-based handlers * Tool definitions with HTTP-based handlers
* Descriptions removed - use progressive_ix tool for parameter documentation * Descriptions removed - use progressive_description tool for parameter documentation
*/ */
const tools = [ const tools = [
{ {
name: 'search', name: 'search',
description: 'Search observations, sessions, and prompts', description: 'Search memory',
inputSchema: z.object({ inputSchema: z.object({
query: z.string().optional(), query: z.string().optional(),
format: z.enum(['index', 'full']).default('index'),
type: z.enum(['observations', 'sessions', 'prompts']).optional(), type: z.enum(['observations', 'sessions', 'prompts']).optional(),
obs_type: z.string().optional(), obs_type: z.string().optional(),
concepts: z.string().optional(), concepts: z.string().optional(),
@@ -209,13 +208,12 @@ const tools = [
}, },
{ {
name: 'timeline', name: 'timeline',
description: 'Get timeline around observation ID or query', description: 'Timeline context',
inputSchema: z.object({ inputSchema: z.object({
query: z.string().optional(), query: z.string().optional(),
anchor: z.number().optional(), anchor: z.number().optional(),
depth_before: z.number().min(0).max(100).default(10), depth_before: z.number().min(0).max(100).default(10),
depth_after: z.number().min(0).max(100).default(10), depth_after: z.number().min(0).max(100).default(10),
format: z.enum(['index', 'full']).default('index'),
type: z.string().optional(), type: z.string().optional(),
concepts: z.string().optional(), concepts: z.string().optional(),
files: z.string().optional(), files: z.string().optional(),
@@ -228,10 +226,9 @@ const tools = [
}, },
{ {
name: 'get_recent_context', name: 'get_recent_context',
description: 'Get recent timeline items', description: 'Recent context',
inputSchema: z.object({ inputSchema: z.object({
limit: z.number().min(1).max(100).default(30), limit: z.number().min(1).max(100).default(30),
format: z.enum(['index', 'full']).default('index'),
type: z.string().optional(), type: z.string().optional(),
concepts: z.string().optional(), concepts: z.string().optional(),
files: z.string().optional(), files: z.string().optional(),
@@ -246,12 +243,11 @@ const tools = [
}, },
{ {
name: 'get_context_timeline', name: 'get_context_timeline',
description: 'Get timeline around specific observation', description: 'Timeline around ID',
inputSchema: z.object({ inputSchema: z.object({
anchor: z.number(), anchor: z.number(),
depth_before: z.number().min(0).max(100).default(10), depth_before: z.number().min(0).max(100).default(10),
depth_after: z.number().min(0).max(100).default(10), depth_after: z.number().min(0).max(100).default(10),
format: z.enum(['index', 'full']).default('index'),
type: z.string().optional(), type: z.string().optional(),
concepts: z.string().optional(), concepts: z.string().optional(),
files: z.string().optional(), files: z.string().optional(),
@@ -263,19 +259,19 @@ const tools = [
} }
}, },
{ {
name: 'progressive_ix', name: 'progressive_description',
description: 'Load parameter docs and usage instructions', description: 'Usage help',
inputSchema: z.object({ inputSchema: z.object({
topic: z.enum(['workflow', 'search_params', 'examples', 'all']).default('all') topic: z.enum(['workflow', 'search_params', 'examples', 'all']).default('all')
}), }),
handler: async (args: any) => { handler: async (args: any) => {
const endpoint = TOOL_ENDPOINT_MAP['progressive_ix']; const endpoint = TOOL_ENDPOINT_MAP['progressive_description'];
return await callWorkerAPI(endpoint, args); return await callWorkerAPI(endpoint, args);
} }
}, },
{ {
name: 'get_observation', name: 'get_observation',
description: 'Get observation by ID', description: 'Fetch by ID',
inputSchema: z.object({ inputSchema: z.object({
id: z.number() id: z.number()
}), }),
@@ -285,7 +281,7 @@ const tools = [
}, },
{ {
name: 'get_batch_observations', name: 'get_batch_observations',
description: 'Get multiple observations by IDs', description: 'Batch fetch',
inputSchema: z.object({ inputSchema: z.object({
ids: z.array(z.number()), ids: z.array(z.number()),
orderBy: z.enum(['date_desc', 'date_asc']).optional(), orderBy: z.enum(['date_desc', 'date_asc']).optional(),
@@ -298,7 +294,7 @@ const tools = [
}, },
{ {
name: 'get_session', name: 'get_session',
description: 'Get session summary by ID', description: 'Session by ID',
inputSchema: z.object({ inputSchema: z.object({
id: z.number() id: z.number()
}), }),
@@ -308,7 +304,7 @@ const tools = [
}, },
{ {
name: 'get_prompt', name: 'get_prompt',
description: 'Get user prompt by ID', description: 'Prompt by ID',
inputSchema: z.object({ inputSchema: z.object({
id: z.number() id: z.number()
}), }),
src/services/worker/http/routes/SearchRoutes.ts
+11 -17
View File
@@ -45,7 +45,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Unified search (observations + sessions + prompts) * Unified search (observations + sessions + prompts)
* GET /api/search?query=...&type=observations&format=index&limit=20 * GET /api/search?query=...&type=observations&limit=20
*/ */
private handleUnifiedSearch = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleUnifiedSearch = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.search(req.query); const result = await this.searchManager.search(req.query);
@@ -63,7 +63,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Semantic shortcut for finding decision observations * Semantic shortcut for finding decision observations
* GET /api/decisions?format=index&limit=20 * GET /api/decisions?limit=20
*/ */
private handleDecisions = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleDecisions = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.decisions(req.query); const result = await this.searchManager.decisions(req.query);
@@ -72,7 +72,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Semantic shortcut for finding change-related observations * Semantic shortcut for finding change-related observations
* GET /api/changes?format=index&limit=20 * GET /api/changes?limit=20
*/ */
private handleChanges = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleChanges = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.changes(req.query); const result = await this.searchManager.changes(req.query);
@@ -81,7 +81,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Semantic shortcut for finding "how it works" explanations * Semantic shortcut for finding "how it works" explanations
* GET /api/how-it-works?format=index&limit=20 * GET /api/how-it-works?limit=20
*/ */
private handleHowItWorks = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleHowItWorks = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.howItWorks(req.query); const result = await this.searchManager.howItWorks(req.query);
@@ -90,7 +90,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Search observations (use /api/search?type=observations instead) * Search observations (use /api/search?type=observations instead)
* GET /api/search/observations?query=...&format=index&limit=20&project=... * GET /api/search/observations?query=...&limit=20&project=...
*/ */
private handleSearchObservations = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleSearchObservations = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.searchObservations(req.query); const result = await this.searchManager.searchObservations(req.query);
@@ -99,7 +99,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Search session summaries * Search session summaries
* GET /api/search/sessions?query=...&format=index&limit=20 * GET /api/search/sessions?query=...&limit=20
*/ */
private handleSearchSessions = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleSearchSessions = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.searchSessions(req.query); const result = await this.searchManager.searchSessions(req.query);
@@ -108,7 +108,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Search user prompts * Search user prompts
* GET /api/search/prompts?query=...&format=index&limit=20 * GET /api/search/prompts?query=...&limit=20
*/ */
private handleSearchPrompts = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleSearchPrompts = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.searchUserPrompts(req.query); const result = await this.searchManager.searchUserPrompts(req.query);
@@ -117,7 +117,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Search observations by concept * Search observations by concept
* GET /api/search/by-concept?concept=discovery&format=index&limit=5 * GET /api/search/by-concept?concept=discovery&limit=5
*/ */
private handleSearchByConcept = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleSearchByConcept = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.findByConcept(req.query); const result = await this.searchManager.findByConcept(req.query);
@@ -126,7 +126,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Search by file path * Search by file path
* GET /api/search/by-file?filePath=...&format=index&limit=10 * GET /api/search/by-file?filePath=...&limit=10
*/ */
private handleSearchByFile = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleSearchByFile = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.findByFile(req.query); const result = await this.searchManager.findByFile(req.query);
@@ -135,7 +135,7 @@ export class SearchRoutes extends BaseRouteHandler {
/** /**
* Search observations by type * Search observations by type
* GET /api/search/by-type?type=bugfix&format=index&limit=10 * GET /api/search/by-type?type=bugfix&limit=10
*/ */
private handleSearchByType = this.wrapHandler(async (req: Request, res: Response): Promise<void> => { private handleSearchByType = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
const result = await this.searchManager.findByType(req.query); const result = await this.searchManager.findByType(req.query);
@@ -252,7 +252,6 @@ export class SearchRoutes extends BaseRouteHandler {
description: 'Search observations using full-text search', description: 'Search observations using full-text search',
parameters: { parameters: {
query: 'Search query (required)', query: 'Search query (required)',
format: 'Response format: "index" or "full" (default: "full")',
limit: 'Number of results (default: 20)', limit: 'Number of results (default: 20)',
project: 'Filter by project name (optional)' project: 'Filter by project name (optional)'
} }
@@ -263,7 +262,6 @@ export class SearchRoutes extends BaseRouteHandler {
description: 'Search session summaries using full-text search', description: 'Search session summaries using full-text search',
parameters: { parameters: {
query: 'Search query (required)', query: 'Search query (required)',
format: 'Response format: "index" or "full" (default: "full")',
limit: 'Number of results (default: 20)' limit: 'Number of results (default: 20)'
} }
}, },
@@ -273,7 +271,6 @@ export class SearchRoutes extends BaseRouteHandler {
description: 'Search user prompts using full-text search', description: 'Search user prompts using full-text search',
parameters: { parameters: {
query: 'Search query (required)', query: 'Search query (required)',
format: 'Response format: "index" or "full" (default: "full")',
limit: 'Number of results (default: 20)', limit: 'Number of results (default: 20)',
project: 'Filter by project name (optional)' project: 'Filter by project name (optional)'
} }
@@ -284,7 +281,6 @@ export class SearchRoutes extends BaseRouteHandler {
description: 'Find observations by concept tag', description: 'Find observations by concept tag',
parameters: { parameters: {
concept: 'Concept tag (required): discovery, decision, bugfix, feature, refactor', concept: 'Concept tag (required): discovery, decision, bugfix, feature, refactor',
format: 'Response format: "index" or "full" (default: "full")',
limit: 'Number of results (default: 10)', limit: 'Number of results (default: 10)',
project: 'Filter by project name (optional)' project: 'Filter by project name (optional)'
} }
@@ -295,7 +291,6 @@ export class SearchRoutes extends BaseRouteHandler {
description: 'Find observations and sessions by file path', description: 'Find observations and sessions by file path',
parameters: { parameters: {
filePath: 'File path or partial path (required)', filePath: 'File path or partial path (required)',
format: 'Response format: "index" or "full" (default: "full")',
limit: 'Number of results per type (default: 10)', limit: 'Number of results per type (default: 10)',
project: 'Filter by project name (optional)' project: 'Filter by project name (optional)'
} }
@@ -306,7 +301,6 @@ export class SearchRoutes extends BaseRouteHandler {
description: 'Find observations by type', description: 'Find observations by type',
parameters: { parameters: {
type: 'Observation type (required): discovery, decision, bugfix, feature, refactor', type: 'Observation type (required): discovery, decision, bugfix, feature, refactor',
format: 'Response format: "index" or "full" (default: "full")',
limit: 'Number of results (default: 10)', limit: 'Number of results (default: 10)',
project: 'Filter by project name (optional)' project: 'Filter by project name (optional)'
} }
@@ -350,7 +344,7 @@ export class SearchRoutes extends BaseRouteHandler {
} }
], ],
examples: [ examples: [
'curl "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5"', 'curl "http://localhost:37777/api/search/observations?query=authentication&limit=5"',
'curl "http://localhost:37777/api/search/by-type?type=bugfix&limit=10"', 'curl "http://localhost:37777/api/search/by-type?type=bugfix&limit=10"',
'curl "http://localhost:37777/api/context/recent?project=claude-mem&limit=3"', 'curl "http://localhost:37777/api/context/recent?project=claude-mem&limit=3"',
'curl "http://localhost:37777/api/context/timeline?anchor=123&depth_before=5&depth_after=5"' 'curl "http://localhost:37777/api/context/timeline?anchor=123&depth_before=5&depth_after=5"'