@vectorize-io/hindsight-openclaw 0.4.6 → 0.4.8

package/README.md

@@ -5,9 +5,15 @@ Biomimetic long-term memory for [OpenClaw](https://openclaw.ai) using [Hindsight
 ## Quick Start
 
 ```bash
-# 1. Configure your LLM provider
+# 1. Configure your LLM provider for memory extraction
+# Option A: OpenAI
 export OPENAI_API_KEY="sk-your-key"
-openclaw config set 'agents.defaults.models."openai/gpt-4o-mini"' '{}'
+
+# Option B: Claude Code (no API key needed)
+export HINDSIGHT_API_LLM_PROVIDER=claude-code
+
+# Option C: OpenAI Codex (no API key needed)
+export HINDSIGHT_API_LLM_PROVIDER=openai-codex
 
 # 2. Install and enable the plugin
 openclaw plugins install @vectorize-io/hindsight-openclaw
@@ -24,6 +30,40 @@ For full documentation, configuration options, troubleshooting, and development
 
 **[OpenClaw Integration Documentation](https://vectorize.io/hindsight/sdks/integrations/openclaw)**
 
+## Development
+
+To test local changes to the Hindsight package before publishing:
+
+1. Add `embedPackagePath` to your plugin config in `~/.openclaw/openclaw.json`:
+```json
+{
+  "plugins": {
+    "entries": {
+      "hindsight-openclaw": {
+        "enabled": true,
+        "config": {
+          "embedPackagePath": "/path/to/hindsight-wt3/hindsight-embed"
+        }
+      }
+    }
+  }
+}
+```
+
+2. The plugin will use `uv run --directory <path> hindsight-embed` instead of `uvx hindsight-embed@latest`
+
+3. To use a specific profile for testing:
+```bash
+# Check daemon status
+uvx hindsight-embed@latest -p openclaw daemon status
+
+# View logs
+tail -f ~/.hindsight/profiles/openclaw.log
+
+# List profiles
+uvx hindsight-embed@latest profile list
+```
+
 ## Links
 
 - [Hindsight Documentation](https://vectorize.io/hindsight)

package/dist/client.d.ts

@@ -5,10 +5,14 @@ export declare class HindsightClient {
     private llmApiKey;
     private llmModel?;
     private embedVersion;
-    constructor(llmProvider: string, llmApiKey: string, llmModel?: string, embedVersion?: string);
+    private embedPackagePath?;
+    constructor(llmProvider: string, llmApiKey: string, llmModel?: string, embedVersion?: string, embedPackagePath?: string);
+    /**
+     * Get the command prefix to run hindsight-embed (either local or from PyPI)
+     */
+    private getEmbedCommandPrefix;
     setBankId(bankId: string): void;
     setBankMission(mission: string): Promise<void>;
-    private getEnv;
     retain(request: RetainRequest): Promise<RetainResponse>;
     recall(request: RecallRequest): Promise<RecallResponse>;
 }

package/dist/client.js

@@ -7,11 +7,27 @@ export class HindsightClient {
     llmApiKey;
     llmModel;
     embedVersion;
-    constructor(llmProvider, llmApiKey, llmModel, embedVersion = 'latest') {
+    embedPackagePath;
+    constructor(llmProvider, llmApiKey, llmModel, embedVersion = 'latest', embedPackagePath) {
         this.llmProvider = llmProvider;
         this.llmApiKey = llmApiKey;
         this.llmModel = llmModel;
         this.embedVersion = embedVersion || 'latest';
+        this.embedPackagePath = embedPackagePath;
+    }
+    /**
+     * Get the command prefix to run hindsight-embed (either local or from PyPI)
+     */
+    getEmbedCommandPrefix() {
+        if (this.embedPackagePath) {
+            // Local package: uv run --directory <path> hindsight-embed
+            return `uv run --directory ${this.embedPackagePath} hindsight-embed`;
+        }
+        else {
+            // PyPI package: uvx hindsight-embed@version
+            const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
+            return `uvx ${embedPackage}`;
+        }
     }
     setBankId(bankId) {
         this.bankId = bankId;
@@ -21,10 +37,10 @@ export class HindsightClient {
             return;
         }
         const escapedMission = mission.replace(/'/g, "'\\''"); // Escape single quotes
-        const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
-        const cmd = `uvx ${embedPackage} bank mission ${this.bankId} '${escapedMission}'`;
+        const embedCmd = this.getEmbedCommandPrefix();
+        const cmd = `${embedCmd} --profile openclaw bank mission ${this.bankId} '${escapedMission}'`;
         try {
-            const { stdout } = await execAsync(cmd, { env: this.getEnv() });
+            const { stdout } = await execAsync(cmd);
             console.log(`[Hindsight] Bank mission set: ${stdout.trim()}`);
         }
         catch (error) {
@@ -32,24 +48,13 @@ export class HindsightClient {
             console.warn(`[Hindsight] Could not set bank mission (bank may not exist yet): ${error}`);
         }
     }
-    getEnv() {
-        const env = {
-            ...process.env,
-            HINDSIGHT_EMBED_LLM_PROVIDER: this.llmProvider,
-            HINDSIGHT_EMBED_LLM_API_KEY: this.llmApiKey,
-        };
-        if (this.llmModel) {
-            env.HINDSIGHT_EMBED_LLM_MODEL = this.llmModel;
-        }
-        return env;
-    }
     async retain(request) {
         const content = request.content.replace(/'/g, "'\\''"); // Escape single quotes
         const docId = request.document_id || 'conversation';
-        const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
-        const cmd = `uvx ${embedPackage} memory retain ${this.bankId} '${content}' --doc-id '${docId}' --async`;
+        const embedCmd = this.getEmbedCommandPrefix();
+        const cmd = `${embedCmd} --profile openclaw memory retain ${this.bankId} '${content}' --doc-id '${docId}' --async`;
         try {
-            const { stdout } = await execAsync(cmd, { env: this.getEnv() });
+            const { stdout } = await execAsync(cmd);
             console.log(`[Hindsight] Retained (async): ${stdout.trim()}`);
             // Return a simple response
             return {
@@ -65,10 +70,10 @@ export class HindsightClient {
     async recall(request) {
         const query = request.query.replace(/'/g, "'\\''"); // Escape single quotes
         const maxTokens = request.max_tokens || 1024;
-        const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
-        const cmd = `uvx ${embedPackage} memory recall ${this.bankId} '${query}' --output json --max-tokens ${maxTokens}`;
+        const embedCmd = this.getEmbedCommandPrefix();
+        const cmd = `${embedCmd} --profile openclaw memory recall ${this.bankId} '${query}' --output json --max-tokens ${maxTokens}`;
         try {
-            const { stdout } = await execAsync(cmd, { env: this.getEnv() });
+            const { stdout } = await execAsync(cmd);
             // Parse JSON output - returns { entities: {...}, results: [...] }
             const response = JSON.parse(stdout);
             const results = response.results || [];

package/dist/embed-manager.d.ts

@@ -6,14 +6,22 @@ export declare class HindsightEmbedManager {
     private llmProvider;
     private llmApiKey;
     private llmModel?;
+    private llmBaseUrl?;
     private daemonIdleTimeout;
     private embedVersion;
-    constructor(port: number, llmProvider: string, llmApiKey: string, llmModel?: string, daemonIdleTimeout?: number, // Default: never timeout
-    embedVersion?: string);
+    private embedPackagePath?;
+    constructor(port: number, llmProvider: string, llmApiKey: string, llmModel?: string, llmBaseUrl?: string, daemonIdleTimeout?: number, // Default: never timeout
+    embedVersion?: string, // Default: latest
+    embedPackagePath?: string);
+    /**
+     * Get the command to run hindsight-embed (either local or from PyPI)
+     */
+    private getEmbedCommand;
     start(): Promise<void>;
     stop(): Promise<void>;
     private waitForReady;
     getBaseUrl(): string;
     isRunning(): boolean;
-    private writeConfigEnv;
+    checkHealth(): Promise<boolean>;
+    private configureProfile;
 }

package/dist/embed-manager.js

@@ -1,5 +1,4 @@
 import { spawn } from 'child_process';
-import { promises as fs } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 export class HindsightEmbedManager {
@@ -10,38 +9,67 @@ export class HindsightEmbedManager {
     llmProvider;
     llmApiKey;
     llmModel;
+    llmBaseUrl;
     daemonIdleTimeout;
     embedVersion;
-    constructor(port, llmProvider, llmApiKey, llmModel, daemonIdleTimeout = 0, // Default: never timeout
-    embedVersion = 'latest' // Default: latest
+    embedPackagePath;
+    constructor(port, llmProvider, llmApiKey, llmModel, llmBaseUrl, daemonIdleTimeout = 0, // Default: never timeout
+    embedVersion = 'latest', // Default: latest
+    embedPackagePath // Local path to hindsight package
     ) {
-        this.port = 8889; // hindsight-embed uses fixed port 8889
-        this.baseUrl = `http://127.0.0.1:8889`;
+        // Use the configured port (default: 9077 from config)
+        this.port = port;
+        this.baseUrl = `http://127.0.0.1:${port}`;
         this.embedDir = join(homedir(), '.openclaw', 'hindsight-embed');
         this.llmProvider = llmProvider;
         this.llmApiKey = llmApiKey;
         this.llmModel = llmModel;
+        this.llmBaseUrl = llmBaseUrl;
         this.daemonIdleTimeout = daemonIdleTimeout;
         this.embedVersion = embedVersion || 'latest';
+        this.embedPackagePath = embedPackagePath;
+    }
+    /**
+     * Get the command to run hindsight-embed (either local or from PyPI)
+     */
+    getEmbedCommand() {
+        if (this.embedPackagePath) {
+            // Local package: uv run --directory <path> hindsight-embed
+            return ['uv', 'run', '--directory', this.embedPackagePath, 'hindsight-embed'];
+        }
+        else {
+            // PyPI package: uvx hindsight-embed@version
+            const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
+            return ['uvx', embedPackage];
+        }
     }
     async start() {
         console.log(`[Hindsight] Starting hindsight-embed daemon...`);
-        // Build environment variables
+        // Build environment variables using standard HINDSIGHT_API_LLM_* variables
         const env = {
             ...process.env,
-            HINDSIGHT_EMBED_LLM_PROVIDER: this.llmProvider,
-            HINDSIGHT_EMBED_LLM_API_KEY: this.llmApiKey,
+            HINDSIGHT_API_LLM_PROVIDER: this.llmProvider,
+            HINDSIGHT_API_LLM_API_KEY: this.llmApiKey,
             HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT: this.daemonIdleTimeout.toString(),
         };
         if (this.llmModel) {
-            env['HINDSIGHT_EMBED_LLM_MODEL'] = this.llmModel;
+            env['HINDSIGHT_API_LLM_MODEL'] = this.llmModel;
+        }
+        // Pass through base URL for OpenAI-compatible providers (OpenRouter, etc.)
+        if (this.llmBaseUrl) {
+            env['HINDSIGHT_API_LLM_BASE_URL'] = this.llmBaseUrl;
+        }
+        // On macOS, force CPU for embeddings/reranker to avoid MPS/Metal issues in daemon mode
+        if (process.platform === 'darwin') {
+            env['HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU'] = '1';
+            env['HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU'] = '1';
         }
-        // Write env vars to ~/.hindsight/config.env for daemon persistence
-        await this.writeConfigEnv(env);
-        // Start hindsight-embed daemon (it manages itself)
-        const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
-        const startDaemon = spawn('uvx', [embedPackage, 'daemon', 'start'], {
-            env,
+        // Configure "openclaw" profile using hindsight-embed configure (non-interactive)
+        console.log('[Hindsight] Configuring "openclaw" profile...');
+        await this.configureProfile(env);
+        // Start hindsight-embed daemon with openclaw profile
+        const embedCmd = this.getEmbedCommand();
+        const startDaemon = spawn(embedCmd[0], [...embedCmd.slice(1), 'daemon', '--profile', 'openclaw', 'start'], {
             stdio: 'pipe',
         });
         // Collect output
@@ -77,8 +105,8 @@ export class HindsightEmbedManager {
     }
     async stop() {
         console.log('[Hindsight] Stopping hindsight-embed daemon...');
-        const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
-        const stopDaemon = spawn('uvx', [embedPackage, 'daemon', 'stop'], {
+        const embedCmd = this.getEmbedCommand();
+        const stopDaemon = spawn(embedCmd[0], [...embedCmd.slice(1), 'daemon', '--profile', 'openclaw', 'stop'], {
             stdio: 'pipe',
         });
         await new Promise((resolve) => {
@@ -120,58 +148,63 @@ export class HindsightEmbedManager {
     isRunning() {
         return this.process !== null;
     }
-    async writeConfigEnv(env) {
-        const hindsightDir = join(homedir(), '.hindsight');
-        const embedConfigPath = join(hindsightDir, 'embed');
-        // Ensure directory exists
-        await fs.mkdir(hindsightDir, { recursive: true });
-        // Read existing config to preserve extra settings
-        let existingContent = '';
-        let extraSettings = [];
+    async checkHealth() {
         try {
-            existingContent = await fs.readFile(embedConfigPath, 'utf-8');
-            // Extract non-LLM settings (like FORCE_CPU flags)
-            const lines = existingContent.split('\n');
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (trimmed && !trimmed.startsWith('#') &&
-                    !trimmed.startsWith('HINDSIGHT_EMBED_LLM_') &&
-                    !trimmed.startsWith('HINDSIGHT_EMBED_BANK_ID') &&
-                    !trimmed.startsWith('HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT')) {
-                    extraSettings.push(line);
-                }
-            }
+            const response = await fetch(`${this.baseUrl}/health`, { signal: AbortSignal.timeout(2000) });
+            return response.ok;
         }
         catch {
-            // File doesn't exist yet, that's fine
+            return false;
         }
-        // Build config file with header
-        const configLines = [
-            '# Hindsight Embed Configuration',
-            '# Generated by OpenClaw Hindsight plugin',
-            '',
+    }
+    async configureProfile(env) {
+        // Build profile create command args with --merge, --port and --env flags
+        // Use --merge to allow updating existing profile
+        const createArgs = ['profile', 'create', 'openclaw', '--merge', '--port', this.port.toString()];
+        // Add all environment variables as --env flags
+        const envVars = [
+            'HINDSIGHT_API_LLM_PROVIDER',
+            'HINDSIGHT_API_LLM_MODEL',
+            'HINDSIGHT_API_LLM_API_KEY',
+            'HINDSIGHT_API_LLM_BASE_URL',
+            'HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT',
+            'HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU',
+            'HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU',
         ];
-        // Add LLM config
-        if (env.HINDSIGHT_EMBED_LLM_PROVIDER) {
-            configLines.push(`HINDSIGHT_EMBED_LLM_PROVIDER=${env.HINDSIGHT_EMBED_LLM_PROVIDER}`);
-        }
-        if (env.HINDSIGHT_EMBED_LLM_MODEL) {
-            configLines.push(`HINDSIGHT_EMBED_LLM_MODEL=${env.HINDSIGHT_EMBED_LLM_MODEL}`);
-        }
-        if (env.HINDSIGHT_EMBED_LLM_API_KEY) {
-            configLines.push(`HINDSIGHT_EMBED_LLM_API_KEY=${env.HINDSIGHT_EMBED_LLM_API_KEY}`);
-        }
-        if (env.HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT) {
-            configLines.push(`HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT=${env.HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT}`);
-        }
-        // Add extra settings if they exist
-        if (extraSettings.length > 0) {
-            configLines.push('');
-            configLines.push('# Additional settings');
-            configLines.push(...extraSettings);
+        for (const envVar of envVars) {
+            if (env[envVar]) {
+                createArgs.push('--env', `${envVar}=${env[envVar]}`);
+            }
         }
-        // Write to file
-        await fs.writeFile(embedConfigPath, configLines.join('\n') + '\n', 'utf-8');
-        console.log(`[Hindsight] Wrote config to ${embedConfigPath}`);
+        // Run profile create command (non-interactive, overwrites if exists)
+        const embedCmd = this.getEmbedCommand();
+        const create = spawn(embedCmd[0], [...embedCmd.slice(1), ...createArgs], {
+            stdio: 'pipe',
+        });
+        let output = '';
+        create.stdout?.on('data', (data) => {
+            const text = data.toString();
+            output += text;
+            console.log(`[Hindsight] ${text.trim()}`);
+        });
+        create.stderr?.on('data', (data) => {
+            const text = data.toString();
+            output += text;
+            console.error(`[Hindsight] ${text.trim()}`);
+        });
+        await new Promise((resolve, reject) => {
+            create.on('exit', (code) => {
+                if (code === 0) {
+                    console.log('[Hindsight] Profile "openclaw" configured successfully');
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Profile create failed with code ${code}: ${output}`));
+                }
+            });
+            create.on('error', (error) => {
+                reject(error);
+            });
+        });
     }
 }

package/dist/index.js

@@ -24,69 +24,102 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Default bank name
 const BANK_NAME = 'openclaw';
-// Provider mapping: moltbot provider name -> hindsight provider name
-const PROVIDER_MAP = {
-    anthropic: 'anthropic',
-    openai: 'openai',
-    'openai-codex': 'openai',
-    gemini: 'gemini',
-    groq: 'groq',
-    ollama: 'ollama',
-};
-// Environment variable mapping
-const ENV_KEY_MAP = {
-    anthropic: 'ANTHROPIC_API_KEY',
-    openai: 'OPENAI_API_KEY',
-    'openai-codex': 'OPENAI_API_KEY',
-    gemini: 'GEMINI_API_KEY',
-    groq: 'GROQ_API_KEY',
-    ollama: '', // No key needed for local ollama
-};
-function detectLLMConfig(api) {
-    // Get models from config (agents.defaults.models is a dictionary of models)
-    const models = api.config.agents?.defaults?.models;
-    if (!models || Object.keys(models).length === 0) {
-        throw new Error('No models configured in Moltbot. Please configure at least one model in agents.defaults.models');
+// Provider detection from standard env vars
+const PROVIDER_DETECTION = [
+    { name: 'openai', keyEnv: 'OPENAI_API_KEY', defaultModel: 'gpt-4o-mini' },
+    { name: 'anthropic', keyEnv: 'ANTHROPIC_API_KEY', defaultModel: 'claude-3-5-haiku-20241022' },
+    { name: 'gemini', keyEnv: 'GEMINI_API_KEY', defaultModel: 'gemini-2.5-flash' },
+    { name: 'groq', keyEnv: 'GROQ_API_KEY', defaultModel: 'openai/gpt-oss-20b' },
+    { name: 'ollama', keyEnv: '', defaultModel: 'llama3.2' },
+    { name: 'openai-codex', keyEnv: '', defaultModel: 'gpt-5.2-codex' },
+    { name: 'claude-code', keyEnv: '', defaultModel: 'claude-sonnet-4-5-20250929' },
+];
+function detectLLMConfig(pluginConfig) {
+    // Override values from HINDSIGHT_API_LLM_* env vars (highest priority)
+    const overrideProvider = process.env.HINDSIGHT_API_LLM_PROVIDER;
+    const overrideModel = process.env.HINDSIGHT_API_LLM_MODEL;
+    const overrideKey = process.env.HINDSIGHT_API_LLM_API_KEY;
+    const overrideBaseUrl = process.env.HINDSIGHT_API_LLM_BASE_URL;
+    // Priority 1: If provider is explicitly set via env var, use that
+    if (overrideProvider) {
+        // Providers that don't require an API key (use OAuth or local models)
+        const noKeyRequired = ['ollama', 'openai-codex', 'claude-code'];
+        if (!overrideKey && !noKeyRequired.includes(overrideProvider)) {
+            throw new Error(`HINDSIGHT_API_LLM_PROVIDER is set to "${overrideProvider}" but HINDSIGHT_API_LLM_API_KEY is not set.\n` +
+                `Please set: export HINDSIGHT_API_LLM_API_KEY=your-api-key`);
+        }
+        const providerInfo = PROVIDER_DETECTION.find(p => p.name === overrideProvider);
+        return {
+            provider: overrideProvider,
+            apiKey: overrideKey || '',
+            model: overrideModel || (providerInfo?.defaultModel),
+            baseUrl: overrideBaseUrl,
+            source: 'HINDSIGHT_API_LLM_PROVIDER override',
+        };
     }
-    // Try all configured models to find one with an available API key
-    const configuredModels = Object.keys(models);
-    for (const modelKey of configuredModels) {
-        const [moltbotProvider, ...modelParts] = modelKey.split('/');
-        const model = modelParts.join('/');
-        const hindsightProvider = PROVIDER_MAP[moltbotProvider];
-        if (!hindsightProvider) {
-            continue; // Skip unsupported providers
+    // Priority 2: Plugin config llmProvider/llmModel
+    if (pluginConfig?.llmProvider) {
+        const providerInfo = PROVIDER_DETECTION.find(p => p.name === pluginConfig.llmProvider);
+        // Resolve API key: llmApiKeyEnv > provider's standard keyEnv
+        let apiKey = '';
+        if (pluginConfig.llmApiKeyEnv) {
+            apiKey = process.env[pluginConfig.llmApiKeyEnv] || '';
+        }
+        else if (providerInfo?.keyEnv) {
+            apiKey = process.env[providerInfo.keyEnv] || '';
         }
-        const envKey = ENV_KEY_MAP[moltbotProvider];
-        const apiKey = envKey ? process.env[envKey] || '' : '';
-        // For ollama, no key is needed
-        if (hindsightProvider === 'ollama') {
-            return { provider: hindsightProvider, apiKey: '', model, envKey: '' };
+        // Providers that don't require an API key (use OAuth or local models)
+        const noKeyRequired = ['ollama', 'openai-codex', 'claude-code'];
+        if (!apiKey && !noKeyRequired.includes(pluginConfig.llmProvider)) {
+            const keySource = pluginConfig.llmApiKeyEnv || providerInfo?.keyEnv || 'unknown';
+            throw new Error(`Plugin config llmProvider is set to "${pluginConfig.llmProvider}" but no API key found.\n` +
+                `Expected env var: ${keySource}\n` +
+                `Set the env var or use llmApiKeyEnv in plugin config to specify a custom env var name.`);
+        }
+        return {
+            provider: pluginConfig.llmProvider,
+            apiKey,
+            model: pluginConfig.llmModel || overrideModel || providerInfo?.defaultModel,
+            baseUrl: overrideBaseUrl,
+            source: 'plugin config',
+        };
+    }
+    // Priority 3: Auto-detect from standard provider env vars
+    for (const providerInfo of PROVIDER_DETECTION) {
+        const apiKey = providerInfo.keyEnv ? process.env[providerInfo.keyEnv] : '';
+        // Skip providers that don't use API keys in auto-detection (must be explicitly requested)
+        const noKeyRequired = ['ollama', 'openai-codex', 'claude-code'];
+        if (noKeyRequired.includes(providerInfo.name)) {
+            continue;
         }
-        // If we found a key, use this provider
         if (apiKey) {
-            return { provider: hindsightProvider, apiKey, model, envKey };
+            return {
+                provider: providerInfo.name,
+                apiKey,
+                model: overrideModel || providerInfo.defaultModel,
+                baseUrl: overrideBaseUrl, // Only use explicit HINDSIGHT_API_LLM_BASE_URL
+                source: `auto-detected from ${providerInfo.keyEnv}`,
+            };
         }
     }
-    // No API keys found for any provider - show helpful error
-    const configuredProviders = configuredModels
-        .map(m => m.split('/')[0])
-        .filter(p => PROVIDER_MAP[p]);
-    const keyInstructions = configuredProviders
-        .map(p => {
-        const envVar = ENV_KEY_MAP[p];
-        return envVar ? `  • ${envVar} (for ${p})` : null;
-    })
-        .filter(Boolean)
-        .join('\n');
-    throw new Error(`No API keys found for Hindsight memory plugin.\n\n` +
-        `Configured providers in Moltbot: ${configuredProviders.join(', ')}\n\n` +
-        `Please set one of these environment variables:\n${keyInstructions}\n\n` +
-        `You can set them in your shell profile (~/.zshrc or ~/.bashrc):\n` +
-        `  export ANTHROPIC_API_KEY="your-key-here"\n\n` +
-        `Or run OpenClaw with the environment variable:\n` +
-        `  ANTHROPIC_API_KEY="your-key" openclaw gateway\n\n` +
-        `Alternatively, configure ollama provider which doesn't require an API key.`);
+    // No configuration found - show helpful error
+    throw new Error(`No LLM configuration found for Hindsight memory plugin.\n\n` +
+        `Option 1: Set a standard provider API key (auto-detect):\n` +
+        `  export OPENAI_API_KEY=sk-your-key        # Uses gpt-4o-mini\n` +
+        `  export ANTHROPIC_API_KEY=your-key       # Uses claude-3-5-haiku\n` +
+        `  export GEMINI_API_KEY=your-key          # Uses gemini-2.5-flash\n` +
+        `  export GROQ_API_KEY=your-key            # Uses openai/gpt-oss-20b\n\n` +
+        `Option 2: Use Codex or Claude Code (no API key needed):\n` +
+        `  export HINDSIGHT_API_LLM_PROVIDER=openai-codex    # Requires 'codex auth login'\n` +
+        `  export HINDSIGHT_API_LLM_PROVIDER=claude-code     # Requires Claude Code CLI\n\n` +
+        `Option 3: Set llmProvider in openclaw.json plugin config:\n` +
+        `  "llmProvider": "openai", "llmModel": "gpt-4o-mini"\n\n` +
+        `Option 4: Override with Hindsight-specific env vars:\n` +
+        `  export HINDSIGHT_API_LLM_PROVIDER=openai\n` +
+        `  export HINDSIGHT_API_LLM_MODEL=gpt-4o-mini\n` +
+        `  export HINDSIGHT_API_LLM_API_KEY=sk-your-key\n` +
+        `  export HINDSIGHT_API_LLM_BASE_URL=https://openrouter.ai/api/v1  # Optional\n\n` +
+        `Tip: Use a cheap/fast model for memory extraction (e.g., gpt-4o-mini, claude-3-5-haiku, or free models on OpenRouter)`);
 }
 function getPluginConfig(api) {
     const config = api.config.plugins?.entries?.['hindsight-openclaw']?.config || {};
@@ -96,42 +129,49 @@ function getPluginConfig(api) {
         embedPort: config.embedPort || 0,
         daemonIdleTimeout: config.daemonIdleTimeout !== undefined ? config.daemonIdleTimeout : 0,
         embedVersion: config.embedVersion || 'latest',
+        embedPackagePath: config.embedPackagePath,
+        llmProvider: config.llmProvider,
+        llmModel: config.llmModel,
+        llmApiKeyEnv: config.llmApiKeyEnv,
     };
 }
 export default function (api) {
     try {
         console.log('[Hindsight] Plugin loading...');
-        // Detect LLM configuration from Moltbot
+        // Get plugin config first (needed for LLM detection)
+        console.log('[Hindsight] Getting plugin config...');
+        const pluginConfig = getPluginConfig(api);
+        // Detect LLM configuration (env vars > plugin config > auto-detect)
         console.log('[Hindsight] Detecting LLM config...');
-        const llmConfig = detectLLMConfig(api);
+        const llmConfig = detectLLMConfig(pluginConfig);
+        const baseUrlInfo = llmConfig.baseUrl ? `, base URL: ${llmConfig.baseUrl}` : '';
+        const modelInfo = llmConfig.model || 'default';
         if (llmConfig.provider === 'ollama') {
-            console.log(`[Hindsight] ✓ Using provider: ${llmConfig.provider}, model: ${llmConfig.model || 'default'} (no API key required)`);
+            console.log(`[Hindsight] ✓ Using provider: ${llmConfig.provider}, model: ${modelInfo} (${llmConfig.source})`);
         }
         else {
-            console.log(`[Hindsight] ✓ Using provider: ${llmConfig.provider}, model: ${llmConfig.model || 'default'} (API key: ${llmConfig.envKey})`);
+            console.log(`[Hindsight] ✓ Using provider: ${llmConfig.provider}, model: ${modelInfo} (${llmConfig.source}${baseUrlInfo})`);
         }
-        console.log('[Hindsight] Getting plugin config...');
-        const pluginConfig = getPluginConfig(api);
         if (pluginConfig.bankMission) {
             console.log(`[Hindsight] Custom bank mission configured: "${pluginConfig.bankMission.substring(0, 50)}..."`);
         }
         console.log(`[Hindsight] Daemon idle timeout: ${pluginConfig.daemonIdleTimeout}s (0 = never timeout)`);
-        // Determine port
-        const port = pluginConfig.embedPort || Math.floor(Math.random() * 10000) + 10000;
-        console.log(`[Hindsight] Port: ${port}`);
+        // Get API port from config (default: 9077)
+        const apiPort = pluginConfig.apiPort || 9077;
+        console.log(`[Hindsight] API Port: ${apiPort}`);
         // Initialize in background (non-blocking)
         console.log('[Hindsight] Starting initialization in background...');
         initPromise = (async () => {
             try {
                 // Initialize embed manager
                 console.log('[Hindsight] Creating HindsightEmbedManager...');
-                embedManager = new HindsightEmbedManager(port, llmConfig.provider, llmConfig.apiKey, llmConfig.model, pluginConfig.daemonIdleTimeout, pluginConfig.embedVersion);
+                embedManager = new HindsightEmbedManager(apiPort, llmConfig.provider, llmConfig.apiKey, llmConfig.model, llmConfig.baseUrl, pluginConfig.daemonIdleTimeout, pluginConfig.embedVersion, pluginConfig.embedPackagePath);
                 // Start the embedded server
                 console.log('[Hindsight] Starting embedded server...');
                 await embedManager.start();
                 // Initialize client
                 console.log('[Hindsight] Creating HindsightClient...');
-                client = new HindsightClient(llmConfig.provider, llmConfig.apiKey, llmConfig.model, pluginConfig.embedVersion);
+                client = new HindsightClient(llmConfig.provider, llmConfig.apiKey, llmConfig.model, pluginConfig.embedVersion, pluginConfig.embedPackagePath);
                 // Use openclaw bank
                 console.log(`[Hindsight] Using bank: ${BANK_NAME}`);
                 client.setBankId(BANK_NAME);
@@ -154,10 +194,46 @@ export default function (api) {
         api.registerService({
             id: 'hindsight-memory',
             async start() {
+                console.log('[Hindsight] Service start called - checking daemon health...');
                 // Wait for background init if still pending
-                console.log('[Hindsight] Service start called - ensuring initialization complete...');
-                if (initPromise)
-                    await initPromise;
+                if (initPromise) {
+                    try {
+                        await initPromise;
+                    }
+                    catch (error) {
+                        console.error('[Hindsight] Initial initialization failed:', error);
+                        // Continue to health check below
+                    }
+                }
+                // Check if daemon is actually healthy (handles SIGUSR1 restart case)
+                if (embedManager && isInitialized) {
+                    const healthy = await embedManager.checkHealth();
+                    if (healthy) {
+                        console.log('[Hindsight] Daemon is healthy');
+                        return;
+                    }
+                    console.log('[Hindsight] Daemon is not responding - reinitializing...');
+                    // Reset state for reinitialization
+                    embedManager = null;
+                    client = null;
+                    isInitialized = false;
+                }
+                // Reinitialize if needed (fresh start or recovery from dead daemon)
+                if (!isInitialized) {
+                    console.log('[Hindsight] Reinitializing daemon...');
+                    const pluginConfig = getPluginConfig(api);
+                    const llmConfig = detectLLMConfig(pluginConfig);
+                    const apiPort = pluginConfig.apiPort || 9077;
+                    embedManager = new HindsightEmbedManager(apiPort, llmConfig.provider, llmConfig.apiKey, llmConfig.model, llmConfig.baseUrl, pluginConfig.daemonIdleTimeout, pluginConfig.embedVersion, pluginConfig.embedPackagePath);
+                    await embedManager.start();
+                    client = new HindsightClient(llmConfig.provider, llmConfig.apiKey, llmConfig.model, pluginConfig.embedVersion, pluginConfig.embedPackagePath);
+                    client.setBankId(BANK_NAME);
+                    if (pluginConfig.bankMission) {
+                        await client.setBankMission(pluginConfig.bankMission);
+                    }
+                    isInitialized = true;
+                    console.log('[Hindsight] Reinitialization complete');
+                }
             },
             async stop() {
                 try {

package/dist/types.d.ts

@@ -29,6 +29,11 @@ export interface PluginConfig {
     embedPort?: number;
     daemonIdleTimeout?: number;
     embedVersion?: string;
+    embedPackagePath?: string;
+    llmProvider?: string;
+    llmModel?: string;
+    llmApiKeyEnv?: string;
+    apiPort?: number;
 }
 export interface ServiceConfig {
     id: string;

package/openclaw.plugin.json

@@ -24,6 +24,28 @@
         "type": "string",
         "description": "hindsight-embed version to use (e.g. 'latest', '0.4.2', or empty for latest)",
         "default": "latest"
+      },
+      "llmProvider": {
+        "type": "string",
+        "description": "LLM provider for Hindsight memory (e.g. 'openai', 'anthropic', 'gemini', 'groq', 'ollama', 'openai-codex', 'claude-code'). Takes priority over auto-detection but not over HINDSIGHT_API_LLM_PROVIDER env var.",
+        "enum": ["openai", "anthropic", "gemini", "groq", "ollama", "openai-codex", "claude-code"]
+      },
+      "llmModel": {
+        "type": "string",
+        "description": "LLM model to use (e.g. 'gpt-4o-mini', 'claude-3-5-haiku-20241022'). Used with llmProvider."
+      },
+      "llmApiKeyEnv": {
+        "type": "string",
+        "description": "Name of the env var holding the API key (e.g. 'MY_CUSTOM_KEY'). If not set, uses the standard env var for the chosen provider."
+      },
+      "embedPackagePath": {
+        "type": "string",
+        "description": "Local path to hindsight package for development (e.g. '/path/to/hindsight'). When set, uses 'uv run --directory <path>' instead of 'uvx hindsight-embed@latest'."
+      },
+      "apiPort": {
+        "type": "number",
+        "description": "Port for the openclaw profile daemon (default: 9077)",
+        "default": 9077
       }
     },
     "additionalProperties": false
@@ -44,6 +66,26 @@
     "embedVersion": {
       "label": "Hindsight Embed Version",
       "placeholder": "latest (or pin to specific version like 0.4.2)"
+    },
+    "llmProvider": {
+      "label": "LLM Provider",
+      "placeholder": "e.g. openai, anthropic, gemini, groq"
+    },
+    "llmModel": {
+      "label": "LLM Model",
+      "placeholder": "e.g. gpt-4o-mini, claude-3-5-haiku-20241022"
+    },
+    "llmApiKeyEnv": {
+      "label": "API Key Env Var",
+      "placeholder": "e.g. MY_CUSTOM_API_KEY (optional)"
+    },
+    "embedPackagePath": {
+      "label": "Local Package Path (Dev)",
+      "placeholder": "/path/to/hindsight (for local development)"
+    },
+    "apiPort": {
+      "label": "API Port",
+      "placeholder": "9077 (default)"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorize-io/hindsight-openclaw",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Hindsight memory plugin for OpenClaw - biomimetic long-term memory with fact extraction",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",