MCP Memory Service

# HTTP Server Management The MCP Memory Service HTTP server is **required** for Claude Code hooks (Natural Memory Triggers) to work. This guide explains how to check and manage the HTTP server. ## Why is the HTTP Server Required? When using **Natural Memory Triggers** in Claude Code: - The session-start hook needs the HTTP server to retrieve relevant memories - Without the HTTP server, hooks fail silently and no memories are injected - HTTP protocol avoids conflicts with Claude Code's MCP server ## Checking Server Status ### Quick Check ```bash # Verbose output (default, recommended for troubleshooting) uv run python scripts/server/check_http_server.py # Quiet mode (only exit code, useful for scripts) uv run python scripts/server/check_http_server.py -q ``` **Sample Output (Running):** ``` [OK] HTTP server is running Version: 8.3.0 Endpoint: http://localhost:8000/api/health Status: healthy ``` **Sample Output (Not Running):** ``` [ERROR] HTTP server is NOT running To start the HTTP server, run: uv run python scripts/server/run_http_server.py Or for HTTPS: MCP_HTTPS_ENABLED=true uv run python scripts/server/run_http_server.py Error: [WinError 10061] No connection could be made... ``` ## Starting the Server ### Manual Start ```bash # HTTP mode (default, port 8000) uv run python scripts/server/run_http_server.py # HTTPS mode (port 8443) MCP_HTTPS_ENABLED=true uv run python scripts/server/run_http_server.py ``` ### Auto-Start Scripts These scripts check if the server is running and start it only if needed: **Unix/macOS:** ```bash ./scripts/server/start_http_server.sh ``` **Windows:** ```cmd scripts\server\start_http_server.bat ``` **Features:** - Checks if server is already running (avoids duplicate instances) - Starts server in background/new window - Verifies successful startup - Shows server status and logs location ## Troubleshooting ### Hook Not Injecting Memories **Symptom:** Claude Code starts but no memories are shown **Solution:** 1. Check if HTTP server is running: ```bash uv run python scripts/server/check_http_server.py ``` 2. If not running, start it: ```bash uv run python scripts/server/run_http_server.py ``` 3. Restart Claude Code to trigger session-start hook ### Wrong Port or Endpoint **Symptom:** Hooks fail to connect, "Invalid URL" or connection errors in logs **Common Issue:** Port mismatch between hooks configuration and actual server **Check your hooks configuration:** ```bash cat ~/.claude/hooks/config.json | grep -A5 "http" ``` Should match your server configuration: - Default HTTP: `http://localhost:8000` or `http://127.0.0.1:8000` - Default HTTPS: `https://localhost:8443` **Important:** The HTTP server uses port **8000** by default (configured in `.env`). If your hooks are configured for a different port (e.g., 8889), you need to either: 1. Update hooks config to match port 8000, OR 2. Change `MCP_HTTP_PORT` in `.env` and restart the server **Fix for port mismatch:** ```bash # Option 1: Update hooks config (recommended) # Edit ~/.claude/hooks/config.json and change endpoint to: # "endpoint": "http://127.0.0.1:8000" # Option 2: Change server port (if needed) # Edit .env: MCP_HTTP_PORT=8889 # Then restart: systemctl --user restart mcp-memory-http.service ``` ### Server Startup Issues **Common causes:** - Port already in use - Missing dependencies - Configuration errors **Debug steps:** 1. Check if port is in use: ```bash # Unix/macOS lsof -i :8000 ``` ```cmd # Windows netstat -ano | findstr :8000 ``` 2. Check server logs (when using auto-start scripts): ```bash # Unix/macOS tail -f /tmp/mcp-http-server.log # Windows # Check the server window ``` ## Integration with Hooks The session-start hook automatically: 1. Attempts to connect to HTTP server (preferred) 2. Falls back to MCP if HTTP unavailable 3. Falls back to environment-only if both fail **Recommended setup for Claude Code** (`~/.claude/hooks/config.json`): ```json { "memoryService": { "protocol": "http", "preferredProtocol": "http", "http": { "endpoint": "http://localhost:8000", "healthCheckTimeout": 3000 } } } ``` ## Automation ### Start Server on System Boot **Unix/macOS (launchd):** Create `~/Library/LaunchAgents/com.mcp.memory.http.plist` and replace `/path/to/repository` with the absolute path to this repository: ```xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.mcp.memory.http</string> <key>ProgramArguments</key> <array> <string>/path/to/repository/scripts/server/start_http_server.sh</string> </array> <key>RunAtLoad</key> <true/> </dict> </plist> ``` **Windows (Task Scheduler):** 1. Open Task Scheduler 2. Create Basic Task 3. Trigger: At log on 4. Action: Start a program 5. Program: `C:\path\to\repository\scripts\server\start_http_server.bat` (replace `C:\path\to\repository` with the full path to this repository) ### Pre-Claude Code Script Add to your shell profile (`.bashrc`, `.zshrc`, etc.): ```bash # Auto-start MCP Memory HTTP server before Claude Code # Replace /path/to/repository with the absolute path to this project alias claude-code='/path/to/repository/scripts/server/start_http_server.sh && claude' ``` **Linux (systemd user service - RECOMMENDED):** For a persistent, auto-starting service on Linux, use systemd. See [Systemd Service Guide](deployment/systemd-service.md) for detailed setup. Quick setup: ```bash # Install service bash scripts/service/install_http_service.sh # Start service systemctl --user start mcp-memory-http.service # Enable auto-start systemctl --user enable mcp-memory-http.service loginctl enable-linger $USER # Run even when logged out ``` **Quick Commands:** ```bash # Service control systemctl --user start/stop/restart mcp-memory-http.service systemctl --user status mcp-memory-http.service # View logs journalctl --user -u mcp-memory-http.service -f # Health check curl http://127.0.0.1:8000/api/health ``` ## See Also - [Claude Code Hooks Configuration](../CLAUDE.md#claude-code-hooks-configuration-) - [Natural Memory Triggers](../CLAUDE.md#natural-memory-triggers-v710-latest) - [Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)