specmem-hardwicksoftware 3.5.99

package/commands/specmem-drilldown.md

@@ -0,0 +1,208 @@
+# SpecMem Drilldown - Interactive Memory Retrieval with User Control
+
+## IMMEDIATE ACTION REQUIRED
+
+**Step 1: Check Input**
+Look at what comes after `/specmem-drilldown`:
+
+- If EMPTY, whitespace only, "help", "--help", or "-h" -> Show HELP below, STOP
+- If input is a NUMERIC ID (e.g., `123`, `456`) -> Go to Step 2A
+- If input is a UUID (e.g., `abc12345-...`) -> Go to Step 2C
+- Otherwise (text query) -> Go to Step 2B
+
+---
+
+## Step 2A: Drilldown by Numeric ID
+
+When input is a numeric ID like `/specmem-drilldown 123`:
+
+**VALIDATION:**
+- Check that input is a valid integer
+- If invalid (NaN, negative, etc.) -> Show HELP, STOP
+
+**EXECUTE THIS MCP TOOL NOW:**
+
+```
+mcp__specmem__drill_down({
+  drilldownID: <the numeric ID as integer>,
+  includeCode: true,
+  includeContext: true,
+  includeRelated: true,
+  relatedLimit: 5,
+  compress: true
+})
+```
+
+**Display results as:**
+```
+DRILLDOWN: Memory #<ID>
+
+Content:
+<full memory content from result.fullContent>
+
+Paired Message:
+<if pairedMessage exists, show result.pairedMessage.label and content>
+<This shows the user prompt that triggered a Claude response, or vice versa>
+
+Code References:
+<code pointers from result.codeReferences if any>
+
+Conversation Context:
+<context before/after from result.conversationContext>
+
+Related Memories:
+1. [Drill: xxx] <preview>... (similarity: 0.XX)
+2. [Drill: yyy] <preview>... (similarity: 0.XX)
+...
+
+Use /specmem-drilldown <ID> to explore related memories
+```
+
+---
+
+## Step 2B: Search then Drilldown
+
+When input is a query like `/specmem-drilldown authentication flow`:
+
+**VALIDATION:**
+- Check that query is not empty after trimming
+- If empty -> Show HELP, STOP
+
+**EXECUTE THIS MCP TOOL NOW:**
+
+```
+mcp__specmem__find_memory({
+  query: "<the query text>",
+  limit: 10,
+  cameraRollMode: true,
+  summarize: true,
+  maxContentLength: 300
+})
+```
+
+**Display results with drilldown IDs:**
+```
+MEMORIES FOR: "<query>"
+
+1. [Drill: 123] <preview text>... (score: 0.XX)
+2. [Drill: 456] <preview text>... (score: 0.XX)
+3. [Drill: 789] <preview text>... (score: 0.XX)
+...
+
+To explore deeper: /specmem-drilldown <ID>
+```
+
+---
+
+## Step 2C: Get Full Memory by UUID
+
+When input is a UUID like `/specmem-drilldown abc12345-6789-...`:
+
+**VALIDATION:**
+- Check that input looks like a UUID (contains dashes, hex chars)
+- If invalid -> Show HELP, STOP
+
+**EXECUTE THIS MCP TOOL NOW:**
+
+```
+mcp__specmem__get_memory({
+  id: "<the UUID string>",
+  summarize: false
+})
+```
+
+**Display the full memory content.**
+
+---
+
+## HELP
+
+Show this when no args, empty input, "help", or validation fails:
+
+```
+SpecMem Drilldown - Memory Exploration
+
+USAGE:
+  /specmem-drilldown <query>       Search and get drilldown IDs
+  /specmem-drilldown <ID>          Drill into specific memory by ID
+  /specmem-drilldown <UUID>        Get memory by UUID
+  /specmem-drilldown help          Show this help
+
+EXAMPLES:
+  /specmem-drilldown authentication system
+  /specmem-drilldown 123
+  /specmem-drilldown database schema design
+
+CAMERA ROLL WORKFLOW:
+  1. Search with a query -> get drilldown IDs in "camera roll" view
+  2. Pick an ID -> drill into full content with drill_down
+  3. Explore related memories -> repeat drilling
+  4. View paired messages to see user prompts ↔ Claude responses
+
+WHAT YOU GET:
+  - Full memory content (not truncated, with compression for efficiency)
+  - Paired message (the user prompt or Claude response that pairs with this)
+  - Code references with live file content
+  - Conversation context (before/after messages in conversation)
+  - Related memories for further exploration
+
+MCP TOOLS USED:
+  - mcp__specmem__drill_down (by numeric ID)
+  - mcp__specmem__find_memory (query search)
+  - mcp__specmem__get_memory (by UUID)
+
+RELATED:
+  /specmem-find      Basic memory search
+  /specmem-pointers  Code-focused search
+```
+
+---
+
+## Tool Schemas
+
+### drill_down
+```json
+{
+  "drilldownID": "number - required - numeric ID from camera roll results",
+  "includeCode": "boolean - include code references (default: true)",
+  "includeContext": "boolean - include conversation context (default: true)",
+  "includeRelated": "boolean - include related memories (default: true)",
+  "relatedLimit": "number 1-20 - max related memories (default: 5)",
+  "compress": "boolean - apply Traditional Chinese token compression (default: true)"
+}
+```
+
+**NOTES:**
+- `compress: true` uses round-trip verified compression for token efficiency
+- Compression keeps English where Chinese would lose context
+- Returns `pairedMessage` showing user prompt ↔ Claude response pairing
+
+### find_memory
+```json
+{
+  "query": "string - natural language search query",
+  "limit": "number 1-1000 - results count (default: 10)",
+  "cameraRollMode": "boolean - enable drilldown IDs (set true)",
+  "summarize": "boolean - truncate content (default: true)",
+  "maxContentLength": "number - content preview length (default: 500)"
+}
+```
+
+### get_memory
+```json
+{
+  "id": "string - UUID of specific memory",
+  "summarize": "boolean - truncate content (default: false for drill-down)"
+}
+```
+
+### get_memory_by_id
+```json
+{
+  "drilldownID": "number - numeric ID from camera roll results"
+}
+```
+
+**NOTES:**
+- Simpler than `drill_down` - just returns content without exploration options
+- Returns `{ content: string, memoryID: string }` or `null` if not found

