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

docs(nemoclaw): add Cloud API URL to quickstart and config default (#1700 )
* docs(nemoclaw): prioritize Hindsight Cloud with callout banners * feat(nemoclaw): default --api-url to Hindsight Cloud, make it optional
2026-05-22 09:53:48 -04:00 · 2026-05-22 09:52:58 -04:00 · 2026-05-22 09:37:02 -04:00 · 2026-05-22 09:36:15 -04:00 · 2026-05-22 09:35:29 -04:00 · 2026-05-22 09:33:44 -04:00
48 changed files with 396 additions and 141 deletions
@@ -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)
@@ -40,6 +40,10 @@ pip install hindsight-agentcore

 ## 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
 import os
 from hindsight_agentcore import HindsightRuntimeAdapter, TurnContext, configure
@@ -24,6 +24,10 @@ pip install hindsight-agno

 ## 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 agno.agent import Agent
 from agno.models.openai import OpenAIChat
@@ -33,7 +37,8 @@ agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        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
    )],
 )

@@ -41,6 +46,10 @@ agent.print_response("Remember that I prefer dark mode")
 agent.print_response("What are my preferences?")
 ```

+### Self-hosting (local development)
+
+If you're running Hindsight locally with `./scripts/dev/start-api.sh`, swap the URL to `http://localhost:8888`. See the [installation guide](/developer/installation) for setup.
+
 The agent now has three tools it can call:

 - **`retain_memory`** — Store information to long-term memory
@@ -58,11 +67,11 @@ agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        bank_id="user-123",
-        hindsight_api_url="http://localhost:8888",
+        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
    instructions=[memory_instructions(
        bank_id="user-123",
-        hindsight_api_url="http://localhost:8888",
+        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
 )
 ```
@@ -74,7 +83,7 @@ Include only the tools you need:
 ```python
 tools = [HindsightTools(
    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
@@ -93,7 +102,7 @@ The bank ID is resolved in order:
 # Per-user banks from RunContext
 agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
-    tools=[HindsightTools(hindsight_api_url="http://localhost:8888")],
+    tools=[HindsightTools(hindsight_api_url="https://api.hindsight.vectorize.io")],
    user_id="user-123",  # Used as bank_id
 )

@@ -105,7 +114,7 @@ agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        bank_resolver=resolve_bank,
-        hindsight_api_url="http://localhost:8888",
+        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
 )
 ```
@@ -118,7 +127,7 @@ Instead of passing connection details to every toolkit, configure once:
 from hindsight_agno import configure, HindsightTools

 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
@@ -171,7 +180,7 @@ tools = [HindsightTools(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 |
@@ -10,6 +10,12 @@ We built `@vectorize-io/hindsight-chat` to give [Vercel Chat SDK](https://github

 [View Changelog →](/changelog/integrations/chat)

+## Setup
+
+:::tip Hindsight Cloud (recommended)
+[Sign up free](https://ui.hindsight.vectorize.io/signup) — get an API key instantly, no infrastructure to run. Self-hosting? See the [installation guide](/developer/installation).
+:::
+
 ## Installation

 ```bash
@@ -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:

@@ -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",
@@ -28,6 +28,10 @@ After install, the **Hindsight** plugin appears under **Tools** in the workflow

 ## Setup

+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) and grab an API key — no self-hosting required.
+:::
+
 1. **Sign up** at [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) (free tier) or [self-host](/developer/installation)
 2. **Get an API key** from the Hindsight dashboard
 3. **In Dify**, open the Hindsight plugin and add credentials:
@@ -35,6 +35,10 @@ Restart n8n; the **Hindsight** node appears in the node panel.

 ## Setup

+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) and grab an API key — no self-hosting required.
+:::
+
 1. **Sign up** at [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) (free tier) or [self-host](/developer/installation)
 2. **Get an API key** from the Hindsight dashboard
 3. **In n8n**, create a new **Hindsight API** credential with your API URL (defaults to Hindsight Cloud) and the `hsk_...` key
