Skip to main content

Multi-Server Setup

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.

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:

// 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:

// 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:

// 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:

// 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:

// 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 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:

{
  "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:

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." })
}