Skip to main content

CLI Reference

The Hindsight CLI provides command-line access to memory operations and bank management.

Installation​

curl -fsSL https://raw.githubusercontent.com/vectorize-io/hindsight/refs/heads/main/hindsight-cli/install.sh | bash

Configuration​

Configure the API URL:

# Interactive configuration
hindsight configure

# Or set directly
hindsight configure --api-url http://localhost:8888

# Or use environment variable (highest priority)
export HINDSIGHT_API_URL=http://localhost:8888

Core Commands​

Retain (Store Memory)​

Store a single memory:

hindsight memory retain <bank_id> "Alice works at Google as a software engineer"

# With context
hindsight memory retain <bank_id> "Bob loves hiking" --context "hobby discussion"

# Queue for background processing
hindsight memory retain <bank_id> "Meeting notes" --async

Retain Files​

Bulk import from files:

# Single file
hindsight memory retain-files <bank_id> notes.txt

# Directory (recursive by default)
hindsight memory retain-files <bank_id> ./documents/

# With context
hindsight memory retain-files <bank_id> meeting-notes.txt --context "team meeting"

# Background processing
hindsight memory retain-files <bank_id> ./data/ --async

Search memories using semantic similarity:

hindsight memory recall <bank_id> "What does Alice do?"

# With options
hindsight memory recall <bank_id> "hiking recommendations" \
  --budget high \
  --max-tokens 8192

# Filter by fact type
hindsight memory recall <bank_id> "query" --fact-type world,opinion

# Show trace information
hindsight memory recall <bank_id> "query" --trace

Reflect (Generate Response)​

Generate a response using memories and bank personality:

hindsight memory reflect <bank_id> "What do you know about Alice?"

# With additional context
hindsight memory reflect <bank_id> "Should I learn Python?" --context "career advice"

# Higher budget for complex questions
hindsight memory reflect <bank_id> "Summarize my week" --budget high

Bank Management​

List Banks​

hindsight bank list

View Profile​

hindsight bank profile <bank_id>

View Statistics​

hindsight bank stats <bank_id>

Set Bank Name​

hindsight bank name <bank_id> "My Assistant"

Set Background​

hindsight bank background <bank_id> "I am a helpful AI assistant interested in technology"

# Skip automatic personality inference
hindsight bank background <bank_id> "Background text" --no-update-personality

Document Management​

# List documents
hindsight document list <bank_id>

# Get document details
hindsight document get <bank_id> <document_id>

# Delete document and its memories
hindsight document delete <bank_id> <document_id>

Entity Management​

# List entities
hindsight entity list <bank_id>

# Get entity details
hindsight entity get <bank_id> <entity_id>

# Regenerate entity observations
hindsight entity regenerate <bank_id> <entity_id>

Output Formats​

# Pretty (default)
hindsight memory recall <bank_id> "query"

# JSON
hindsight memory recall <bank_id> "query" -o json

# YAML
hindsight memory recall <bank_id> "query" -o yaml

Global Options​

FlagDescription
-v, --verboseShow detailed output including request/response
-o, --output <format>Output format: pretty, json, yaml
--helpShow help
--versionShow version

Interactive Explorer​

Launch the TUI explorer for visual navigation:

hindsight explore

Example Workflow​

# Configure API URL
hindsight configure --api-url http://localhost:8888

# Store some memories
hindsight memory retain demo "Alice works at Google"
hindsight memory retain demo "Bob is a data scientist"
hindsight memory retain demo "Alice and Bob are colleagues"

# Search memories
hindsight memory recall demo "Who works with Alice?"

# Generate a response
hindsight memory reflect demo "What do you know about the team?"

# Check bank profile
hindsight bank profile demo