@@ -14,16 +14,17 @@ NemoClaw runs [OpenClaw](https://openclaw.ai) inside an OpenShell sandbox with c

 ## Quick Start

+:::tip Hindsight Cloud (recommended)
+[Sign up free](https://ui.hindsight.vectorize.io/signup) — get an API key instantly, no infrastructure to run.
+:::
+
 ```bash
 npx @vectorize-io/hindsight-nemoclaw setup \
  --sandbox my-assistant \
-  --api-url https://api.hindsight.vectorize.io \
  --api-token <your-api-key> \
  --bank-prefix my-sandbox
 ```

-Get an API key at [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup).
-
 You'll see output like:

 ```
@@ -79,8 +80,8 @@ hindsight-nemoclaw setup [options]

 Options:
  --sandbox <name>       NemoClaw sandbox name (required)
-  --api-url <url>        Hindsight API URL (required)
  --api-token <token>    Hindsight API token (required)
+  --api-url <url>        Hindsight API URL (default: https://api.hindsight.vectorize.io)
  --bank-prefix <prefix> Memory bank prefix (default: "nemoclaw")
  --skip-policy          Skip sandbox network policy update
  --skip-plugin-install  Skip openclaw plugin installation
@@ -20,17 +20,18 @@ Then configure in **Settings → Plugins → Hindsight Memory**.

 ## Prerequisites

-Either:
+:::tip Hindsight Cloud (recommended)
+[Sign up free](https://ui.hindsight.vectorize.io/signup) — no infrastructure to run. Skip straight to Configuration below.
+:::
+
+**Self-hosting alternative** — run Hindsight locally:

 ```bash
-# Self-hosted
 pip install hindsight-all
 export HINDSIGHT_API_LLM_API_KEY=your-openai-key
 hindsight-api
 ```

-Or [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — no self-hosting required.
-
 ## How It Works

 ```
@@ -58,7 +59,7 @@ Memory is keyed to `companyId` + `agentId` — never to the run ID — so it acc

 | Field | Default | Description |
 |-------|---------|-------------|
-| `hindsightApiUrl` | `http://localhost:8888` | Hindsight server URL |
+| `hindsightApiUrl` | `https://api.hindsight.vectorize.io` | Hindsight server URL (Cloud default; use `http://localhost:8888` for self-hosted) |
 | `hindsightApiKeyRef` | — | Paperclip secret name holding Hindsight Cloud API key |
 | `bankGranularity` | `["company", "agent"]` | Memory isolation: per company+agent, per company, or per agent |
 | `recallBudget` | `mid` | `low` = fastest, `mid` = balanced, `high` = most thorough |
@@ -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",
 )
@@ -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 |
@@ -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 |
@@ -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 |
@@ -31,7 +31,7 @@ This guide covers the quick-start path, the HTTP and process adapter patterns, b
 Before you start, make sure you have:

 - A Paperclip agent already running through the heartbeat model
- A reachable Hindsight backend, either self-hosted or [Hindsight Cloud](https://hindsight.vectorize.io)
+- A Hindsight backend: [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) (recommended — free tier, no infrastructure to run) or [self-hosted](https://hindsight.vectorize.io/developer/installation)
 - Stable identifiers for `companyId` and `agentId`

 The identifier design matters. Paperclip's default isolation pattern works well because it maps cleanly to a multi-tenant setup.
@@ -44,6 +44,8 @@ pip install hindsight-agentcore

 ## Step 2: Connect AgentCore Runtime to Hindsight

+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — free tier, no self-hosting required.
+
 ```python
 import os
 from hindsight_agentcore import configure
@@ -54,6 +56,8 @@ configure(
 )
 ```

+If you'd rather self-host on AWS (ECS/EKS with RDS PostgreSQL + pgvector), set `hindsight_api_url` to your in-VPC Hindsight endpoint.
+
 ## Step 3: Wire memory into your runtime

 ```python
@@ -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
@@ -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

@@ -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,
 )
@@ -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",
@@ -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(
@@ -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(
@@ -34,6 +34,8 @@ pip install hindsight-agentcore

 ## 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
 import os
 from hindsight_agentcore import HindsightRuntimeAdapter, TurnContext, configure
@@ -18,6 +18,8 @@ pip install hindsight-agno

 ## 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 agno.agent import Agent
 from agno.models.openai import OpenAIChat
@@ -27,7 +29,8 @@ agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        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
    )],
 )

@@ -41,6 +44,19 @@ The agent now has three tools it can call:
 - **`recall_memory`** — Search long-term memory for relevant facts
 - **`reflect_on_memory`** — 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=[HindsightTools(
+    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:
@@ -52,11 +68,11 @@ agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        bank_id="user-123",
-        hindsight_api_url="http://localhost:8888",
+        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
    instructions=[memory_instructions(
        bank_id="user-123",
-        hindsight_api_url="http://localhost:8888",
+        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
 )
 ```
@@ -68,7 +84,7 @@ Include only the tools you need:
 ```python
 tools = [HindsightTools(
    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
@@ -87,7 +103,7 @@ The bank ID is resolved in order:
 # Per-user banks from RunContext
 agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
-    tools=[HindsightTools(hindsight_api_url="http://localhost:8888")],
+    tools=[HindsightTools(hindsight_api_url="https://api.hindsight.vectorize.io")],
    user_id="user-123",  # Used as bank_id
 )

@@ -99,7 +115,7 @@ agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        bank_resolver=resolve_bank,
-        hindsight_api_url="http://localhost:8888",
+        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
 )
 ```
@@ -112,7 +128,7 @@ Instead of passing connection details to every toolkit, configure once:
 from hindsight_agno import configure, HindsightTools

 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
@@ -165,7 +181,7 @@ tools = [HindsightTools(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 |
@@ -13,11 +13,11 @@ Basic usage::
        model=OpenAIChat(id="gpt-4o-mini"),
        tools=[HindsightTools(
            bank_id="user-123",
-            hindsight_api_url="http://localhost:8888",
+            hindsight_api_url="https://api.hindsight.vectorize.io",
        )],
        instructions=[memory_instructions(
            bank_id="user-123",
-            hindsight_api_url="http://localhost:8888",
+            hindsight_api_url="https://api.hindsight.vectorize.io",
        )],
    )

@@ -96,7 +96,8 @@ class HindsightTools(Toolkit):
            model=OpenAIChat(id="gpt-4o-mini"),
            tools=[HindsightTools(
                bank_id="user-123",
-                hindsight_api_url="http://localhost:8888",
+                hindsight_api_url="https://api.hindsight.vectorize.io",
+                api_key="hsk_...",
            )],
        )
        agent.print_response("Remember that I prefer dark mode")
@@ -2,6 +2,12 @@

 Give your [Vercel Chat SDK](https://github.com/vercel/chat) bots persistent, per-user memory with a single handler wrapper. Works with Slack, Discord, Teams, Google Chat, GitHub, and Linear.

+## Setup
+
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — sign up free, get an API key, and you're ready. No infrastructure to run.
+>
+> Self-hosting alternative: [installation guide](https://hindsight.vectorize.io/developer/installation).
+
 ## Quick Start

 ```bash
@@ -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
@@ -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 |
@@ -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=[...],
@@ -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)
@@ -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(
@@ -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
@@ -10,6 +10,8 @@ Three tools — **Retain**, **Recall**, **Reflect** — drop into any Dify workf

 ## Setup

+> ✨ **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.
+
 1. **Sign up** at [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) (free tier) or [self-host](https://hindsight.vectorize.io/developer/installation).
 2. **Get an API key** from the Hindsight dashboard.
 3. **In Dify**, install this plugin (Marketplace or upload `.difypkg`), then add credentials:
@@ -27,6 +27,8 @@ Restart n8n and the **Hindsight** node appears in the node panel.

 ## Setup

+> ✨ **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.
+
 1. **Create a Hindsight account** at [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) (free tier available) — or self-host with the [Hindsight installer](https://hindsight.vectorize.io/developer/installation)
 2. **Get an API key** from the Hindsight dashboard
 3. **In n8n**, create a new **Hindsight API** credential:
@@ -6,16 +6,15 @@ NemoClaw runs [OpenClaw](https://openclaw.ai) inside an OpenShell sandbox with s

 ## Quick Start

+> ✨ **Recommended:** Use [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — sign up free and get an API key instantly. No infrastructure to run.
+
 ```bash
 npx @vectorize-io/hindsight-nemoclaw setup \
  --sandbox my-assistant \
-  --api-url https://api.hindsight.vectorize.io \
  --api-token <your-api-key> \
  --bank-prefix my-sandbox
 ```

-Get an API key at [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup).
-
 ## Documentation

 Full setup guide, pitfalls, and troubleshooting:
@@ -31,8 +30,8 @@ hindsight-nemoclaw setup [options]

 Options:
  --sandbox <name>       NemoClaw sandbox name (required)
-  --api-url <url>        Hindsight API URL (required)
  --api-token <token>    Hindsight API token (required)
+  --api-url <url>        Hindsight API URL (default: https://api.hindsight.vectorize.io)
  --bank-prefix <prefix> Memory bank prefix (default: "nemoclaw")
  --skip-policy          Skip sandbox network policy update
  --skip-plugin-install  Skip openclaw plugin installation
@@ -10,11 +10,11 @@ Usage:

 Required options:
  --sandbox <name>       NemoClaw sandbox name (e.g. my-assistant)
-  --api-url <url>        Hindsight Cloud API URL (https://api.hindsight.vectorize.io)
  --api-token <token>    Hindsight API key from https://ui.hindsight.vectorize.io
  --bank-prefix <prefix> Bank ID prefix (memories go to <prefix>-openclaw)

 Optional options:
+  --api-url <url>        Hindsight API URL (default: https://api.hindsight.vectorize.io)
  --skip-policy          Skip the openshell policy update
  --skip-plugin-install  Skip openclaw plugins install
  --dry-run              Print what would be changed without executing
@@ -23,7 +23,6 @@ Optional options:
 Example:
  hindsight-nemoclaw setup \\
    --sandbox my-assistant \\
-    --api-url https://api.hindsight.vectorize.io \\
    --api-token hsk_abc123 \\
    --bank-prefix my-sandbox
 `);
@@ -49,13 +48,12 @@ function parseArgs(argv: string[]): CliArgs | null {
  };

  const sandbox = get("--sandbox");
-  const apiUrl = get("--api-url");
+  const apiUrl = get("--api-url") ?? "https://api.hindsight.vectorize.io";
  const apiToken = get("--api-token");
  const bankPrefix = get("--bank-prefix");

  const missing: string[] = [];
  if (!sandbox) missing.push("--sandbox");
-  if (!apiUrl) missing.push("--api-url");
  if (!apiToken) missing.push("--api-token");
  if (!bankPrefix) missing.push("--bank-prefix");

@@ -20,26 +20,25 @@ Then configure in **Settings → Plugins → Hindsight Memory**.

 ## Prerequisites

-Either:
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — sign up free, get an API key, and skip the self-hosting setup entirely.
+
+**Self-hosting alternative** — run Hindsight locally:

 ```bash
-# Self-hosted (runs locally)
 pip install hindsight-all
 export HINDSIGHT_API_LLM_API_KEY=your-openai-key
 hindsight-api
 ```

-Or [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — no self-hosting required.
-
 ## Configuration

-| Field                | Default                 | Description                                                    |
-| -------------------- | ----------------------- | -------------------------------------------------------------- |
-| `hindsightApiUrl`    | `http://localhost:8888` | Hindsight server URL                                           |
-| `hindsightApiKeyRef` | —                       | Paperclip secret name holding Hindsight Cloud API key          |
-| `bankGranularity`    | `["company", "agent"]`  | Memory isolation: per company+agent, per company, or per agent |
-| `recallBudget`       | `mid`                   | `low` = fastest, `mid` = balanced, `high` = most thorough      |
-| `autoRetain`         | `true`                  | Automatically retain run output after every run                |
+| Field                | Default                              | Description                                                                       |
+| -------------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
+| `hindsightApiUrl`    | `https://api.hindsight.vectorize.io` | Hindsight server URL (Cloud default; use `http://localhost:8888` for self-hosted) |
+| `hindsightApiKeyRef` | —                                    | Paperclip secret name holding Hindsight Cloud API key                             |
+| `bankGranularity`    | `["company", "agent"]`               | Memory isolation: per company+agent, per company, or per agent                    |
+| `recallBudget`       | `mid`                                | `low` = fastest, `mid` = balanced, `high` = most thorough                         |
+| `autoRetain`         | `true`                               | Automatically retain run output after every run                                   |

 ## Bank ID Format

@@ -31,8 +31,8 @@ const manifest: PaperclipPluginManifestV1 = {
        type: "string",
        title: "Hindsight API URL",
        description:
-          "Base URL of your Hindsight instance. Use http://localhost:8888 for self-hosted.",
-        default: "http://localhost:8888",
+          "Base URL of your Hindsight instance. Defaults to Hindsight Cloud. Use http://localhost:8888 for self-hosted.",
+        default: "https://api.hindsight.vectorize.io",
      },
      hindsightApiKeyRef: {
        type: "string",
@@ -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",
 )
@@ -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 |
@@ -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",
@@ -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 |
@@ -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(
@@ -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(
@@ -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)
@@ -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
@@ -76,6 +76,7 @@ Browse all supported integrations in the Integrations Hub.
 - MiniMax
 - DeepSeek
 - z.ai
+- opencode-go
 - Volcano Engine
 - OpenRouter
 - OpenAI Codex
Author	SHA1	Message	Date
Ben	73bbe5f736	Merge branch 'main' into docs-chat-cloud-first	2026-05-22 09:53:48 -04:00
Ben	806fbcd41c	docs(nemoclaw): add Cloud API URL to quickstart and config default (#1700 ) * docs(nemoclaw): prioritize Hindsight Cloud with callout banners * feat(nemoclaw): default --api-url to Hindsight Cloud, make it optional	2026-05-22 09:52:58 -04:00
Ben	a75c3c85ad	docs(paperclip): add Cloud API URL to quickstart and config default (#1699 ) * docs(paperclip): prioritize Hindsight Cloud in setup docs and config default * style(paperclip): align table columns after linter reformat	2026-05-22 09:37:02 -04:00
Ben	0db9f3da19	docs(dify): add Cloud Recommended callout (#1698 ) dify already led with Cloud signup — adds the explicit ✨ Recommended banner for visual consistency.	2026-05-22 09:36:15 -04:00
Ben	8940710c72	docs(n8n): add Cloud Recommended callout (#1697 ) n8n already led with Cloud signup — adds the explicit ✨ Recommended banner to README and docs page Setup sections for visual consistency with the other cloud-first integrations.	2026-05-22 09:35:29 -04:00
Ben	6252643de0	docs(agno): prioritize Hindsight Cloud in quickstart (#1696 ) Lead README + docs Quick Start with Cloud sign-up + Cloud API URL. Bulk-replace localhost:8888 examples with Cloud URL. Demote self-hosted to a 'Self-hosting (local development)' section below. Update docstring examples in __init__.py and tools.py.	2026-05-22 09:33:44 -04:00
Ben	3fce309c0d	docs(agentcore): add Cloud Recommended callout in quickstart (#1694 ) Adds ✨ Recommended Hindsight Cloud callout to README + docs + guide Quick Start sections. agentcore already led with Cloud URL in code examples — this just makes the recommendation explicit.	2026-05-22 09:32:33 -04:00
Ben	3fc361aabd	docs(codex): prioritize Hindsight Cloud over local daemon (#1693 ) Add Cloud Recommended callouts to README + docs + guide. Reframe the 'Local Daemon' section as the self-hosting alternative rather than a peer option. No code default changes — codex still defaults to empty hindsightApiUrl (local daemon) to avoid breaking existing local users.	2026-05-22 09:31:43 -04:00
Ben	f559ae1649	docs(smolagents): prioritize Hindsight Cloud in quickstart (#1692 ) 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.	2026-05-22 09:17:39 -04:00
Ben	8ed9a4ebb2	docs(pydantic-ai): prioritize Hindsight Cloud in quickstart (#1691 ) Lead README/docs/guide Quick Start with Cloud sign-up + Cloud base_url example; demote self-hosted localhost:8888 to a 'Self-hosting (local development)' section below. Update docstring example in __init__.py.	2026-05-22 09:17:07 -04:00
Ben	722aa902fb	Regenerate hindsight-docs skill references (#1686 ) Adds opencode-go to the integration lists in the generated skill references. Picked up by the generate-docs-skill.sh pre-commit hook as drift from the hindsight-docs sources on main.	2026-05-22 09:16:27 -04:00
Ben	5c7e783e18	docs(pipecat): prioritize Hindsight Cloud in quickstart (#1695 ) Lead README/docs/guide Quick Start with Cloud, demote self-hosted to its own section. Updates configure() global example to Cloud default.	2026-05-22 09:15:48 -04:00
Ben	e779f10fc7	docs(strands): prioritize Hindsight Cloud in quickstart (#1690 ) Lead README/docs/guide Quick Start with Hindsight Cloud sign-up and Cloud API URL example; demote self-hosted localhost:8888 to a 'Self-hosting (local development)' section below. Update docstring example in __init__.py to show Cloud-first usage. Includes 2-line incidental skills/hindsight-docs/ regeneration drift.	2026-05-22 09:15:24 -04:00
Ben	1b2c9f63aa	docs(crewai): prioritize Hindsight Cloud in quickstart (#1689 ) - Lead README/docs/guide Quick Start with Hindsight Cloud sign-up and the Cloud API URL example; demote self-hosted localhost:8888 to a "Self-hosting (local development)" section below. - Fix unconfigured-fallback inconsistency in HindsightStorage and HindsightReflectTool: previously fell back to localhost:8888 even though the documented default is Cloud. Now both fallbacks use DEFAULT_HINDSIGHT_API_URL. - Update docstring examples in __init__.py and storage.py to reflect the Cloud-first default. - Update fallback assertion in tests/test_storage.py.	2026-05-22 09:14:56 -04:00
Ben	6bdb1a08f5	docs(chat): add Hindsight Cloud setup callout to README and docs	2026-05-21 14:36:48 -04:00
Ben	7ffe6a104b	style: apply ruff format to openai_compatible_llm.py (#1703 )	2026-05-21 14:36:17 -04:00