@stackmemoryai/stackmemory 0.3.17 → 0.3.19

package/scripts/setup-claude-integration.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+
+# StackMemory Claude Integration Setup Script
+# Automatically configures Claude Desktop to use StackMemory MCP server
+
+set -e
+
+echo "🚀 Setting up StackMemory integration with Claude Desktop..."
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Claude Desktop config path (macOS)
+CLAUDE_CONFIG_DIR="$HOME/Library/Application Support/Claude"
+CLAUDE_CONFIG_FILE="$CLAUDE_CONFIG_DIR/claude_desktop_config.json"
+
+# Check if running on macOS
+if [[ "$OSTYPE" != "darwin"* ]]; then
+    echo -e "${RED}This script currently only supports macOS.${NC}"
+    echo "For other platforms, manually add the configuration to your Claude Desktop config."
+    exit 1
+fi
+
+# Build the project first
+echo "📦 Building StackMemory..."
+cd "$PROJECT_ROOT"
+npm run build
+
+# Create Claude config directory if it doesn't exist
+mkdir -p "$CLAUDE_CONFIG_DIR"
+
+# Function to merge MCP server config
+merge_mcp_config() {
+    local mcp_config='{
+      "stackmemory": {
+        "command": "node",
+        "args": ["'$PROJECT_ROOT'/dist/mcp/stackmemory-mcp-server.js"],
+        "env": {
+          "STACKMEMORY_PROJECT": "'$PROJECT_ROOT'"
+        }
+      }
+    }'
+    
+    if [ -f "$CLAUDE_CONFIG_FILE" ]; then
+        echo "📝 Updating existing Claude config..."
+        
+        # Backup existing config
+        cp "$CLAUDE_CONFIG_FILE" "$CLAUDE_CONFIG_FILE.backup.$(date +%Y%m%d_%H%M%S)"
+        
+        # Use Node.js to merge configs properly
+        node -e "
+        const fs = require('fs');
+        const existingConfig = JSON.parse(fs.readFileSync('$CLAUDE_CONFIG_FILE', 'utf8'));
+        const newServer = $mcp_config;
+        
+        if (!existingConfig.mcpServers) {
+            existingConfig.mcpServers = {};
+        }
+        
+        existingConfig.mcpServers.stackmemory = newServer.stackmemory;
+        
+        fs.writeFileSync('$CLAUDE_CONFIG_FILE', JSON.stringify(existingConfig, null, 2));
+        console.log('✅ Configuration merged successfully');
+        "
+    else
+        echo "📝 Creating new Claude config..."
+        cat > "$CLAUDE_CONFIG_FILE" << EOF
+{
+  "mcpServers": $mcp_config
+}
+EOF
+    fi
+}
+
+# Add MCP server to Claude config
+merge_mcp_config
+
+# Create a convenience command for manual testing
+echo "📝 Creating stackmemory-mcp command..."
+cat > "$PROJECT_ROOT/stackmemory-mcp" << 'EOF'
+#!/bin/bash
+# Run StackMemory MCP server for testing
+node "$(dirname "$0")/dist/mcp/stackmemory-mcp-server.js"
+EOF
+chmod +x "$PROJECT_ROOT/stackmemory-mcp"
+
+# Create example usage documentation
+cat > "$PROJECT_ROOT/docs/CLAUDE-INTEGRATION.md" << 'EOF'
+# StackMemory Claude Integration
+
+## Setup Complete! 🎉
+
+StackMemory is now integrated with Claude Desktop. Restart Claude Desktop to activate the integration.
+
+## Available Tools in Claude
+
+Once activated, you can use these commands in any Claude conversation:
+
+### Task Management
+- `create_task` - Create a new task with optional auto-execution
+- `execute_task` - Start agent execution for a task
+- `task_status` - Check task status
+- `breakdown_task` - Break complex tasks into subtasks
+
+### Agent Execution
+- `agent_turn` - Execute a single turn in an active session
+- `session_feedback` - Get feedback from the last turn
+- `list_active_sessions` - View all active agent sessions
+- `retry_session` - Retry a failed session with learned context
+
+### Context Management
+- `save_context` - Save important information from the conversation
+- `load_context` - Retrieve relevant context from StackMemory
+
+## Example Usage in Claude
+
+```
+"Create a task to refactor the authentication module"
+-> Claude will use create_task with auto_execute
+
+"What's the status of my current tasks?"
+-> Claude will use task_status to show active tasks
+
+"Save this architecture decision for future reference"
+-> Claude will use save_context to persist the information
+
+"What did we decide about the API structure last week?"
+-> Claude will use load_context to retrieve relevant decisions
+```
+
+## Troubleshooting
+
+1. **Restart Claude Desktop** after installation
+2. Check logs at: `~/.stackmemory/logs/`
+3. Verify MCP server is running: `ps aux | grep stackmemory-mcp`
+4. Test manually: `./stackmemory-mcp`
+
+## Configuration
+
+The MCP server configuration is stored at:
+`~/Library/Application Support/Claude/claude_desktop_config.json`
+
+You can modify environment variables in the config:
+- `STACKMEMORY_PROJECT` - Set the project directory
+- `LOG_LEVEL` - Set logging verbosity (debug, info, warn, error)
+EOF
+
+echo ""
+echo -e "${GREEN}✅ StackMemory Claude integration setup complete!${NC}"
+echo ""
+echo -e "${YELLOW}Next steps:${NC}"
+echo "1. Restart Claude Desktop to activate the integration"
+echo "2. In any Claude conversation, the StackMemory tools will be automatically available"
+echo "3. Claude will automatically use these tools when relevant to your tasks"
+echo ""
+echo "📚 Documentation created at: $PROJECT_ROOT/docs/CLAUDE-INTEGRATION.md"
+echo ""
+echo -e "${GREEN}Example usage in Claude:${NC}"
+echo '  "Create a task to implement user authentication"'
+echo '  "Show me the status of my current tasks"'
+echo '  "Save this important decision about the architecture"'
+echo ""
+
+# Check if Claude is running and suggest restart
+if pgrep -x "Claude" > /dev/null; then
+    echo -e "${YELLOW}⚠️  Claude Desktop is currently running. Please restart it to activate the integration.${NC}"
+    echo ""
+    read -p "Would you like to restart Claude Desktop now? (y/n) " -n 1 -r
+    echo ""
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        osascript -e 'quit app "Claude"'
+        sleep 2
+        open -a "Claude"
+        echo -e "${GREEN}✅ Claude Desktop restarted!${NC}"
+    fi
+fi

