@vectorize-io/hindsight-openclaw 0.4.14 → 0.4.16

package/README.md

@@ -24,6 +24,47 @@ openclaw gateway
 
 That's it! The plugin will automatically start capturing and recalling memories.
 
+## Features
+
+- **Auto-capture** and **auto-recall** of memories each turn
+- **Memory isolation** — configurable per agent, channel, user, or provider via `dynamicBankGranularity`
+- **Retention controls** — choose which message roles to retain and toggle auto-retain on/off
+
+## Configuration
+
+Optional settings in `~/.openclaw/openclaw.json` under `plugins.entries.hindsight-openclaw.config`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `apiPort` | `9077` | Port for the local Hindsight daemon |
+| `daemonIdleTimeout` | `0` | Seconds before daemon shuts down from inactivity (0 = never) |
+| `embedPort` | `0` | Port for `hindsight-embed` server (`0` = auto-assign) |
+| `embedVersion` | `"latest"` | hindsight-embed version |
+| `embedPackagePath` | — | Local path to `hindsight-embed` package for development |
+| `bankMission` | — | Agent identity/purpose stored on the memory bank. Helps the engine understand context for better fact extraction. Set once per bank — not a recall prompt. |
+| `llmProvider` | auto-detect | LLM provider override for memory extraction (`openai`, `anthropic`, `gemini`, `groq`, `ollama`, `openai-codex`, `claude-code`) |
+| `llmModel` | provider default | LLM model override used with `llmProvider` |
+| `llmApiKeyEnv` | provider standard env var | Custom env var name for the provider API key |
+| `dynamicBankId` | `true` | Enable per-context memory banks |
+| `bankIdPrefix` | — | Prefix for bank IDs (e.g. `"prod"`) |
+| `dynamicBankGranularity` | `["agent", "channel", "user"]` | Fields used to derive bank ID. Options: `agent`, `channel`, `user`, `provider` |
+| `excludeProviders` | `[]` | Message providers to skip for recall/retain (e.g. `slack`, `telegram`, `discord`) |
+| `autoRecall` | `true` | Auto-inject memories before each turn. Set to `false` when the agent has its own recall tool. |
+| `autoRetain` | `true` | Auto-retain conversations after each turn |
+| `retainRoles` | `["user", "assistant"]` | Which message roles to retain. Options: `user`, `assistant`, `system`, `tool` |
+| `retainEveryNTurns` | `1` | Retain every Nth turn. `1` = every turn (default). Values > 1 enable chunked retention with a sliding window. |
+| `retainOverlapTurns` | `0` | Extra prior turns included when chunked retention fires. Window = `retainEveryNTurns + retainOverlapTurns`. Only applies when `retainEveryNTurns > 1`. |
+| `recallBudget` | `"mid"` | Recall effort: `low`, `mid`, or `high`. Higher budgets use more retrieval strategies. |
+| `recallMaxTokens` | `1024` | Max tokens for recall response. Controls how much memory context is injected per turn. |
+| `recallTypes` | `["world", "experience"]` | Memory types to recall. Options: `world`, `experience`, `observation`. Excludes verbose `observation` entries by default. |
+| `recallRoles` | `["user", "assistant"]` | Roles included when building prior context for recall query composition. Options: `user`, `assistant`, `system`, `tool`. |
+| `recallTopK` | — | Max number of memories to inject per turn. Applied after API response as a hard cap. |
+| `recallContextTurns` | `1` | Number of user turns to include when composing recall query context. `1` keeps latest-message-only behavior. |
+| `recallMaxQueryChars` | `800` | Maximum character length for the composed recall query before calling recall. |
+| `recallPromptPreamble` | built-in string | Prompt text placed above recalled memories in the injected `<hindsight_memories>` block. |
+| `hindsightApiUrl` | — | External Hindsight API URL (skips local daemon) |
+| `hindsightApiToken` | — | Auth token for external API |
+
 ## Documentation
 
 For full documentation, configuration options, troubleshooting, and development guide, see:

