@keyoku/openclaw 1.0.0

package/src/migration.ts

@@ -0,0 +1,241 @@
+/**
+ * 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

@@ -0,0 +1,145 @@
+/**
+ * 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

@@ -0,0 +1,239 @@
+/**
+ * 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

@@ -0,0 +1,40 @@
+/**
+ * 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>;
+};