feat(skills): /add-hindsight — bundled MCP wrapper for Hindsight memory

[carstenf]

Summary

Adds an opt-in /add-hindsight skill that wires NanoClaw v2 agent groups to a Hindsight long-term memory engine. The MCP wrapper that bridges Hindsight's HTTP API to MCP is bundled in this PR (under hindsight-mcp/) — operators don't need to clone external repos to install the skill.

Each wired agent group gets a per-group memory bank with three MCP tools:

• mcp__hindsight__memory_recall — semantic search across past memories
• mcp__hindsight__memory_retain — persist a durable fact
• mcp__hindsight__memory_reflect — synthesise an answer with evidence

Relationship to existing memory skills

/add-mnemon already exists for graph-based memory. This is a sibling option backed by Vectorize.io's Hindsight engine — different backend, different operational characteristics (Hindsight extracts entities + links them into a queryable knowledge graph server-side).

Operators should pick one — running both is redundant. The skill mentions this in its Credits section.

Structure

• .claude/skills/add-hindsight/SKILL.md — operator setup (5 phases: build wrapper, extract stdio binary to host path, register mount, wire each group via ncl groups config add-mcp-server, verify).
• container/skills/hindsight/SKILL.md — in-container memory discipline (when to recall, when to retain, anti-patterns).
• hindsight-mcp/ — self-contained TypeScript wrapper. Two transports (HTTP + stdio), shared tool implementation. Wrapper-only docker-compose (engine deployment is out of scope; assumes operator already has Hindsight running).

Prereq (out of scope for this skill)

The Hindsight engine itself is not deployed by this skill. Operator follows the upstream Hindsight install first, then points the wrapper at it via HINDSIGHT_URL.

This split mirrors /add-gmail-tool, /add-gcal-tool etc. — the skill handles the NanoClaw-side integration; the external service is the operator's responsibility.

What's deliberately not in this PR

• Auto-wiring at group-init. Per CONTRIBUTING ("source code changes should only be things 90%+ of users need"), wiring is opt-in via /add-hindsight, not automatic for every new group.
• ncl groups config add-mount. The skill currently uses a direct sqlite UPDATE to add the wrapper-binary mount to a group's container_configs.additional_mounts. Happy to drop the SQL once ncl grows an add-mount verb (separate PR).
• The Hindsight engine docker stack. Wrapper-only — see Prereq above.

Testing

Verified on a NanoClaw v2.0.56 install with a Hindsight engine reachable on localhost:3850:

• cd hindsight-mcp && cp .env.example .env && [edit] && docker compose up -d → wrapper healthy at 127.0.0.1:3852/health
• npm install && npm run build inside hindsight-mcp/ produces a clean dist/
• ncl groups config add-mcp-server + sqlite UPDATE for the mount → group respawn → agent sees mcp__hindsight__* tools in its allowlist
• Agent successfully calls memory_retain/memory_recall/memory_reflect against the engine
• Removing the skill (config remove-mcp-server + sqlite UPDATE to drop the mount + group restart) cleans up

Test plan for reviewers

• Read .claude/skills/add-hindsight/SKILL.md end-to-end — confirm operator can follow without prior knowledge
• Read container/skills/hindsight/SKILL.md — confirm no install-specific examples
• cd hindsight-mcp && npm install && npm run build — confirm wrapper builds cleanly
• cd hindsight-mcp && docker compose build — confirm wrapper image builds
• Optional: dry-run setup against a local Hindsight engine

🤖 Generated with Claude Code

[carstenf]

Validation summary

This PR has been tested end-to-end on a real NanoClaw v2.0.56 install (running Andy on Discord). Three full passes through the SKILL.md flow confirmed it works as documented.

Pass 1 — fresh migration on dm-with-carsten

Pre-existing hindsight wiring (from a manual setup pre-dating this skill) was on /home/hindsight-mcp/app. Following the SKILL.md literally:

• Pre-flight detection query found the wiring correctly.
• Removal (ncl remove-mcp-server + sqlite UPDATE drop) cleaned the row.
• Phase 3 wired the bundled hindsight-mcp/ path.
• Discord verify prompt: agent called memory_retain + memory_recall round-trip, retrieved the test marker plus older memories from the same bank prefix.

Pass 2 — fresh install on cli-with-carsten

Different group, same flow. Final container_configs row byte-identical to Pass 1 (modulo the auto-extracted NO_PROXY port detail).

Pass 3 — re-install on dm-with-carsten

Idempotency check. Pre-flight detection re-fired, removal cleaned, re-wire restored identical state. No surprises.

What we found mid-test (already in the latest push)

The first agent message after migration failed with fetch failed. Root cause: NanoClaw's gateway injects http_proxy / HTTPS_PROXY env into every container. Node 22's fetch then CONNECT-tunnels plain HTTP through it, and the OneCLI gateway can't complete the TLS handshake (it's not TLS). Fix: SKILL.md Phase 3 now auto-extracts ENGINE_HOST from HINDSIGHT_URL and sets NO_PROXY + no_proxy in the MCP server's env. Documented in Phase 4 troubleshooting.

CONTRIBUTING checklist

• Source code changes: none on main. Code lives under hindsight-mcp/ (would naturally fit a skill/hindsight branch if maintainers want that shape — happy to restructure).
• SKILL.md flow validated end-to-end with real engine + real Discord.
• One thing per PR: only /add-hindsight.
• Operator-runnable without prior knowledge of this install.

Happy to push fixes on this branch if anything needs adjusting.

🤖 Co-tested with Claude Code