# Multi-Server Setup

Route different agents in the same gateway to different Hindsight servers.

hindclaw supports per-agent infrastructure routing -- different agents in the same gateway can connect to different Hindsight servers. This enables scenarios like separating personal and company memory, or mixing a local daemon with remote servers.

## How it works

The plugin resolves `hindsightApiUrl` per-agent. The default is the local daemon (started automatically), but any agent can override it to point at a different server.

```mermaid
graph LR
    GW["Gateway"] --> A1["agent-1"]
    GW --> A2["agent-2"]
    GW --> A3["agent-3"]
    GW --> A4["agent-4"]
    A1 --> HOME["Home server"]
    A2 --> HOME
    A3 --> OFFICE["Office server"]
    A4 --> LOCAL["Local daemon"]

    style GW fill:#0f766e,color:#fff,stroke:#0f766e
    style A1 fill:#1d4ed8,color:#fff,stroke:#1d4ed8
    style A2 fill:#1d4ed8,color:#fff,stroke:#1d4ed8
    style A3 fill:#1d4ed8,color:#fff,stroke:#1d4ed8
    style A4 fill:#1d4ed8,color:#fff,stroke:#1d4ed8
    style HOME fill:#8b5cf6,color:#fff,stroke:#8b5cf6
    style OFFICE fill:#c2410c,color:#fff,stroke:#c2410c
    style LOCAL fill:#f59e0b,color:#fff,stroke:#f59e0b
```

One gateway, one plugin instance, multiple Hindsight backends.

## Configuration

### Plugin-level default

Set a default Hindsight server in the plugin config. All agents use this unless overridden:

```json5
// In openclaw.json (or $include'd config)
"hindclaw": {
  "enabled": true,
  "config": {
    "hindsightApiUrl": "https://hindsight.home.local",
    "hindsightApiToken": "home-token-here"
  }
}
```

### Per-agent override

Override the URL in the plugin config's agent entry to point an agent at a different server:

```json5
// In openclaw.json plugin config, agents section
{
  "agents": {
    "ops-agent": {
      "hindsightApiUrl": "https://hindsight.office.local",
      "hindsightApiToken": "office-token-here"
    }
  }
}
```

The bank's server-side settings (retain mission, entity labels, etc.) are managed via Terraform on the target server.

### Mixing local daemon and remote servers

If some agents should use the local daemon (no URL override) and others should use a remote server, simply omit `hindsightApiUrl` for the local agents:

```json5
// In openclaw.json plugin config
{
  "agents": {
    "my-agent": {},                    // uses local daemon (default)
    "ops-agent": {
      "hindsightApiUrl": "https://hindsight.office.local",
      "hindsightApiToken": "office-token-here"
    }
  }
}
```

The local daemon starts automatically when any agent uses it. Agents pointing at remote servers do not trigger the daemon.

## Use cases

### Home vs office separation

Keep personal memories on a home server and company memories on an office server:

```
Gateway
├── agent-1   (private)   --> https://hindsight.home.local
├── agent-2   (private)   --> https://hindsight.home.local
├── agent-3   (company)   --> https://hindsight.office.local
├── agent-4   (company)   --> https://hindsight.office.local
└── agent-5   (health)    --> local daemon (no URL)
```

This keeps data physically separated. Personal conversations never leave the home network; company data stays on the office server.

### Development and production

Use a local daemon for development agents while production agents connect to a stable remote server:

```json5
// In openclaw.json plugin config
{
  "agents": {
    "dev-agent": {},                        // uses local daemon
    "prod-agent": {
      "hindsightApiUrl": "https://hindsight.prod.internal",
      "hindsightApiToken": "prod-token"
    }
  }
}
```

### Multi-tenant deployment

In a shared gateway serving multiple organizations, each tenant's agents can point to their own Hindsight instance:

```json5
// In openclaw.json plugin config
{
  "agents": {
    "tenant-a-agent": {
      "hindsightApiUrl": "https://hindsight.tenant-a.local",
      "hindsightApiToken": "tenant-a-token"
    },
    "tenant-b-agent": {
      "hindsightApiUrl": "https://hindsight.tenant-b.local",
      "hindsightApiToken": "tenant-b-token"
    }
  }
}
```

## Cross-agent recall across servers

When an agent uses `recallFrom` to recall from another agent's bank, the target bank must be accessible from the same Hindsight server. Cross-server recall (agent on server A recalling from a bank on server B) is not supported -- all banks in a `recallFrom` list must be on the same server as the requesting agent.

If you need cross-server knowledge sharing, consider using [session start models](./session-context.md) to pre-load context from different servers at session start.

## Authentication

Each server can have its own authentication token. Set `hindsightApiToken` alongside `hindsightApiUrl` in either the plugin config (for the default) or the bank config (for per-agent overrides).

Tokens should be stored securely. If your gateway config supports environment variable references, use those instead of hardcoding tokens:

```json5
{
  "hindsightApiUrl": "https://hindsight.office.local",
  "hindsightApiToken": "${HINDSIGHT_OFFICE_TOKEN}"
}
```

## Terraform with multi-server

When using Terraform to manage bank configs across multiple servers, use separate provider aliases:

```hcl
provider "hindclaw" {
  alias   = "home"
  api_url = "https://hindsight.home.local"
  api_key = var.home_api_key
}

provider "hindclaw" {
  alias   = "office"
  api_url = "https://hindsight.office.local"
  api_key = var.office_api_key
}

resource "hindclaw_bank_config" "advisor" {
  provider = hindclaw.home
  bank_id  = "advisor"
  config   = jsonencode({ retain_mission = "Strategic decisions." })
}

resource "hindclaw_bank_config" "ops_agent" {
  provider = hindclaw.office
  bank_id  = "ops-agent"
  config   = jsonencode({ retain_mission = "Operational decisions." })
}
```