@keyoku/openclaw 1.0.0 → 1.1.0

package/src/migration.ts

@@ -1,241 +0,0 @@
-/**
- * Migration utility — imports OpenClaw's file-based memories into Keyoku.
- *
- * Reads MEMORY.md and memory/*.md files, chunks them by heading sections,
- * deduplicates against existing Keyoku memories, and stores each chunk.
- *
- * Usage: `openclaw memory import --dir /path/to/workspace`
- */
-
-import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
-import { join, basename } from 'path';
-import type { KeyokuClient } from '@keyoku/memory';
-
-export interface ImportResult {
-  imported: number;
-  skipped: number;
-  errors: number;
-}
-
-interface MemoryChunk {
-  content: string;
-  source: string; // original filename
-  section?: string; // heading text
-}
-
-/**
- * Split markdown content by ## or ### headings.
- * Each heading section becomes one chunk.
- * If no headings, split by --- separators or paragraphs.
- */
-function chunkByHeadings(content: string, maxChunkChars = 1000): MemoryChunk[] {
-  const chunks: MemoryChunk[] = [];
-
-  // Try splitting by headings first
-  const headingPattern = /^#{2,3}\s+(.+)$/gm;
-  const headings: { index: number; title: string }[] = [];
-  let match: RegExpExecArray | null;
-
-  while ((match = headingPattern.exec(content)) !== null) {
-    headings.push({ index: match.index, title: match[1].trim() });
-  }
-
-  if (headings.length > 0) {
-    for (let i = 0; i < headings.length; i++) {
-      const start = headings[i].index;
-      const end = i + 1 < headings.length ? headings[i + 1].index : content.length;
-      const sectionText = content.slice(start, end).trim();
-
-      if (sectionText.length < 10) continue;
-
-      // If section is too long, split by paragraphs
-      if (sectionText.length > maxChunkChars) {
-        const paragraphs = splitByParagraphs(sectionText, maxChunkChars);
-        for (const p of paragraphs) {
-          chunks.push({ content: p, source: '', section: headings[i].title });
-        }
-      } else {
-        chunks.push({ content: sectionText, source: '', section: headings[i].title });
-      }
-    }
-
-    // Content before the first heading
-    const preamble = content.slice(0, headings[0].index).trim();
-    if (preamble.length >= 10) {
-      const paragraphs = splitByParagraphs(preamble, maxChunkChars);
-      for (const p of paragraphs) {
-        chunks.push({ content: p, source: '' });
-      }
-    }
-  } else {
-    // No headings — try --- separators
-    const sections = content.split(/^---+$/m);
-    if (sections.length > 1) {
-      for (const section of sections) {
-        const trimmed = section.trim();
-        if (trimmed.length < 10) continue;
-        const paragraphs = splitByParagraphs(trimmed, maxChunkChars);
-        for (const p of paragraphs) {
-          chunks.push({ content: p, source: '' });
-        }
-      }
-    } else {
-      // No structure — split by paragraphs
-      const paragraphs = splitByParagraphs(content, maxChunkChars);
-      for (const p of paragraphs) {
-        chunks.push({ content: p, source: '' });
-      }
-    }
-  }
-
-  return chunks;
-}
-
-/**
- * Split text by double-newline (paragraphs), merging small paragraphs
- * and splitting oversized ones.
- */
-function splitByParagraphs(text: string, maxChars = 1000): string[] {
-  const rawParagraphs = text.split(/\n\n+/);
-  const results: string[] = [];
-  let buffer = '';
-
-  for (const para of rawParagraphs) {
-    const trimmed = para.trim();
-    if (!trimmed) continue;
-
-    if (buffer.length + trimmed.length + 2 <= maxChars) {
-      buffer = buffer ? `${buffer}\n\n${trimmed}` : trimmed;
-    } else {
-      if (buffer) results.push(buffer);
-      if (trimmed.length > maxChars) {
-        // Hard split at maxChars boundary
-        for (let i = 0; i < trimmed.length; i += maxChars) {
-          results.push(trimmed.slice(i, i + maxChars));
-        }
-        buffer = '';
-      } else {
-        buffer = trimmed;
-      }
-    }
-  }
-
-  if (buffer && buffer.length >= 10) results.push(buffer);
-  return results;
-}
-
-/**
- * Small delay helper for rate limiting.
- */
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * Import OpenClaw memory files into Keyoku.
- */
-export async function importMemoryFiles(params: {
-  client: KeyokuClient;
-  entityId: string;
-  workspaceDir: string;
-  agentId?: string;
-  dryRun?: boolean;
-  logger?: { info: (msg: string) => void; warn: (msg: string) => void };
-}): Promise<ImportResult> {
-  const { client, entityId, workspaceDir, agentId, dryRun = false, logger = console } = params;
-  const result: ImportResult = { imported: 0, skipped: 0, errors: 0 };
-
-  // Discover memory files
-  const files: { path: string; name: string }[] = [];
-
-  // Check for MEMORY.md
-  const memoryMdPath = join(workspaceDir, 'MEMORY.md');
-  if (existsSync(memoryMdPath)) {
-    files.push({ path: memoryMdPath, name: 'MEMORY.md' });
-  }
-
-  // Check for memory/ directory
-  const memoryDir = join(workspaceDir, 'memory');
-  if (existsSync(memoryDir) && statSync(memoryDir).isDirectory()) {
-    const entries = readdirSync(memoryDir)
-      .filter((f) => f.endsWith('.md'))
-      .sort(); // chronological for dated files
-
-    for (const entry of entries) {
-      files.push({ path: join(memoryDir, entry), name: `memory/${entry}` });
-    }
-  }
-
-  if (files.length === 0) {
-    logger.info('No memory files found in workspace.');
-    return result;
-  }
-
-  logger.info(`Found ${files.length} memory file(s) to import.`);
-
-  // Process each file
-  for (const file of files) {
-    let content: string;
-    try {
-      content = readFileSync(file.path, 'utf-8');
-    } catch (err) {
-      logger.warn(`Failed to read ${file.name}: ${String(err)}`);
-      result.errors++;
-      continue;
-    }
-
-    if (content.trim().length < 10) {
-      logger.info(`Skipping ${file.name} (too short)`);
-      result.skipped++;
-      continue;
-    }
-
-    const chunks = chunkByHeadings(content);
-
-    for (const chunk of chunks) {
-      chunk.source = file.name;
-
-      // Build the content to store — include source context
-      const taggedContent = chunk.section
-        ? `[Imported from ${file.name} — ${chunk.section}]\n${chunk.content}`
-        : `[Imported from ${file.name}]\n${chunk.content}`;
-
-      if (dryRun) {
-        logger.info(`[dry-run] Would import: ${taggedContent.slice(0, 80)}...`);
-        result.imported++;
-        continue;
-      }
-
-      // Dedup check: search for similar content
-      try {
-        const queryText = chunk.content.slice(0, 100);
-        const existing = await client.search(entityId, queryText, { limit: 1, min_score: 0.95 });
-
-        if (existing.length > 0) {
-          result.skipped++;
-          continue;
-        }
-      } catch {
-        // Search failed — proceed with import anyway
-      }
-
-      // Store the memory
-      try {
-        await client.remember(entityId, taggedContent, {
-          agent_id: agentId,
-          source: 'migration',
-        });
-        result.imported++;
-        logger.info(`Imported: ${chunk.content.slice(0, 60)}...`);
-      } catch (err) {
-        logger.warn(`Failed to store chunk from ${file.name}: ${String(err)}`);
-        result.errors++;
-      }
-
-      // Rate limit
-      await delay(50);
-    }
-  }
-
-  return result;
-}

