feat(hindsight-embed): external API support + OpenClaw fixes (#263, #264) (#265)

* feat(hindsight-embed): external API support + OpenClaw fixes

Adds comprehensive external API support and fixes critical OpenClaw plugin issues.

**External API Support:**
- Add HINDSIGHT_EMBED_API_URL to connect to external Hindsight API servers
- Add HINDSIGHT_EMBED_API_TOKEN for Bearer token authentication
- Add HINDSIGHT_EMBED_API_DATABASE_URL for custom PostgreSQL databases
- Skip daemon startup when external API URL is configured
- Add 10 comprehensive unit tests for external API scenarios

**OpenClaw Plugin Fixes:**
- Fix #263: Port mismatch (DEFAULT_PORT 8888 → 8889)
- Fix #264: Add daemon recovery after OpenClaw SIGUSR1 restarts
- Fix OpenRouter support: Pass HINDSIGHT_API_LLM_BASE_URL to daemon
- Fix macOS crashes: Auto-set FORCE_CPU flags for MPS/Metal issues

**LLM Configuration Refactor:**
- Auto-detect provider from standard env vars (OPENAI_API_KEY, etc.)
- Support explicit override via HINDSIGHT_API_LLM_* env vars
- Update model defaults (gemini-2.5-flash, openai/gpt-oss-20b)
- Remove provider-specific base URL support (only HINDSIGHT_API_LLM_BASE_URL)

**Documentation Updates:**
- Rewrite OpenClaw integration docs with crystal clear examples
- Add external API usage examples
- Add OpenRouter free model examples
- Update Quick Start with simplified provider setup

Closes #263, Closes #264

* docs(openclaw): streamline docs and add config inspection

- Remove duplicate/verbose sections (468 → 216 lines)
- Add section showing how to check ~/.hindsight/embed config file
- Add daemon status checking commands
- Keep only essential configuration examples
- Consolidate troubleshooting sections

* fix(test): update daemon health check port from 8889 to 8888

The test was checking port 8889 but we changed the daemon to use port 8888.

Author: nicoloboschi

hindsight-api/hindsight_api/daemon.py

@@ -15,7 +15,7 @@
 logger = logging.getLogger(__name__)
 
 # Default daemon configuration
-DEFAULT_DAEMON_PORT = 8889
+DEFAULT_DAEMON_PORT = 8888
 DEFAULT_IDLE_TIMEOUT = 0  # 0 = no auto-exit (hindsight-embed passes its own timeout)
 LOCKFILE_PATH = Path.home() / ".hindsight" / "daemon.lock"
 DAEMON_LOG_PATH = Path.home() / ".hindsight" / "daemon.log"

hindsight-docs/docs/sdks/embed.md

@@ -15,15 +15,15 @@ Zero-configuration local memory system with automatic daemon management. Perfect
 1. **First command triggers startup**: When you run any `hindsight-embed` command, it checks if a local daemon is running
 2. **Auto-daemon management**: If no daemon exists, it automatically spawns `hindsight-api --daemon` in the background
 3. **Embedded database**: The daemon uses `pg0` (embedded PostgreSQL) — no separate database installation required
-4. **Command forwarding**: Your command is forwarded to the local daemon via HTTP (localhost:8889)
+4. **Command forwarding**: Your command is forwarded to the local daemon via HTTP (localhost:8888)
 5. **Auto-shutdown**: After 5 minutes of inactivity (configurable), the daemon gracefully shuts down to free resources
 
 **Key features:**
 
 - **Zero setup** — One `configure` command and you're ready
 - **Automatic lifecycle** — Daemon starts on-demand, stops when idle
 - **Isolated storage** — Each bank gets its own embedded PostgreSQL database
-- **Local-only** — Binds to `127.0.0.1:8889`, not accessible from network
+- **Local-only** — Binds to `127.0.0.1:8888`, not accessible from network
 - **Production-grade engine** — Uses the same memory engine as the full API service
 
 Think of it as SQLite for long-term memory — all the power of Hindsight without managing servers.
@@ -209,7 +209,7 @@ hindsight-embed daemon logs -f
 
 Common issues:
 - **Missing API key**: Set `HINDSIGHT_EMBED_LLM_API_KEY`
-- **Port conflict**: Another service using port 8889
+- **Port conflict**: Another service using port 8888
 - **Permissions**: Check `~/.hindsight/` directory permissions
 
 ### Daemon Exits Immediately