---
sidebar_position: 4
---

# OpenClawd

Biomimetic long-term memory for [OpenClawd](https://openclawd.ai) using [Hindsight](https://vectorize.io/hindsight).

This plugin integrates [hindsight-embed](https://vectorize.io/hindsight/cli), 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

```bash
# 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

```bash
# 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`:

```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:
```bash
export OPENAI_API_KEY="sk-your-key"
clawdbot config set 'agents.defaults.models."openai/gpt-4o-mini"' '{}'
```

## Verification

**Check if plugin is loaded:**
```bash
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:**
```bash
tail -f ~/.hindsight/daemon.log
```

**Check memories in database:**
```bash
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:**
```bash
uvx hindsight-embed@latest daemon logs
# Or follow logs in real-time:
tail -f ~/.hindsight/daemon.log
```

**Open web UI:**
```bash
uvx hindsight-embed@latest ui
# Opens browser to http://localhost:8890
# Browse memories, facts, entities, and relationships
```

**List memory banks:**
```bash
uvx hindsight-embed@latest bank list
# Shows all banks including 'openclawd'
```

**Query memories:**
```bash
# 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:**
```bash
# 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?**
```bash
# Check plugin installation
clawdbot plugins list | grep -i hindsight

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

**Daemon not starting?**
```bash
# 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?**
```bash
# Set in shell profile
echo 'export OPENAI_API_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc

# Verify
echo $OPENAI_API_KEY
```

**Memories not being stored?**
```bash
# 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

```bash
# 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](https://vectorize.io/hindsight)
- [OpenClawd Documentation](https://openclawd.ai)
- [GitHub Repository](https://github.com/vectorize-io/hindsight)