fleet-memory/hindsight-integrations/nemoclaw/NEMOCLAW.md

Using hindsight-openclaw with NemoClaw

This guide covers running the hindsight-openclaw plugin inside a NemoClaw sandbox. NemoClaw runs OpenClaw inside an OpenShell sandbox, so the plugin's outbound calls to api.hindsight.vectorize.io must be explicitly allowed in the sandbox's network egress policy.

Prerequisites

• NemoClaw installed and a sandbox created (nemoclaw onboard)
• OpenClaw installed (brew install openclaw or equivalent)
• A Hindsight API key from ui.hindsight.vectorize.io
• The plugin source built (npm run build in this directory)

Step 1: Create a Hindsight memory bank

Create the bank the plugin will write to. The bank ID follows the pattern {bankIdPrefix}-openclaw when dynamicBankId is false:

curl -X PUT "https://api.hindsight.vectorize.io/v1/default/banks/my-sandbox-openclaw" \
  -H "Authorization: Bearer <your-hindsight-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"mission": "Memory bank for my NemoClaw sandbox."}'

Step 2: Install the plugin

Install the plugin as a copy (not a symlink) so the OpenClaw LaunchAgent can access it:

# Build first if you haven't already
npm run build

# Install (copy, not link — required for LaunchAgent access)
openclaw plugins install /path/to/hindsight-integrations/openclaw

Alternatively, install from npm:

openclaw plugins install @vectorize-io/hindsight-openclaw

Step 3: Configure the plugin

Add the plugin config to ~/.openclaw/openclaw.json under plugins.entries.hindsight-openclaw:

{
  "plugins": {
    "entries": {
      "hindsight-openclaw": {
        "enabled": true,
        "config": {
          "hindsightApiUrl": "https://api.hindsight.vectorize.io",
          "hindsightApiToken": "<your-hindsight-api-key>",
          "llmProvider": "claude-code",
          "dynamicBankId": false,
          "bankIdPrefix": "my-sandbox"
        }
      }
    }
  }
}

Config notes:

Field	Value	Why
hindsightApiUrl + hindsightApiToken	External API URL + key	Skips the local daemon; no uvx/uv required inside the sandbox
llmProvider: "claude-code"	"claude-code"	Satisfies LLM detection without a separate API key — Claude Code is available in the sandbox via the claude_code policy
dynamicBankId: false	false	All conversations write to one bank; easier to verify during testing
bankIdPrefix	e.g. "my-sandbox"	Results in bank ID my-sandbox-openclaw

Note: The gateway log will say Dynamic bank IDs disabled - using static bank: openclaw — this is a misleading log message. The actual bank ID used at runtime correctly applies the prefix (e.g. my-sandbox-openclaw). You can verify by watching for [Hindsight] Default bank: my-sandbox-openclaw in the logs after full initialization.

Step 4: Add the Hindsight network policy to the sandbox

The sandbox blocks all outbound traffic by default. You need to add api.hindsight.vectorize.io to the egress policy.

Get the current full policy by running openshell sandbox get <name> and save it to a YAML file, then add the hindsight block under network_policies:

network_policies:
  # ... your existing policies ...
  hindsight:
    name: hindsight
    endpoints:
      - host: api.hindsight.vectorize.io
        port: 443
        protocol: rest
        tls: terminate
        enforcement: enforce
        rules:
          - allow:
              method: GET
              path: /**
          - allow:
              method: POST
              path: /**
          - allow:
              method: PUT
              path: /**
    binaries:
      - path: /usr/local/bin/openclaw

Apply it:

openshell policy set <sandbox-name> --policy /path/to/full-policy.yaml --wait

Important: openshell policy set replaces the entire policy, not just patches it. Make sure your YAML includes all existing network policies or they will be removed.

Verify the policy loaded:

openshell policy get <sandbox-name>
# Should show: Status: Loaded, and version incremented

Step 5: Restart the OpenClaw gateway

openclaw gateway restart

Watch the logs to confirm the plugin loaded and the API is reachable:

# Should see:
# [Hindsight] Plugin loaded successfully
# [Hindsight] ✓ Using external API: https://api.hindsight.vectorize.io
# [Hindsight] External API health: {"status":"healthy","database":"connected"}
# [Hindsight] Default bank: my-sandbox-openclaw
# [Hindsight] ✓ Ready (external API mode)
grep Hindsight ~/.openclaw/logs/gateway.log | tail -20

Step 6: Test

Send a message to the agent:

openclaw agent --agent main --session-id test-1 \
  -m "My name is Ben and I work on Hindsight. I prefer detailed commit messages."

Verify memory was retained (check logs):

grep "Retained\|agent_end" ~/.openclaw/logs/gateway.log | tail -5
# Should see: [Hindsight] Retained N messages to bank my-sandbox-openclaw for session ...

Test recall in a new session:

openclaw agent --agent main --session-id test-2 \
  -m "What do you remember about me?"
# Should recall your name and preferences from the previous session

You can also verify directly against the API:

curl -s -X POST "https://api.hindsight.vectorize.io/v1/default/banks/my-sandbox-openclaw/memories/recall" \
  -H "Authorization: Bearer <your-hindsight-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "what do you know about the user", "max_tokens": 512}'

Troubleshooting

Plugin fails to load with EPERM: operation not permitted, scandir

You used --link when installing. The OpenClaw LaunchAgent runs under a restricted macOS security context and cannot access ~/Documents or other user directories by symlink. Reinstall without --link:

openclaw plugins uninstall hindsight-openclaw
openclaw plugins install /path/to/hindsight-integrations/openclaw  # no --link

[Hindsight] Failed to retain memory (HTTP 403)

The sandbox network policy is blocking the outbound call. Check that:

1. The hindsight network policy block is present in your policy YAML
2. The policy was applied and shows Status: Loaded (openshell policy get <name>)
3. The binaries list includes /usr/local/bin/openclaw

Gateway restart times out but then recovers

This is normal on first restart after installing a plugin — the LaunchAgent takes a moment to reload. The gateway is healthy if openclaw gateway status shows RPC probe: ok.

openclaw agent fails with Pass --to, --session-id, or --agent

You need to specify a session. Use --agent main to use the default agent, or --session-id <any-string> to create a named session.