package/commands/specmem-find.md

@@ -0,0 +1,195 @@
+# SpecMem Find
+Semantic memory search - finds memories by meaning, not just keywords.
+
+## Tool Mapping
+This command executes: `mcp__specmem__find_memory`
+
+## EXECUTION INSTRUCTIONS
+
+**STEP 1: Check arguments**
+```
+IF args is empty OR args equals "help" OR args equals "--help":
+    OUTPUT the Help Output section below
+    STOP - do not call any tools
+```
+
+**STEP 2: Parse the input**
+```
+1. Extract flags:
+   --limit N           Results count (1-1000, default: 10)
+   --threshold N       Similarity score 0-1 (default: 0.25)
+   --type TYPE         Memory type filter (episodic, semantic, procedural, working, consolidated)
+   --tags TAGS         Tag filter (comma-separated)
+   --importance IMP    Importance filter (critical, high, medium, low, trivial)
+   --after DATE        After date ("yesterday", "last week", "2024-01-15")
+   --before DATE       Before date
+   --recent N          Force include N recent memories (0-50)
+   --no-recency-boost  Disable recency boost
+   --no-keyword        Disable keyword fallback
+   --role ROLE         Filter by role (user, assistant)
+   --full              Return full content (no summarization)
+   --max-length N      Max content length in chars (default: 500, 0 = no limit)
+   --gallery           Enable gallery mode with Mini COT analysis
+   --camera-roll       Enable camera roll format with drilldownIDs
+   --zoom LEVEL        Zoom level: ultra-wide, wide, normal, close, macro
+   --project PATH      Search specific project path
+   --all-projects      Search ALL projects (cross-project search)
+
+2. Everything remaining after flags is the QUERY
+3. IF query is empty after parsing:
+    OUTPUT the Error Output section below
+    STOP - do not call any tools
+```
+
+**STEP 3: Execute MCP tool (REQUIRED - must actually call this)**
+```
+mcp__specmem__find_memory({
+  query: "<the extracted query string>",
+  limit: <--limit value or default 10>,
+  threshold: <--threshold value or default 0.25>,
+  memoryTypes: <array with --type value if provided, otherwise omit>,
+  tags: <array from --tags split by comma if provided, otherwise omit>,
+  importance: <array from --importance split by comma if provided, otherwise omit>,
+  dateRange: <object with start/end if --after/--before provided, otherwise omit>,
+  includeRecent: <--recent value or default 0>,
+  recencyBoost: <true unless --no-recency-boost specified>,
+  keywordFallback: <true unless --no-keyword specified>,
+  role: <--role value if provided, otherwise omit>,
+  summarize: <false if --full specified, otherwise true>,
+  maxContentLength: <--max-length value or default 500>,
+  galleryMode: <true if --gallery specified, otherwise false>,
+  cameraRollMode: <true if --camera-roll specified, otherwise false>,
+  zoomLevel: <--zoom value if provided, otherwise omit>,
+  projectPath: <--project value if provided, otherwise omit>,
+  allProjects: <true if --all-projects specified, otherwise false>
+})
+```
+
+**STEP 4: Display results**
+Format the tool response for the user, showing matching memories with their content and relevance scores.
+
+---
+
+## Usage
+```
+/specmem-find <query>           # REQUIRED: query cannot be empty
+/specmem-find --limit 5 <query>
+/specmem-find --type procedural <query>
+/specmem-find --recent 10 <query>
+/specmem-find --camera-roll --zoom wide <query>
+/specmem-find --all-projects <query>
+```
+
+## Help Output
+(shown when no args or "help")
+
+```
+SpecMem Find - Semantic Memory Search
+
+USAGE:
+  /specmem-find <query>
+  /specmem-find [options] <query>
+
+SEARCH OPTIONS:
+  --limit N           Results count (1-1000, default: 10)
+  --threshold N       Similarity 0-1 (default: 0.25, lower = more results)
+  --recent N          Force include N recent memories (0-50)
+  --no-recency-boost  Disable automatic recency boost
+  --no-keyword        Disable keyword fallback search
+
+FILTER OPTIONS:
+  --type TYPE         Memory type: episodic, semantic, procedural, working, consolidated
+  --tags TAGS         Filter by tags (comma-separated)
+  --importance IMP    Filter by importance: critical, high, medium, low, trivial
+  --role ROLE         Filter by role: user (your messages), assistant (Claude)
+  --after DATE        After date ("yesterday", "last week", "2024-01-15")
+  --before DATE       Before date
+
+OUTPUT OPTIONS:
+  --full              Return full content (no truncation)
+  --max-length N      Max content length in chars (default: 500, 0 = unlimited)
+  --gallery           Enable gallery mode with Mini COT analysis
+  --camera-roll       Enable camera roll format with drilldownIDs
+  --zoom LEVEL        Zoom: ultra-wide (50), wide (25), normal (15), close (10), macro (5)
+
+PROJECT OPTIONS:
+  --project PATH      Search specific project path
+  --all-projects      Search ALL projects (cross-project search)
+
+EXAMPLES:
+  /specmem-find authentication flow
+  /specmem-find --limit 5 database schema
+  /specmem-find --type procedural deployment steps
+  /specmem-find --tags api,auth token handling
+  /specmem-find --after yesterday recent decisions
+  /specmem-find --recent 10 what did we discuss
+  /specmem-find --role user what I asked about
+  /specmem-find --camera-roll --zoom wide project architecture
+  /specmem-find --all-projects similar patterns
+
+SEMANTIC SEARCH:
+  Uses vector embeddings for meaning-based search.
+  "auth tokens" finds memories about "JWT cookies" even
+  if those exact words weren't used.
+
+CAMERA ROLL MODE:
+  Returns compact results with drilldownIDs for exploration.
+  Use /specmem-drilldown <ID> to get full details.
+
+ZOOM LEVELS:
+  ultra-wide: 50 results, 15% threshold (broad overview)
+  wide:       25 results, 25% threshold (balanced)
+  normal:     15 results, 40% threshold (focused)
+  close:      10 results, 60% threshold (precise)
+  macro:       5 results, 80% threshold (exact matches)
+
+RELATED COMMANDS:
+  /specmem-remember   Store new memories
+  /specmem-drilldown  Deep dive into a memory
+  /specmem-stats      View memory statistics
+```
+
+## Tool Schema
+```json
+{
+  "query": "string - natural language search query (not required, empty shows help)",
+  "limit": "number 1-1000 - results count (default: 10)",
+  "threshold": "number 0-1 - min similarity (default: 0.25)",
+  "includeRecent": "number 0-50 - force include N recent memories (default: 0)",
+  "recencyBoost": "boolean - boost recent memories (default: true)",
+  "keywordFallback": "boolean - fallback to keyword search if no results (default: true)",
+  "memoryTypes": ["episodic", "semantic", "procedural", "working", "consolidated"],
+  "tags": ["array", "of", "filter", "tags"],
+  "importance": ["critical", "high", "medium", "low", "trivial"],
+  "dateRange": {
+    "start": "ISO date string",
+    "end": "ISO date string"
+  },
+  "includeExpired": "boolean - include expired memories (default: false)",
+  "role": "string - user or assistant filter",
+  "summarize": "boolean - truncate content (default: true)",
+  "maxContentLength": "number - max content chars (default: 500, 0 = unlimited)",
+  "galleryMode": "boolean or 'ask' - Mini COT analysis (default: false)",
+  "cameraRollMode": "boolean - camera roll format with drilldownIDs (default: false)",
+  "zoomLevel": "string - ultra-wide, wide, normal, close, macro",
+  "projectPath": "string - search specific project path",
+  "allProjects": "boolean - search ALL projects (default: false)"
+}
+```
+
+## Error Output
+(shown for invalid input)
+
+```
+Error: No search query provided
+
+USAGE: /specmem-find <query>
+
+Examples:
+  /specmem-find authentication system
+  /specmem-find --limit 5 database schema
+  /specmem-find --type procedural how to deploy
+  /specmem-find --recent 10 recent discussions
+
+Run /specmem-find help for full options.
+```

