@keyoku/openclaw 1.2.12 → 1.2.14

package/dist/init.js

@@ -14,7 +14,7 @@
  * 9. Offers migration of existing OpenClaw memories
  * 10. Health check to verify everything works
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, createWriteStream, cpSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, createWriteStream, cpSync, } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
@@ -22,6 +22,8 @@ import { pipeline } from 'node:stream/promises';
 import { KeyokuClient } from '@keyoku/memory';
 import { importMemoryFiles } from './migration.js';
 import { migrateAllVectorStores, discoverVectorDbs } from './migrate-vector-store.js';
+import { extractHeartbeatRules, migrateHeartbeatRules, } from './heartbeat-migration.js';
+import { findKeyokuBinary, loadKeyokuEnv, waitForHealthy } from './service.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOME = process.env.HOME ?? '';
 const OPENCLAW_CONFIG_PATH = join(HOME, '.openclaw', 'openclaw.json');
@@ -48,7 +50,7 @@ const c = {
 };
 // ── Output Helpers ───────────────────────────────────────────────────────
 let currentStep = 0;
-const totalSteps = 10;
+const totalSteps = 11;
 function stepHeader(label) {
     currentStep++;
     console.log('');
@@ -187,7 +189,7 @@ async function downloadBinary() {
             fail(`Could not fetch latest release: ${releaseRes.status} ${releaseRes.statusText}`);
             return false;
         }
-        const release = await releaseRes.json();
+        const release = (await releaseRes.json());
         const asset = release.assets.find((a) => a.name === assetName);
         if (!asset) {
             fail(`No binary found for ${os}/${arch} in release ${release.tag_name}`);
@@ -357,14 +359,15 @@ function installSkill() {
  * Install HEARTBEAT.md to the OpenClaw workspace directory.
  * Must be done at init time (not at plugin register time) because OpenClaw's
  * heartbeat system overwrites the file with a default placeholder after plugins register.
+ *
+ * If an existing HEARTBEAT.md has user content, preserves it and appends keyoku section.
+ * Returns extracted heartbeat rules for migration into Keyoku.
  */
 function installHeartbeatMd() {
     const workspaceDir = join(HOME, '.openclaw', 'workspace');
     mkdirSync(workspaceDir, { recursive: true });
     const heartbeatPath = join(workspaceDir, 'HEARTBEAT.md');
-    const HEARTBEAT_CONTENT = `# Heartbeat Check
-
-<!-- keyoku-heartbeat-start -->
+    const KEYOKU_SECTION = `<!-- keyoku-heartbeat-start -->
 ## Keyoku Memory Heartbeat
 
 You have been checked in on. Your memory system has reviewed your recent activity and surfaced anything that needs your attention. The signals are injected into your context automatically — look for the <heartbeat-signals> block.
@@ -380,85 +383,50 @@ IMPORTANT: If the signals contain \`should_act: true\` or a "Tell the User" sect
 5. ONLY reply HEARTBEAT_OK if \`should_act\` is false AND there is truly nothing in the signals worth mentioning.
 
 Do not repeat old tasks from prior conversations. Only act on what the signals say right now.
-<!-- keyoku-heartbeat-end -->
-`;
-    // If file exists and already has keyoku section, skip
+<!-- keyoku-heartbeat-end -->`;
+    let extractedRules = [];
     if (existsSync(heartbeatPath)) {
         const existing = readFileSync(heartbeatPath, 'utf-8');
+        // Extract user rules before modifying the file
+        extractedRules = extractHeartbeatRules(existing);
+        if (extractedRules.length > 0) {
+            info(`Found ${extractedRules.length} heartbeat rule(s) to migrate`);
+        }
         if (existing.includes('keyoku-heartbeat-start')) {
             success('HEARTBEAT.md already configured');
-            return;
+            return extractedRules;
         }
+        // Preserve existing user content, append keyoku section
+        const content = existing.trimEnd() + `\n\n---\n\n${KEYOKU_SECTION}\n`;
+        writeFileSync(heartbeatPath, content, 'utf-8');
+        success(`HEARTBEAT.md updated (preserved existing content) → ${c.dim}~/.openclaw/workspace/${c.reset}`);
+        return extractedRules;
     }
-    writeFileSync(heartbeatPath, HEARTBEAT_CONTENT, 'utf-8');
+    // No existing file — write full template
+    writeFileSync(heartbeatPath, `# Heartbeat Check\n\n${KEYOKU_SECTION}\n`, 'utf-8');
     success(`HEARTBEAT.md installed → ${c.dim}~/.openclaw/workspace/${c.reset}`);
+    return extractedRules;
 }
 // ── LLM Provider Setup ──────────────────────────────────────────────────
 /**
  * Set up LLM provider and API keys.
- * Embeddings auto-match the extraction provider (no separate key needed for Gemini).
+ *
+ * Flow:
+ *   5a. Embedding provider (Gemini or OpenAI only — Anthropic has no embedding models)
+ *   5b. Extraction provider (Gemini, OpenAI, or Anthropic)
+ *   5c. Extraction model (depends on provider, shows benchmark notes)
+ *   5d. API key(s) for each unique provider selected
  */
 async function setupLlmProvider() {
     // Check existing env vars
     const hasOpenAI = !!process.env.OPENAI_API_KEY;
     const hasGemini = !!process.env.GEMINI_API_KEY;
-    // Extraction provider
-    const currentProvider = process.env.KEYOKU_EXTRACTION_PROVIDER;
-    if (currentProvider) {
-        success(`Extraction: ${c.bold}${currentProvider}${c.reset} (${process.env.KEYOKU_EXTRACTION_MODEL || 'default model'})`);
-    }
-    else {
-        // Auto-detect best available provider
-        if (hasGemini) {
-            appendToEnvFile('KEYOKU_EXTRACTION_PROVIDER', 'gemini');
-            appendToEnvFile('KEYOKU_EXTRACTION_MODEL', 'gemini-2.5-flash');
-            appendToEnvFile('KEYOKU_EMBEDDING_PROVIDER', 'gemini');
-            appendToEnvFile('KEYOKU_EMBEDDING_MODEL', 'gemini-embedding-001');
-            success(`Auto-configured: ${c.bold}Gemini${c.reset} for extraction + embeddings`);
-        }
-        else if (hasOpenAI) {
-            appendToEnvFile('KEYOKU_EXTRACTION_PROVIDER', 'openai');
-            appendToEnvFile('KEYOKU_EXTRACTION_MODEL', 'gpt-5-mini');
-            appendToEnvFile('KEYOKU_EMBEDDING_PROVIDER', 'openai');
-            appendToEnvFile('KEYOKU_EMBEDDING_MODEL', 'text-embedding-3-small');
-            success(`Auto-configured: ${c.bold}OpenAI${c.reset} for extraction + embeddings`);
-        }
-        else {
-            // No API key detected — prompt for provider
-            const provider = await choose('Which LLM provider?', [
-                { label: 'OpenAI', value: 'openai', desc: 'extraction + embeddings' },
-                { label: 'Gemini', value: 'gemini', desc: 'extraction + embeddings' },
-            ]);
-            if (provider === 'gemini') {
-                const key = await prompt('Gemini API key:');
-                if (key) {
-                    appendToEnvFile('GEMINI_API_KEY', key);
-                    appendToEnvFile('KEYOKU_EXTRACTION_PROVIDER', 'gemini');
-                    appendToEnvFile('KEYOKU_EXTRACTION_MODEL', 'gemini-2.5-flash');
-                    appendToEnvFile('KEYOKU_EMBEDDING_PROVIDER', 'gemini');
-                    appendToEnvFile('KEYOKU_EMBEDDING_MODEL', 'gemini-embedding-001');
-                    success('Gemini configured');
-                }
-                else {
-                    warn('No key provided — set GEMINI_API_KEY manually');
-                }
-            }
-            else {
-                // Default: OpenAI
-                const key = await prompt('OpenAI API key (sk-...):');
-                if (key && key.startsWith('sk-')) {
-                    appendToEnvFile('OPENAI_API_KEY', key);
-                    appendToEnvFile('KEYOKU_EXTRACTION_PROVIDER', 'openai');
-                    appendToEnvFile('KEYOKU_EXTRACTION_MODEL', 'gpt-5-mini');
-                    appendToEnvFile('KEYOKU_EMBEDDING_PROVIDER', 'openai');
-                    appendToEnvFile('KEYOKU_EMBEDDING_MODEL', 'text-embedding-3-small');
-                    success('OpenAI configured');
-                }
-                else {
-                    warn('Invalid key — set OPENAI_API_KEY manually');
-                }
-            }
-        }
+    const hasAnthropic = !!process.env.ANTHROPIC_API_KEY;
+    // Show current config if already set (but still allow reconfiguration)
+    const currentExtraction = process.env.KEYOKU_EXTRACTION_PROVIDER;
+    const currentEmbedding = process.env.KEYOKU_EMBEDDING_PROVIDER;
+    if (currentExtraction && currentEmbedding) {
+        info(`Current: ${c.dim}${currentExtraction}/${process.env.KEYOKU_EXTRACTION_MODEL || 'default'} + ${currentEmbedding}/${process.env.KEYOKU_EMBEDDING_MODEL || 'default'}${c.reset}`);
     }
     // Show detected API keys
     const detected = [];
@@ -466,9 +434,108 @@ async function setupLlmProvider() {
         detected.push('OpenAI');
     if (hasGemini)
         detected.push('Gemini');
+    if (hasAnthropic)
+        detected.push('Anthropic');
     if (detected.length > 0) {
         success(`API keys detected: ${c.bold}${detected.join(', ')}${c.reset}`);
     }
+    // ── 5a: Embedding provider ──────────────────────────────────────────
+    console.log('');
+    log('Embeddings convert text into vectors for semantic search.');
+    log(`${c.yellow}Anthropic does not offer embedding models.${c.reset}`);
+    const embeddingProvider = await choose('Embedding provider?', [
+        { label: 'Gemini', value: 'gemini', desc: 'gemini-embedding-001' },
+        { label: 'OpenAI', value: 'openai', desc: 'text-embedding-3-small' },
+    ]);
+    if (embeddingProvider === 'gemini') {
+        appendToEnvFile('KEYOKU_EMBEDDING_PROVIDER', 'gemini'); // engine uses "gemini"
+        appendToEnvFile('KEYOKU_EMBEDDING_MODEL', 'gemini-embedding-001');
+    }
+    else {
+        appendToEnvFile('KEYOKU_EMBEDDING_PROVIDER', 'openai');
+        appendToEnvFile('KEYOKU_EMBEDDING_MODEL', 'text-embedding-3-small');
+    }
+    success(`Embedding → ${c.bold}${embeddingProvider}${c.reset}`);
+    // ── 5b: Extraction provider ─────────────────────────────────────────
+    const extractionProvider = await choose('Extraction provider?', [
+        { label: 'Gemini (recommended)', value: 'gemini', desc: 'Best price-to-quality ratio' },
+        { label: 'OpenAI', value: 'openai', desc: 'Reliable, widely supported' },
+        {
+            label: 'Anthropic',
+            value: 'anthropic',
+            desc: 'Highest quality, no embeddings (uses your embedding provider)',
+        },
+    ]);
+    appendToEnvFile('KEYOKU_EXTRACTION_PROVIDER', extractionProvider);
+    // ── 5c: Extraction model ────────────────────────────────────────────
+    let extractionModel;
+    if (extractionProvider === 'gemini') {
+        extractionModel = await choose('Extraction model?', [
+            {
+                label: 'gemini-3.1-flash-lite-preview (recommended)',
+                value: 'gemini-3.1-flash-lite-preview',
+                desc: 'Cheapest and fastest, near-perfect quality',
+            },
+            {
+                label: 'gemini-2.5-flash',
+                value: 'gemini-2.5-flash',
+                desc: 'Thinking model, highest accuracy, slower',
+            },
+        ]);
+    }
+    else if (extractionProvider === 'openai') {
+        extractionModel = await choose('Extraction model?', [
+            { label: 'gpt-4.1-mini', value: 'gpt-4.1-mini', desc: 'Balanced speed and quality' },
+            {
+                label: 'gpt-4.1-nano',
+                value: 'gpt-4.1-nano',
+                desc: 'Cheapest, slightly less reliable on complex schemas',
+            },
+        ]);
+    }
+    else {
+        // Anthropic — single model
+        extractionModel = 'claude-haiku-4-5-20251001';
+        info(`Extraction model: ${c.bold}claude-haiku-4-5-20251001${c.reset}  ${c.dim}Fast, top-tier quality${c.reset}`);
+    }
+    appendToEnvFile('KEYOKU_EXTRACTION_MODEL', extractionModel);
+    success(`Extraction → ${c.bold}${extractionProvider}/${extractionModel}${c.reset}`);
+    log(`${c.dim}More models coming soon — re-run init to update.${c.reset}`);
+    // ── 5d: API keys ────────────────────────────────────────────────────
+    // Collect the unique providers that need keys
+    const neededProviders = new Set([embeddingProvider, extractionProvider]);
+    for (const provider of neededProviders) {
+        if (provider === 'gemini' && !hasGemini) {
+            const key = await prompt('Gemini API key:');
+            if (key) {
+                appendToEnvFile('GEMINI_API_KEY', key);
+                success('Gemini API key saved');
+            }
+            else {
+                warn('No key provided — set GEMINI_API_KEY manually');
+            }
+        }
+        else if (provider === 'openai' && !hasOpenAI) {
+            const key = await prompt('OpenAI API key (sk-...):');
+            if (key && key.startsWith('sk-')) {
+                appendToEnvFile('OPENAI_API_KEY', key);
+                success('OpenAI API key saved');
+            }
+            else {
+                warn('Invalid key — set OPENAI_API_KEY manually');
+            }
+        }
+        else if (provider === 'anthropic' && !hasAnthropic) {
+            const key = await prompt('Anthropic API key (sk-ant-...):');
+            if (key && key.startsWith('sk-ant-')) {
+                appendToEnvFile('ANTHROPIC_API_KEY', key);
+                success('Anthropic API key saved');
+            }
+            else {
+                warn('Invalid key — set ANTHROPIC_API_KEY manually');
+            }
+        }
+    }
 }
 // ── Environment File Management ──────────────────────────────────────────
 /**
@@ -578,7 +645,7 @@ async function setupTimezoneAndQuietHours() {
     console.log('');
     const tzAnswer = await prompt(`Timezone? [1-${tzOptions.length}]:`);
     const tzIdx = parseInt(tzAnswer, 10) - 1;
-    const timezone = (tzIdx >= 0 && tzIdx < tzOptions.length) ? tzOptions[tzIdx].value : detected;
+    const timezone = tzIdx >= 0 && tzIdx < tzOptions.length ? tzOptions[tzIdx].value : detected;
     appendToEnvFile('KEYOKU_QUIET_HOURS_TIMEZONE', timezone);
     success(`Timezone → ${c.bold}${timezone}${c.reset}`);
     // Quiet hours
@@ -606,6 +673,172 @@ async function setupTimezoneAndQuietHours() {
     }
     success(`Quiet hours → ${c.bold}${isNaN(start) ? 23 : start}:00 – ${isNaN(end) ? 7 : end}:00${c.reset} (${timezone})`);
 }
+// ── Heartbeat Delivery Setup ─────────────────────────────────────────────
+/**
+ * Platform-specific instructions for finding group chat IDs.
+ */
+const GROUP_ID_HINTS = {
+    telegram: 'Add @RawDataBot to your group — it replies with the chat ID (a negative number like -4970078838)',
+    discord: 'Right-click your channel → Copy Channel ID (enable Developer Mode in Settings → Advanced first)',
+    slack: 'Open channel details → scroll to the bottom → Channel ID',
+    whatsapp: 'Group JID (shown in WhatsApp Web URL or API logs)',
+    googlechat: 'Space ID from the URL (spaces/<id>)',
+    msteams: 'Channel ID from Teams admin or Graph API',
+    signal: 'Group ID from Signal API logs',
+};
+/**
+ * Set up heartbeat delivery in openclaw.json.
+ *
+ * Detects configured channels, asks for a group chat ID,
+ * and writes agents.defaults.heartbeat with target + to.
+ */
+async function setupHeartbeatDelivery(config) {
+    // Detect configured channels from openclaw.json
+    const channels = config.channels;
+    const configuredChannels = channels ? Object.keys(channels).filter((k) => k !== 'defaults') : [];
+    if (configuredChannels.length === 0) {
+        log('No messaging channels configured in openclaw.json');
+        log("Heartbeat will run but messages won't be delivered externally");
+        log(`${c.dim}Configure a channel (telegram, discord, etc.) and re-run init${c.reset}`);
+        return;
+    }
+    info(`Detected channel(s): ${c.bold}${configuredChannels.join(', ')}${c.reset}`);
+    console.log('');
+    log('Heartbeat lets your agent proactively message you when something needs attention.');
+    log(`${c.yellow}Heartbeats deliver to group chats only — DMs are blocked by OpenClaw.${c.reset}`);
+    const enableDelivery = await choose('Set up heartbeat delivery now?', [
+        { label: 'Yes', value: 'yes', desc: 'configure group chat delivery' },
+        { label: 'Skip', value: 'no', desc: 'heartbeat runs but no messages sent' },
+    ]);
+    if (enableDelivery === 'no') {
+        // Write target: "none" explicitly so it's clear in config
+        ensureAgentsDefaults(config);
+        config.agents.defaults.heartbeat = {
+            ...config.agents.defaults.heartbeat,
+            every: '30m',
+            target: 'none',
+        };
+        writeOpenClawConfig(config);
+        success('Heartbeat delivery → none (runs silently)');
+        return;
+    }
+    // Pick channel
+    let targetChannel;
+    if (configuredChannels.length === 1) {
+        targetChannel = configuredChannels[0];
+        info(`Using ${c.bold}${targetChannel}${c.reset} (only configured channel)`);
+    }
+    else {
+        const channelOptions = configuredChannels.map((ch) => ({
+            label: ch.charAt(0).toUpperCase() + ch.slice(1),
+            value: ch,
+        }));
+        targetChannel = await choose('Which channel should receive heartbeat messages?', channelOptions);
+    }
+    // Get group chat ID
+    const hint = GROUP_ID_HINTS[targetChannel];
+    console.log('');
+    log(`Enter the ${c.bold}group chat ID${c.reset} for ${targetChannel}.`);
+    if (hint) {
+        log(`${c.dim}Tip: ${hint}${c.reset}`);
+    }
+    log(`${c.yellow}Must be a group/channel — DMs will not work.${c.reset}`);
+    console.log('');
+    const groupId = await prompt(`${targetChannel} group chat ID:`);
+    if (!groupId) {
+        warn('No group ID provided — heartbeat delivery disabled');
+        ensureAgentsDefaults(config);
+        config.agents.defaults.heartbeat = {
+            ...config.agents.defaults.heartbeat,
+            every: '30m',
+            target: 'none',
+        };
+        writeOpenClawConfig(config);
+        return;
+    }
+    // Pick interval
+    const interval = await choose('Heartbeat interval?', [
+        { label: '15 minutes', value: '15m', desc: 'balanced' },
+        { label: '30 minutes', value: '30m', desc: 'default, lower cost' },
+        { label: '1 hour', value: '1h', desc: 'minimal cost' },
+        { label: '5 minutes', value: '5m', desc: 'frequent, higher cost' },
+    ]);
+    // Write to openclaw.json
+    ensureAgentsDefaults(config);
+    config.agents.defaults.heartbeat = {
+        ...config.agents.defaults.heartbeat,
+        every: interval,
+        target: targetChannel,
+        to: groupId,
+    };
+    writeOpenClawConfig(config);
+    success(`Heartbeat → ${c.bold}${targetChannel}${c.reset} (group: ${c.dim}${groupId}${c.reset}, every ${interval})`);
+}
+/**
+ * Ensure agents.defaults exists in config.
+ */
+function ensureAgentsDefaults(config) {
+    if (!config.agents)
+        config.agents = {};
+    if (!config.agents.defaults)
+        config.agents.defaults = {};
+    if (!config.agents.defaults.heartbeat)
+        config.agents.defaults.heartbeat = {};
+}
+// ── Start Keyoku for Migration ──────────────────────────────────────────
+/**
+ * Temporarily start the keyoku binary so migration can call the API.
+ * Returns a cleanup function to kill the process afterward.
+ */
+async function startKeyokuForMigration() {
+    const { spawn } = await import('node:child_process');
+    const { randomBytes } = await import('node:crypto');
+    // Check if already running
+    if (await waitForHealthy('http://localhost:18900', 2000, 500)) {
+        info('Keyoku already running');
+        return () => { }; // no-op cleanup
+    }
+    const binary = findKeyokuBinary();
+    if (!binary) {
+        warn('Keyoku binary not found — migration will be skipped');
+        return () => { };
+    }
+    const keyokuEnv = loadKeyokuEnv();
+    const env = { ...keyokuEnv, ...process.env };
+    if (!env.KEYOKU_SESSION_TOKEN) {
+        env.KEYOKU_SESSION_TOKEN = randomBytes(16).toString('hex');
+    }
+    process.env.KEYOKU_SESSION_TOKEN = env.KEYOKU_SESSION_TOKEN;
+    if (!env.KEYOKU_DB_PATH) {
+        const dbDir = join(HOME, '.keyoku', 'data');
+        mkdirSync(dbDir, { recursive: true });
+        env.KEYOKU_DB_PATH = join(dbDir, 'keyoku.db');
+    }
+    info('Starting keyoku for migration...');
+    const proc = spawn(binary, [], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: false,
+        env,
+    });
+    // Suppress output during migration
+    proc.stdout?.resume();
+    proc.stderr?.resume();
+    const healthy = await waitForHealthy('http://localhost:18900', 10000, 500);
+    if (healthy) {
+        info('Keyoku ready for migration');
+    }
+    else {
+        warn('Keyoku health check timed out — migration may fail');
+    }
+    return () => {
+        try {
+            proc.kill('SIGTERM');
+        }
+        catch {
+            // Process already exited
+        }
+    };
+}
 // ── Health Check ─────────────────────────────────────────────────────────
 /**
  * Run a health check against keyoku-engine to verify the install works.
@@ -722,65 +955,92 @@ export async function init() {
     // Step 7: Timezone & quiet hours
     stepHeader('Timezone & Quiet Hours');
     await setupTimezoneAndQuietHours();
-    // Step 8: SKILL.md
+    // Step 8: Heartbeat delivery
+    stepHeader('Heartbeat Delivery');
+    await setupHeartbeatDelivery(config);
+    // Step 9: SKILL.md
     stepHeader('Install Skill Guide');
     installSkill();
-    // Step 8b: HEARTBEAT.md
-    installHeartbeatMd();
-    // Step 9: Migration
+    // Step 9b: HEARTBEAT.md (extract user rules before writing keyoku section)
+    const heartbeatRules = installHeartbeatMd();
+    // Step 10: Migration
     const memoryMdPath = join(HOME, '.openclaw', 'MEMORY.md');
     const hasMemoryMd = existsSync(memoryMdPath);
     const vectorDbs = discoverVectorDbs(OPENCLAW_MEMORY_DIR);
     const hasVectorStores = vectorDbs.length > 0;
-    if (hasMemoryMd || hasVectorStores) {
+    const hasHeartbeatRules = heartbeatRules.length > 0;
+    if (hasMemoryMd || hasVectorStores || hasHeartbeatRules) {
         stepHeader('Migrate Memories');
         if (hasMemoryMd)
             info('Found MEMORY.md');
         if (hasVectorStores)
             info(`Found ${vectorDbs.length} vector store(s)`);
+        if (hasHeartbeatRules)
+            info(`Found ${heartbeatRules.length} heartbeat rule(s)`);
         const migrate = await choose('Migrate existing memories into Keyoku?', [
             { label: 'Yes', value: 'yes', desc: 'import everything now' },
             { label: 'No', value: 'no', desc: 'skip for now' },
         ]);
         if (migrate === 'yes') {
-            info('Starting migration...');
-            const client = new KeyokuClient({
-                baseUrl: 'http://localhost:18900',
-                token: process.env.KEYOKU_SESSION_TOKEN,
-                timeout: 60000,
-            });
-            const entityId = 'default';
-            // Migrate markdown files
-            if (hasMemoryMd) {
-                try {
-                    const mdResult = await importMemoryFiles({
-                        client,
-                        entityId,
-                        workspaceDir: join(HOME, '.openclaw'),
-                        logger: console,
-                    });
-                    success(`Markdown: ${mdResult.imported} imported, ${mdResult.skipped} skipped`);
-                }
-                catch (err) {
-                    warn(`Markdown migration failed: ${String(err)}`);
-                    log('Make sure Keyoku is running (it auto-starts when OpenClaw loads the plugin)');
+            // Start keyoku temporarily for migration
+            const cleanup = await startKeyokuForMigration();
+            try {
+                const client = new KeyokuClient({
+                    baseUrl: 'http://localhost:18900',
+                    token: process.env.KEYOKU_SESSION_TOKEN,
+                    timeout: 60000,
+                });
+                const entityId = 'default';
+                // Migrate markdown files
+                if (hasMemoryMd) {
+                    try {
+                        const mdResult = await importMemoryFiles({
+                            client,
+                            entityId,
+                            workspaceDir: join(HOME, '.openclaw'),
+                            logger: console,
+                        });
+                        success(`Markdown: ${mdResult.imported} imported, ${mdResult.skipped} skipped`);
+                    }
+                    catch (err) {
+                        warn(`Markdown migration failed: ${String(err)}`);
+                    }
                 }
-            }
-            // Migrate vector stores
-            if (hasVectorStores) {
-                try {
-                    const vsResult = await migrateAllVectorStores({
-                        client,
-                        entityId,
-                        memoryDir: OPENCLAW_MEMORY_DIR,
-                        logger: console,
-                    });
-                    success(`Vector stores: ${vsResult.imported} imported, ${vsResult.skipped} skipped`);
+                // Migrate vector stores
+                if (hasVectorStores) {
+                    try {
+                        const vsResult = await migrateAllVectorStores({
+                            client,
+                            entityId,
+                            memoryDir: OPENCLAW_MEMORY_DIR,
+                            logger: console,
+                        });
+                        success(`Vector stores: ${vsResult.imported} imported, ${vsResult.skipped} skipped`);
+                    }
+                    catch (err) {
+                        warn(`Vector store migration failed: ${String(err)}`);
+                    }
                 }
-                catch (err) {
-                    warn(`Vector store migration failed: ${String(err)}`);
+                // Migrate heartbeat rules (preferences, rules, scheduled tasks)
+                if (hasHeartbeatRules) {
+                    try {
+                        const hbResult = await migrateHeartbeatRules({
+                            client,
+                            entityId,
+                            agentId: 'default',
+                            rules: heartbeatRules,
+                            logger: console,
+                        });
+                        success(`Heartbeat: ${hbResult.preferences} preferences, ${hbResult.rules} rules, ${hbResult.schedules} schedules`);
+                    }
+                    catch (err) {
+                        warn(`Heartbeat migration failed: ${String(err)}`);
+                    }
                 }
             }
+            finally {
+                cleanup();
+            }
         }
         else {
             log('Skipping — you can re-run init later to migrate');
@@ -790,7 +1050,7 @@ export async function init() {
         stepHeader('Migrate Memories');
         log('No existing memories found — nothing to migrate');
     }
-    // Step 10: Health check
+    // Step 11: Health check
     stepHeader('Health Check');
     await healthCheck();
     // Close readline before exiting
@@ -815,6 +1075,10 @@ export async function init() {
     console.log(`     ${c.dim}openclaw memory status${c.reset}    ${c.dim}check memory index status${c.reset}`);
     console.log(`     ${c.dim}openclaw memory search${c.reset}    ${c.dim}search stored memories${c.reset}`);
     console.log('');
+    console.log(`  ${c.gray}3.${c.reset} ${c.yellow}Heartbeat requires a group chat${c.reset}`);
+    console.log(`     ${c.dim}OpenClaw delivers heartbeats to group chats only (not DMs).${c.reset}`);
+    console.log(`     ${c.dim}Add your bot to a Telegram/Discord/WhatsApp group to receive proactive check-ins.${c.reset}`);
+    console.log('');
     console.log(`  ${c.indigo}${'━'.repeat(52)}${c.reset}`);
     console.log('');
 }