From dd58b9af9270ebcb7bef003a5412c06e2e2e332c Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 16 Mar 2026 16:34:36 -0400 Subject: [PATCH 1/2] feat(skills): add hindsight-memory skill for persistent agent memory Adds a new agent skill that teaches sandboxed agents how to use Hindsight for persistent memory across ephemeral sandbox sessions. Includes the skill definition with recall/retain/reflect workflows, a CLI reference, and an example network policy for Hindsight API access. Closes #371 Signed-off-by: Ben --- .agents/skills/hindsight-memory/SKILL.md | 294 ++++++++++++++++++ .../skills/hindsight-memory/cli-reference.md | 141 +++++++++ .../hindsight-memory/example-policy.yaml | 49 +++ CONTRIBUTING.md | 1 + 4 files changed, 485 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 00000000..f1467f45 --- /dev/null +++ b/.agents/skills/hindsight-memory/SKILL.md @@ -0,0 +1,294 @@ +--- +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 an OpenShell sandbox. + +## Prerequisites + +- The `hindsight` CLI must be installed in the sandbox image +- A Hindsight provider must be attached to the sandbox (see Setup) +- A memory bank must exist (the user provides the bank ID) + +## Setup + +### 1. Create the Hindsight Provider + +The Hindsight provider injects `HINDSIGHT_API_KEY` and `HINDSIGHT_API_URL` into the sandbox. + +```bash +# From existing environment variables +openshell provider create --name hindsight --type generic \ + --credential HINDSIGHT_API_KEY \ + --config HINDSIGHT_API_URL + +# Or with explicit values +openshell provider create --name hindsight --type generic \ + --credential HINDSIGHT_API_KEY=hs-your-api-key \ + --config HINDSIGHT_API_URL=https://api.hindsight.vectorize.io +``` + +### 2. Create a Sandbox with Hindsight + +Attach the provider and ensure the sandbox has network access to the Hindsight API: + +```bash +openshell sandbox create \ + --provider hindsight \ + --policy sandbox-policy.yaml \ + -- claude +``` + +### 3. Configure the CLI Inside the Sandbox + +On first use, create the Hindsight CLI config: + +```bash +mkdir -p ~/.hindsight +cat > ~/.hindsight/config << 'EOF' +api_url = "${HINDSIGHT_API_URL}" +api_key = "${HINDSIGHT_API_KEY}" +EOF +chmod 600 ~/.hindsight/config +``` + +If the `hindsight` CLI is not available in the base image, install it: + +```bash +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. + +```bash +# Recall context about the area you're about to work on +hindsight memory recall "authentication module architecture" + +# Recall what went wrong last time +hindsight memory recall "issues encountered with database migrations" + +# Recall team conventions +hindsight memory recall "coding standards and project conventions" + +# Recall a specific person's preferences +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 + +```bash +# Higher budget for complex questions (more thorough search) +hindsight memory recall "query" --budget high + +# Limit response size +hindsight memory recall "query" --max-tokens 4096 + +# Filter by fact type +hindsight memory recall "query" --fact-type world,experience + +# JSON output for programmatic use +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. + +```bash +# Store a project convention +hindsight memory retain "Project uses 2-space indentation with Prettier" + +# Store a learning with context +hindsight memory retain "Build failed when using Node 18, works with Node 20" --context learnings + +# Store a procedure +hindsight memory retain "Running integration tests requires Docker and POSTGRES_URL set" --context procedures + +# Store a debugging outcome +hindsight memory retain "The auth timeout was caused by missing CONNECTION_POOL_SIZE env var, default of 5 was too low" --context debugging +``` + +### What to Store + +| Category | Examples | Context Tag | +|----------|----------|-------------| +| Project conventions | Coding standards, branch naming, PR conventions | `conventions` | +| Procedures | Steps that completed a task, required env vars | `procedures` | +| Learnings | Bugs and solutions, what worked and what didn't | `learnings` | +| Architecture | Design decisions, component relationships | `architecture` | +| Team knowledge | Onboarding info, domain knowledge, pitfalls | `team` | +| Individual preferences | "Alice prefers explicit type annotations" | `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 tags** — they help with filtering during recall. +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. + +```bash +# Synthesize context for a task +hindsight memory reflect "How should I approach adding a new API endpoint based on past experience?" + +# Get a summary +hindsight memory reflect "What do we know about the payment processing module?" + +# Higher budget for complex synthesis +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: + +```bash +# Retain a single file +hindsight memory retain-files investigation-notes.txt + +# Retain a directory +hindsight memory retain-files ./reports/ + +# With context +hindsight memory retain-files debug-log.txt --context "debugging auth timeout issue" + +# Background processing for large files +hindsight memory retain-files ./large-dataset/ --async +``` + +## Workflow 5: Cross-Sandbox Continuity + +This is the core value of Hindsight in OpenShell. 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:** + +```bash +# Agent discovers something during work +hindsight memory retain my-project "The retry logic in api/client.rs has no backoff jitter, causing thundering herd under load" --context learnings + +# Agent completes a partial fix +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 +``` + +**New sandbox session:** + +```bash +# Agent recalls where the previous session left off +hindsight memory recall my-project "retry logic and backoff changes" + +# Agent gets the full context and continues the work +``` + +### 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 progress` + +## Network Policy + +The sandbox must have a network policy allowing egress to the Hindsight API. Use the `generate-sandbox-policy` skill to create one, or add this block to your existing policy: + +```yaml +network_policies: + hindsight_memory: + name: hindsight_memory + endpoints: + - host: api.hindsight.vectorize.io + port: 443 + protocol: rest + tls: terminate + enforcement: enforce + access: read-write + binaries: + - { path: /usr/local/bin/hindsight } + - { path: /usr/bin/curl } +``` + +For self-hosted Hindsight instances on private networks, add `allowed_ips`: + +```yaml +network_policies: + hindsight_memory: + name: hindsight_memory + endpoints: + - host: hindsight.internal.corp + port: 8888 + protocol: rest + enforcement: enforce + access: read-write + allowed_ips: + - "10.0.5.0/24" + binaries: + - { path: /usr/local/bin/hindsight } +``` + +See the `generate-sandbox-policy` skill for full policy generation from these examples. + +## Bank Management + +Banks are isolated memory stores. Each project or team typically has its own bank. + +```bash +# List available banks +hindsight bank list + +# View bank statistics +hindsight bank stats + +# View bank disposition (personality traits affecting reflect) +hindsight bank disposition +``` + +## Companion Skills + +| Skill | When to Use | +|-------|-------------| +| `generate-sandbox-policy` | Generate or refine the network policy for Hindsight API access | +| `openshell-cli` | Manage providers, sandbox lifecycle, and policy attachment | +| `debug-inference` | If Hindsight uses a local inference endpoint for embeddings | + +## CLI Quick Reference + +| Command | Description | +|---------|-------------| +| `hindsight memory retain "text"` | Store a memory | +| `hindsight memory retain "text" --context ` | Store with context tag | +| `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 00000000..c5b93aed --- /dev/null +++ b/.agents/skills/hindsight-memory/cli-reference.md @@ -0,0 +1,141 @@ +# Hindsight CLI Reference + +## Installation + +```bash +curl -fsSL https://hindsight.vectorize.io/get-cli | bash +``` + +## Configuration + +```bash +# 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 + +```bash +hindsight memory retain "" +hindsight memory retain "" --context +hindsight memory retain "" --async +``` + +| Flag | Description | +|------|-------------| +| `--context ` | Context tag for categorization (e.g., learnings, procedures, conventions) | +| `--async` | Queue for background processing instead of waiting | + +### retain-files — Bulk Import from Files + +```bash +hindsight memory retain-files +hindsight memory retain-files --context +hindsight memory retain-files --async +``` + +| Flag | Description | +|------|-------------| +| `--context ` | Context tag applied to all retained content | +| `--async` | Queue for background processing | + +Directories are processed recursively by default. + +### recall — Search Memories + +```bash +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, medium, high (default: medium) | +| `--max-tokens ` | Maximum tokens in response | +| `--fact-type ` | Comma-separated: world, experience, observation | +| `--trace` | Show trace information for debugging | + +### reflect — Synthesized Response + +```bash +hindsight memory reflect "" +hindsight memory reflect "" --context +hindsight memory reflect "" --budget high +``` + +| Flag | Description | +|------|-------------| +| `--context ` | Additional context for the reflection | +| `--budget ` | Search thoroughness: low, medium, high | + +## Bank Management + +```bash +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 background "" # Set bank background context +``` + +## Document Management + +```bash +hindsight document list # List documents +hindsight document get # Get document details +hindsight document delete # Delete document and memories +``` + +## Entity Management + +```bash +hindsight entity list # List entities +hindsight entity get # Get entity details +hindsight entity regenerate # Regenerate observations +``` + +## Output Formats + +```bash +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}/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 | +| POST | `/v1/default/banks/{bank_id}/documents` | Upload documents | diff --git a/.agents/skills/hindsight-memory/example-policy.yaml b/.agents/skills/hindsight-memory/example-policy.yaml new file mode 100644 index 00000000..c14202b5 --- /dev/null +++ b/.agents/skills/hindsight-memory/example-policy.yaml @@ -0,0 +1,49 @@ +# Example sandbox policy with Hindsight memory access. +# +# This policy grants the sandbox agent access to the Hindsight Cloud API +# for memory recall and retain operations. It uses read-write access, +# which allows GET (recall) and POST (retain) but not DELETE. +# +# Usage: +# openshell sandbox create --policy example-policy.yaml --provider hindsight -- claude +# +# For self-hosted Hindsight instances, change the host and add allowed_ips +# for private IP ranges. See SKILL.md for examples. + +version: 1 + +filesystem_policy: + include_workdir: true + read_only: + - /usr + - /lib + - /proc + - /dev/urandom + - /app + - /etc + - /var/log + read_write: + - /sandbox + - /tmp + - /dev/null + +landlock: + compatibility: best_effort + +process: + run_as_user: sandbox + run_as_group: sandbox + +network_policies: + hindsight_memory: + name: hindsight_memory + endpoints: + - host: api.hindsight.vectorize.io + port: 443 + protocol: rest + tls: terminate + enforcement: enforce + access: read-write + binaries: + - { path: /usr/local/bin/hindsight } + - { path: /usr/bin/curl } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f558cdeb..a4521a3f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,6 +43,7 @@ Skills live in `.agents/skills/`. Your agent's harness can discover and load the | Reviewing | `watch-github-actions` | Monitor CI pipeline status and logs | | Triage | `triage-issue` | Assess, classify, and route community-filed issues | | Platform | `generate-sandbox-policy` | Generate YAML sandbox policies from requirements or API docs | +| Platform | `hindsight-memory` | Persistent agent memory across sandbox sessions using Hindsight | | Platform | `tui-development` | Development guide for the ratatui-based terminal UI | | Documentation | `update-docs` | Scan recent commits and draft doc updates for user-facing changes | | Maintenance | `sync-agent-infra` | Detect and fix drift across agent-first infrastructure files | From 4c77518b17c7ffbe2e64b878b1b6b207168c04a2 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 16 Mar 2026 16:53:51 -0400 Subject: [PATCH 2/2] fix: correct CLI flags, API endpoints, and config in hindsight-memory skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix --budget values: "medium" → "mid" (matches CLI default) - Fix --fact-type values: "observation" → "opinion" (matches CLI) - Fix --context description: it's freeform text, not a structured tag - Fix API endpoints table: add missing POST /memories (retain), fix documents endpoint to GET (list), not POST - Replace deprecated `bank background` with `bank mission` - Fix config setup: use `hindsight configure` instead of writing TOML with shell variable interpolation (which doesn't work) - Add missing reflect flags: --max-tokens, --schema - Add missing recall flags: --include-chunks, --chunk-max-tokens Co-Authored-By: Claude Opus 4.6 --- .agents/skills/hindsight-memory/SKILL.md | 44 +++++++++---------- .../skills/hindsight-memory/cli-reference.md | 29 +++++++----- 2 files changed, 38 insertions(+), 35 deletions(-) diff --git a/.agents/skills/hindsight-memory/SKILL.md b/.agents/skills/hindsight-memory/SKILL.md index f1467f45..481ed7ad 100644 --- a/.agents/skills/hindsight-memory/SKILL.md +++ b/.agents/skills/hindsight-memory/SKILL.md @@ -59,12 +59,10 @@ openshell sandbox create \ On first use, create the Hindsight CLI config: ```bash -mkdir -p ~/.hindsight -cat > ~/.hindsight/config << 'EOF' -api_url = "${HINDSIGHT_API_URL}" -api_key = "${HINDSIGHT_API_KEY}" -EOF -chmod 600 ~/.hindsight/config +# The CLI reads HINDSIGHT_API_URL and HINDSIGHT_API_KEY env vars directly, +# so no config file is needed when the provider injects them. +# To persist config explicitly: +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: @@ -124,32 +122,32 @@ hindsight memory recall "query" -o json hindsight memory retain "Project uses 2-space indentation with Prettier" # Store a learning with context -hindsight memory retain "Build failed when using Node 18, works with Node 20" --context learnings +hindsight memory retain "Build failed when using Node 18, works with Node 20" --context "learnings from CI pipeline" # Store a procedure -hindsight memory retain "Running integration tests requires Docker and POSTGRES_URL set" --context procedures +hindsight memory retain "Running integration tests requires Docker and POSTGRES_URL set" --context "setup procedures" # Store a debugging outcome -hindsight memory retain "The auth timeout was caused by missing CONNECTION_POOL_SIZE env var, default of 5 was too low" --context debugging +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 Tag | -|----------|----------|-------------| -| Project conventions | Coding standards, branch naming, PR conventions | `conventions` | -| Procedures | Steps that completed a task, required env vars | `procedures` | -| Learnings | Bugs and solutions, what worked and what didn't | `learnings` | -| Architecture | Design decisions, component relationships | `architecture` | -| Team knowledge | Onboarding info, domain knowledge, pitfalls | `team` | -| Individual preferences | "Alice prefers explicit type annotations" | `preferences` | +| 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 tags** — they help with filtering during recall. +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 @@ -193,10 +191,10 @@ This is the core value of Hindsight in OpenShell. When a sandbox is destroyed an ```bash # Agent discovers something during work -hindsight memory retain my-project "The retry logic in api/client.rs has no backoff jitter, causing thundering herd under load" --context learnings +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" # Agent completes a partial fix -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 +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:** @@ -213,8 +211,8 @@ hindsight memory recall my-project "retry logic and backoff changes" 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 progress` +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 @@ -284,7 +282,7 @@ hindsight bank disposition | Command | Description | |---------|-------------| | `hindsight memory retain "text"` | Store a memory | -| `hindsight memory retain "text" --context ` | Store with context tag | +| `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 | diff --git a/.agents/skills/hindsight-memory/cli-reference.md b/.agents/skills/hindsight-memory/cli-reference.md index c5b93aed..35c7b8d7 100644 --- a/.agents/skills/hindsight-memory/cli-reference.md +++ b/.agents/skills/hindsight-memory/cli-reference.md @@ -28,26 +28,26 @@ Config file location: `~/.hindsight/config` ```bash hindsight memory retain "" -hindsight memory retain "" --context +hindsight memory retain "" --context "" hindsight memory retain "" --async ``` | Flag | Description | |------|-------------| -| `--context ` | Context tag for categorization (e.g., learnings, procedures, conventions) | +| `--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 ```bash hindsight memory retain-files -hindsight memory retain-files --context +hindsight memory retain-files --context "" hindsight memory retain-files --async ``` | Flag | Description | |------|-------------| -| `--context ` | Context tag applied to all retained content | +| `--context ` | Freeform context applied to all retained content | | `--async` | Queue for background processing | Directories are processed recursively by default. @@ -64,23 +64,27 @@ hindsight memory recall "" --trace | Flag | Description | |------|-------------| -| `--budget ` | Search thoroughness: low, medium, high (default: medium) | -| `--max-tokens ` | Maximum tokens in response | -| `--fact-type ` | Comma-separated: world, experience, observation | +| `--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 ```bash hindsight memory reflect "" -hindsight memory reflect "" --context +hindsight memory reflect "" --context "" hindsight memory reflect "" --budget high ``` | Flag | Description | |------|-------------| -| `--context ` | Additional context for the reflection | -| `--budget ` | Search thoroughness: low, medium, high | +| `--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 @@ -89,7 +93,7 @@ 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 background "" # Set bank background context +hindsight bank mission "" # Set bank mission statement ``` ## Document Management @@ -131,6 +135,7 @@ 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 | @@ -138,4 +143,4 @@ The Hindsight API exposes these endpoints (relevant for network policy authoring | 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 | -| POST | `/v1/default/banks/{bank_id}/documents` | Upload documents | +| GET | `/v1/default/banks/{bank_id}/documents` | List documents |