🧠 Hindsight Memory Plugin for Agent Zero

Augments Agent Zero's built-in memory with Hindsight by Vectorize.io. Gives Agent Zero persistent, semantically-rich memory that goes beyond simple vector similarity — with disposition-aware context generation.

What It Does

How It Works

┌─────────────┐     retain        ┌──────────────┐     reflect       ┌──────────────┐
│  Agent Zero  │ ───────────────▶  │  Hindsight   │ ───────────────▶  │  Disposition  │
│  (your chat) │                   │  (memory)    │   context gen     │  (insights)   │
└──────┬───────┘                   └──────┬───────┘                   └──────────────┘
       │                                  │
       │◀──── recall + reflect ───────────┘
       │      (system prompt injection)

1. Retain — After each conversation turn, key facts and information are extracted and stored in Hindsight via the monologue_end extension
2. Recall — On each recall cycle, Hindsight is queried alongside the built-in memory for enriched semantic search results
3. Reflect — Hindsight generates disposition-aware context that is injected into the system prompt

Installation

1. Clone into Agent Zero's user plugins directory

cd /a0/usr/plugins
git clone https://github.com/YOUR_USERNAME/a0-plugin-hindsight.git hindsight

Or copy the plugin files directly into /a0/usr/plugins/hindsight/.

2. Install dependencies

pip install hindsight-client>=0.4.0

3. Set up a Hindsight server

Follow the Hindsight installation guide to run a local server:

docker run -p 8888:8888 vectorize/hindsight

Or use the Vectorize.io hosted service.

4. Configure in Agent Zero

1. Go to Settings → Agents → Hindsight Memory and set:

   • Hindsight Base URL — your Hindsight server URL (optional; e.g. http://localhost:8888)
   • HINDSIGHT_API_KEY — (optional) API key if required by your server (in Settings → Secrets)

2. Go to Settings → Plugins and enable Hindsight Memory

3. (Optional) Click Configure on the plugin to adjust:

   • Bank ID prefix
   • Enable/disable retain, recall, reflect individually
   • Recall/reflect budgets and token limits
   • Cache TTL

5. Restart Agent Zero

The plugin will be discovered on restart. You'll see [Hindsight] Integration enabled for bank: a0-default in the logs.

Plugin Structure

hindsight/
├── plugin.yaml                          # Plugin manifest
├── default_config.yaml                  # Settings defaults
├── requirements.txt                     # hindsight-client>=0.4.0
├── hooks.py                             # Install/update hooks
├── execute.py                           # User-triggered setup & health check
├── helpers/
│   ├── __init__.py
│   └── hindsight_helper.py              # Core integration logic
├── extensions/
│   └── python/
│       ├── monologue_start/
│       │   └── _20_hindsight_init.py    # Initialize Hindsight on agent start
│       ├── monologue_end/
│       │   └── _52_hindsight_retain.py  # Retain memories to Hindsight
│       ├── message_loop_prompts_after/
│       │   └── _51_hindsight_recall.py  # Enrich recall with Hindsight
│       └── system_prompt/
│           └── _30_hindsight_reflect.py # Inject reflect context into prompt
├── prompts/
│   ├── hindsight.retain_extract.sys.md  # Memory extraction prompt
│   ├── hindsight.recall.md              # Recall injection template
│   └── hindsight.reflect.md             # Reflect injection template
├── webui/
│   └── config.html                      # Settings UI
└── README.md

Configuration

Secrets (Settings → Secrets)

*Note: HINDSIGHT_BASE_URL is configured in the plugin settings UI. Setting it in Secrets is deprecated but still supported for backwards compatibility.

Plugin Settings (Settings → Plugins → Hindsight → Configure)

Hindsight Companion Skill (Optional CLI Access)

While the Hindsight plugin handles automatic lifecycle operations (retain, recall, reflect), you can also use the Hindsight companion skill for direct, opt-in CLI-style access to memory banks.

Loading the Skill

skills_tool:load hindsight

Once loaded, the skill provides:

When to Use the Skill

• Plugin alone: Automatic background operation (good for hands-off memory management)
• Plugin + Skill: Manual intervention when you need to:
  • Query specific memories outside normal conversation flow
  • Consolidate or reorganize memory banks
  • Export memory data for inspection
  • Troubleshoot or debug Hindsight service issues
  • Trigger memory operations explicitly within agent workflows

Architecture

The plugin and skill form a complementary pair:

┌─────────────────────────────────────┐
│  Plugin (Automatic Lifecycle)       │
├─────────────────────────────────────┤
│ • Retain after each conversation   │
│ • Recall during memory phase       │
│ • Reflect into system prompt       │
│ • Runs invisibly in background     │
└─────────────────────────────────────┘
         ↓         ↑
  Hindsight Server
         ↑         ↓
┌─────────────────────────────────────┐
│  Skill (Manual CLI Access)          │
├─────────────────────────────────────┤
│ • Query memories on demand         │
│ • Manage memory banks explicitly   │
│ • Export and analyze data          │
│ • Requires explicit load command   │
└─────────────────────────────────────┘

Both use the same Hindsight server and bank infrastructure—the plugin provides automatic operation, the skill provides manual control.

Hindsight Concepts

Requirements

• Agent Zero (with plugin system)
• Python 3.12+
• hindsight-client >= 0.4.0
• A running Hindsight server (local Docker or hosted)

Links

• Hindsight GitHub
• Vectorize.io
• Agent Zero

License

MIT