Merge branch 'main' into docs-codex-cloud-first

Lead README/docs/guide Quick Start with Cloud sign-up + Cloud API
URL example; demote self-hosted localhost:8888 to a 'Self-hosting
(local development)' section below. Update docstring example.

hindsight-api-slim/hindsight_api/engine/providers/openai_compatible_llm.py

@@ -306,15 +306,19 @@ class OpenAICompatibleLLM(LLMInterface):
             self.api_key = "local"
 
         # Validate API key for cloud providers
-        if self.provider in (
-            "openai",
-            "groq",
-            "minimax",
-            "deepseek",
-            "openrouter",
-            "zai",
-            "opencode-go",
-        ) and not self.api_key:
+        if (
+            self.provider
+            in (
+                "openai",
+                "groq",
+                "minimax",
+                "deepseek",
+                "openrouter",
+                "zai",
+                "opencode-go",
+            )
+            and not self.api_key
+        ):
             raise ValueError(f"API key is required for {self.provider}")
 
         # Service tier configuration (from config, not env vars)

hindsight-docs/docs-integrations/codex.md

@@ -12,11 +12,15 @@ Persistent memory for [Codex CLI](https://github.com/openai/codex) using [Hindsi
 
 ## Quick Start
 
+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) for a Hindsight Cloud API key — no self-hosting, no local daemon to manage.
+:::
+
 ```bash
 curl -fsSL https://hindsight.vectorize.io/get-codex | bash
 ```
 
-The installer will guide you through choosing local or cloud mode and configuring your connection. Once installed, start a new Codex session — memory is live.
+The installer will guide you through choosing Cloud or local-daemon mode and configuring your connection. Once installed, start a new Codex session — memory is live.
 
 To uninstall:
 

hindsight-docs/docs-integrations/crewai.md

@@ -26,12 +26,19 @@ pip install hindsight-crewai
 
 ## Quick Start
 
+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) and grab an API key — no self-hosting required.
+:::
+
 ```python
 from hindsight_crewai import configure, HindsightStorage
 from crewai.memory.external.external_memory import ExternalMemory
 from crewai import Agent, Crew, Task
 
-configure(hindsight_api_url="http://localhost:8888")
+configure(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
+)
 
 crew = Crew(
     agents=[Agent(role="Researcher", goal="Find information", backstory="...")],
@@ -50,6 +57,16 @@ That's it. CrewAI will automatically:
 
 Memories persist across crew runs, so your crew learns over time.
 
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, swap the URL:
+
+```python
+configure(hindsight_api_url="http://localhost:8888")
+```
+
+See the [installation guide](/developer/installation) for self-hosting setup.
+
 ## How It Works
 
 The integration maps CrewAI's 3-method `Storage` interface to Hindsight's API:
@@ -68,7 +85,7 @@ CrewAI calls `search()` automatically at the start of each task and `save()` aft
 from hindsight_crewai import configure
 
 configure(
-    hindsight_api_url="http://localhost:8888",  # Hindsight API URL
+    hindsight_api_url="https://api.hindsight.vectorize.io",  # Hindsight Cloud (default)
     api_key="your-api-key",                     # Or set HINDSIGHT_API_KEY env var
     budget="mid",                               # Recall budget: "low", "mid", "high"
     max_tokens=4096,                            # Max tokens for recall results
@@ -161,7 +178,10 @@ from hindsight_crewai import configure, HindsightStorage, HindsightReflectTool
 from crewai.memory.external.external_memory import ExternalMemory
 from crewai import Agent, Crew, Task
 
-configure(hindsight_api_url="http://localhost:8888")
+configure(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+)
 
 storage = HindsightStorage(
     bank_id="research-crew",

hindsight-docs/docs-integrations/pipecat.md

@@ -10,13 +10,11 @@ Persistent long-term memory for [Pipecat](https://github.com/pipecat-ai/pipecat)
 
 ## Quick Start
 
-```bash
-# 1. Start Hindsight (self-hosted)
-pip install hindsight-all
-export HINDSIGHT_API_LLM_API_KEY=your-openai-key
-hindsight-api
+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) and grab an API key — no self-hosting required.
+:::
 