package/scripts/setup-railway-deployment.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[railway-setup] Starting setup..."
+
+# Ensure tsx is available
+if ! command -v npx >/dev/null 2>&1; then
+  echo "npx not found; please run via npm scripts (npm run railway:setup)" >&2
+  exit 1
+fi
+
+# Default SQLite path if DATABASE_URL not provided
+if [[ -z "${DATABASE_URL:-}" ]]; then
+  mkdir -p .stackmemory
+  export DATABASE_URL="$(pwd)/.stackmemory/railway.db"
+  echo "[railway-setup] DATABASE_URL not set; using ${DATABASE_URL}"
+fi
+
+echo "[railway-setup] Applying migrations to ${DATABASE_URL}"
+npx tsx src/cli/commands/migrate.ts apply --to latest
+
+echo "[railway-setup] Verifying schema version"
+if npx tsx scripts/verify-railway-schema.ts; then
+  echo "[railway-setup] Schema verified"
+else
+  code=$?
+  if [[ "$code" == "2" ]]; then
+    echo "[railway-setup] Schema below latest; retrying apply"
+    npx tsx src/cli/commands/migrate.ts apply --to latest
+  else
+    echo "[railway-setup] Verification failed with code $code" >&2
+    exit $code
+  fi
+fi
+
+echo "[railway-setup] Done."
+

package/scripts/setup.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# StackMemory Quick Setup Script
+
+echo "🚀 Setting up StackMemory..."
+
+# Install dependencies
+echo "📦 Installing dependencies..."
+npm install
+
+# Build TypeScript
+echo "🔨 Building TypeScript..."
+npm run build
+
+# Initialize StackMemory
+echo "🎯 Initializing StackMemory..."
+npm run init
+
+echo ""
+echo "✅ Setup complete!"
+echo ""
+echo "📝 Next steps:"
+echo "1. Copy the MCP configuration shown above to your Claude Code settings"
+echo "2. Restart Claude Code"
+echo "3. The StackMemory tools will be available in Claude Code!"
+echo ""
+echo "🎮 Commands:"
+echo "  npm run mcp:dev    - Start MCP server in dev mode"
+echo "  npm run status     - Check StackMemory status"
+echo "  npm run analyze    - Analyze context usage"
+echo ""

