hindclaw-openclaw 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import type { RetainRequest, RetainResponse, RecallRequest, RecallResponse, ReflectRequest, ReflectResponse, MentalModel, PluginHookAgentContext } from './types.js';
+export declare function generateJwt(ctx: PluginHookAgentContext, jwtSecret: string, clientId: string): string;
+export declare class HindsightHttpError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export interface HindsightClientOptions {
+    llmModel?: string;
+    embedVersion?: string;
+    embedPackagePath?: string;
+    apiUrl?: string;
+    jwtSecret?: string;
+    clientId?: string;
+}
+export declare class HindsightClient {
+    private apiUrl?;
+    private jwtSecret?;
+    private clientId;
+    private llmModel?;
+    private embedVersion;
+    private embedPackagePath?;
+    constructor(opts: HindsightClientOptions);
+    get httpMode(): boolean;
+    retain(bankId: string, request: RetainRequest, ctx?: PluginHookAgentContext): Promise<RetainResponse>;
+    recall(bankId: string, request: RecallRequest, timeoutMs?: number, ctx?: PluginHookAgentContext): Promise<RecallResponse>;
+    reflect(bankId: string, request: ReflectRequest, ctx?: PluginHookAgentContext): Promise<ReflectResponse>;
+    getMentalModel(bankId: string, modelId: string, timeoutMs?: number, ctx?: PluginHookAgentContext): Promise<MentalModel>;
+    listMentalModels(bankId: string, ctx?: PluginHookAgentContext): Promise<MentalModel[]>;
+    private bankUrl;
+    private httpHeaders;
+    private requireHttpMode;
+    private httpRequest;
+    private httpRequestRaw;
+    /**
+     * Get the command and base args to run hindsight-embed.
+     * Returns [command, ...baseArgs] for use with execFile/spawn (no shell).
+     */
+    private getEmbedCommand;
+    private retainSubprocess;
+    private recallSubprocess;
+}

package/dist/client.js