package/commands/specmem-getdashboard.md

@@ -0,0 +1,243 @@
+# SpecMem Get Dashboard - Dashboard Location & Port Information
+
+Shows dashboard URL, port, and access mode.
+
+## COMMAND PARSING
+
+```javascript
+const args = "$ARGUMENTS".trim();
+
+if (args === "help" || args === "--help" || args === "-h") {
+  // Show HELP OUTPUT below
+  return;
+}
+
+// If NO args or any other input → Execute GET DASHBOARD INFO
+```
+
+---
+
+## INPUT VALIDATION
+
+```javascript
+const args = "$ARGUMENTS".trim();
+
+if (args === "help" || args === "--help" || args === "-h") {
+  // Show HELP OUTPUT below
+  return;
+}
+
+// Otherwise, execute immediately (no args required)
+```
+
+---
+
+## HELP OUTPUT
+
+```
+SpecMem Get Dashboard - Show Dashboard Location
+
+USAGE:
+  /specmem-getdashboard         Show dashboard information
+  /specmem-getdashboard help    Show this help
+
+WHAT IT SHOWS:
+  - Dashboard host and port
+  - Full URL to access dashboard
+  - Access mode (public/private)
+  - Quick links to dashboard pages
+
+CONFIGURATION:
+  Port from:     .specmem/ports.json
+  Mode via:      SPECMEM_DASHBOARD_MODE env var
+
+  Modes:
+    private (default):   127.0.0.1, localhost only
+    public:              0.0.0.0, network accessible
+
+RELATED:
+  /specmem-stats      View statistics
+  /specmem-service    Service management
+
+NOTE: This command does NOT use MCP tools.
+      It reads configuration files using Bash.
+```
+
+---
+
+## GET DASHBOARD INFO
+
+Execute immediately when no args or just the command.
+
+### Step 1: Read Configuration
+
+Use Bash to read ports.json:
+
+```bash
+if [ -f .specmem/ports.json ]; then
+  cat .specmem/ports.json
+else
+  echo '{"ports":{"dashboard":9294}}'
+fi
+```
+
+### Step 2: Determine Values
+
+Parse the JSON output to extract:
+- **Port**: From `ports.json` → `ports.dashboard` field (default: 9294)
+- **Mode**: From `$SPECMEM_DASHBOARD_MODE` env var (default: private)
+- **Host**:
+  - If mode is 'private': 127.0.0.1
+  - If mode is 'public': 0.0.0.0
+
+### Step 3: Output Dashboard Info
+
+Format and display:
+
+```
+SpecMem Dashboard Information
+
+  Host:   [host] ([mode])
+  Port:   [port]
+  URL:    http://[host]:[port]
+  Mode:   [mode]
+  Access: [Localhost only / Network accessible]
+
+Configuration Sources:
+  Port from:    .specmem/ports.json
+  Mode from:    SPECMEM_DASHBOARD_MODE=[value or "default: private"]
+
+Quick Links:
+  Main Dashboard:    http://[host]:[port]/dashboard-v2.html
+  Prompt Console:    http://[host]:[port]/prompt-console.html
+  Data Export:       http://[host]:[port]/data-export.html
+```
+
+### Example Output (Private Mode)
+
+```
+SpecMem Dashboard Information
+
+  Host:   127.0.0.1 (private)
+  Port:   9294
+  URL:    http://127.0.0.1:9294
+  Mode:   private
+  Access: Localhost only
+
+Configuration Sources:
+  Port from:    .specmem/ports.json
+  Mode from:    SPECMEM_DASHBOARD_MODE (default: private)
+
+Quick Links:
+  Main Dashboard:    http://127.0.0.1:9294/dashboard-v2.html
+  Prompt Console:    http://127.0.0.1:9294/prompt-console.html
+  Data Export:       http://127.0.0.1:9294/data-export.html
+```
+
+### Example Output (Public Mode)
+
+```
+SpecMem Dashboard Information
+
+  Host:   0.0.0.0 (public)
+  Port:   9294
+  URL:    http://0.0.0.0:9294
+  Mode:   public
+  Access: Network accessible (WARNING: Open to network!)
+
+Configuration Sources:
+  Port from:    .specmem/ports.json
+  Mode from:    SPECMEM_DASHBOARD_MODE=public
+
+Quick Links:
+  Main Dashboard:    http://0.0.0.0:9294/dashboard-v2.html
+  Prompt Console:    http://0.0.0.0:9294/prompt-console.html
+  Data Export:       http://0.0.0.0:9294/data-export.html
+
+WARNING: Public mode exposes dashboard to your network.
+         Only use on trusted networks.
+```
+
+---
+
+## IMPLEMENTATION APPROACH
+
+Use Bash commands to:
+
+1. Read `.specmem/ports.json` to get dashboard port
+2. Check `$SPECMEM_DASHBOARD_MODE` environment variable
+3. Format and display the output
+
+Example implementation:
+
+```bash
+# Read port from JSON
+PORT=$(cat .specmem/ports.json 2>/dev/null | grep -o '"dashboard":[0-9]*' | cut -d: -f2)
+PORT=${PORT:-9294}
+
+# Get mode from environment
+MODE=${SPECMEM_DASHBOARD_MODE:-private}
+
+# Determine host based on mode
+if [ "$MODE" = "public" ]; then
+  HOST="0.0.0.0"
+  ACCESS="Network accessible (WARNING: Open to network!)"
+  WARNING="\nWARNING: Public mode exposes dashboard to your network.\n         Only use on trusted networks."
+else
+  HOST="127.0.0.1"
+  ACCESS="Localhost only"
+  WARNING=""
+fi
+
+# Display formatted output
+echo "SpecMem Dashboard Information"
+echo ""
+echo "  Host:   $HOST ($MODE)"
+echo "  Port:   $PORT"
+echo "  URL:    http://$HOST:$PORT"
+echo "  Mode:   $MODE"
+echo "  Access: $ACCESS"
+echo ""
+echo "Configuration Sources:"
+echo "  Port from:    .specmem/ports.json"
+if [ -n "$SPECMEM_DASHBOARD_MODE" ]; then
+  echo "  Mode from:    SPECMEM_DASHBOARD_MODE=$SPECMEM_DASHBOARD_MODE"
+else
+  echo "  Mode from:    SPECMEM_DASHBOARD_MODE (default: private)"
+fi
+echo ""
+echo "Quick Links:"
+echo "  Main Dashboard:    http://$HOST:$PORT/dashboard-v2.html"
+echo "  Prompt Console:    http://$HOST:$PORT/prompt-console.html"
+echo "  Data Export:       http://$HOST:$PORT/data-export.html"
+if [ -n "$WARNING" ]; then
+  echo "$WARNING"
+fi
+```
+
+---
+
+## MCP TOOLS USED
+
+**NONE** - This command uses Bash exclusively for reading configuration files.
+
+---
+
+## RELATED COMMANDS
+
+- `/specmem-stats` - View system statistics including dashboard status
+- `/specmem-service` - Manage SpecMem service (start/stop/restart)
+
+---
+
+## EXAMPLES
+
+### Show dashboard info
+```
+/specmem-getdashboard
+```
+
+### Show help
+```
+/specmem-getdashboard help
+```