package/scripts/show-linear-summary.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Show Linear task summary with all statuses
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+interface LinearIssue {
+  identifier: string;
+  title: string;
+  state: {
+    name: string;
+    type: string;
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+
+async function showLinearSummary() {
+  // Load Linear tokens
+  const tokensPath = join(process.cwd(), '.stackmemory', 'linear-tokens.json');
+  let accessToken: string;
+
+  try {
+    const tokensData = readFileSync(tokensPath, 'utf8');
+    const tokens = JSON.parse(tokensData);
+    accessToken = tokens.accessToken;
+  } catch {
+    console.error(
+      '❌ Failed to load Linear tokens. Please run: stackmemory linear setup'
+    );
+    process.exit(1);
+  }
+
+  // GraphQL helper
+  const linearApiUrl = 'https://api.linear.app/graphql';
+
+  async function graphqlRequest(
+    query: string,
+    variables: Record<string, unknown> = {}
+  ) {
+    const response = await fetch(linearApiUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ query, variables }),
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Linear API error: ${response.status} ${response.statusText}`
+      );
+    }
+
+    const result = (await response.json()) as {
+      errors?: unknown[];
+      data: unknown;
+    };
+    if (result.errors) {
+      throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
+    }
+
+    return result.data;
+  }
+
+  // Get issues grouped by state
+  const issuesQuery = `
+    query {
+      issues(first: 250) {
+        nodes {
+          identifier
+          title
+          state {
+            name
+            type
+          }
+          createdAt
+          updatedAt
+        }
+      }
+    }
+  `;
+
+  const data = (await graphqlRequest(issuesQuery)) as {
+    issues: { nodes: LinearIssue[] };
+  };
+  const issues = data.issues.nodes;
+
+  // Group by state type
+  const grouped = new Map<string, LinearIssue[]>();
+
+  for (const issue of issues) {
+    const stateType = issue.state.type;
+    if (!grouped.has(stateType)) {
+      grouped.set(stateType, []);
+    }
+    const stateIssues = grouped.get(stateType);
+    if (stateIssues) {
+      stateIssues.push(issue);
+    }
+  }
+
+  // Display summary
+  console.log('\n📊 Linear Task Summary\n');
+  console.log('='.repeat(60));
+
+  const stateOrder = [
+    'backlog',
+    'unstarted',
+    'started',
+    'completed',
+    'canceled',
+  ];
+
+  for (const state of stateOrder) {
+    const stateIssues = grouped.get(state) || [];
+    if (stateIssues.length === 0) continue;
+
+    const emoji =
+      {
+        backlog: '📋',
+        unstarted: '⏳',
+        started: '🔄',
+        completed: '✅',
+        canceled: '❌',
+      }[state] || '⚪';
+
+    console.log(
+      `\n${emoji} ${state.toUpperCase()} (${stateIssues.length} tasks)`
+    );
+    console.log('-'.repeat(40));
+
+    // Show recent items (last 5)
+    const recent = stateIssues
+      .sort(
+        (a, b) =>
+          new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+      )
+      .slice(0, state === 'canceled' ? 20 : 5);
+
+    for (const issue of recent) {
+      const updatedDate = new Date(issue.updatedAt).toLocaleDateString();
+      console.log(
+        `  ${issue.identifier.padEnd(10)} ${issue.title.slice(0, 50).padEnd(50)} ${updatedDate}`
+      );
+    }
+
+    if (stateIssues.length > recent.length) {
+      console.log(`  ... and ${stateIssues.length - recent.length} more`);
+    }
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('\n📈 Total Issues: ' + issues.length);
+  const activeCount =
+    (grouped.get('started')?.length ?? 0) +
+    (grouped.get('unstarted')?.length ?? 0) +
+    (grouped.get('backlog')?.length ?? 0);
+  console.log('   Active: ' + activeCount);
+  console.log('   Completed: ' + (grouped.get('completed')?.length ?? 0));
+  console.log('   Canceled: ' + (grouped.get('canceled')?.length ?? 0));
+}
+
+// Run
+showLinearSummary().catch((error) => {
+  console.error('❌ Error:', error);
+  process.exit(1);
+});

package/scripts/stackmemory-auto-handoff.sh

@@ -0,0 +1,231 @@
+#!/bin/bash
+# StackMemory Auto-Handoff Wrapper
+# Wraps any command and captures context on termination
+
+set -e
+
+# Configuration
+STACKMEMORY_BIN="${STACKMEMORY_BIN:-stackmemory}"
+HANDOFF_DIR="${HOME}/.stackmemory/handoffs"
+LOG_FILE="${HANDOFF_DIR}/auto-handoff.log"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Ensure directories exist
+mkdir -p "$HANDOFF_DIR"
+
+# Log function
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
+}
+
+# Function to capture handoff
+capture_handoff() {
+    local reason="$1"
+    local exit_code="${2:-0}"
+    
+    echo -e "${YELLOW}📸 Capturing handoff context...${NC}"
+    log "Capturing handoff: reason=$reason, exit_code=$exit_code"
+    
+    # Run stackmemory handoff command
+    if command -v "$STACKMEMORY_BIN" &> /dev/null; then
+        # Capture the handoff
+        "$STACKMEMORY_BIN" handoff --no-commit 2>&1 | tee -a "$LOG_FILE"
+        
+        # Save additional metadata
+        local metadata_file="${HANDOFF_DIR}/last-handoff-meta.json"
+        cat > "$metadata_file" << EOF
+{
+    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+    "reason": "$reason",
+    "exit_code": $exit_code,
+    "command": "$WRAPPED_COMMAND",
+    "pid": $$,
+    "cwd": "$(pwd)",
+    "user": "$USER",
+    "session_duration": $(($(date +%s) - SESSION_START))
+}
+EOF
+        
+        echo -e "${GREEN}✅ Handoff captured successfully${NC}"
+        log "Handoff captured: $metadata_file"
+        
+        # Show quick summary
+        echo -e "${BLUE}📋 Session Summary:${NC}"
+        echo "  Duration: $(($(date +%s) - SESSION_START)) seconds"
+        echo "  Exit reason: $reason"
+        
+        # Check for uncommitted changes
+        if git status --short 2>/dev/null | grep -q .; then
+            echo -e "${YELLOW}⚠️  You have uncommitted changes${NC}"
+            echo "  Run 'git status' to review"
+        fi
+        
+        # Check for active tasks
+        local active_tasks=$("$STACKMEMORY_BIN" task list --state in_progress --format json 2>/dev/null | jq -r '.[].title' 2>/dev/null)
+        if [ -n "$active_tasks" ]; then
+            echo -e "${BLUE}📝 Active tasks:${NC}"
+            echo "$active_tasks" | while read -r task; do
+                echo "  • $task"
+            done
+        fi
+        
+        echo -e "${GREEN}✨ Run 'stackmemory handoff restore' in your next session${NC}"
+    else
+        echo -e "${RED}❌ StackMemory not found${NC}"
+        log "ERROR: StackMemory binary not found"
+    fi
+}
+
+# Signal handlers
+handle_sigint() {
+    echo -e "\n${YELLOW}⚠️  Interrupted (Ctrl+C)${NC}"
+    capture_handoff "SIGINT" 130
+    exit 130
+}
+
+handle_sigterm() {
+    echo -e "\n${YELLOW}⚠️  Terminated${NC}"
+    capture_handoff "SIGTERM" 143
+    exit 143
+}
+
+handle_sighup() {
+    echo -e "\n${YELLOW}⚠️  Hangup signal${NC}"
+    capture_handoff "SIGHUP" 129
+    exit 129
+}
+
+handle_exit() {
+    local exit_code=$?
+    if [ $exit_code -ne 0 ] && [ $exit_code -ne 130 ] && [ $exit_code -ne 143 ] && [ $exit_code -ne 129 ]; then
+        echo -e "${YELLOW}⚠️  Unexpected exit (code: $exit_code)${NC}"
+        capture_handoff "unexpected_exit" $exit_code
+    elif [ $exit_code -eq 0 ]; then
+        # Normal exit - ask if user wants to capture handoff
+        if [ "$AUTO_CAPTURE_ON_EXIT" = "true" ]; then
+            capture_handoff "normal_exit" 0
+        else
+            echo -e "${BLUE}💡 Session ending normally. Create handoff? (y/N):${NC} \c"
+            read -t 5 -n 1 response || response="n"
+            echo
+            if [[ "$response" =~ ^[Yy]$ ]]; then
+                capture_handoff "normal_exit" 0
+            fi
+        fi
+    fi
+}
+
+# Usage information
+usage() {
+    cat << EOF
+Usage: $0 [OPTIONS] COMMAND [ARGS...]
+
+Wraps a command with automatic handoff capture on termination.
+
+Options:
+    -h, --help              Show this help message
+    -a, --auto              Auto-capture on normal exit (no prompt)
+    -q, --quiet             Suppress output
+    -t, --tag TAG           Tag this session
+    
+Examples:
+    $0 claude                          # Wrap Claude session
+    $0 -a npm run dev                  # Auto-capture on exit
+    $0 -t "feature-work" vim          # Tagged session
+    
+Environment Variables:
+    STACKMEMORY_BIN         Path to stackmemory binary
+    AUTO_CAPTURE_ON_EXIT    Set to 'true' for auto-capture
+
+Without arguments, enables handoff mode for current shell session.
+EOF
+}
+
+# Parse arguments
+AUTO_CAPTURE_ON_EXIT="${AUTO_CAPTURE_ON_EXIT:-false}"
+SESSION_TAG=""
+QUIET_MODE="false"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        -a|--auto)
+            AUTO_CAPTURE_ON_EXIT="true"
+            shift
+            ;;
+        -q|--quiet)
+            QUIET_MODE="true"
+            shift
+            ;;
+        -t|--tag)
+            SESSION_TAG="$2"
+            shift 2
+            ;;
+        *)
+            break
+            ;;
+    esac
+done
+
+# If no command provided, just set up handlers for current session
+if [ $# -eq 0 ]; then
+    echo -e "${BLUE}🛡️  StackMemory Auto-Handoff Enabled${NC}"
+    echo -e "${GRAY}Context will be captured on session termination${NC}"
+    echo -e "${YELLOW}Press Ctrl+C to test or exit normally to continue${NC}"
+    
+    # Set up signal handlers
+    trap handle_sigint SIGINT
+    trap handle_sigterm SIGTERM
+    trap handle_sighup SIGHUP
+    trap handle_exit EXIT
+    
+    # Record session start
+    export SESSION_START=$(date +%s)
+    export WRAPPED_COMMAND="interactive_shell"
+    
+    # Keep running
+    while true; do
+        sleep 1
+    done
+else
+    # Wrap the provided command
+    WRAPPED_COMMAND="$*"
+    
+    if [ "$QUIET_MODE" = "false" ]; then
+        echo -e "${BLUE}🛡️  StackMemory Auto-Handoff Wrapper${NC}"
+        echo -e "Wrapping: $WRAPPED_COMMAND"
+        if [ -n "$SESSION_TAG" ]; then
+            echo -e "Tag: $SESSION_TAG"
+        fi
+        echo -e "${GRAY}Handoff will be captured on termination${NC}"
+        echo
+    fi
+    
+    # Set up signal handlers
+    trap handle_sigint SIGINT
+    trap handle_sigterm SIGTERM
+    trap handle_sighup SIGHUP
+    trap handle_exit EXIT
+    
+    # Record session start
+    export SESSION_START=$(date +%s)
+    
+    log "Starting wrapped session: $WRAPPED_COMMAND"
+    
+    # Execute the wrapped command
+    "$@"
+    
+    # Command completed normally
+    exit_code=$?
+    log "Command completed with exit code: $exit_code"
+    exit $exit_code
+fi

package/scripts/stackmemory-daemon.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# StackMemory background daemon
+# Automatically saves context every 5 minutes and on exit
+
+INTERVAL=${1:-300}  # Default 5 minutes
+PID_FILE="/tmp/stackmemory-daemon.pid"
+
+cleanup() {
+    echo "🛑 Stopping StackMemory daemon..."
+    if [ -d ".stackmemory" ]; then
+        stackmemory status
+        [ -n "$LINEAR_API_KEY" ] && stackmemory linear sync
+    fi
+    rm -f "$PID_FILE"
+    exit 0
+}
+
+trap cleanup EXIT INT TERM
+
+# Save PID
+echo $$ > "$PID_FILE"
+
+echo "🚀 StackMemory daemon started (PID: $$)"
+echo "   Auto-save interval: ${INTERVAL}s"
+echo "   Press Ctrl+C to stop"
+
+while true; do
+    sleep "$INTERVAL"
+    
+    if [ -d ".stackmemory" ]; then
+        echo "[$(date)] Auto-saving StackMemory context..."
+        stackmemory status 2>/dev/null || true
+        
+        # Only sync with Linear once per hour
+        if [ $(($(date +%s) % 3600)) -lt "$INTERVAL" ] && [ -n "$LINEAR_API_KEY" ]; then
+            stackmemory linear sync 2>/dev/null || true
+        fi
+    fi
+done