@hippodid/openclaw-plugin 1.0.0

package/src/hippodid-client.ts

@@ -0,0 +1,283 @@
+import type {
+  ApiError,
+  Result,
+  TierInfo,
+  TierApiResponse,
+  SyncResponse,
+  SyncApiResponse,
+  SyncLatestResponse,
+  SyncLatestApiResponse,
+  SyncStatusEntry,
+  SyncStatusResponse,
+  SearchResult,
+  SearchResultApiResponse,
+} from './types.js';
+import { ok, err } from './types.js';
+
+const MAX_RETRIES = 3;
+const REQUEST_TIMEOUT_MS = 10_000;
+const TIER_CACHE_TTL_MS = 5 * 60 * 1000;
+
+interface CachedTier {
+  info: TierInfo;
+  fetchedAt: number;
+}
+
+export interface HippoDidClient {
+  getTier(characterId: string): Promise<Result<TierInfo>>;
+  syncFile(
+    characterId: string,
+    sourcePath: string,
+    label: string,
+    fileContent: string,
+    checksum: string,
+  ): Promise<Result<SyncResponse>>;
+  getLatestSync(
+    characterId: string,
+    sourcePath: string,
+  ): Promise<Result<SyncLatestResponse | null>>;
+  getSyncStatus(characterId: string): Promise<Result<SyncStatusResponse>>;
+  searchMemories(
+    characterId: string,
+    query: string,
+    topK?: number,
+  ): Promise<Result<SearchResult[]>>;
+  addMemory(
+    characterId: string,
+    content: string,
+    source?: string,
+  ): Promise<Result<void>>;
+}
+
+export function createClient(apiKey: string, baseUrl: string): HippoDidClient {
+  let tierCache: CachedTier | null = null;
+
+  function headers(): Record<string, string> {
+    return {
+      'X-Api-Key': apiKey,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  function isRetryable(status: number): boolean {
+    return status === 429 || status >= 500;
+  }
+
+  function toApiError(status: number, message: string): ApiError {
+    return { status, message, retryable: isRetryable(status) };
+  }
+
+  async function fetchWithTimeout(
+    url: string,
+    init: RequestInit,
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async function request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<Result<T>> {
+    const url = `${baseUrl}${path}`;
+    let lastError: ApiError | null = null;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      if (attempt > 0) {
+        const delay = Math.min(1000 * Math.pow(2, attempt - 1), 8000);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+
+      try {
+        const resp = await fetchWithTimeout(url, {
+          method,
+          headers: headers(),
+          body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+
+        if (!resp.ok) {
+          const errorText = await resp.text().catch(() => 'Unknown error');
+          lastError = toApiError(resp.status, errorText);
+
+          if (!isRetryable(resp.status)) {
+            return err(lastError);
+          }
+          continue;
+        }
+
+        if (resp.status === 204) {
+          return ok(undefined as T);
+        }
+
+        const data = (await resp.json()) as T;
+        return ok(data);
+      } catch (e) {
+        const message =
+          e instanceof Error ? e.message : 'Unknown network error';
+        lastError = toApiError(0, message);
+
+        if (attempt < MAX_RETRIES) {
+          continue;
+        }
+      }
+    }
+
+    return err(lastError ?? toApiError(0, 'Request failed after retries'));
+  }
+
+  function mapTierResponse(raw: TierApiResponse): TierInfo {
+    return {
+      tier: raw.tier,
+      features: {
+        autoRecallAvailable: raw.features.auto_recall_available,
+        autoCaptureAvailable: raw.features.auto_capture_available,
+        minSyncIntervalSeconds: raw.features.min_sync_interval_seconds,
+      },
+    };
+  }
+
+  function mapSyncResponse(raw: SyncApiResponse): SyncResponse {
+    return {
+      status: raw.status,
+      snapshotId: raw.snapshot_id,
+      changed: raw.changed,
+    };
+  }
+
+  function mapSyncLatestResponse(
+    raw: SyncLatestApiResponse,
+  ): SyncLatestResponse {
+    return {
+      sourcePath: raw.source_path,
+      fileContent: raw.file_content,
+      snapshotId: raw.snapshot_id,
+      syncedAt: raw.synced_at,
+    };
+  }
+
+  return {
+    async getTier(characterId: string): Promise<Result<TierInfo>> {
+      const now = Date.now();
+      if (tierCache && now - tierCache.fetchedAt < TIER_CACHE_TTL_MS) {
+        return ok(tierCache.info);
+      }
+
+      const result = await request<TierApiResponse>(
+        'GET',
+        `/v1/tier?characterId=${encodeURIComponent(characterId)}`,
+      );
+
+      if (!result.ok) return result;
+
+      const info = mapTierResponse(result.value);
+      tierCache = { info, fetchedAt: now };
+      return ok(info);
+    },
+
+    async syncFile(
+      characterId: string,
+      sourcePath: string,
+      label: string,
+      fileContent: string,
+      checksum: string,
+    ): Promise<Result<SyncResponse>> {
+      const result = await request<SyncApiResponse>(
+        'POST',
+        `/v1/characters/${encodeURIComponent(characterId)}/sync`,
+        {
+          source_path: sourcePath,
+          label,
+          file_content: fileContent,
+          checksum,
+        },
+      );
+
+      if (!result.ok) return result;
+      return ok(mapSyncResponse(result.value));
+    },
+
+    async getLatestSync(
+      characterId: string,
+      sourcePath: string,
+    ): Promise<Result<SyncLatestResponse | null>> {
+      const result = await request<SyncLatestApiResponse>(
+        'GET',
+        `/v1/characters/${encodeURIComponent(characterId)}/sync/latest?source_path=${encodeURIComponent(sourcePath)}`,
+      );
+
+      if (!result.ok) {
+        if (result.error.status === 404) {
+          return ok(null);
+        }
+        return result;
+      }
+
+      return ok(mapSyncLatestResponse(result.value));
+    },
+
+    async getSyncStatus(
+      characterId: string,
+    ): Promise<Result<SyncStatusResponse>> {
+      const result = await request<{ entries: Array<{ source_path: string; label: string; last_synced_at: string; snapshot_id: string }> }>(
+        'GET',
+        `/v1/characters/${encodeURIComponent(characterId)}/sync/status`,
+      );
+
+      if (!result.ok) return result;
+
+      return ok({
+        entries: result.value.entries.map(
+          (e): SyncStatusEntry => ({
+            sourcePath: e.source_path,
+            label: e.label,
+            lastSyncedAt: e.last_synced_at,
+            snapshotId: e.snapshot_id,
+          }),
+        ),
+      });
+    },
+
+    async searchMemories(
+      characterId: string,
+      query: string,
+      topK?: number,
+    ): Promise<Result<SearchResult[]>> {
+      const result = await request<SearchResultApiResponse[]>(
+        'POST',
+        `/v1/characters/${encodeURIComponent(characterId)}/search`,
+        { query, top_k: topK ?? 5 },
+      );
+
+      if (!result.ok) return result;
+
+      return ok(
+        result.value.map(
+          (r): SearchResult => ({
+            content: r.content,
+            category: r.category,
+            score: r.score,
+            createdAt: r.created_at,
+          }),
+        ),
+      );
+    },
+
+    async addMemory(
+      characterId: string,
+      content: string,
+      source?: string,
+    ): Promise<Result<void>> {
+      return request<void>(
+        'POST',
+        `/v1/characters/${encodeURIComponent(characterId)}/memories`,
+        { content, source: source ?? 'openclaw-plugin' },
+      );
+    },
+  };
+}

package/src/hooks/auto-capture.ts

@@ -0,0 +1,58 @@
+import type { HippoDidClient } from '../hippodid-client.js';
+import type { PluginConfig, OpenClawPluginAPI } from '../types.js';
+
+export function createAutoCaptureHook(
+  client: HippoDidClient,
+  config: PluginConfig,
+  logger: { info(msg: string): void; warn(msg: string): void },
+): (api: OpenClawPluginAPI) => void {
+  return (api: OpenClawPluginAPI) => {
+    api.hooks.on('agent_end', (...args: unknown[]) => {
+      try {
+        const exchange = extractExchange(args);
+        if (!exchange) return;
+
+        client
+          .addMemory(config.characterId, exchange, 'openclaw-auto-capture')
+          .then((result) => {
+            if (result.ok) {
+              logger.info('hippodid: captured exchange for memory extraction');
+            } else {
+              logger.warn(
+                `hippodid: capture failed: ${result.error.message}`,
+              );
+            }
+          })
+          .catch((e) => {
+            logger.warn(
+              `hippodid: capture error: ${e instanceof Error ? e.message : 'unknown'}`,
+            );
+          });
+      } catch (e) {
+        logger.warn(
+          `hippodid: capture hook error: ${e instanceof Error ? e.message : 'unknown'}`,
+        );
+      }
+    });
+  };
+}
+
+function extractExchange(args: unknown[]): string | null {
+  if (args.length > 0 && typeof args[0] === 'object' && args[0] !== null) {
+    const event = args[0] as Record<string, unknown>;
+
+    const userMsg =
+      typeof event['userMessage'] === 'string' ? event['userMessage'] : '';
+    const agentResp =
+      typeof event['agentResponse'] === 'string' ? event['agentResponse'] : '';
+
+    if (userMsg || agentResp) {
+      return `User: ${userMsg}\n\nAgent: ${agentResp}`;
+    }
+
+    if (typeof event['content'] === 'string') return event['content'];
+    if (typeof event['text'] === 'string') return event['text'];
+  }
+  if (typeof args[0] === 'string') return args[0];
+  return null;
+}

package/src/hooks/auto-recall.ts

@@ -0,0 +1,67 @@
+import type { HippoDidClient } from '../hippodid-client.js';
+import type { PluginConfig, OpenClawPluginAPI } from '../types.js';
+
+export function createAutoRecallHook(
+  client: HippoDidClient,
+  config: PluginConfig,
+  logger: { info(msg: string): void; warn(msg: string): void },
+): (api: OpenClawPluginAPI) => void {
+  return (api: OpenClawPluginAPI) => {
+    api.hooks.on('before_agent_start', async (...args: unknown[]) => {
+      try {
+        const userMessage = extractUserMessage(args);
+        if (!userMessage) return;
+
+        const result = await client.searchMemories(
+          config.characterId,
+          userMessage,
+          5,
+        );
+
+        if (!result.ok) {
+          logger.warn(
+            `hippodid: recall search failed: ${result.error.message}`,
+          );
+          return;
+        }
+
+        const memories = result.value;
+        if (memories.length === 0) {
+          logger.info('hippodid: no relevant memories found');
+          return;
+        }
+
+        const contextBlock = formatMemoriesBlock(memories);
+        api.context.prepend(contextBlock);
+        logger.info(`hippodid: recalled ${memories.length} memories for context`);
+      } catch (e) {
+        logger.warn(
+          `hippodid: recall hook error: ${e instanceof Error ? e.message : 'unknown'}`,
+        );
+      }
+    });
+  };
+}
+
+function extractUserMessage(args: unknown[]): string | null {
+  if (args.length > 0 && typeof args[0] === 'object' && args[0] !== null) {
+    const event = args[0] as Record<string, unknown>;
+    if (typeof event['message'] === 'string') return event['message'];
+    if (typeof event['content'] === 'string') return event['content'];
+    if (typeof event['text'] === 'string') return event['text'];
+  }
+  if (typeof args[0] === 'string') return args[0];
+  return null;
+}
+
+interface MemoryEntry {
+  content: string;
+  category: string;
+}
+
+function formatMemoriesBlock(memories: MemoryEntry[]): string {
+  const lines = memories.map(
+    (m) => `- [Category: ${m.category}] ${m.content}`,
+  );
+  return `<hippodid-memories>\n${lines.join('\n')}\n</hippodid-memories>`;
+}

package/src/hooks/memory-flush.ts

@@ -0,0 +1,22 @@
+import type { FileSync } from '../file-sync.js';
+import type { OpenClawPluginAPI } from '../types.js';
+
+export function createMemoryFlushHook(
+  fileSync: FileSync,
+  logger: { info(msg: string): void; warn(msg: string): void },
+): (api: OpenClawPluginAPI) => void {
+  return (api: OpenClawPluginAPI) => {
+    api.hooks.on('memoryFlush', async () => {
+      try {
+        const { synced, changed } = await fileSync.flushNow();
+        logger.info(
+          `hippodid: pre-compaction flush — synced ${synced} files (${changed} changed)`,
+        );
+      } catch (e) {
+        logger.warn(
+          `hippodid: pre-compaction flush failed: ${e instanceof Error ? e.message : 'unknown'}`,
+        );
+      }
+    });
+  };
+}

package/src/hooks/session-lifecycle.ts

@@ -0,0 +1,42 @@
+import type { FileSync } from '../file-sync.js';
+import type { TierManager } from '../tier-manager.js';
+import type { OpenClawPluginAPI } from '../types.js';
+
+export function createSessionHooks(
+  fileSync: FileSync,
+  tierManager: TierManager,
+  autoRecallEnabled: boolean,
+  logger: { info(msg: string): void; warn(msg: string): void },
+): (api: OpenClawPluginAPI) => void {
+  return (api: OpenClawPluginAPI) => {
+    api.hooks.on('session:start', async () => {
+      try {
+        await tierManager.initialize();
+
+        if (tierManager.shouldHydrateOnStart(autoRecallEnabled)) {
+          const count = await fileSync.hydrateFromCloud();
+          logger.info(`hippodid: session started, hydrated ${count} files from cloud`);
+        } else {
+          logger.info('hippodid: session started, hydration skipped (autoRecall active)');
+        }
+      } catch (e) {
+        logger.warn(
+          `hippodid: session start error: ${e instanceof Error ? e.message : 'unknown'}`,
+        );
+      }
+    });
+
+    api.hooks.on('session:end', async () => {
+      try {
+        const { synced, changed } = await fileSync.flushNow();
+        logger.info(
+          `hippodid: session ended, final sync — ${synced} files (${changed} changed)`,
+        );
+      } catch (e) {
+        logger.warn(
+          `hippodid: session end flush failed: ${e instanceof Error ? e.message : 'unknown'}`,
+        );
+      }
+    });
+  };
+}

package/src/index.ts

@@ -0,0 +1,220 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { OpenClawPluginAPI, PluginConfig } from './types.js';
+import { createClient, type HippoDidClient } from './hippodid-client.js';
+import { createFileSync, type FileSync } from './file-sync.js';
+import { resolveWatchPaths } from './workspace-detector.js';
+import { createTierManager, type TierManager } from './tier-manager.js';
+import { createMemoryFlushHook } from './hooks/memory-flush.js';
+import { createSessionHooks } from './hooks/session-lifecycle.js';
+import { createAutoRecallHook } from './hooks/auto-recall.js';
+import { createAutoCaptureHook } from './hooks/auto-capture.js';
+
+export const id = 'hippodid';
+
+const VERSION = '1.0.0';
+
+export default function register(api: OpenClawPluginAPI): void {
+  try {
+    const config = resolveConfig(api.config);
+    const logger = api.logger ?? {
+      info: (msg: string) => console.log(msg),
+      warn: (msg: string) => console.warn(msg),
+      error: (msg: string) => console.error(msg),
+    };
+
+    const client = createClient(config.apiKey, config.baseUrl);
+    const tierManager = createTierManager(client, config.characterId, logger);
+    const watchPaths = resolveWatchPaths(config);
+    const effectiveSyncInterval = Math.max(config.syncIntervalSeconds, 60);
+    const fileSync = createFileSync(client, config, watchPaths, logger, effectiveSyncInterval);
+
+    const registerMemoryFlush = createMemoryFlushHook(fileSync, logger);
+    registerMemoryFlush(api);
+
+    const registerSessionHooks = createSessionHooks(
+      fileSync,
+      tierManager,
+      config.autoRecall,
+      logger,
+    );
+    registerSessionHooks(api);
+
+    tierManager.initialize().then((tier) => {
+      if (tierManager.shouldMountAutoRecall(config.autoRecall)) {
+        const registerAutoRecall = createAutoRecallHook(client, config, logger);
+        registerAutoRecall(api);
+      }
+
+      if (tierManager.shouldMountAutoCapture(config.autoCapture)) {
+        const registerAutoCapture = createAutoCaptureHook(client, config, logger);
+        registerAutoCapture(api);
+      }
+
+      if (tierManager.shouldMountFileSync(config.autoCapture)) {
+        fileSync.start();
+      }
+
+      const autoRecallStatus = tierManager.shouldMountAutoRecall(config.autoRecall)
+        ? 'ON'
+        : 'OFF';
+      const autoCaptureStatus = tierManager.shouldMountAutoCapture(config.autoCapture)
+        ? 'ON'
+        : 'OFF';
+
+      logger.info(
+        `hippodid: v${VERSION} | character: ${config.characterId} | tier: ${tier.tier} | watching ${watchPaths.length} paths | autoRecall: ${autoRecallStatus} | autoCapture: ${autoCaptureStatus}`,
+      );
+    }).catch((e) => {
+      logger.warn(
+        `hippodid: tier initialization failed, running in free mode: ${e instanceof Error ? e.message : 'unknown'}`,
+      );
+      fileSync.start();
+    });
+
+    registerCommands(api, config, client, fileSync, tierManager, logger);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : 'unknown';
+    (api.logger ?? console).error(`hippodid: plugin initialization failed: ${msg}`);
+  }
+}
+
+function resolveConfig(raw: PluginConfig): PluginConfig {
+  return {
+    apiKey: raw.apiKey,
+    characterId: raw.characterId,
+    baseUrl: raw.baseUrl ?? 'https://api.hippodid.com',
+    syncIntervalSeconds: raw.syncIntervalSeconds ?? 300,
+    autoRecall: raw.autoRecall ?? false,
+    autoCapture: raw.autoCapture ?? false,
+    additionalPaths: raw.additionalPaths ?? [],
+  };
+}
+
+function registerCommands(
+  api: OpenClawPluginAPI,
+  config: PluginConfig,
+  client: HippoDidClient,
+  fileSync: FileSync,
+  tierManager: TierManager,
+  logger: { info(msg: string): void; warn(msg: string): void },
+): void {
+  api.commands.register('hippodid:status', {
+    description: 'Show HippoDid tier, sync status, and watched paths',
+    handler: async () => {
+      const tier = tierManager.getCurrentTier();
+      const statusResult = await client.getSyncStatus(config.characterId);
+
+      logger.info(`--- HippoDid Status ---`);
+      logger.info(`Character: ${config.characterId}`);
+      logger.info(`Tier: ${tier.tier}`);
+      logger.info(
+        `Auto-Recall: ${tier.features.autoRecallAvailable ? 'available' : 'unavailable'} (config: ${config.autoRecall ? 'ON' : 'OFF'})`,
+      );
+      logger.info(
+        `Auto-Capture: ${tier.features.autoCaptureAvailable ? 'available' : 'unavailable'} (config: ${config.autoCapture ? 'ON' : 'OFF'})`,
+      );
+
+      if (statusResult.ok) {
+        logger.info(`Synced sources: ${statusResult.value.entries.length}`);
+        for (const entry of statusResult.value.entries) {
+          logger.info(
+            `  ${entry.sourcePath} (${entry.label}) — last sync: ${entry.lastSyncedAt}`,
+          );
+        }
+      } else {
+        logger.warn(`Could not fetch sync status: ${statusResult.error.message}`);
+      }
+    },
+  });
+
+  api.commands.register('hippodid:sync', {
+    description: 'Trigger immediate sync of all watched files',
+    handler: async () => {
+      logger.info('hippodid: manual sync triggered...');
+      const { synced, changed } = await fileSync.flushNow();
+      logger.info(
+        `hippodid: manual sync complete — ${synced} files (${changed} changed)`,
+      );
+    },
+  });
+
+  api.commands.register('hippodid:import', {
+    description: 'Import existing workspace memory into HippoDid character',
+    args: [
+      {
+        name: 'workspace',
+        description: 'Path to OpenClaw workspace (default: auto-detect)',
+        required: false,
+      },
+    ],
+    handler: async (args: Record<string, string>) => {
+      const { readdir } = await import('node:fs/promises');
+      const { join, extname } = await import('node:path');
+      const { createHash } = await import('node:crypto');
+
+      const workspacePath = args['workspace']
+        ? resolve(args['workspace'])
+        : resolve(process.cwd());
+
+      const memoryDir = join(workspacePath, 'memory');
+      const memoryMd = join(workspacePath, 'MEMORY.md');
+      const filesToImport: Array<{ path: string; label: string }> = [];
+
+      try {
+        const entries = await readdir(memoryDir);
+        for (const entry of entries) {
+          if (extname(entry) === '.md') {
+            filesToImport.push({
+              path: join(memoryDir, entry),
+              label: 'workspace-memory',
+            });
+          }
+        }
+      } catch {
+        // memory dir may not exist
+      }
+
+      try {
+        await readFile(memoryMd);
+        filesToImport.push({ path: memoryMd, label: 'MEMORY.md' });
+      } catch {
+        // MEMORY.md may not exist
+      }
+
+      if (filesToImport.length === 0) {
+        logger.info('hippodid: no memory files found to import');
+        return;
+      }
+
+      logger.info(
+        `hippodid: importing ${filesToImport.length} files from ${workspacePath}...`,
+      );
+
+      let imported = 0;
+      for (const file of filesToImport) {
+        try {
+          const content = await readFile(file.path);
+          const hash = createHash('sha256').update(content).digest('hex');
+          const base64 = content.toString('base64');
+          const result = await client.syncFile(
+            config.characterId,
+            file.path,
+            file.label,
+            base64,
+            hash,
+          );
+          if (result.ok) imported++;
+        } catch (e) {
+          logger.warn(
+            `hippodid: import failed for ${file.path}: ${e instanceof Error ? e.message : 'unknown'}`,
+          );
+        }
+      }
+
+      logger.info(
+        `hippodid: import complete — ${imported}/${filesToImport.length} files imported`,
+      );
+    },
+  });
+}