@@ -0,0 +1,211 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { writeFile, mkdir, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomBytes, createHmac } from 'crypto';
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 5 * 1024 * 1024; // 5 MB — large transcripts can exceed default 1 MB
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** Strip null bytes from strings — Node 22 rejects them in execFile() args */
+const sanitize = (s) => s.replace(/\0/g, '');
+/**
+ * Sanitize a string for use as a cross-platform filename.
+ * Replaces characters illegal on Windows or Unix with underscores.
+ */
+function sanitizeFilename(name) {
+    return name.replace(/[\\/:*?"<>|\x00-\x1f]/g, '_').slice(0, 200) || 'content';
+}
+export function generateJwt(ctx, jwtSecret, clientId) {
+    const header = { alg: 'HS256', typ: 'JWT' };
+    const now = Math.floor(Date.now() / 1000);
+    const payload = {
+        client_id: clientId,
+        sender: ctx.senderId ? `${ctx.messageProvider}:${ctx.senderId}` : undefined,
+        agent: ctx.agentId,
+        channel: ctx.messageProvider,
+        topic: ctx.channelId || undefined,
+        iat: now,
+        exp: now + 300,
+    };
+    const b64 = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
+    const unsigned = `${b64(header)}.${b64(payload)}`;
+    const signature = createHmac('sha256', jwtSecret).update(unsigned).digest('base64url');
+    return `${unsigned}.${signature}`;
+}
+export class HindsightHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'HindsightHttpError';
+    }
+}
+export class HindsightClient {
+    apiUrl;
+    jwtSecret;
+    clientId;
+    llmModel;
+    embedVersion;
+    embedPackagePath;
+    constructor(opts) {
+        this.llmModel = opts.llmModel;
+        this.embedVersion = opts.embedVersion || 'latest';
+        this.embedPackagePath = opts.embedPackagePath;
+        this.apiUrl = opts.apiUrl?.replace(/\/$/, '');
+        this.jwtSecret = opts.jwtSecret;
+        this.clientId = opts.clientId || 'openclaw';
+    }
+    get httpMode() {
+        return !!this.apiUrl;
+    }
+    // ── Core memory operations ───────────────────────────────────────
+    async retain(bankId, request, ctx) {
+        if (this.httpMode) {
+            return this.httpRequest('POST', `${this.bankUrl(bankId)}/memories`, {
+                items: request.items,
+                async: request.async ?? true,
+            }, undefined, ctx);
+        }
+        return this.retainSubprocess(bankId, request);
+    }
+    async recall(bankId, request, timeoutMs, ctx) {
+        if (this.httpMode) {
+            // Defense-in-depth: truncate query to stay under API's 500-token limit
+            const MAX_QUERY_CHARS = 800;
+            const query = request.query.length > MAX_QUERY_CHARS
+                ? (console.warn(`[Hindsight] Truncating recall query from ${request.query.length} to ${MAX_QUERY_CHARS} chars`),
+                    request.query.substring(0, MAX_QUERY_CHARS))
+                : request.query;
+            const body = {
+                query,
+                max_tokens: request.max_tokens || 1024,
+            };
+            if (request.budget) {
+                body.budget = request.budget;
+            }
+            if (request.types) {
+                body.types = request.types;
+            }
+            if (request.tag_groups) {
+                body.tag_groups = request.tag_groups;
+            }
+            return this.httpRequest('POST', `${this.bankUrl(bankId)}/memories/recall`, body, timeoutMs ?? DEFAULT_TIMEOUT_MS, ctx);
+        }
+        return this.recallSubprocess(bankId, request, timeoutMs);
+    }
+    async reflect(bankId, request, ctx) {
+        this.requireHttpMode('reflect');
+        return this.httpRequest('POST', `${this.bankUrl(bankId)}/reflect`, request, undefined, ctx);
+    }
+    // ── Mental models ────────────────────────────────────────────────
+    async getMentalModel(bankId, modelId, timeoutMs, ctx) {
+        this.requireHttpMode('getMentalModel');
+        return this.httpRequest('GET', `${this.bankUrl(bankId)}/mental-models/${encodeURIComponent(modelId)}`, undefined, timeoutMs, ctx);
+    }
+    async listMentalModels(bankId, ctx) {
+        this.requireHttpMode('listMentalModels');
+        const resp = await this.httpRequest('GET', `${this.bankUrl(bankId)}/mental-models`, undefined, undefined, ctx);
+        return resp.items;
+    }
+    // ── Internal: URL + HTTP helpers ─────────────────────────────────
+    bankUrl(bankId) {
+        return `${this.apiUrl}/v1/default/banks/${encodeURIComponent(bankId)}`;
+    }
+    httpHeaders(ctx) {
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.jwtSecret && ctx) {
+            headers['Authorization'] = `Bearer ${generateJwt(ctx, this.jwtSecret, this.clientId)}`;
+        }
+        return headers;
+    }
+    requireHttpMode(method) {
+        if (!this.httpMode) {
+            throw new Error(`${method} requires HTTP mode (apiUrl must be set)`);
+        }
+    }
+    async httpRequest(method, url, body, timeoutMs, ctx) {
+        const res = await this.httpRequestRaw(method, url, body, timeoutMs, ctx);
+        // For 204 No Content, return undefined cast as T
+        if (res.status === 204) {
+            return undefined;
+        }
+        return res.json();
+    }
+    async httpRequestRaw(method, url, body, timeoutMs, ctx) {
+        const opts = {
+            method,
+            headers: this.httpHeaders(ctx),
+            signal: AbortSignal.timeout(timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        };
+        if (body !== undefined) {
+            opts.body = JSON.stringify(body);
+        }
+        const res = await fetch(url, opts);
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new HindsightHttpError(res.status, `HTTP ${res.status}: ${text}`);
+        }
+        return res;
+    }
+    // ── Internal: subprocess mode (retain/recall only) ───────────────
+    /**
+     * Get the command and base args to run hindsight-embed.
+     * Returns [command, ...baseArgs] for use with execFile/spawn (no shell).
+     */
+    getEmbedCommand() {
+        if (this.embedPackagePath) {
+            return ['uv', 'run', '--directory', this.embedPackagePath, 'hindsight-embed'];
+        }
+        const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
+        // Inject claude-agent-sdk when using claude-code provider (uvx runs in isolated venv)
+        const provider = process.env.HINDSIGHT_API_LLM_PROVIDER;
+        if (provider === 'claude-code') {
+            return ['uvx', '--with', 'claude-agent-sdk', embedPackage];
+        }
+        return ['uvx', embedPackage];
+    }
+    async retainSubprocess(bankId, request) {
+        // Subprocess mode: use first item's content, write to temp file
+        const content = request.items.map(i => i.content).join('\n\n');
+        const docId = request.items[0]?.document_id || 'conversation';
+        const tempDir = join(tmpdir(), `hindsight_${randomBytes(8).toString('hex')}`);
+        const safeFilename = sanitizeFilename(docId);
+        const tempFile = join(tempDir, `${safeFilename}.txt`);
+        try {
+            await mkdir(tempDir, { recursive: true });
+            await writeFile(tempFile, sanitize(content), 'utf8');
+            const [cmd, ...baseArgs] = this.getEmbedCommand();
+            const args = [...baseArgs, '--profile', 'openclaw', 'memory', 'retain-files', bankId, tempFile, '--async'];
+            const { stdout } = await execFileAsync(cmd, args, { maxBuffer: MAX_BUFFER });
+            console.log(`[Hindsight] Retained (async): ${stdout.trim()}`);
+            return {
+                message: 'Memory queued for background processing',
+                document_id: docId,
+                memory_unit_ids: [],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to retain memory: ${error}`, { cause: error });
+        }
+        finally {
+            await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+    async recallSubprocess(bankId, request, timeoutMs) {
+        const query = sanitize(request.query);
+        const maxTokens = request.max_tokens || 1024;
+        const [cmd, ...baseArgs] = this.getEmbedCommand();
+        const args = [...baseArgs, '--profile', 'openclaw', 'memory', 'recall', bankId, query, '--output', 'json', '--max-tokens', String(maxTokens)];
+        try {
+            const { stdout } = await execFileAsync(cmd, args, {
+                maxBuffer: MAX_BUFFER,
+                timeout: timeoutMs ?? 30_000,
+            });
+            return JSON.parse(stdout);
+        }
+        catch (error) {
+            throw new Error(`Failed to recall memories: ${error}`, { cause: error });
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+import type { BankConfig, PluginConfig, ResolvedConfig, AgentEntry } from './types.js';
+/**
+ * Recursively resolve $include directives in a parsed config object.
+ * Each { "$include": "./path" } is replaced with the parsed contents of the referenced file.
+ * Paths are resolved relative to basePath.
+ */
+export declare function resolveIncludes<T>(obj: T, basePath: string, depth?: number, seen?: Set<string>): T;
+/**
+ * Parse a JSON5 bank config file content into a BankConfig object.
+ */
+export declare function parseBankConfigFile(content: string): BankConfig;
+/**
+ * Resolve per-agent config by merging plugin defaults with bank config overrides.
+ *
+ * Resolution order: pluginDefaults → bankFile (shallow merge, bank file wins).
+ *
+ * Extracted behavioral fields (recallFrom, sessionStartModels, reflect*) are
+ * hoisted to their underscore-prefixed counterparts.
+ * Everything else is merged as behavioral/infrastructure overrides.
+ */
+export declare function resolveAgentConfig(agentId: string, pluginDefaults: Omit<PluginConfig, 'agents'>, bankConfigs: Map<string, BankConfig>): ResolvedConfig;
+/**
+ * Load all bank config files for the given agents map.
+ * Reads files synchronously — called at plugin init time, not in the hot path.
+ *
+ * @param agents  Record<agentId, AgentEntry> from PluginConfig.agents
+ * @param basePath  Base directory to resolve relative bankConfig paths against
+ * @returns Map<agentId, BankConfig>
+ */
+export declare function loadBankConfigFiles(agents: Record<string, AgentEntry>, basePath: string): Map<string, BankConfig>;

package/dist/config.js

@@ -0,0 +1,132 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import JSON5 from 'json5';
+import { debug } from './debug.js';
+// ── Field classification sets ─────────────────────────────────────────
+const EXTRACTED_FIELDS = new Set([
+    'recallFrom',
+    'sessionStartModels',
+    'reflectOnRecall',
+    'reflectBudget',
+    'reflectMaxTokens',
+]);
+// ── $include resolution ───────────────────────────────────────────────
+const MAX_INCLUDE_DEPTH = 10;
+/**
+ * Recursively resolve $include directives in a parsed config object.
+ * Each { "$include": "./path" } is replaced with the parsed contents of the referenced file.
+ * Paths are resolved relative to basePath.
+ */
+export function resolveIncludes(obj, basePath, depth = 0, seen = new Set()) {
+    if (depth > MAX_INCLUDE_DEPTH) {
+        throw new Error(`$include depth exceeded (max ${MAX_INCLUDE_DEPTH})`);
+    }
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        return obj;
+    }
+    const record = obj;
+    // Check if this object IS an $include directive
+    if ('$include' in record && typeof record.$include === 'string' && Object.keys(record).length === 1) {
+        const includePath = record.$include;
+        const filePath = includePath.startsWith('/') ? includePath : join(basePath, includePath);
+        if (seen.has(filePath)) {
+            throw new Error(`Circular $include detected: ${filePath}`);
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        const parsed = JSON5.parse(content);
+        const nextSeen = new Set(seen);
+        nextSeen.add(filePath);
+        return resolveIncludes(parsed, dirname(filePath), depth + 1, nextSeen);
+    }
+    // Walk child properties
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        result[key] = resolveIncludes(value, basePath, depth, seen);
+    }
+    return result;
+}
+// ── Public API ────────────────────────────────────────────────────────
+/**
+ * Parse a JSON5 bank config file content into a BankConfig object.
+ */
+export function parseBankConfigFile(content) {
+    return JSON5.parse(content);
+}
+/**
+ * Resolve per-agent config by merging plugin defaults with bank config overrides.
+ *
+ * Resolution order: pluginDefaults → bankFile (shallow merge, bank file wins).
+ *
+ * Extracted behavioral fields (recallFrom, sessionStartModels, reflect*) are
+ * hoisted to their underscore-prefixed counterparts.
+ * Everything else is merged as behavioral/infrastructure overrides.
+ */
+export function resolveAgentConfig(agentId, pluginDefaults, bankConfigs) {
+    const bankConfig = bankConfigs.get(agentId);
+    if (!bankConfig) {
+        debug(`[Hindsight] No bank config for agent "${agentId}" — using plugin defaults`);
+        return {
+            ...pluginDefaults,
+        };
+    }
+    // Separate extracted fields from behavioral overrides
+    const overrides = {};
+    for (const [key, value] of Object.entries(bankConfig)) {
+        if (!EXTRACTED_FIELDS.has(key)) {
+            overrides[key] = value;
+        }
+    }
+    // Build the merged behavioral/infrastructure config
+    const merged = {
+        ...pluginDefaults,
+        ...overrides,
+    };
+    // Hoist extracted fields
+    if (bankConfig.recallFrom !== undefined) {
+        merged._recallFrom = bankConfig.recallFrom;
+    }
+    if (bankConfig.sessionStartModels !== undefined) {
+        merged._sessionStartModels = bankConfig.sessionStartModels;
+    }
+    if (bankConfig.reflectOnRecall !== undefined) {
+        merged._reflectOnRecall = bankConfig.reflectOnRecall;
+    }
+    if (bankConfig.reflectBudget !== undefined) {
+        merged._reflectBudget = bankConfig.reflectBudget;
+    }
+    if (bankConfig.reflectMaxTokens !== undefined) {
+        merged._reflectMaxTokens = bankConfig.reflectMaxTokens;
+    }
+    return merged;
+}
+/**
+ * Load all bank config files for the given agents map.
+ * Reads files synchronously — called at plugin init time, not in the hot path.
+ *
+ * @param agents  Record<agentId, AgentEntry> from PluginConfig.agents
+ * @param basePath  Base directory to resolve relative bankConfig paths against
+ * @returns Map<agentId, BankConfig>
+ */
+export function loadBankConfigFiles(agents, basePath) {
+    const result = new Map();
+    for (const [agentId, entry] of Object.entries(agents)) {
+        if (!entry?.bankConfig) {
+            console.warn(`[Hindsight] Agent "${agentId}" has no bankConfig path — skipping`);
+            continue;
+        }
+        const filePath = entry.bankConfig.startsWith('/')
+            ? entry.bankConfig
+            : join(basePath, entry.bankConfig);
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            const parsed = parseBankConfigFile(content);
+            const resolved = resolveIncludes(parsed, dirname(filePath));
+            result.set(agentId, resolved);
+            debug(`[Hindsight] Loaded bank config for agent "${agentId}" from ${filePath}`);
+        }
+        catch (error) {
+            console.warn(`[Hindsight] Failed to load bank config for agent "${agentId}" from ${filePath}:`, error instanceof Error ? error.message : error);
+        }
+    }
+    return result;
+}

package/dist/debug.d.ts

@@ -0,0 +1,3 @@
+export declare const debug: (...args: unknown[]) => void;
+export declare function setDebugEnabled(value: boolean): void;
+export declare function isDebugEnabled(): boolean;

package/dist/debug.js

@@ -0,0 +1,15 @@
+// ── Shared debug logging ─────────────────────────────────────────────
+// Silent by default, enable with debug: true in plugin config.
+// Extracted into a standalone module so hooks can import without
+// circular dependencies back to index.ts.
+let debugEnabled = false;
+export const debug = (...args) => {
+    if (debugEnabled)
+        console.log(...args);
+};
+export function setDebugEnabled(value) {
+    debugEnabled = value;
+}
+export function isDebugEnabled() {
+    return debugEnabled;
+}

package/dist/derive-bank-id.d.ts

@@ -0,0 +1,17 @@
+import type { PluginHookAgentContext, PluginConfig } from './types.js';
+/**
+ * Parse the OpenClaw sessionKey to extract context fields.
+ * Format: "agent:{agentId}:{provider}:{channelType}:{channelId}[:{extra}]"
+ * Example: "agent:c0der:telegram:group:-1003825475854:topic:42"
+ */
+export declare function parseSessionKey(sessionKey: string): {
+    agentId?: string;
+    provider?: string;
+    channel?: string;
+};
+/**
+ * Derive a bank ID from the agent context.
+ * Uses configurable dynamicBankGranularity to determine bank segmentation.
+ * Falls back to default bank when context is unavailable.
+ */
+export declare function deriveBankId(ctx: PluginHookAgentContext | undefined, pluginConfig: PluginConfig): string;

package/dist/derive-bank-id.js

@@ -0,0 +1,60 @@
+import { debug } from './debug.js';
+// Default bank name (fallback when channel context not available)
+const DEFAULT_BANK_NAME = 'openclaw';
+/**
+ * Parse the OpenClaw sessionKey to extract context fields.
+ * Format: "agent:{agentId}:{provider}:{channelType}:{channelId}[:{extra}]"
+ * Example: "agent:c0der:telegram:group:-1003825475854:topic:42"
+ */
+export function parseSessionKey(sessionKey) {
+    const parts = sessionKey.split(':');
+    if (parts.length < 5 || parts[0] !== 'agent')
+        return {};
+    // parts[1] = agentId, parts[2] = provider, parts[3] = channelType, parts[4..] = channelId + extras
+    return {
+        agentId: parts[1],
+        provider: parts[2],
+        // Rejoin from channelType onward as the channel identifier (e.g. "group:-1003825475854:topic:42")
+        channel: parts.slice(3).join(':'),
+    };
+}
+/**
+ * Derive a bank ID from the agent context.
+ * Uses configurable dynamicBankGranularity to determine bank segmentation.
+ * Falls back to default bank when context is unavailable.
+ */
+export function deriveBankId(ctx, pluginConfig) {
+    if (pluginConfig.dynamicBankId === false) {
+        return pluginConfig.bankIdPrefix ? `${pluginConfig.bankIdPrefix}-${DEFAULT_BANK_NAME}` : DEFAULT_BANK_NAME;
+    }
+    // When no context is available, fall back to the static default bank.
+    if (!ctx) {
+        return pluginConfig.bankIdPrefix ? `${pluginConfig.bankIdPrefix}-${DEFAULT_BANK_NAME}` : DEFAULT_BANK_NAME;
+    }
+    const fields = pluginConfig.dynamicBankGranularity?.length ? pluginConfig.dynamicBankGranularity : ['agent', 'channel', 'user'];
+    // Validate field names at runtime — typos silently produce 'unknown' segments
+    const validFields = new Set(['agent', 'channel', 'user', 'provider']);
+    for (const f of fields) {
+        if (!validFields.has(f)) {
+            console.warn(`[Hindsight] Unknown dynamicBankGranularity field "${f}" — will resolve to "unknown" in bank ID. Valid fields: agent, channel, user, provider`);
+        }
+    }
+    // Parse sessionKey as fallback when direct context fields are missing
+    const sessionParsed = ctx?.sessionKey ? parseSessionKey(ctx.sessionKey) : {};
+    // Warn when 'user' is in active fields but senderId is missing
+    if (fields.includes('user') && ctx && !ctx.senderId) {
+        debug('[Hindsight] senderId not available in context — bank ID will use "anonymous". Ensure your OpenClaw provider passes senderId.');
+    }
+    const fieldMap = {
+        agent: ctx?.agentId || sessionParsed.agentId || 'default',
+        channel: ctx?.channelId || sessionParsed.channel || 'unknown',
+        user: ctx?.senderId || 'anonymous',
+        provider: ctx?.messageProvider || sessionParsed.provider || 'unknown',
+    };
+    const baseBankId = fields
+        .map(f => encodeURIComponent(fieldMap[f] || 'unknown'))
+        .join('::');
+    return pluginConfig.bankIdPrefix
+        ? `${pluginConfig.bankIdPrefix}-${baseBankId}`
+        : baseBankId;
+}

package/dist/embed-manager.d.ts

@@ -0,0 +1,32 @@
+export declare class HindsightEmbedManager {
+    private process;
+    private port;
+    private baseUrl;
+    private embedDir;
+    private llmProvider;
+    private llmApiKey;
+    private llmModel?;
+    private llmBaseUrl?;
+    private daemonIdleTimeout;
+    private embedVersion;
+    private embedPackagePath?;
+    private jwtSecret?;
+    private clientId;
+    constructor(port: number, llmProvider: string, llmApiKey: string, llmModel?: string, llmBaseUrl?: string, daemonIdleTimeout?: number, // Default: never timeout
+    embedVersion?: string, // Default: latest
+    embedPackagePath?: string, // Local path to hindsight package
+    jwtSecret?: string, clientId?: string);
+    /**
+     * Get the command to run hindsight-embed (either local or from PyPI)
+     */
+    private getEmbedCommand;
+    private getExtraEmbedPackages;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private waitForReady;
+    getBaseUrl(): string;
+    isRunning(): boolean;
+    checkHealth(): Promise<boolean>;
+    private configureProfile;
+    private resolvePg0Port;
+}