Release v0.4.2
- Update version to 0.4.2 in all components - Python packages: hindsight-api, hindsight-dev, hindsight-all, hindsight-litellm, hindsight-embed - Python client: hindsight-clients/python - TypeScript client: hindsight-clients/typescript - Rust CLI: hindsight-cli - Control Plane: hindsight-control-plane - Helm chart - Sync documentation to version-0.4
This commit is contained in:
Nicolò Boschi
parent
3f211f0729
commit
15540075b2
16 changed files with 570 additions and 14 deletions
|
|
@ -2,8 +2,8 @@ apiVersion: v2
|
|||
name: hindsight
|
||||
description: Hindsight helm chart
|
||||
type: application
|
||||
version: 0.4.1
|
||||
appVersion: "0.4.1"
|
||||
version: 0.4.2
|
||||
appVersion: "0.4.2"
|
||||
keywords:
|
||||
- ai
|
||||
- memory
|
||||
|
|
|
|||
|
|
@ -46,4 +46,4 @@ __all__ = [
|
|||
"RemoteTEICrossEncoder",
|
||||
"LLMConfig",
|
||||
]
|
||||
__version__ = "0.4.1"
|
||||
__version__ = "0.4.2"
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|||
|
||||
[project]
|
||||
name = "hindsight-api"
|
||||
version = "0.4.1"
|
||||
version = "0.4.2"
|
||||
description = "Hindsight: Agent Memory That Works Like Human Memory"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.11"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[package]
|
||||
name = "hindsight-cli"
|
||||
version = "0.4.1"
|
||||
version = "0.4.2"
|
||||
edition = "2021"
|
||||
authors = ["Hindsight Team"]
|
||||
description = "A beautiful CLI for Hindsight - semantic memory system"
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
""" # noqa: E501
|
||||
|
||||
|
||||
__version__ = "0.0.7"
|
||||
__version__ = "0.4.2"
|
||||
|
||||
# import apis into sdk package
|
||||
from hindsight_client_api.api.banks_api import BanksApi
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[project]
|
||||
name = "hindsight-client"
|
||||
version = "0.4.1"
|
||||
version = "0.4.2"
|
||||
description = "Python client for Hindsight - Semantic memory system with personality-driven thinking"
|
||||
authors = [
|
||||
{name = "Hindsight Team"}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "@vectorize-io/hindsight-client",
|
||||
"version": "0.4.1",
|
||||
"version": "0.4.2",
|
||||
"description": "TypeScript client for Hindsight - Semantic memory system with personality-driven thinking",
|
||||
"main": "./dist/src/index.js",
|
||||
"types": "./dist/src/index.d.ts",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "@vectorize-io/hindsight-control-plane",
|
||||
"version": "0.4.1",
|
||||
"version": "0.4.2",
|
||||
"description": "Control plane for Hindsight - Semantic memory system",
|
||||
"bin": {
|
||||
"hindsight-control-plane": "./bin/cli.js"
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|||
|
||||
[project]
|
||||
name = "hindsight-dev"
|
||||
version = "0.4.1"
|
||||
version = "0.4.2"
|
||||
description = "Development utilities for Hindsight"
|
||||
requires-python = ">=3.11"
|
||||
dependencies = [
|
||||
|
|
|
|||
|
|
@ -66,6 +66,9 @@ hindsight-admin run-db-migration --schema tenant_acme
|
|||
| `HINDSIGHT_API_LLM_MODEL` | Model name | `gpt-5-mini` |
|
||||
| `HINDSIGHT_API_LLM_BASE_URL` | Custom LLM endpoint | Provider default |
|
||||
| `HINDSIGHT_API_LLM_MAX_CONCURRENT` | Max concurrent LLM requests | `32` |
|
||||
| `HINDSIGHT_API_LLM_MAX_RETRIES` | Max retry attempts for LLM API calls | `10` |
|
||||
| `HINDSIGHT_API_LLM_INITIAL_BACKOFF` | Initial retry backoff in seconds (exponential backoff) | `1.0` |
|
||||
| `HINDSIGHT_API_LLM_MAX_BACKOFF` | Max retry backoff cap in seconds | `60.0` |
|
||||
| `HINDSIGHT_API_LLM_TIMEOUT` | LLM request timeout in seconds | `120` |
|
||||
| `HINDSIGHT_API_LLM_GROQ_SERVICE_TIER` | Groq service tier: `on_demand`, `flex`, `auto` | `auto` |
|
||||
|
||||
|
|
@ -121,14 +124,29 @@ Different memory operations have different requirements. **Retain** (fact extrac
|
|||
| `HINDSIGHT_API_RETAIN_LLM_API_KEY` | API key for retain LLM | Falls back to `HINDSIGHT_API_LLM_API_KEY` |
|
||||
| `HINDSIGHT_API_RETAIN_LLM_MODEL` | Model for retain operations | Falls back to `HINDSIGHT_API_LLM_MODEL` |
|
||||
| `HINDSIGHT_API_RETAIN_LLM_BASE_URL` | Base URL for retain LLM | Falls back to `HINDSIGHT_API_LLM_BASE_URL` |
|
||||
| `HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT` | Max concurrent requests for retain | Falls back to `HINDSIGHT_API_LLM_MAX_CONCURRENT` |
|
||||
| `HINDSIGHT_API_RETAIN_LLM_MAX_RETRIES` | Max retries for retain | Falls back to `HINDSIGHT_API_LLM_MAX_RETRIES` |
|
||||
| `HINDSIGHT_API_RETAIN_LLM_INITIAL_BACKOFF` | Initial backoff for retain retries (seconds) | Falls back to `HINDSIGHT_API_LLM_INITIAL_BACKOFF` |
|
||||
| `HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF` | Max backoff cap for retain retries (seconds) | Falls back to `HINDSIGHT_API_LLM_MAX_BACKOFF` |
|
||||
| `HINDSIGHT_API_RETAIN_LLM_TIMEOUT` | Timeout for retain requests (seconds) | Falls back to `HINDSIGHT_API_LLM_TIMEOUT` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_PROVIDER` | LLM provider for reflect operations | Falls back to `HINDSIGHT_API_LLM_PROVIDER` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_API_KEY` | API key for reflect LLM | Falls back to `HINDSIGHT_API_LLM_API_KEY` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_MODEL` | Model for reflect operations | Falls back to `HINDSIGHT_API_LLM_MODEL` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_BASE_URL` | Base URL for reflect LLM | Falls back to `HINDSIGHT_API_LLM_BASE_URL` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_MAX_CONCURRENT` | Max concurrent requests for reflect | Falls back to `HINDSIGHT_API_LLM_MAX_CONCURRENT` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_MAX_RETRIES` | Max retries for reflect | Falls back to `HINDSIGHT_API_LLM_MAX_RETRIES` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_INITIAL_BACKOFF` | Initial backoff for reflect retries (seconds) | Falls back to `HINDSIGHT_API_LLM_INITIAL_BACKOFF` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_MAX_BACKOFF` | Max backoff cap for reflect retries (seconds) | Falls back to `HINDSIGHT_API_LLM_MAX_BACKOFF` |
|
||||
| `HINDSIGHT_API_REFLECT_LLM_TIMEOUT` | Timeout for reflect requests (seconds) | Falls back to `HINDSIGHT_API_LLM_TIMEOUT` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_PROVIDER` | LLM provider for observation consolidation | Falls back to `HINDSIGHT_API_LLM_PROVIDER` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_API_KEY` | API key for consolidation LLM | Falls back to `HINDSIGHT_API_LLM_API_KEY` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_MODEL` | Model for consolidation operations | Falls back to `HINDSIGHT_API_LLM_MODEL` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_BASE_URL` | Base URL for consolidation LLM | Falls back to `HINDSIGHT_API_LLM_BASE_URL` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT` | Max concurrent requests for consolidation | Falls back to `HINDSIGHT_API_LLM_MAX_CONCURRENT` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_MAX_RETRIES` | Max retries for consolidation | Falls back to `HINDSIGHT_API_LLM_MAX_RETRIES` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_INITIAL_BACKOFF` | Initial backoff for consolidation retries (seconds) | Falls back to `HINDSIGHT_API_LLM_INITIAL_BACKOFF` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_MAX_BACKOFF` | Max backoff cap for consolidation retries (seconds) | Falls back to `HINDSIGHT_API_LLM_MAX_BACKOFF` |
|
||||
| `HINDSIGHT_API_CONSOLIDATION_LLM_TIMEOUT` | Timeout for consolidation requests (seconds) | Falls back to `HINDSIGHT_API_LLM_TIMEOUT` |
|
||||
|
||||
:::tip When to Use Per-Operation Config
|
||||
- **Retain**: Use models with strong structured output (e.g., GPT-4o, Claude) for accurate fact extraction
|
||||
|
|
@ -153,6 +171,25 @@ export HINDSIGHT_API_REFLECT_LLM_API_KEY=gsk_xxxxxxxxxxxx
|
|||
export HINDSIGHT_API_REFLECT_LLM_MODEL=llama-3.3-70b-versatile
|
||||
```
|
||||
|
||||
**Example: Tuning Retry Behavior for Rate-Limited APIs**
|
||||
|
||||
```bash
|
||||
# For Anthropic with tight rate limits (10k output tokens/minute)
|
||||
export HINDSIGHT_API_LLM_PROVIDER=anthropic
|
||||
export HINDSIGHT_API_LLM_API_KEY=sk-ant-xxxxxxxxxxxx
|
||||
export HINDSIGHT_API_LLM_MODEL=claude-sonnet-4-20250514
|
||||
|
||||
# Reduce concurrent requests for retain to avoid rate limits
|
||||
export HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT=3
|
||||
|
||||
# Fail faster with fewer retries
|
||||
export HINDSIGHT_API_RETAIN_LLM_MAX_RETRIES=3
|
||||
|
||||
# Or increase backoff times to wait out rate limit windows
|
||||
export HINDSIGHT_API_RETAIN_LLM_INITIAL_BACKOFF=2.0 # Start at 2s instead of 1s
|
||||
export HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF=120.0 # Cap at 2min instead of 1min
|
||||
```
|
||||
|
||||
### Embeddings
|
||||
|
||||
| Variable | Description | Default |
|
||||
|
|
|
|||
262
hindsight-docs/versioned_docs/version-0.4/sdks/embed.md
Normal file
262
hindsight-docs/versioned_docs/version-0.4/sdks/embed.md
Normal file
|
|
@ -0,0 +1,262 @@
|
|||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Embedded SDK (hindsight-embed)
|
||||
|
||||
Zero-configuration local memory system with automatic daemon management. Perfect for development, prototyping, and single-user applications.
|
||||
|
||||
## Overview
|
||||
|
||||
`hindsight-embed` is a zero-configuration SDK that wraps the Hindsight API and PostgreSQL database into a single auto-managed local daemon. It's designed for development, prototyping, and single-user applications where you want memory capabilities without infrastructure overhead.
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. **First command triggers startup**: When you run any `hindsight-embed` command, it checks if a local daemon is running
|
||||
2. **Auto-daemon management**: If no daemon exists, it automatically spawns `hindsight-api --daemon` in the background
|
||||
3. **Embedded database**: The daemon uses `pg0` (embedded PostgreSQL) — no separate database installation required
|
||||
4. **Command forwarding**: Your command is forwarded to the local daemon via HTTP (localhost:8889)
|
||||
5. **Auto-shutdown**: After 5 minutes of inactivity (configurable), the daemon gracefully shuts down to free resources
|
||||
|
||||
**Key features:**
|
||||
|
||||
- **Zero setup** — One `configure` command and you're ready
|
||||
- **Automatic lifecycle** — Daemon starts on-demand, stops when idle
|
||||
- **Isolated storage** — Each bank gets its own embedded PostgreSQL database
|
||||
- **Local-only** — Binds to `127.0.0.1:8889`, not accessible from network
|
||||
- **Production-grade engine** — Uses the same memory engine as the full API service
|
||||
|
||||
Think of it as SQLite for long-term memory — all the power of Hindsight without managing servers.
|
||||
|
||||
## Installation
|
||||
|
||||
Install via `uvx` (recommended - always latest version):
|
||||
|
||||
```bash
|
||||
# Run directly without installation
|
||||
uvx hindsight-embed@latest configure
|
||||
|
||||
# Or use pipx for persistent installation
|
||||
pipx install hindsight-embed
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Configure
|
||||
|
||||
```bash
|
||||
# Interactive configuration
|
||||
hindsight-embed configure
|
||||
|
||||
# Or non-interactive via environment variables
|
||||
export HINDSIGHT_EMBED_LLM_PROVIDER=openai
|
||||
export HINDSIGHT_EMBED_LLM_API_KEY=sk-xxxxxxxxxxxx
|
||||
export HINDSIGHT_EMBED_LLM_MODEL=gpt-4o-mini
|
||||
hindsight-embed configure
|
||||
```
|
||||
|
||||
Configuration is saved to `~/.hindsight/embed`:
|
||||
|
||||
```bash
|
||||
HINDSIGHT_EMBED_LLM_PROVIDER=openai
|
||||
HINDSIGHT_EMBED_LLM_MODEL=gpt-4o-mini
|
||||
HINDSIGHT_EMBED_BANK_ID=default
|
||||
HINDSIGHT_EMBED_LLM_API_KEY=sk-xxxxxxxxxxxx
|
||||
|
||||
# Daemon settings (macOS: force CPU to avoid MPS/XPC issues)
|
||||
HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU=1
|
||||
HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU=1
|
||||
```
|
||||
|
||||
### 2. Use Memory Operations
|
||||
|
||||
```bash
|
||||
# Store a memory
|
||||
hindsight-embed memory retain default "User prefers dark mode"
|
||||
|
||||
# Query memories
|
||||
hindsight-embed memory recall default "user preferences"
|
||||
|
||||
# Reasoning with memory
|
||||
hindsight-embed memory reflect default "What color scheme should I use?"
|
||||
```
|
||||
|
||||
The daemon starts automatically on first use!
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `HINDSIGHT_EMBED_LLM_API_KEY` | **Required**. API key for LLM provider | - |
|
||||
| `HINDSIGHT_EMBED_LLM_PROVIDER` | LLM provider: `openai`, `anthropic`, `gemini`, `groq`, `ollama` | `openai` |
|
||||
| `HINDSIGHT_EMBED_LLM_MODEL` | Model name | `gpt-4o-mini` |
|
||||
| `HINDSIGHT_EMBED_BANK_ID` | Default memory bank ID | `default` |
|
||||
| `HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT` | Seconds before daemon auto-exits when idle (0 = never) | `300` |
|
||||
|
||||
**Provider Examples:**
|
||||
|
||||
```bash
|
||||
# OpenAI
|
||||
export HINDSIGHT_EMBED_LLM_PROVIDER=openai
|
||||
export HINDSIGHT_EMBED_LLM_API_KEY=sk-xxxxxxxxxxxx
|
||||
export HINDSIGHT_EMBED_LLM_MODEL=gpt-4o
|
||||
|
||||
# Groq (fast inference)
|
||||
export HINDSIGHT_EMBED_LLM_PROVIDER=groq
|
||||
export HINDSIGHT_EMBED_LLM_API_KEY=gsk_xxxxxxxxxxxx
|
||||
export HINDSIGHT_EMBED_LLM_MODEL=llama-3.3-70b-versatile
|
||||
|
||||
# Anthropic
|
||||
export HINDSIGHT_EMBED_LLM_PROVIDER=anthropic
|
||||
export HINDSIGHT_EMBED_LLM_API_KEY=sk-ant-xxxxxxxxxxxx
|
||||
export HINDSIGHT_EMBED_LLM_MODEL=claude-sonnet-4-20250514
|
||||
```
|
||||
|
||||
## Daemon Management
|
||||
|
||||
### Idle Timeout
|
||||
|
||||
Customize how long the daemon stays alive when idle:
|
||||
|
||||
```bash
|
||||
# Never timeout (daemon runs until manually stopped)
|
||||
export HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT=0
|
||||
|
||||
# Shorter timeout: 1 minute
|
||||
export HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT=60
|
||||
|
||||
# Longer timeout: 30 minutes
|
||||
export HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT=1800
|
||||
```
|
||||
|
||||
### Daemon Commands
|
||||
|
||||
```bash
|
||||
# Check daemon status
|
||||
hindsight-embed daemon status
|
||||
|
||||
# View daemon logs in real-time
|
||||
hindsight-embed daemon logs -f
|
||||
|
||||
# Stop daemon manually
|
||||
hindsight-embed daemon stop
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
All memory operations follow the same interface as the CLI:
|
||||
|
||||
### Retain (Store Memory)
|
||||
|
||||
```bash
|
||||
hindsight-embed memory retain <bank_id> "content"
|
||||
|
||||
# With context
|
||||
hindsight-embed memory retain <bank_id> "content" --context "source information"
|
||||
|
||||
# Background processing
|
||||
hindsight-embed memory retain <bank_id> "content" --async
|
||||
```
|
||||
|
||||
### Recall (Search)
|
||||
|
||||
```bash
|
||||
hindsight-embed memory recall <bank_id> "query"
|
||||
|
||||
# With budget control
|
||||
hindsight-embed memory recall <bank_id> "query" --budget high
|
||||
|
||||
# Show trace
|
||||
hindsight-embed memory recall <bank_id> "query" --trace
|
||||
```
|
||||
|
||||
### Reflect (Generate Response)
|
||||
|
||||
```bash
|
||||
hindsight-embed memory reflect <bank_id> "prompt"
|
||||
|
||||
# With additional context
|
||||
hindsight-embed memory reflect <bank_id> "prompt" --context "additional info"
|
||||
```
|
||||
|
||||
### Bank Management
|
||||
|
||||
```bash
|
||||
# List all banks
|
||||
hindsight-embed bank list
|
||||
|
||||
# View bank stats
|
||||
hindsight-embed bank stats <bank_id>
|
||||
|
||||
# Set bank name
|
||||
hindsight-embed bank name <bank_id> "My Assistant"
|
||||
|
||||
# Set bank mission
|
||||
hindsight-embed bank mission <bank_id> "I am a helpful AI assistant"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Daemon Won't Start
|
||||
|
||||
Check the daemon logs:
|
||||
|
||||
```bash
|
||||
hindsight-embed daemon logs
|
||||
# Or watch in real-time
|
||||
hindsight-embed daemon logs -f
|
||||
```
|
||||
|
||||
Common issues:
|
||||
- **Missing API key**: Set `HINDSIGHT_EMBED_LLM_API_KEY`
|
||||
- **Port conflict**: Another service using port 8889
|
||||
- **Permissions**: Check `~/.hindsight/` directory permissions
|
||||
|
||||
### Daemon Exits Immediately
|
||||
|
||||
Check if you have the idle timeout set too low:
|
||||
|
||||
```bash
|
||||
# Disable idle timeout for debugging
|
||||
export HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT=0
|
||||
hindsight-embed daemon status
|
||||
```
|
||||
|
||||
### Reset Configuration
|
||||
|
||||
```bash
|
||||
# Remove config file and reconfigure
|
||||
rm ~/.hindsight/embed
|
||||
hindsight-embed configure
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
While `hindsight-embed` aims to be zero-config, you can customize the underlying API behavior by setting `HINDSIGHT_API_*` variables in `~/.hindsight/embed`:
|
||||
|
||||
```bash
|
||||
# Example: Custom embedding model
|
||||
HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
|
||||
HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL=text-embedding-3-large
|
||||
|
||||
# Example: Verbose extraction
|
||||
HINDSIGHT_API_RETAIN_EXTRACTION_MODE=verbose
|
||||
```
|
||||
|
||||
See [Configuration](/developer/configuration) for all available `HINDSIGHT_API_*` options.
|
||||
|
||||
## When to Use
|
||||
|
||||
**Perfect for:**
|
||||
- Development and prototyping
|
||||
- Single-user applications
|
||||
- Local-first tools
|
||||
- Quick experiments with Hindsight
|
||||
|
||||
**Not suitable for:**
|
||||
- Production multi-user deployments
|
||||
- Network-accessible services
|
||||
- High-availability requirements
|
||||
- Multi-tenant applications
|
||||
|
||||
For production deployments, use the [API Service](/developer/services) with external PostgreSQL instead.
|
||||
|
|
@ -0,0 +1,257 @@
|
|||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Moltbot (Clawdbot)
|
||||
|
||||
Biomimetic long-term memory for [Moltbot](https://molt.bot) using [Hindsight](https://vectorize.io/hindsight). Automatically captures conversations and intelligently recalls relevant context.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Install the plugin
|
||||
npm install -g @vectorize-io/hindsight-moltbot-plugin
|
||||
|
||||
# 2. Configure your LLM provider
|
||||
export OPENAI_API_KEY="sk-your-key"
|
||||
clawdbot config set 'agents.defaults.models."openai/gpt-4o-mini"' '{}'
|
||||
|
||||
# 3. Enable the plugin
|
||||
clawdbot plugins enable hindsight-memory
|
||||
|
||||
# 4. Start Moltbot
|
||||
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 Moltbot Concepts
|
||||
|
||||
### Plugins
|
||||
Extensions that add functionality to Moltbot. 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
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Moltbot 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)
|
||||
• Fact extraction
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js** 22+
|
||||
- **Moltbot** (Clawdbot) with plugin support
|
||||
- **uv/uvx** for running `hindsight-embed`
|
||||
- **LLM API key** (OpenAI, Anthropic, etc.)
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# 1. Install the plugin
|
||||
npm install -g @vectorize-io/hindsight-moltbot-plugin
|
||||
|
||||
# 2. Configure your LLM provider
|
||||
export OPENAI_API_KEY="sk-your-key"
|
||||
clawdbot config set 'agents.defaults.models."openai/gpt-4o-mini"' '{}'
|
||||
|
||||
# 3. Enable the plugin
|
||||
clawdbot plugins enable hindsight-memory
|
||||
|
||||
# 4. Start Moltbot
|
||||
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-memory": {
|
||||
"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
|
||||
|
||||
## 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 Moltbot 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 memory recall moltbot "pizza" --output json
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Plugin not loading?**
|
||||
```bash
|
||||
# Check plugin installation
|
||||
npm list -g @vectorize-io/hindsight-moltbot-plugin
|
||||
|
||||
# Reinstall if needed
|
||||
npm install -g @vectorize-io/hindsight-moltbot-plugin
|
||||
clawdbot plugins enable hindsight-memory
|
||||
```
|
||||
|
||||
**Daemon not starting?**
|
||||
```bash
|
||||
# Check daemon status
|
||||
uvx hindsight-embed daemon status
|
||||
|
||||
# Manually start
|
||||
uvx hindsight-embed 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/moltbot
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build
|
||||
npm run build
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Install locally
|
||||
npm run build && ./install.sh
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Node.js** 22+
|
||||
- **Moltbot** (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)
|
||||
- [Moltbot Documentation](https://docs.molt.bot)
|
||||
- [GitHub Repository](https://github.com/vectorize-io/hindsight)
|
||||
|
|
@ -1,3 +1,3 @@
|
|||
"""Hindsight embedded CLI - local memory operations without a server."""
|
||||
|
||||
__version__ = "0.4.1"
|
||||
__version__ = "0.4.2"
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|||
|
||||
[project]
|
||||
name = "hindsight-embed"
|
||||
version = "0.4.1"
|
||||
version = "0.4.2"
|
||||
description = "Hindsight embedded CLI - local memory operations without a server"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.11"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[project]
|
||||
name = "hindsight-litellm"
|
||||
version = "0.4.1"
|
||||
version = "0.4.2"
|
||||
description = "Universal LLM memory integration via LiteLLM - works with 100+ providers"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.10"
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|||
|
||||
[project]
|
||||
name = "hindsight-all"
|
||||
version = "0.4.1"
|
||||
version = "0.4.2"
|
||||
description = "Hindsight: Agent Memory That Works Like Human Memory - All-in-One Bundle"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.11"
|
||||
|
|
|
|||
Loading…
Reference in a new issue