package/src/service.ts

@@ -1,145 +0,0 @@
-/**
- * Keyoku binary lifecycle management.
- * Starts/stops the Keyoku Go binary as a child process.
- */
-
-import { spawn, type ChildProcess } from 'node:child_process';
-import { existsSync, mkdirSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { randomBytes } from 'node:crypto';
-import type { PluginApi } from './types.js';
-
-let keyokuProcess: ChildProcess | null = null;
-
-/**
- * Check if Keyoku is already running by attempting a health check.
- */
-async function isKeyokuRunning(url: string): Promise<boolean> {
-  try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 2000);
-    const res = await fetch(`${url}/health`, { signal: controller.signal });
-    clearTimeout(timer);
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Wait for Keyoku to become healthy, polling every interval up to a timeout.
- */
-async function waitForHealthy(url: string, timeoutMs = 5000, intervalMs = 500): Promise<boolean> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (await isKeyokuRunning(url)) return true;
-    await new Promise((r) => setTimeout(r, intervalMs));
-  }
-  return false;
-}
-
-/**
- * Find keyoku binary on disk or PATH.
- */
-function findKeyokuBinary(): string | null {
-  const home = process.env.HOME ?? '';
-  const candidates = [
-    resolve(home, '.keyoku', 'bin', 'keyoku'),
-    resolve(home, '.local', 'bin', 'keyoku'),
-  ];
-
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) return candidate;
-  }
-
-  // Fall back to PATH resolution
-  return 'keyoku';
-}
-
-/**
- * Ensure the Keyoku data directory exists and return the DB path.
- */
-function ensureDataDir(): string {
-  const dir = resolve(process.env.HOME ?? '', '.keyoku', 'data');
-  mkdirSync(dir, { recursive: true });
-  return resolve(dir, 'keyoku.db');
-}
-
-export function registerService(api: PluginApi, keyokuUrl: string): void {
-  api.registerService({
-    id: 'keyoku-engine',
-
-    async start() {
-      // Skip if already running
-      if (await isKeyokuRunning(keyokuUrl)) {
-        api.logger.info('keyoku: Keyoku already running');
-        return;
-      }
-
-      const binary = findKeyokuBinary();
-      if (!binary) {
-        api.logger.warn('keyoku: Keyoku binary not found — memory features require Keyoku to be running');
-        return;
-      }
-
-      // Prepare environment
-      const env = { ...process.env };
-      if (!env.KEYOKU_SESSION_TOKEN) {
-        env.KEYOKU_SESSION_TOKEN = randomBytes(16).toString('hex');
-        api.logger.info('keyoku: Generated session token');
-      }
-      if (!env.KEYOKU_DB_PATH) {
-        env.KEYOKU_DB_PATH = ensureDataDir();
-        api.logger.info(`keyoku: Using database at ${env.KEYOKU_DB_PATH}`);
-      }
-
-      try {
-        keyokuProcess = spawn(binary, [], {
-          stdio: ['ignore', 'pipe', 'pipe'],
-          detached: false,
-          env,
-        });
-
-        // Pipe stdout/stderr to logger
-        keyokuProcess.stdout?.on('data', (data: Buffer) => {
-          const line = data.toString().trim();
-          if (line) api.logger.info(`keyoku: ${line}`);
-        });
-
-        keyokuProcess.stderr?.on('data', (data: Buffer) => {
-          const line = data.toString().trim();
-          if (line) api.logger.warn(`keyoku: ${line}`);
-        });
-
-        keyokuProcess.on('error', (err) => {
-          api.logger.warn(`keyoku: Failed to start Keyoku: ${err.message}`);
-          keyokuProcess = null;
-        });
-
-        keyokuProcess.on('exit', (code) => {
-          if (code !== 0 && code !== null) {
-            api.logger.warn(`keyoku: Keyoku exited with code ${code}`);
-          }
-          keyokuProcess = null;
-        });
-
-        // Wait for health check with retry
-        if (await waitForHealthy(keyokuUrl)) {
-          api.logger.info('keyoku: Keyoku started successfully');
-        } else {
-          api.logger.warn('keyoku: Keyoku started but health check failed — it may still be initializing');
-        }
-      } catch (err) {
-        api.logger.warn(`keyoku: Could not start Keyoku: ${String(err)}`);
-      }
-    },
-
-    stop() {
-      if (keyokuProcess) {
-        keyokuProcess.kill('SIGTERM');
-        keyokuProcess = null;
-        api.logger.info('keyoku: Keyoku stopped');
-      }
-    },
-  });
-}

