fleet-memory/hindsight-docs/docs/sdks/cli.md

sidebar_position
3

CLI Reference

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

Installation

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

Configuration

Set environment variables or use command flags:

export HINDSIGHT_API_URL=http://localhost:8888
export HINDSIGHT_AGENT_ID=my-agent

Commands

Memory Operations

put

Store a memory:

hindsight put <agent_id> "Alice works at Google as a software engineer"

# With context
hindsight put <agent_id> "Bob loves hiking" --context "hobby discussion"

# With event date
hindsight put <agent_id> "Meeting with Carol" --date "2024-01-15"

put-files

Store file contents as memories:

# Store a single file
hindsight put-files <agent_id> notes.txt

# Store multiple files
hindsight put-files <agent_id> file1.txt file2.md file3.json

# With context
hindsight put-files <agent_id> meeting-notes.txt --context "team meeting"

search

Search memories:

hindsight search <agent_id> "What does Alice do?"

# With options
hindsight search <agent_id> "hiking recommendations" --budget 100 --top-k 5

# Verbose output
hindsight search <agent_id> "query" -v

think

Generate a response using memories and opinions:

hindsight think <agent_id> "What do you know about Alice?"

# Verbose mode shows reasoning
hindsight think <agent_id> "Should I recommend Python or Java?" -v

Memory bank Management

memory banks

List all memory banks:

hindsight memory banks

Output:

Available memory banks:
  - alice-agent
  - bob-agent
  - tech-advisor

profile

View memory bank profile:

hindsight profile <agent_id>

Output:

Memory bank: my-agent

Personality:
  Openness:          0.80
  Conscientiousness: 0.60
  Extraversion:      0.50
  Agreeableness:     0.70
  Neuroticism:       0.30
  Bias Strength:     0.70

Background:
  I am a helpful AI assistant interested in technology.

set-personality

Update personality traits:

hindsight set-personality <agent_id> \
  --openness 0.8 \
  --conscientiousness 0.6 \
  --extraversion 0.5 \
  --agreeableness 0.7 \
  --neuroticism 0.3 \
  --bias-strength 0.7

background

Add or merge background:

# Set/merge background
hindsight background <agent_id> "I have expertise in distributed systems"

MCP Server

Start the MCP server:

hindsight mcp-server

# With custom configuration
HINDSIGHT_API_URL=http://api.example.com hindsight mcp-server

Output Formats

Pretty (Default)

Human-readable formatted output:

hindsight search <agent_id> "query"

JSON

Machine-readable JSON output:

hindsight search <agent_id> "query" -o json

YAML

YAML formatted output:

hindsight search <agent_id> "query" -o yaml

Verbose Mode

Add -v or --verbose for detailed output:

hindsight search <agent_id> "query" -v

Shows:

• Request payload
• Response details
• Timing information

Global Options

Flag	Description
-v, --verbose	Verbose output
-o, --output <format>	Output format: pretty, json, yaml
--api-url <url>	Override API URL
--help	Show help
--version	Show version

Examples

Full Workflow

# Create a memory bank
curl -X PUT http://localhost:8888/api/memory banks/demo-agent \
  -H "Content-Type: application/json" \
  -d '{"background": "Demo agent"}'

# Store memories
hindsight put demo-agent "Alice works at Google"
hindsight put demo-agent "Bob is a data scientist"
hindsight put demo-agent "Alice and Bob are colleagues"

# Search
hindsight search demo-agent "Who works with Alice?"

# Think (with opinions)
hindsight think demo-agent "What do you know about the team?"

# Update personality
hindsight set-personality demo-agent \
  --openness 0.9 \
  --conscientiousness 0.7 \
  --extraversion 0.6 \
  --agreeableness 0.8 \
  --neuroticism 0.2 \
  --bias-strength 0.6

# Check profile
hindsight profile demo-agent