From fdc08fb30ea19d290e9a3af919ee3a2c00dd698c Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 16 Mar 2026 17:13:21 -0400 Subject: [PATCH 1/2] feat(skills): add hindsight-memory skill for persistent agent memory Add a skill that teaches sandboxed agents how to use Hindsight for persistent memory across ephemeral sandbox sessions. Includes five workflows (recall, retain, reflect, file ingestion, cross-sandbox continuity), CLI reference, and a network policy template adapted to NemoClaw's explicit rules format. Closes #37 Signed-off-by: Ben --- .agents/skills/hindsight-memory/SKILL.md | 249 ++++++++++++++++++ .../skills/hindsight-memory/cli-reference.md | 149 +++++++++++ .../hindsight-memory/example-policy.yaml | 33 +++ 3 files changed, 431 insertions(+) create mode 100644 .agents/skills/hindsight-memory/SKILL.md create mode 100644 .agents/skills/hindsight-memory/cli-reference.md create mode 100644 .agents/skills/hindsight-memory/example-policy.yaml diff --git a/.agents/skills/hindsight-memory/SKILL.md b/.agents/skills/hindsight-memory/SKILL.md new file mode 100644 index 000000000..309f47743 --- /dev/null +++ b/.agents/skills/hindsight-memory/SKILL.md @@ -0,0 +1,249 @@ +--- +name: hindsight-memory +description: Give sandboxed agents persistent memory across sessions using Hindsight. Use to recall context before starting work, store learnings after completing tasks, and maintain continuity across ephemeral sandbox sessions. Trigger keywords - remember, recall, retain, memory, context, what did we learn, previous session, store knowledge, hindsight, persistent memory, cross-session context. +--- + + + + +# Hindsight Memory + +Give sandboxed agents persistent memory across ephemeral sandbox sessions using [Hindsight](https://github.com/vectorize-io/hindsight). + +Sandboxes are isolated and disposable. When a sandbox is destroyed, everything the agent learned is lost. Hindsight solves this by providing a structured memory API that agents can call from inside the sandbox to recall past context and store new learnings. + +## Overview + +Hindsight is an agent memory system that provides long-term memory using biomimetic data structures. Memories are organized as: + +- **World facts**: General knowledge ("The project uses ESLint with Airbnb config") +- **Experience facts**: Personal experiences ("Build failed when using Node 18, works with Node 20") +- **Mental models**: Consolidated knowledge synthesized from facts ("User prefers functional programming patterns") + +This skill teaches agents when and how to use Hindsight memory from inside a NemoClaw sandbox. + +## Prerequisites + +- The `hindsight` CLI must be installed in the sandbox image +- The sandbox network policy must allow egress to the Hindsight API (see Network Policy) +- A memory bank must exist (the user provides the bank ID) + +## Setup + +### Add Hindsight to the Sandbox Network Policy + +NemoClaw manages network policies through its blueprint. Add a Hindsight policy block to the sandbox policy file or apply it dynamically after sandbox creation. + +**Option A — Edit the baseline policy** + +Add the `hindsight_memory` block to `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`, then re-apply: + +```console +$ openclaw nemoclaw migrate +``` + +**Option B — Apply dynamically after launch** + +```console +$ openshell policy set --sandbox my-assistant --file hindsight-policy.yaml +``` + +See `example-policy.yaml` in this skill directory for a ready-to-use policy template. + +### Configure Credentials Inside the Sandbox + +Connect to the sandbox and set the Hindsight API credentials: + +```console +$ nemoclaw my-assistant connect +sandbox@my-assistant:~$ export HINDSIGHT_API_URL=https://api.hindsight.vectorize.io +sandbox@my-assistant:~$ export HINDSIGHT_API_KEY=hs-your-api-key +``` + +To persist the configuration across sessions: + +```console +sandbox@my-assistant:~$ hindsight configure --api-url "$HINDSIGHT_API_URL" --api-key "$HINDSIGHT_API_KEY" +``` + +If the `hindsight` CLI is not available in the base image, install it: + +```console +sandbox@my-assistant:~$ curl -fsSL https://hindsight.vectorize.io/get-cli | bash +``` + +## Workflow 1 — Recall Before Starting Work + +**Always recall relevant context before starting any non-trivial task.** This is the most important workflow. Without it, the agent starts from zero every time. + +```console +$ hindsight memory recall "authentication module architecture" +$ hindsight memory recall "issues encountered with database migrations" +$ hindsight memory recall "coding standards and project conventions" +$ hindsight memory recall "Alice preferences for code review" +``` + +### When to Recall + +- Before starting any non-trivial task +- Before making implementation decisions +- When working in an unfamiliar area of the codebase +- When answering questions about the project +- When a previous sandbox session worked on the same topic + +### Recall Options + +```console +$ hindsight memory recall "query" --budget high +$ hindsight memory recall "query" --max-tokens 4096 +$ hindsight memory recall "query" --fact-type world,experience +$ hindsight memory recall "query" -o json +``` + +## Workflow 2 — Retain After Completing Work + +**Store what you learned immediately after discovering it.** Do not wait until the end of the session. Sandboxes can be destroyed at any time. + +```console +$ hindsight memory retain "Project uses 2-space indentation with Prettier" +$ hindsight memory retain "Build failed when using Node 18, works with Node 20" --context "learnings from CI pipeline" +$ hindsight memory retain "Running integration tests requires Docker and POSTGRES_URL set" --context "setup procedures" +$ hindsight memory retain "The auth timeout was caused by missing CONNECTION_POOL_SIZE env var, default of 5 was too low" --context "debugging auth timeout" +``` + +### What to Store + +| Category | Examples | Context | +|----------|----------|---------| +| Project conventions | Coding standards, branch naming, PR conventions | `"project conventions"` | +| Procedures | Steps that completed a task, required env vars | `"setup procedures"` | +| Learnings | Bugs and solutions, what worked and what didn't | `"learnings from debugging"` | +| Architecture | Design decisions, component relationships | `"architecture decisions"` | +| Team knowledge | Onboarding info, domain knowledge, pitfalls | `"team knowledge"` | +| Individual preferences | "Alice prefers explicit type annotations" | `"Alice preferences"` | + +### Retain Best Practices + +1. **Store immediately** — do not batch. The sandbox could be destroyed. +2. **Be specific** — store "npm test requires --experimental-vm-modules flag" not "tests need a flag". +3. **Include outcomes** — store what worked AND what did not work. +4. **Use `--context`** — provide descriptive context to help Hindsight understand the memory's purpose. +5. **Attribute preferences** — store "Alice prefers X" not "user prefers X". + +## Workflow 3 — Reflect for Synthesized Answers + +Use `reflect` when you need Hindsight to synthesize an answer from multiple memories rather than returning raw recall results. + +```console +$ hindsight memory reflect "How should I approach adding a new API endpoint based on past experience?" +$ hindsight memory reflect "What do we know about the payment processing module?" +$ hindsight memory reflect "Summarize all architecture decisions" --budget high +``` + +## Workflow 4 — Retain Files for Bulk Knowledge + +When a sandbox session produces artifacts (logs, reports, investigation notes), retain the files directly: + +```console +$ hindsight memory retain-files investigation-notes.txt +$ hindsight memory retain-files ./reports/ +$ hindsight memory retain-files debug-log.txt --context "debugging auth timeout issue" +$ hindsight memory retain-files ./large-dataset/ --async +``` + +## Workflow 5 — Cross-Sandbox Continuity + +This is the core value of Hindsight in NemoClaw. When a sandbox is destroyed and a new one is created, the agent can pick up where the previous session left off. + +**Previous sandbox session:** + +```console +$ hindsight memory retain my-project "The retry logic in api/client.rs has no backoff jitter, causing thundering herd under load" --context "learnings from load testing" +$ hindsight memory retain my-project "Fixed retry backoff in api/client.rs by adding exponential jitter. Still need to add circuit breaker logic." --context "progress on retry backoff fix" +``` + +**New sandbox session:** + +```console +$ hindsight memory recall my-project "retry logic and backoff changes" +``` + +### Pattern — Session Bookends + +Adopt this pattern for every sandbox session: + +1. **Session start**: `hindsight memory recall ""` +2. **During work**: `hindsight memory retain "" --context "learnings"` (as discoveries happen) +3. **Session end**: `hindsight memory retain "" --context "session progress and next steps"` + +## Network Policy + +The sandbox must have a network policy allowing egress to the Hindsight API. Add this block to `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` or apply it with `openshell policy set`: + +```yaml + hindsight_memory: + name: hindsight_memory + endpoints: + - host: api.hindsight.vectorize.io + port: 443 + protocol: rest + enforcement: enforce + tls: terminate + rules: + - allow: { method: GET, path: "/v1/**" } + - allow: { method: POST, path: "/v1/**" } + binaries: + - { path: /usr/local/bin/hindsight } + - { path: /usr/bin/curl } +``` + +For self-hosted Hindsight instances on private networks, add `allowed_ips`: + +```yaml + hindsight_memory: + name: hindsight_memory + endpoints: + - host: hindsight.internal.corp + port: 8888 + protocol: rest + enforcement: enforce + rules: + - allow: { method: GET, path: "/v1/**" } + - allow: { method: POST, path: "/v1/**" } + allowed_ips: + - "10.0.5.0/24" + binaries: + - { path: /usr/local/bin/hindsight } +``` + +See `example-policy.yaml` in this skill directory for a complete standalone policy template. + +## Bank Management + +Banks are isolated memory stores. Each project or team typically has its own bank. + +```console +$ hindsight bank list +$ hindsight bank stats +$ hindsight bank disposition +``` + +## Companion Skills + +| Skill | When to Use | +|-------|-------------| +| `update-docs-from-commits` | Update documentation after adding Hindsight-related features | + +## CLI Quick Reference + +| Command | Description | +|---------|-------------| +| `hindsight memory retain "text"` | Store a memory | +| `hindsight memory retain "text" --context "desc"` | Store with context | +| `hindsight memory retain-files ` | Retain from files | +| `hindsight memory recall "query"` | Search memories | +| `hindsight memory recall "query" --budget high` | Thorough search | +| `hindsight memory reflect "question"` | Synthesized answer | +| `hindsight bank list` | List banks | +| `hindsight bank stats ` | Bank statistics | +| `hindsight configure` | Interactive CLI setup | diff --git a/.agents/skills/hindsight-memory/cli-reference.md b/.agents/skills/hindsight-memory/cli-reference.md new file mode 100644 index 000000000..8b08d7702 --- /dev/null +++ b/.agents/skills/hindsight-memory/cli-reference.md @@ -0,0 +1,149 @@ + + + +# Hindsight CLI Reference + +## Installation + +```console +$ curl -fsSL https://hindsight.vectorize.io/get-cli | bash +``` + +## Configuration + +```console +# Interactive configuration +$ hindsight configure + +# Or set directly +$ hindsight configure --api-url https://api.hindsight.vectorize.io + +# Or use environment variables (highest priority) +$ export HINDSIGHT_API_URL=https://api.hindsight.vectorize.io +$ export HINDSIGHT_API_KEY=hs-your-api-key +``` + +Config file location: `~/.hindsight/config` + +## Memory Commands + +### retain — Store a Memory + +```console +$ hindsight memory retain "" +$ hindsight memory retain "" --context "" +$ hindsight memory retain "" --async +``` + +| Flag | Description | +|------|-------------| +| `--context ` | Freeform context describing the memory (e.g., "learnings from debugging auth") | +| `--async` | Queue for background processing instead of waiting | + +### retain-files — Bulk Import from Files + +```console +$ hindsight memory retain-files +$ hindsight memory retain-files --context "" +$ hindsight memory retain-files --async +``` + +| Flag | Description | +|------|-------------| +| `--context ` | Freeform context applied to all retained content | +| `--async` | Queue for background processing | + +Directories are processed recursively by default. + +### recall — Search Memories + +```console +$ hindsight memory recall "" +$ hindsight memory recall "" --budget high +$ hindsight memory recall "" --max-tokens 8192 +$ hindsight memory recall "" --fact-type world,experience +$ hindsight memory recall "" --trace +``` + +| Flag | Description | +|------|-------------| +| `--budget ` | Search thoroughness: low, mid, high (default: mid) | +| `--max-tokens ` | Maximum tokens in response (default: 4096) | +| `--fact-type ` | Comma-separated: world, experience, opinion (default: all three) | +| `--trace` | Show trace information for debugging | +| `--include-chunks` | Include source chunks in results | +| `--chunk-max-tokens ` | Maximum tokens for chunks (default: 8192, requires --include-chunks) | + +### reflect — Synthesized Response + +```console +$ hindsight memory reflect "" +$ hindsight memory reflect "" --context "" +$ hindsight memory reflect "" --budget high +``` + +| Flag | Description | +|------|-------------| +| `--context ` | Additional context for the reflection | +| `--budget ` | Search thoroughness: low, mid, high (default: mid) | +| `--max-tokens ` | Maximum tokens for the response | +| `--schema ` | Path to JSON schema file for structured output | + +## Bank Management + +```console +$ hindsight bank list # List all banks +$ hindsight bank stats # View bank statistics +$ hindsight bank disposition # View personality traits +$ hindsight bank name "" # Set bank display name +$ hindsight bank mission "" # Set bank mission statement +``` + +## Document Management + +```console +$ hindsight document list # List documents +$ hindsight document get # Get document details +$ hindsight document delete # Delete document and memories +``` + +## Entity Management + +```console +$ hindsight entity list # List entities +$ hindsight entity get # Get entity details +$ hindsight entity regenerate # Regenerate observations +``` + +## Output Formats + +```console +$ hindsight memory recall "query" # Pretty (default) +$ hindsight memory recall "query" -o json # JSON +$ hindsight memory recall "query" -o yaml # YAML +``` + +## Global Flags + +| Flag | Description | +|------|-------------| +| `-v, --verbose` | Show detailed output including request/response | +| `-o, --output ` | Output format: pretty, json, yaml | +| `--help` | Show help | +| `--version` | Show version | + +## API Endpoints + +The Hindsight API exposes these endpoints (relevant for network policy authoring): + +| Method | Path | Operation | +|--------|------|-----------| +| POST | `/v1/default/banks/{bank_id}/memories` | Retain memories | +| POST | `/v1/default/banks/{bank_id}/files/retain` | Retain files | +| POST | `/v1/default/banks/{bank_id}/memories/recall` | Recall memories | +| POST | `/v1/default/banks/{bank_id}/reflect` | Reflect on memories | +| GET | `/v1/default/banks` | List banks | +| GET | `/v1/default/banks/{bank_id}/stats` | Bank statistics | +| GET | `/v1/default/banks/{bank_id}/entities` | List entities | +| GET | `/v1/default/banks/{bank_id}/memories/list` | List memories | +| GET | `/v1/default/banks/{bank_id}/documents` | List documents | diff --git a/.agents/skills/hindsight-memory/example-policy.yaml b/.agents/skills/hindsight-memory/example-policy.yaml new file mode 100644 index 000000000..15e4d17ff --- /dev/null +++ b/.agents/skills/hindsight-memory/example-policy.yaml @@ -0,0 +1,33 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# +# Network policy preset for Hindsight memory API access. +# +# Grants the sandbox agent access to the Hindsight Cloud API for memory +# recall and retain operations. Uses explicit path rules scoped to the +# /v1/ API prefix. +# +# Usage: +# Add this block to nemoclaw-blueprint/policies/openclaw-sandbox.yaml +# and run `openclaw nemoclaw migrate`, or apply dynamically: +# +# $ openshell policy set --sandbox my-assistant --file example-policy.yaml +# +# For self-hosted Hindsight instances, change the host and port and add +# allowed_ips for private IP ranges. See SKILL.md for examples. + +network_policies: + hindsight_memory: + name: hindsight_memory + endpoints: + - host: api.hindsight.vectorize.io + port: 443 + protocol: rest + enforcement: enforce + tls: terminate + rules: + - allow: { method: GET, path: "/v1/**" } + - allow: { method: POST, path: "/v1/**" } + binaries: + - { path: /usr/local/bin/hindsight } + - { path: /usr/bin/curl } From 6c23086a7255050644a7b51d6f8c98b84bea0cca Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 16 Mar 2026 17:21:10 -0400 Subject: [PATCH 2/2] fix(skills): correct openshell policy set syntax in hindsight-memory skill Use positional argument `openshell policy set ` matching NemoClaw's documented CLI syntax, not `--sandbox`/`--file` flags. Signed-off-by: Ben --- .agents/skills/hindsight-memory/SKILL.md | 7 +++++-- .agents/skills/hindsight-memory/example-policy.yaml | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/.agents/skills/hindsight-memory/SKILL.md b/.agents/skills/hindsight-memory/SKILL.md index 309f47743..8741bc787 100644 --- a/.agents/skills/hindsight-memory/SKILL.md +++ b/.agents/skills/hindsight-memory/SKILL.md @@ -44,8 +44,11 @@ $ openclaw nemoclaw migrate **Option B — Apply dynamically after launch** +Connect to the sandbox first, then apply from inside: + ```console -$ openshell policy set --sandbox my-assistant --file hindsight-policy.yaml +$ nemoclaw my-assistant connect +sandbox@my-assistant:~$ openshell policy set hindsight-policy.yaml ``` See `example-policy.yaml` in this skill directory for a ready-to-use policy template. @@ -178,7 +181,7 @@ Adopt this pattern for every sandbox session: ## Network Policy -The sandbox must have a network policy allowing egress to the Hindsight API. Add this block to `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` or apply it with `openshell policy set`: +The sandbox must have a network policy allowing egress to the Hindsight API. Add this block to `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` or apply it dynamically with `openshell policy set`: ```yaml hindsight_memory: diff --git a/.agents/skills/hindsight-memory/example-policy.yaml b/.agents/skills/hindsight-memory/example-policy.yaml index 15e4d17ff..8c9afbcc4 100644 --- a/.agents/skills/hindsight-memory/example-policy.yaml +++ b/.agents/skills/hindsight-memory/example-policy.yaml @@ -11,7 +11,7 @@ # Add this block to nemoclaw-blueprint/policies/openclaw-sandbox.yaml # and run `openclaw nemoclaw migrate`, or apply dynamically: # -# $ openshell policy set --sandbox my-assistant --file example-policy.yaml +# $ openshell policy set example-policy.yaml # # For self-hosted Hindsight instances, change the host and port and add # allowed_ips for private IP ranges. See SKILL.md for examples.