package/src/tools.ts

@@ -1,239 +0,0 @@
-/**
- * OpenClaw tool registrations for Keyoku memory operations.
- * Registers 7 tools:
- *   memory_search, memory_get (OpenClaw standard — replaces built-in file-based memory)
- *   memory_store, memory_forget, memory_stats (Keyoku memory management)
- *   schedule_create, schedule_list (Keyoku scheduling)
- */
-
-import { Type } from '@sinclair/typebox';
-import type { KeyokuClient } from '@keyoku/memory';
-import type { PluginApi } from './types.js';
-
-export function registerTools(api: PluginApi, client: KeyokuClient, entityId: string, agentId: string): void {
-  // memory_search — OpenClaw-standard search tool (replaces memory-core's built-in)
-  api.registerTool(
-    {
-      name: 'memory_search',
-      label: 'Memory Search',
-      description:
-        'Search through memories for relevant information. Returns semantically similar memories ranked by relevance.',
-      parameters: Type.Object({
-        query: Type.String({ description: 'Search query' }),
-        maxResults: Type.Optional(Type.Number({ description: 'Max results (default: 5)' })),
-        minScore: Type.Optional(Type.Number({ description: 'Minimum relevance score 0-1' })),
-      }),
-      async execute(_toolCallId, params) {
-        const { query, maxResults = 5, minScore = 0.1 } = params as {
-          query: string;
-          maxResults?: number;
-          minScore?: number;
-        };
-        const results = await client.search(entityId, query, { limit: maxResults, min_score: minScore });
-
-        if (results.length === 0) {
-          return {
-            content: [{ type: 'text', text: JSON.stringify({ results: [], provider: 'memory', mode: 'semantic' }) }],
-            details: { count: 0 },
-          };
-        }
-
-        const mapped = results.map((r) => ({
-          path: `mem:${r.memory.id}`,
-          startLine: 1,
-          endLine: 1,
-          score: r.similarity,
-          snippet: r.memory.content,
-          source: 'memory',
-          citation: `mem:${r.memory.id}`,
-        }));
-
-        return {
-          content: [
-            { type: 'text', text: JSON.stringify({ results: mapped, provider: 'memory', mode: 'semantic' }) },
-          ],
-          details: { count: mapped.length },
-        };
-      },
-    },
-    { name: 'memory_search' },
-  );
-
-  // memory_get — OpenClaw-standard memory read tool (replaces file-based reads)
-  api.registerTool(
-    {
-      name: 'memory_get',
-      label: 'Memory Get',
-      description:
-        'Read a specific memory by its ID (mem:<id>) or search for a memory by keyword.',
-      parameters: Type.Object({
-        path: Type.String({ description: 'Memory path (mem:<id>) or keyword to search' }),
-        from: Type.Optional(Type.Number({ description: 'Line offset (unused)' })),
-        lines: Type.Optional(Type.Number({ description: 'Line count (unused)' })),
-      }),
-      async execute(_toolCallId, params) {
-        const { path: memPath } = params as { path: string; from?: number; lines?: number };
-
-        if (memPath.startsWith('mem:') || memPath.startsWith('keyoku:')) {
-          const id = memPath.startsWith('mem:') ? memPath.slice(4) : memPath.slice(7);
-          try {
-            const memory = await client.getMemory(id);
-            return {
-              content: [{ type: 'text', text: JSON.stringify({ text: memory.content, path: memPath }) }],
-            };
-          } catch {
-            return {
-              content: [{ type: 'text', text: JSON.stringify({ text: '', path: memPath, error: 'Memory not found' }) }],
-            };
-          }
-        }
-
-        // Fallback: treat path as a search query
-        const results = await client.search(entityId, memPath, { limit: 1 });
-        if (results.length > 0) {
-          return {
-            content: [
-              {
-                type: 'text',
-                text: JSON.stringify({
-                  text: results[0].memory.content,
-                  path: `mem:${results[0].memory.id}`,
-                }),
-              },
-            ],
-          };
-        }
-
-        return {
-          content: [{ type: 'text', text: JSON.stringify({ text: '', path: memPath, error: 'Not found' }) }],
-        };
-      },
-    },
-    { name: 'memory_get' },
-  );
-
-  // memory_store — store a new memory
-  api.registerTool(
-    {
-      name: 'memory_store',
-      label: 'Memory Store',
-      description:
-        'Save important information in long-term memory. Use for preferences, facts, decisions.',
-      parameters: Type.Object({
-        text: Type.String({ description: 'Information to remember' }),
-      }),
-      async execute(_toolCallId, params) {
-        const { text } = params as { text: string };
-        const result = await client.remember(entityId, text, { agent_id: agentId });
-
-        return {
-          content: [{ type: 'text', text: `Stored: "${text.slice(0, 100)}${text.length > 100 ? '...' : ''}"` }],
-          details: { memories_created: result.memories_created },
-        };
-      },
-    },
-    { name: 'memory_store' },
-  );
-
-  // memory_forget — delete a memory by ID
-  api.registerTool(
-    {
-      name: 'memory_forget',
-      label: 'Memory Forget',
-      description: 'Delete a specific memory by ID.',
-      parameters: Type.Object({
-        memory_id: Type.String({ description: 'The memory ID to delete' }),
-      }),
-      async execute(_toolCallId, params) {
-        const { memory_id } = params as { memory_id: string };
-        const result = await client.deleteMemory(memory_id);
-
-        return {
-          content: [{ type: 'text', text: `Memory ${memory_id} deleted.` }],
-          details: { status: result.status },
-        };
-      },
-    },
-    { name: 'memory_forget' },
-  );
-
-  // memory_stats — get memory statistics
-  api.registerTool(
-    {
-      name: 'memory_stats',
-      label: 'Memory Stats',
-      description: 'Get memory statistics for the current entity.',
-      parameters: Type.Object({}),
-      async execute() {
-        const stats = await client.getStats(entityId);
-
-        const text = [
-          `Total memories: ${stats.total_memories}`,
-          `Active memories: ${stats.active_memories}`,
-          `By type: ${JSON.stringify(stats.by_type)}`,
-          `By state: ${JSON.stringify(stats.by_state)}`,
-        ].join('\n');
-
-        return {
-          content: [{ type: 'text', text }],
-          details: { ...stats } as Record<string, unknown>,
-        };
-      },
-    },
-    { name: 'memory_stats' },
-  );
-
-  // schedule_create — create a scheduled memory
-  api.registerTool(
-    {
-      name: 'schedule_create',
-      label: 'Schedule Create',
-      description:
-        'Create a scheduled task/reminder. Cron tags: "daily", "weekly", "monthly", or a cron expression.',
-      parameters: Type.Object({
-        content: Type.String({ description: 'What to schedule' }),
-        cron_tag: Type.String({ description: 'Cron tag: "daily", "weekly", "monthly", or cron expression' }),
-      }),
-      async execute(_toolCallId, params) {
-        const { content, cron_tag } = params as { content: string; cron_tag: string };
-        const result = await client.createSchedule(entityId, agentId, content, cron_tag);
-
-        return {
-          content: [{ type: 'text', text: `Scheduled: "${content}" (${cron_tag})` }],
-          details: { id: result.id },
-        };
-      },
-    },
-    { name: 'schedule_create' },
-  );
-
-  // schedule_list — list schedules
-  api.registerTool(
-    {
-      name: 'schedule_list',
-      label: 'Schedule List',
-      description: 'List active schedules.',
-      parameters: Type.Object({}),
-      async execute() {
-        const schedules = await client.listSchedules(entityId, agentId);
-
-        if (schedules.length === 0) {
-          return {
-            content: [{ type: 'text', text: 'No active schedules.' }],
-            details: { count: 0 },
-          };
-        }
-
-        const text = schedules
-          .map((s, i) => `${i + 1}. ${s.content} (id: ${s.id})`)
-          .join('\n');
-
-        return {
-          content: [{ type: 'text', text: `${schedules.length} schedules:\n\n${text}` }],
-          details: { count: schedules.length },
-        };
-      },
-    },
-    { name: 'schedule_list' },
-  );
-}

