MCP Memory Service

# Hooks Troubleshooting Quick Reference ## SessionEnd Hook Issues ### When SessionEnd Actually Triggers **Triggers on**: - `/exit` command - Terminal/window close - Normal Claude Code exit **Does NOT trigger on**: - Ctrl+C (once or twice) - This suspends the session - Session resume ### Common Issues | Symptom | Root Cause | Solution | |---------|-----------|----------| | No memory after Ctrl+C | Ctrl+C suspends, doesn't end session | Use `/exit` to properly terminate | | Connection failures during store | HTTP/HTTPS protocol mismatch | Match endpoint in config.json to server protocol (see SessionStart section) | | No memory created despite /exit | Insufficient session content | Ensure 100+ characters and confidence > 0.1 | ### Memory Creation Requirements 1. **Minimum session length**: 100+ characters 2. **Minimum confidence**: > 0.1 from conversation analysis 3. **Session consolidation enabled**: `enableSessionConsolidation: true` in config ### Quick Verification ```bash # Check recent session memories curl -sk "https://localhost:8000/api/search/by-tag" \ -H "Content-Type: application/json" \ -d '{"tags": ["session-consolidation"], "limit": 5}' | \ python -m json.tool | grep created_at_iso # Test SessionEnd hook manually node ~/.claude/hooks/core/session-end.js # Verify connection curl -sk "https://localhost:8000/api/health" ``` ## SessionStart Hook Issues ### No Relevant Memories Found / MCP Fallback **Symptoms**: - Session starts with multiple "MCP Fallback" messages (typically 3x) - Message: "📭 Memory Search → No relevant memories found" - Git analysis works but no memories are injected - Hook appears to work but provides no memory context **Example Output**: ``` 🧠 Memory Hook → Initializing session awareness... 📂 Project Detector → Analyzing mcp-memory-service 📊 Git Context → 10 commits, 3 changelog entries 🔑 Keywords → docs, chore, version, v8.22.0, fix ↩️ MCP Fallback → Using standard MCP tools ↩️ MCP Fallback → Using standard MCP tools ↩️ MCP Fallback → Using standard MCP tools 📭 Memory Search → No relevant memories found ``` **Root Cause**: HTTP/HTTPS protocol mismatch between hook configuration and server **Diagnosis**: ```bash # Check what protocol your server is using grep HTTPS_ENABLED /path/to/mcp-memory-service/.env # If MCP_HTTPS_ENABLED=true, server uses HTTPS # Test HTTP connection (will fail if server uses HTTPS) curl -s http://127.0.0.1:8000/api/health # Empty reply = protocol mismatch # Test HTTPS connection (will work if server uses HTTPS) curl -sk https://127.0.0.1:8000/api/health # {"status":"healthy",...} = server is on HTTPS # Check hook configuration grep endpoint ~/.claude/hooks/config.json # Should match server protocol ``` **Solution**: Update `~/.claude/hooks/config.json` to match your server protocol: ```json { "memoryService": { "http": { "endpoint": "https://127.0.0.1:8000", // Change http → https if server uses HTTPS "apiKey": "your-api-key" } } } ``` Then restart your Claude Code session to pick up the configuration change. **Why This Happens**: - The `.env` file has `MCP_HTTPS_ENABLED=true`, making the server use HTTPS - Hook config was set up for HTTP from earlier installation - HTTP health checks fail silently, causing fallback to MCP tools - MCP fallback path has different behavior, returning no results ### Common Issues | Symptom | Root Cause | Solution | |---------|-----------|----------| | "MCP Fallback" messages (3x) | HTTP/HTTPS protocol mismatch | Update endpoint to match server protocol | | "No relevant memories found" despite healthy DB | Connection timeout or protocol mismatch | Verify endpoint protocol and increase timeout if needed | | Hook completes but no memory context | Code execution disabled or failed | Check `codeExecution.enabled: true` in config | | Slow session starts (>10s) | Cold start + network delays | Normal for first start, use balanced performance profile | ### Quick Verification ```bash # Verify server is responding on correct protocol curl -sk "https://localhost:8000/api/health" # For HTTPS curl -s "http://127.0.0.1:8000/api/health" # For HTTP # Check database has memories curl -sk "https://localhost:8000/api/health" | python -m json.tool # Look for: "total_memories": 2514 (or similar non-zero value) # Test semantic search works curl -sk "https://localhost:8000/api/search" \ -H "Content-Type: application/json" \ -d '{"query": "recent development", "limit": 5}' | \ python -m json.tool | grep -E "content|relevance" ``` ## Windows SessionStart Hook Issue **CRITICAL BUG**: SessionStart hooks cause Claude Code to hang indefinitely on Windows ([#160](https://github.com/doobidoo/mcp-memory-service/issues/160)) ### Symptoms - Claude Code unresponsive on startup - Cannot enter prompts or cancel with Ctrl+C - Must force-close terminal ### Workarounds 1. **Use `/session-start` slash command** (recommended) 2. **Disable SessionStart hooks** in configuration 3. **Use UserPromptSubmit hooks instead** ## Hook Configuration Synchronization ### Port Mismatch Detection ```bash # Windows netstat -ano | findstr "8000" # Linux/macOS lsof -i :8000 # Check hooks config grep endpoint ~/.claude/hooks/config.json ``` ### Common Port Mistakes - Config.json shows 8889 but server runs on 8000 - Using dashboard port instead of API server port - Different ports in settings.json vs hooks config ### Symptoms of Port Mismatch - SessionStart hook hangs/times out - Hooks show "connection timeout" in logs - No memories injected despite hook firing ## Schema Validation Errors After PR Merges ### Quick Fix ```bash # In Claude Code, reconnect MCP /mcp # For HTTP server (separate) systemctl --user restart mcp-memory-http.service ``` ### Root Cause MCP clients cache tool schemas. After merging PRs that change schemas, you must restart the MCP server process to load the new schema. ### Verification ```bash # Check when PR was merged gh pr view <PR_NUMBER> --json mergedAt,title # Check when MCP server started ps aux | grep "memory.*server" | grep -v grep # If server started BEFORE merge, it's running old code ``` ## Emergency Debugging ```bash # Check active MCP servers /mcp # Validate configuration python scripts/validation/diagnose_backend_config.py # Remove conflicting config rm -f .mcp.json # View enhanced logs (macOS) tail -50 ~/Library/Logs/Claude/mcp-server-memory.log | grep -E "(🚀|☁️|✅|❌)" ``` ## Detailed Documentation For comprehensive troubleshooting with diagnosis checklists and technical details, see: - `docs/troubleshooting/session-end-hooks.md` - `docs/troubleshooting/pr162-schema-caching-issue.md` - `docs/http-server-management.md`