package/dist/client.d.ts

@@ -1,7 +1,5 @@
 import type { RetainRequest, RetainResponse, RecallRequest, RecallResponse } from './types.js';
 export interface HindsightClientOptions {
-    llmProvider: string;
-    llmApiKey: string;
     llmModel?: string;
     embedVersion?: string;
     embedPackagePath?: string;
@@ -10,8 +8,6 @@ export interface HindsightClientOptions {
 }
 export declare class HindsightClient {
     private bankId;
-    private llmProvider;
-    private llmApiKey;
     private llmModel?;
     private embedVersion;
     private embedPackagePath?;

package/dist/client.js

@@ -19,16 +19,12 @@ function sanitizeFilename(name) {
 }
 export class HindsightClient {
     bankId = 'default';
-    llmProvider;
-    llmApiKey;
     llmModel;
     embedVersion;
     embedPackagePath;
     apiUrl;
     apiToken;
     constructor(opts) {
-        this.llmProvider = opts.llmProvider;
-        this.llmApiKey = opts.llmApiKey;
         this.llmModel = opts.llmModel;
         this.embedVersion = opts.embedVersion || 'latest';
         this.embedPackagePath = opts.embedPackagePath;
@@ -181,6 +177,12 @@ export class HindsightClient {
             query,
             max_tokens: request.max_tokens || 1024,
         };
+        if (request.budget) {
+            body.budget = request.budget;
+        }
+        if (request.types) {
+            body.types = request.types;
+        }
         const res = await fetch(url, {
             method: 'POST',
             headers: this.httpHeaders(),

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { MoltbotPluginAPI } from './types.js';
+import type { MoltbotPluginAPI, PluginConfig, PluginHookAgentContext, MemoryResult } from './types.js';
 import { HindsightClient } from './client.js';
 /**
  * Strip plugin-injected memory tags from content to prevent retain feedback loop.
@@ -6,6 +6,17 @@ import { HindsightClient } from './client.js';
  * during before_agent_start so they don't get re-stored into the memory bank.
  */
 export declare function stripMemoryTags(content: string): string;
+/**
+ * Extract sender_id from OpenClaw's injected inbound metadata blocks.
+ * Checks both "Conversation info (untrusted metadata)" and "Sender (untrusted metadata)" blocks.
+ * Returns the first sender_id / id string found, or undefined if none.
+ */
+export declare function extractSenderIdFromText(text: string): string | undefined;
+/**
+ * Strip OpenClaw sender/conversation metadata envelopes from message content.
+ * These blocks are injected by OpenClaw but are noise for memory storage and recall.
+ */
+export declare function stripMetadataEnvelopes(content: string): string;
 /**
  * Extract a recall query from a hook event's rawMessage or prompt.
  *
@@ -15,5 +26,14 @@ export declare function stripMemoryTags(content: string): string;
  * Returns null when no usable query (< 5 chars) can be extracted.
  */
 export declare function extractRecallQuery(rawMessage: string | undefined, prompt: string | undefined): string | null;
+export declare function composeRecallQuery(latestQuery: string, messages: any[] | undefined, recallContextTurns: number, recallRoles?: Array<'user' | 'assistant' | 'system' | 'tool'>): string;
+export declare function truncateRecallQuery(query: string, latestQuery: string, maxChars: number): string;
+export declare function deriveBankId(ctx: PluginHookAgentContext | undefined, pluginConfig: PluginConfig): string;
+export declare function formatMemories(results: MemoryResult[]): string;
 export default function (api: MoltbotPluginAPI): void;
+export declare function prepareRetentionTranscript(messages: any[], pluginConfig: PluginConfig, retainFullWindow?: boolean): {
+    transcript: string;
+    messageCount: number;
+} | null;
+export declare function sliceLastTurnsByUserBoundary(messages: any[], turns: number): any[];
 export declare function getClient(): HindsightClient | null;