package/src/types.ts

@@ -1,40 +0,0 @@
-/**
- * Minimal OpenClaw plugin API types.
- * These mirror the types from openclaw/src/plugins/types.ts
- * so that @keyoku/openclaw can compile without importing openclaw directly.
- * At runtime, the actual OpenClaw API object is passed in.
- */
-
-export type PluginLogger = {
-  debug?: (message: string) => void;
-  info: (message: string) => void;
-  warn: (message: string) => void;
-  error: (message: string) => void;
-};
-
-export type ToolResult = {
-  content: Array<{ type: string; text: string }>;
-  details?: Record<string, unknown>;
-};
-
-export type AgentTool = {
-  name: string;
-  label?: string;
-  description: string;
-  parameters: unknown;
-  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
-};
-
-export type PluginApi = {
-  id: string;
-  name: string;
-  logger: PluginLogger;
-  pluginConfig?: Record<string, unknown>;
-  registerTool: (tool: AgentTool, opts?: { name?: string; names?: string[] }) => void;
-  registerHook?: (events: string | string[], handler: (...args: unknown[]) => unknown, opts?: Record<string, unknown>) => void;
-  registerCli: (registrar: (ctx: { program: unknown; config: unknown; logger: PluginLogger }) => void, opts?: { commands?: string[] }) => void;
-  registerService: (service: { id: string; start: (ctx: unknown) => void | Promise<void>; stop?: (ctx: unknown) => void | Promise<void> }) => void;
-  resolvePath: (input: string) => string;
-  on: (hookName: string, handler: (...args: unknown[]) => unknown, opts?: { priority?: number }) => void;
-  config?: Record<string, unknown>;
-};