fleet-memory/hindsight-docs/docs/sdks/integrations/openclawd.md

sidebar_position
4

OpenClawd

Biomimetic long-term memory for OpenClawd using Hindsight.

This plugin integrates hindsight-embed, a standalone daemon that bundles Hindsight's memory engine (API + PostgreSQL) into a single command. The plugin automatically manages the daemon lifecycle and provides hooks for seamless memory capture and recall.

Quick Start

# 1. Configure your LLM provider
export OPENAI_API_KEY="sk-your-key"
clawdbot config set 'agents.defaults.models."openai/gpt-4o-mini"' '{}'

# 2. Install and enable the plugin
clawdbot plugins install @vectorize-io/hindsight-openclawd

# 3. Start OpenClawd
clawdbot gateway

That's it! The plugin will automatically start capturing and recalling memories.

How It Works

Auto-Capture (Hooks)

Every conversation is automatically stored after each turn:

• Extracts facts, entities, and relationships
• Processes in background (non-blocking)
• Stores in PostgreSQL via embedded hindsight-api

Auto-Recall (Before Agent Start)

Before each agent response, relevant memories are automatically injected:

• Relevant memories retrieved (up to 1024 tokens)
• Injected into context with <hindsight-context> tags
• Agent seamlessly uses past context

Understanding OpenClawd Concepts

Plugins

Extensions that add functionality to OpenClawd. This Hindsight plugin:

• Runs a background service (manages hindsight-embed daemon)
• Registers hooks (automatic event handlers)

Hooks

Automatic event handlers that run without agent involvement:

• before_agent_start: Auto-recall - injects memories before agent processes message
• agent_end: Auto-capture - stores conversation after agent responds

Think of hooks as "forced automation" - they always run.

Architecture

┌─────────────────────────────────────────┐
│  OpenClawd Gateway                        │
│                                         │
│  ┌───────────────────────────────────┐ │
│  │  Hindsight Plugin                 │ │
│  │                                   │ │
│  │  • Service: Manages daemon       │ │
│  │  • Hook: before_agent_start      │ │
│  │    → Auto-recall (1024 tokens)   │ │
│  │  • Hook: agent_end               │ │
│  │    → Auto-capture                │ │
│  └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
                  ↓
       uvx hindsight-embed
       • Daemon on port 8889
       • PostgreSQL (pg0://hindsight-embed)
       • Bank: 'openclawd' (isolated within shared database)
       • Fact extraction

Database Architecture: All banks share a single pg0 database instance (pg0://hindsight-embed). Bank isolation happens within the database via separate tables/schemas per bank ID. The 'openclawd' bank is automatically created when the plugin stores its first memory.

Installation

Prerequisites

• Node.js 22+
• OpenClawd (Clawdbot) with plugin support
• uv/uvx for running hindsight-embed
• LLM API key (OpenAI, Anthropic, etc.)

Setup

# 1. Configure your LLM provider
export OPENAI_API_KEY="sk-your-key"
clawdbot config set 'agents.defaults.models."openai/gpt-4o-mini"' '{}'

# 2. Install and enable the plugin
clawdbot plugins install @vectorize-io/hindsight-openclawd

# 3. Start OpenClawd
clawdbot gateway

On first start, uvx will automatically download hindsight-embed (no manual installation needed).

Configuration

Optional settings in ~/.clawdbot/clawdbot.json:

{
  "plugins": {
    "entries": {
      "hindsight-openclawd": {
        "enabled": true,
        "config": {
          "daemonIdleTimeout": 0
        }
      }
    }
  }
}

Options:

• daemonIdleTimeout (number, default: 0) - Seconds before daemon shuts down from inactivity (0 = never)
• embedPort (number, default: auto) - Port for embedded server
• bankMission (string, default: none) - Custom context for the memory bank
• embedVersion (string, default: "latest") - hindsight-embed version to use (e.g., "latest", "0.4.2", or leave empty for latest). Use this to pin a specific version if latest is broken.

Supported LLM Providers

The plugin auto-detects your configured provider and API key:

Provider	Environment Variable	Model Example
OpenAI	OPENAI_API_KEY	openai/gpt-4o-mini
Anthropic	ANTHROPIC_API_KEY	anthropic/claude-sonnet-4
Gemini	GEMINI_API_KEY	gemini/gemini-2.0-flash-exp
Groq	GROQ_API_KEY	groq/llama-3.3-70b
Ollama	None needed	ollama/llama3

Configure with:

export OPENAI_API_KEY="sk-your-key"
clawdbot config set 'agents.defaults.models."openai/gpt-4o-mini"' '{}'

Verification

Check if plugin is loaded:

clawdbot plugins list | grep hindsight
# Should show: ✓ enabled │ Hindsight Memory │ ...

Test auto-recall: Send a message on any OpenClawd channel (Telegram, Slack, etc.):

User: My name is John and I love pizza
Bot: Got it! I'll remember that.

User: What do I like to eat?
Bot: You love pizza!  # ← Used auto-recall

View daemon logs:

tail -f ~/.hindsight/daemon.log

Check memories in database:

uvx hindsight-embed@latest memory recall openclawd "pizza" --output json

Inspecting Memories

The plugin uses hindsight-embed daemon which provides CLI commands for inspection:

View daemon logs:

uvx hindsight-embed@latest daemon logs
# Or follow logs in real-time:
tail -f ~/.hindsight/daemon.log

Open web UI:

uvx hindsight-embed@latest ui
# Opens browser to http://localhost:8890
# Browse memories, facts, entities, and relationships

List memory banks:

uvx hindsight-embed@latest bank list
# Shows all banks including 'openclawd'

Query memories:

# Search memories
uvx hindsight-embed@latest memory recall openclawd "user preferences" --output json

# View recent memories
uvx hindsight-embed@latest memory list openclawd --limit 10

# Export all memories
uvx hindsight-embed@latest memory export openclawd --output memories.json

Inspect facts and entities:

# List extracted facts
uvx hindsight-embed@latest fact list openclawd

# List entities
uvx hindsight-embed@latest entity list openclawd

# Show entity relationships
uvx hindsight-embed@latest entity graph openclawd

Troubleshooting

Plugin not loading?

# Check plugin installation
clawdbot plugins list | grep -i hindsight

# Reinstall if needed
clawdbot plugins install @vectorize-io/hindsight-openclawd

Daemon not starting?

# Check daemon status
uvx hindsight-embed@latest daemon status

# Manually start
uvx hindsight-embed@latest daemon start

# View logs
tail -f ~/.hindsight/daemon.log

No API key error?

# Set in shell profile
echo 'export OPENAI_API_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc

# Verify
echo $OPENAI_API_KEY

Memories not being stored?

# Check gateway logs for auto-capture
tail -f /tmp/clawdbot/clawdbot-*.log | grep Hindsight

# Should see:
# [Hindsight Hook] agent_end triggered
# [Hindsight] Retained X messages for session ...

Development

# Clone repo
git clone https://github.com/vectorize-io/hindsight.git
cd hindsight/hindsight-integrations/openclawd

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Install locally
npm run build && ./install.sh

Requirements

• Node.js 22+
• OpenClawd (Clawdbot) with plugin support
• uv/uvx for running hindsight-embed
• LLM API key (OpenAI, Anthropic, etc.)

License

MIT

Links

• Hindsight Documentation
• OpenClawd Documentation
• GitHub Repository