-# 2. Install the integration
+```bash
 pip install hindsight-pipecat
 ```
 
@@ -26,7 +24,8 @@ from hindsight_pipecat import HindsightMemoryService
 
 memory = HindsightMemoryService(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
 )
 
 pipeline = Pipeline([
@@ -41,13 +40,22 @@ pipeline = Pipeline([
 ])
 ```
 
-Or with [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup):
+### Self-hosting (local development)
+
+If you'd rather self-host:
+
+```bash
+# 1. Start Hindsight
+pip install hindsight-all
+export HINDSIGHT_API_LLM_API_KEY=your-openai-key
+hindsight-api
+```
 
 ```python
+# 2. Point pipecat at the local server
 memory = HindsightMemoryService(
     bank_id="user-123",
-    hindsight_api_url="https://api.hindsight.vectorize.io",
-    api_key="hsk_your_token_here",
+    hindsight_api_url="http://localhost:8888",
 )
 ```
 
@@ -91,7 +99,7 @@ HindsightMemoryService(
 from hindsight_pipecat import configure
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",  # Hindsight Cloud (default)
     api_key="hsk_...",
     recall_budget="mid",
 )

hindsight-docs/docs-integrations/pydantic-ai.md

@@ -26,12 +26,16 @@ pip install hindsight-pydantic-ai
 
 ## Quick Start
 
+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) and grab an API key — no self-hosting required.
+:::
+
 ```python
 from hindsight_client import Hindsight
 from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions
 from pydantic_ai import Agent
 
-client = Hindsight(base_url="http://localhost:8888")
+client = Hindsight(base_url="https://api.hindsight.vectorize.io", api_key="hsk_...")
 
 agent = Agent(
     "openai:gpt-4o",
@@ -51,6 +55,16 @@ The agent now has three tools it can call:
 
 The `memory_instructions` callable automatically recalls relevant memories and injects them into the system prompt on every run.
 
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, swap the URL:
+
+```python
+client = Hindsight(base_url="http://localhost:8888")
+```
+
+See the [installation guide](/developer/installation) for self-hosting setup.
+
 ## Tools Only (No Auto-Injection)
 
 If you want the agent to decide when to use memory rather than always injecting context:
@@ -95,7 +109,7 @@ Instead of passing a client to every call, configure once:
 from hindsight_pydantic_ai import configure, create_hindsight_tools
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",  # Hindsight Cloud (default)
     api_key="your-api-key",       # Or set HINDSIGHT_API_KEY env var
     budget="mid",                  # Recall budget: low/mid/high
     max_tokens=4096,               # Max tokens for recall results
@@ -178,7 +192,7 @@ instructions_fn = memory_instructions(
 
 | Parameter | Default | Description |
 |---|---|---|
-| `hindsight_api_url` | Production API | Hindsight API URL |
+| `hindsight_api_url` | Hindsight Cloud (`https://api.hindsight.vectorize.io`) | Hindsight API URL |
 | `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication |
 | `budget` | `"mid"` | Default recall budget level |
 | `max_tokens` | `4096` | Default max tokens for recall |

hindsight-docs/docs-integrations/smolagents.md

@@ -24,13 +24,18 @@ pip install hindsight-smolagents
 
 ## Quick Start
 
+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) and grab an API key — no self-hosting required.
+:::
+
 ```python
 from smolagents import CodeAgent, HfApiModel
 from hindsight_smolagents import create_hindsight_tools
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
 )
 
 agent = CodeAgent(
@@ -48,6 +53,19 @@ The agent now has three tools it can call:
 - **`hindsight_recall`** — Search long-term memory for relevant facts
 - **`hindsight_reflect`** — Synthesize a reasoned answer from memories
 
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, swap the URL:
+
+```python
+tools = create_hindsight_tools(
+    bank_id="user-123",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+)
+```
+
+See the [installation guide](/developer/installation) for self-hosting setup.
+
 ## With Memory Instructions
 
 Pre-recall relevant memories and inject them into the system prompt:
@@ -57,12 +75,12 @@ from hindsight_smolagents import create_hindsight_tools, memory_instructions
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
 )
 
 memories = memory_instructions(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
 )
 
 agent = CodeAgent(
@@ -83,11 +101,11 @@ agent = CodeAgent(
     tools=[
         HindsightRetainTool(
             bank_id="user-123",
-            hindsight_api_url="http://localhost:8888",
+            hindsight_api_url="https://api.hindsight.vectorize.io",
         ),
         HindsightRecallTool(
             bank_id="user-123",
-            hindsight_api_url="http://localhost:8888",
+            hindsight_api_url="https://api.hindsight.vectorize.io",
         ),
     ],
     model=HfApiModel(),
@@ -101,7 +119,7 @@ Include only the tools you need via the factory:
 ```python
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
     enable_retain=True,
     enable_recall=True,
     enable_reflect=False,  # Omit reflect
@@ -116,7 +134,7 @@ Instead of passing connection details to every tool, configure once:
 from hindsight_smolagents import configure, create_hindsight_tools
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
     api_key="your-api-key",       # Or set HINDSIGHT_API_KEY env var
     budget="mid",                  # Recall budget: low/mid/high
     max_tokens=4096,               # Max tokens for recall results
@@ -168,7 +186,7 @@ tools = create_hindsight_tools(bank_id="user-123")
 
 | Parameter | Default | Description |
 |---|---|---|
-| `hindsight_api_url` | Production API | Hindsight API URL |
+| `hindsight_api_url` | Hindsight Cloud (`https://api.hindsight.vectorize.io`) | Hindsight API URL |
 | `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication |
 | `budget` | `"mid"` | Default recall budget level |
 | `max_tokens` | `4096` | Default max tokens for recall |

hindsight-docs/docs-integrations/strands.md

@@ -23,13 +23,18 @@ pip install hindsight-strands
 
 ## Quick Start
 
+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) and grab an API key — no self-hosting required.
+:::
+
 ```python
 from strands import Agent
 from hindsight_strands import create_hindsight_tools
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
 )
 
 agent = Agent(tools=tools)
@@ -43,6 +48,19 @@ The agent now has three tools it can call:
 - **`hindsight_recall`** — Search long-term memory for relevant facts
 - **`hindsight_reflect`** — Synthesize a reasoned answer from memories
 
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, swap the URL:
+
+```python
+tools = create_hindsight_tools(
+    bank_id="user-123",
+    hindsight_api_url="http://localhost:8888",
+)
+```
+
+See the [installation guide](/developer/installation) for self-hosting setup.
+
 ## With Memory Instructions
 
 Pre-recall relevant memories and inject them into the system prompt:
@@ -52,12 +70,14 @@ from hindsight_strands import create_hindsight_tools, memory_instructions
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
 )
 
 memories = memory_instructions(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
 )
 
 agent = Agent(
@@ -81,7 +101,7 @@ from hindsight_strands import create_hindsight_tools, memory_instructions
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    client = Hindsight(base_url="http://localhost:8888", api_key="test-key")
+    client = Hindsight(base_url="https://api.hindsight.vectorize.io", api_key="hsk_...")
     app.state.hindsight_client = client
     try:
         yield
@@ -111,7 +131,8 @@ Include only the tools you need:
 ```python
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
     enable_retain=True,
     enable_recall=True,
     enable_reflect=False,  # Omit reflect
@@ -178,7 +199,7 @@ tools = create_hindsight_tools(bank_id="user-123")
 
 | Parameter | Default | Description |
 |---|---|---|
-| `hindsight_api_url` | Production API | Hindsight API URL |
+| `hindsight_api_url` | Hindsight Cloud (`https://api.hindsight.vectorize.io`) | Hindsight API URL |
 | `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication |
 | `budget` | `"mid"` | Default recall budget level |
 | `max_tokens` | `4096` | Default max tokens for recall |

hindsight-docs/guides/2026-05-04-guide-codex-memory-with-hindsight.md

@@ -46,6 +46,8 @@ The installer places the hook scripts under `~/.hindsight/codex/scripts/`, write
 
 ## Step 2: Connect Codex CLI to Hindsight
 
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — free tier, no self-hosting required.
+
 ```json
 {
   "hindsightApiUrl": "https://api.hindsight.vectorize.io",
@@ -54,7 +56,7 @@ The installer places the hook scripts under `~/.hindsight/codex/scripts/`, write
 }
 ```
 
-Save that as `~/.hindsight/codex.json`. For local daemon mode, you can leave `hindsightApiUrl` empty and export a provider key before starting Codex:
+Save that as `~/.hindsight/codex.json`. If you'd rather self-host with the local daemon (`hindsight-embed`), leave `hindsightApiUrl` empty and export a provider key before starting Codex:
 
 ```bash
 export OPENAI_API_KEY=sk-your-key

hindsight-docs/guides/2026-05-04-guide-crewai-memory-with-hindsight.md

@@ -44,17 +44,20 @@ pip install hindsight-crewai
 
 ## Step 2: Connect CrewAI to Hindsight
 
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — free tier, no self-hosting required.
+
 ```python
 from hindsight_crewai import configure
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
     budget="mid",
     max_tokens=4096,
 )
 ```
 
-If you use [Hindsight Cloud](https://hindsight.vectorize.io), swap the API URL for `https://api.hindsight.vectorize.io` and include your API key.
+If you're self-hosting Hindsight locally instead, swap the API URL for `http://localhost:8888` and drop the `api_key`.
 
 ## Step 3: Wire memory into your runtime
 

hindsight-docs/guides/2026-05-04-guide-pipecat-memory-with-hindsight.md

@@ -44,16 +44,19 @@ pip install hindsight-pipecat
 
 ## Step 2: Connect Pipecat to Hindsight
 
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — free tier, no self-hosting required.
+
 ```python
 from hindsight_pipecat import HindsightMemoryService
 
 memory = HindsightMemoryService(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
 )
 ```
 
-For [Hindsight Cloud](https://hindsight.vectorize.io), set `hindsight_api_url` to `https://api.hindsight.vectorize.io` and pass your API key.
+If you're self-hosting Hindsight locally instead, set `hindsight_api_url` to `http://localhost:8888` and drop the `api_key`.
 
 ## Step 3: Wire memory into your runtime
 
@@ -63,7 +66,8 @@ from hindsight_pipecat import HindsightMemoryService
 
 memory = HindsightMemoryService(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
     recall_budget="mid",
     recall_max_tokens=4096,
 )

hindsight-docs/guides/2026-05-04-guide-pydantic-ai-memory-with-hindsight.md

@@ -44,12 +44,16 @@ pip install hindsight-pydantic-ai
 
 ## Step 2: Connect Pydantic AI to Hindsight
 
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — free tier, no self-hosting required.
+
 ```python
 from hindsight_client import Hindsight
 
-client = Hindsight(base_url="http://localhost:8888")
+client = Hindsight(base_url="https://api.hindsight.vectorize.io", api_key="hsk_...")
 ```
 
+If you're self-hosting Hindsight locally instead, use `Hindsight(base_url="http://localhost:8888")`.
+
 You can also call `configure()` once and create tools without passing a client each time.
 
 ## Step 3: Wire memory into your runtime
@@ -59,7 +63,7 @@ from hindsight_client import Hindsight
 from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions
 from pydantic_ai import Agent
 
-client = Hindsight(base_url="http://localhost:8888")
+client = Hindsight(base_url="https://api.hindsight.vectorize.io", api_key="hsk_...")
 
 agent = Agent(
     "openai:gpt-4o",

hindsight-docs/guides/2026-05-04-guide-smolagents-memory-with-hindsight.md

@@ -44,16 +44,21 @@ pip install hindsight-smolagents
 
 ## Step 2: Connect SmolAgents to Hindsight
 
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — free tier, no self-hosting required.
+
 ```python
 from hindsight_smolagents import configure
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
     budget="mid",
     max_tokens=4096,
 )
 ```
 
+If you're self-hosting Hindsight locally instead, swap the API URL for `http://localhost:8888` and drop the `api_key`.
+
 You can skip global configuration and pass `hindsight_api_url` directly into `create_hindsight_tools()` if you prefer.
 
 ## Step 3: Wire memory into your runtime
@@ -64,12 +69,14 @@ from hindsight_smolagents import create_hindsight_tools, memory_instructions
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
 )
 
 memories = memory_instructions(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
 )
 
 agent = CodeAgent(

hindsight-docs/guides/2026-05-04-guide-strands-memory-with-hindsight.md

@@ -44,16 +44,21 @@ pip install hindsight-strands
 
 ## Step 2: Connect Strands to Hindsight
 
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — free tier, no self-hosting required.
+
 ```python
 from hindsight_strands import configure
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
     budget="mid",
     max_tokens=4096,
 )
 ```
 
+If you're self-hosting Hindsight locally instead, swap the API URL for `http://localhost:8888` and drop the `api_key`.
+
 ## Step 3: Wire memory into your runtime
 
 ```python
@@ -62,12 +67,14 @@ from hindsight_strands import create_hindsight_tools, memory_instructions
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
 )
 
 memories = memory_instructions(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
 )
 
 agent = Agent(

hindsight-integrations/codex/README.md

@@ -20,6 +20,8 @@ Three Codex hooks keep memory in sync automatically:
 
 ## Installation
 
+> ✨ **Recommended: [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** — free tier, no self-hosting required. Skip the local daemon entirely.
+
 ```bash
 curl -fsSL https://hindsight.vectorize.io/get-codex | bash
 ```
@@ -49,7 +51,9 @@ For personal overrides (stable across updates), create `~/.hindsight/codex.json`
 }
 ```
 
-### Hindsight Cloud
+### Hindsight Cloud (recommended)
+
+> ✨ Sign up free at [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — no self-hosting, no LLM API key, no daemon to manage.
 
 ```json
 {
@@ -58,9 +62,9 @@ For personal overrides (stable across updates), create `~/.hindsight/codex.json`
 }
 ```
 
-### Local daemon (hindsight-embed)
+### Self-hosting: local daemon (`hindsight-embed`)
 
-Set an LLM API key and Hindsight will start the local server automatically:
+If you'd rather run Hindsight locally, leave `hindsightApiUrl` empty and set an LLM API key — Hindsight will start the local server automatically:
 
 ```bash
 export OPENAI_API_KEY=sk-your-key

hindsight-integrations/crewai/README.md

@@ -18,13 +18,18 @@ pip install hindsight-crewai
 
 ## Quick Start
 
+> ✨ **Recommended: [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** — free tier, no self-hosting required. Sign up and grab an API key in under a minute.
+
 ```python
 from hindsight_crewai import configure, HindsightStorage
 from crewai.memory.external.external_memory import ExternalMemory
 from crewai import Agent, Crew, Task
 
-# Step 1: Configure connection
-configure(hindsight_api_url="http://localhost:8888")
+# Step 1: Point CrewAI at Hindsight Cloud
+configure(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
+)
 
 # Step 2: Create crew with Hindsight-backed memory
 crew = Crew(
@@ -49,6 +54,16 @@ That's it. CrewAI will automatically:
 
 Memories persist across crew runs, so your crew learns over time.
 
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, point at your local server instead:
+
+```python
+configure(hindsight_api_url="http://localhost:8888")
+```
+
+See the [Hindsight installation guide](https://hindsight.vectorize.io/developer/installation) for self-hosting setup.
+
 ## Per-Agent Memory Banks
 
 Give each agent its own isolated memory bank:
@@ -111,7 +126,7 @@ storage = HindsightStorage(
 from hindsight_crewai import configure
 
 configure(
-    hindsight_api_url="http://localhost:8888",  # Default: production API
+    hindsight_api_url="https://api.hindsight.vectorize.io",  # Hindsight Cloud (default)
     api_key="your-api-key",                     # Or set HINDSIGHT_API_KEY env var
     budget="mid",                               # Recall budget: low/mid/high
     max_tokens=4096,                            # Max tokens for recall results
@@ -143,7 +158,7 @@ See the [CrewAI memory example](https://github.com/vectorize-io/hindsight-cookbo
 
 | Parameter | Default | Description |
 |---|---|---|
-| `hindsight_api_url` | Production API | Hindsight API URL |
+| `hindsight_api_url` | Hindsight Cloud (`https://api.hindsight.vectorize.io`) | Hindsight API URL |
 | `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication |
 | `budget` | `"mid"` | Recall budget level (low/mid/high) |
 | `max_tokens` | `4096` | Maximum tokens for recall results |

hindsight-integrations/crewai/hindsight_crewai/__init__.py

@@ -9,7 +9,10 @@ Basic usage::
     from crewai.memory.external.external_memory import ExternalMemory
     from crewai import Crew
 
-    configure(hindsight_api_url="http://localhost:8888")
+    configure(
+        hindsight_api_url="https://api.hindsight.vectorize.io",
+        api_key="hsk_...",
+    )
 
     crew = Crew(
         agents=[...],

hindsight-integrations/crewai/hindsight_crewai/storage.py

@@ -14,7 +14,7 @@ from typing import Any, Callable
 from crewai.memory.storage.interface import Storage
 
 from ._compat import call_sync
-from .config import get_config
+from .config import DEFAULT_HINDSIGHT_API_URL, get_config
 from .errors import HindsightError
 
 logger = logging.getLogger(__name__)
@@ -55,7 +55,10 @@ class HindsightStorage(Storage):
         from hindsight_crewai import configure, HindsightStorage
         from crewai.memory.external.external_memory import ExternalMemory
 
-        configure(hindsight_api_url="http://localhost:8888")
+        configure(
+            hindsight_api_url="https://api.hindsight.vectorize.io",
+            api_key="hsk_...",
+        )
         storage = HindsightStorage(bank_id="my-crew")
         external_memory = ExternalMemory(storage=storage)
     """
@@ -84,7 +87,7 @@ class HindsightStorage(Storage):
 
         # Resolve settings: constructor args override global config
         config = get_config()
-        self._api_url = hindsight_api_url or (config.hindsight_api_url if config else "http://localhost:8888")
+        self._api_url = hindsight_api_url or (config.hindsight_api_url if config else DEFAULT_HINDSIGHT_API_URL)
         self._api_key = api_key or (config.api_key if config else None)
         self._budget = budget or (config.budget if config else "mid")
         self._max_tokens = max_tokens or (config.max_tokens if config else 4096)

hindsight-integrations/crewai/hindsight_crewai/tools.py

@@ -15,7 +15,7 @@ from crewai.tools import BaseTool
 from pydantic import Field, PrivateAttr
 
 from ._compat import call_sync
-from .config import get_config
+from .config import DEFAULT_HINDSIGHT_API_URL, get_config
 from .errors import HindsightError
 
 logger = logging.getLogger(__name__)
@@ -76,7 +76,7 @@ class HindsightReflectTool(BaseTool):
             from hindsight_client import Hindsight
 
             config = get_config()
-            api_url = self.hindsight_api_url or (config.hindsight_api_url if config else "http://localhost:8888")
+            api_url = self.hindsight_api_url or (config.hindsight_api_url if config else DEFAULT_HINDSIGHT_API_URL)
             api_key = self.api_key or (config.api_key if config else None)
 
             client = Hindsight(

hindsight-integrations/crewai/tests/test_storage.py

@@ -254,6 +254,6 @@ class TestHindsightStorage:
     def test_falls_back_to_defaults_without_config(self):
         reset_config()
         storage = HindsightStorage(bank_id="test")
-        assert storage._api_url == "http://localhost:8888"
+        assert storage._api_url == "https://api.hindsight.vectorize.io"
         assert storage._budget == "mid"
         assert storage._max_tokens == 4096

hindsight-integrations/pipecat/README.md

@@ -8,13 +8,16 @@ Persistent long-term memory for [Pipecat](https://github.com/pipecat-ai/pipecat)
 pip install hindsight-pipecat
 ```
 
+> ✨ **Recommended: [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** — free tier, no self-hosting required. Sign up and grab an API key in under a minute.
+
 ```python
 from pipecat.pipeline.pipeline import Pipeline
 from hindsight_pipecat import HindsightMemoryService
 
 memory = HindsightMemoryService(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
 )
 
 pipeline = Pipeline([
@@ -29,16 +32,19 @@ pipeline = Pipeline([
 ])
 ```
 
-Or with [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup):
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, point at your local server instead:
 
 ```python
 memory = HindsightMemoryService(
     bank_id="user-123",
-    hindsight_api_url="https://api.hindsight.vectorize.io",
-    api_key="hsk_your_token_here",
+    hindsight_api_url="http://localhost:8888",
 )
 ```
 
+See the [Hindsight installation guide](https://hindsight.vectorize.io/developer/installation) for self-hosting setup.
+
 ## How It Works
 
 ```
@@ -92,7 +98,7 @@ HindsightMemoryService(
 from hindsight_pipecat import configure
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",  # Hindsight Cloud (default)
     api_key="hsk_...",
     recall_budget="mid",
 )

hindsight-integrations/pydantic-ai/README.md

@@ -18,12 +18,14 @@ pip install hindsight-pydantic-ai
 
 ## Quick Start
 
+> ✨ **Recommended: [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** — free tier, no self-hosting required. Sign up and grab an API key in under a minute.
+
 ```python
 from hindsight_client import Hindsight
 from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions
 from pydantic_ai import Agent
 
-client = Hindsight(base_url="http://localhost:8888")
+client = Hindsight(base_url="https://api.hindsight.vectorize.io", api_key="hsk_...")
 
 agent = Agent(
     "openai:gpt-4o",
@@ -43,6 +45,16 @@ The agent now has three tools it can call:
 
 The `memory_instructions` callable automatically recalls relevant memories and injects them into the system prompt on every run.
 
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, point at your local server instead:
+
+```python
+client = Hindsight(base_url="http://localhost:8888")
+```
+
+See the [Hindsight installation guide](https://hindsight.vectorize.io/developer/installation) for self-hosting setup.
+
 ## Tools Only (No Auto-Injection)
 
 If you want the agent to decide when to use memory (rather than always injecting context):
@@ -87,7 +99,7 @@ Instead of passing a client to every call, configure once:
 from hindsight_pydantic_ai import configure, create_hindsight_tools
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",  # Hindsight Cloud (default)
     api_key="your-api-key",       # Or set HINDSIGHT_API_KEY env var
     budget="mid",                  # Recall budget: low/mid/high
     max_tokens=4096,               # Max tokens for recall results
@@ -170,7 +182,7 @@ instructions_fn = memory_instructions(
 
 | Parameter | Default | Description |
 |---|---|---|
-| `hindsight_api_url` | Production API | Hindsight API URL |
+| `hindsight_api_url` | Hindsight Cloud (`https://api.hindsight.vectorize.io`) | Hindsight API URL |
 | `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication |
 | `budget` | `"mid"` | Default recall budget level |
 | `max_tokens` | `4096` | Default max tokens for recall |

hindsight-integrations/pydantic-ai/hindsight_pydantic_ai/__init__.py

@@ -9,7 +9,7 @@ Basic usage::
     from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions
     from pydantic_ai import Agent
 
-    client = Hindsight(base_url="http://localhost:8888")
+    client = Hindsight(base_url="https://api.hindsight.vectorize.io", api_key="hsk_...")
 
     agent = Agent(
         "openai:gpt-4o",

hindsight-integrations/smolagents/README.md

@@ -18,13 +18,16 @@ pip install hindsight-smolagents
 
 ## Quick Start
 
+> ✨ **Recommended: [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** — free tier, no self-hosting required. Sign up and grab an API key in under a minute.
+
 ```python
 from smolagents import CodeAgent, HfApiModel
 from hindsight_smolagents import create_hindsight_tools
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
 )
 
 agent = CodeAgent(
@@ -42,6 +45,19 @@ The agent now has three tools it can call:
 - **`hindsight_recall`** — Search long-term memory for relevant facts
 - **`hindsight_reflect`** — Synthesize a reasoned answer from memories
 
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, point at your local server instead:
+
+```python
+tools = create_hindsight_tools(
+    bank_id="user-123",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+)
+```
+
+See the [Hindsight installation guide](https://hindsight.vectorize.io/developer/installation) for self-hosting setup.
+
 ## With Memory Instructions
 
 Pre-recall relevant memories and inject them into the system prompt:
@@ -51,12 +67,12 @@ from hindsight_smolagents import create_hindsight_tools, memory_instructions
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
 )
 
 memories = memory_instructions(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
 )
 
 agent = CodeAgent(
@@ -77,11 +93,11 @@ agent = CodeAgent(
     tools=[
         HindsightRetainTool(
             bank_id="user-123",
-            hindsight_api_url="http://localhost:8888",
+            hindsight_api_url="https://api.hindsight.vectorize.io",
         ),
         HindsightRecallTool(
             bank_id="user-123",
-            hindsight_api_url="http://localhost:8888",
+            hindsight_api_url="https://api.hindsight.vectorize.io",
         ),
     ],
     model=HfApiModel(),
@@ -95,7 +111,7 @@ Include only the tools you need via the factory:
 ```python
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
     enable_retain=True,
     enable_recall=True,
     enable_reflect=False,  # Omit reflect
@@ -110,7 +126,7 @@ Instead of passing connection details to every tool, configure once:
 from hindsight_smolagents import configure, create_hindsight_tools
 
 configure(
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",  # Hindsight Cloud (default)
     api_key="your-api-key",       # Or set HINDSIGHT_API_KEY env var
     budget="mid",                  # Recall budget: low/mid/high
     max_tokens=4096,               # Max tokens for recall results
@@ -162,7 +178,7 @@ tools = create_hindsight_tools(bank_id="user-123")
 
 | Parameter | Default | Description |
 |---|---|---|
-| `hindsight_api_url` | Production API | Hindsight API URL |
+| `hindsight_api_url` | Hindsight Cloud (`https://api.hindsight.vectorize.io`) | Hindsight API URL |
 | `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication |
 | `budget` | `"mid"` | Default recall budget level |
 | `max_tokens` | `4096` | Default max tokens for recall |

hindsight-integrations/smolagents/hindsight_smolagents/__init__.py

@@ -10,7 +10,8 @@ Basic usage::
 
     tools = create_hindsight_tools(
         bank_id="user-123",
-        hindsight_api_url="http://localhost:8888",
+        hindsight_api_url="https://api.hindsight.vectorize.io",
+        api_key="hsk_...",
     )
 
     agent = CodeAgent(

hindsight-integrations/strands/README.md

@@ -17,13 +17,16 @@ pip install hindsight-strands
 
 ## Quick Start
 
+> ✨ **Recommended: [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** — free tier, no self-hosting required. Sign up and grab an API key in under a minute.
+
 ```python
 from strands import Agent
 from hindsight_strands import create_hindsight_tools
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
 )
 
 agent = Agent(tools=tools)
@@ -38,6 +41,19 @@ The agent now has three tools it can call:
 - **`hindsight_recall`** — Search long-term memory for relevant facts
 - **`hindsight_reflect`** — Synthesize a reasoned answer from memories
 
+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, point at your local server instead:
+
+```python
+tools = create_hindsight_tools(
+    bank_id="user-123",
+    hindsight_api_url="http://localhost:8888",
+)
+```
+
+See the [Hindsight installation guide](https://hindsight.vectorize.io/developer/installation) for self-hosting setup.
+
 ## With Memory Instructions
 
 Pre-recall relevant memories and inject them into the system prompt:
@@ -47,12 +63,14 @@ from hindsight_strands import create_hindsight_tools, memory_instructions
 
 tools = create_hindsight_tools(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
 )
 
 memories = memory_instructions(
     bank_id="user-123",
-    hindsight_api_url="http://localhost:8888",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
 )
 
 agent = Agent(

hindsight-integrations/strands/hindsight_strands/__init__.py

@@ -10,7 +10,8 @@ Basic usage::
 
     tools = create_hindsight_tools(
         bank_id="user-123",
-        hindsight_api_url="http://localhost:8888",
+        hindsight_api_url="https://api.hindsight.vectorize.io",
+        api_key="hsk_...",
     )
 
     agent = Agent(tools=tools)

skills/hindsight-docs/references/developer/models.md

@@ -30,6 +30,7 @@ Used for fact extraction, entity resolution, mental model consolidation, and ans
 - MiniMax
 - DeepSeek
 - z.ai
+- opencode-go
 - Volcano Engine
 - OpenRouter
 - OpenAI Codex

skills/hindsight-docs/references/faq.md

@@ -76,6 +76,7 @@ Browse all supported integrations in the Integrations Hub.
 - MiniMax
 - DeepSeek
 - z.ai
+- opencode-go
 - Volcano Engine
 - OpenRouter
 - OpenAI Codex