memex-mvp 0.5.0

package/bot/README.md

@@ -0,0 +1,169 @@
+# memex-bot — Telegram capture surface for memex
+
+A Telegram bot that lets you capture thoughts, voice notes, and forwarded
+messages on the go. Everything you send (or forward) flows into the same
+FTS5 corpus as the rest of your memex memory.
+
+## How it works
+
+```
+You message @your_memex_bot
+    ↓
+bot process (long-poll getUpdates)
+    ↓
+builds Telegram-export-format JSON snippet
+    ↓
+~/.memex/inbox/bot-<ts>-<msg_id>.json
+    ↓
+[memex MCP server's existing inbox watcher imports → memex.db]
+```
+
+The bot writes JSON files in the same shape as a Telegram Desktop export.
+The existing `importTelegram` parser in `server.js` ingests them. **Zero new
+ingest code path** — voice transcripts, forwards, and direct messages all
+land in the dedicated `tg-memex-bot-<your_user_id>` conversation. The
+synthetic `memex-bot-` prefix keeps the bot thread separate from any real
+Telegram chat (including Saved Messages, which Telegram Desktop exports
+with `chat.id == your own user_id`).
+
+To search only what you captured via the bot, scope by chat title:
+
+```
+memex_search({ query: "...", chat: "Memex Bot" })
+```
+
+## What's captured
+
+| Input                 | Stored as                                                      |
+|-----------------------|----------------------------------------------------------------|
+| Text message          | `text` field, `from = "me"`                                    |
+| Forwarded message     | `↪ Forwarded from <X>:\n\n<text>` (so it's searchable via FTS5)|
+| Voice note (v0.2+)    | Nexara transcript prefixed with `🎙`; original OGG kept on disk|
+| Photos / documents    | _Not yet — acknowledged with a warning so you know._           |
+
+Idempotency is automatic: each message uses Telegram's stable `msg.id` and
+the `messages` table has `UNIQUE(source, conversation_id, msg_id)`. Restarts
+and re-emits are safe.
+
+## Setup
+
+### 1. Create a bot
+
+Talk to [@BotFather](https://t.me/BotFather) on Telegram:
+
+1. `/newbot`
+2. Give it a name (shown to you only) and a username (must end in `bot`).
+3. Save the **HTTP API token** BotFather gives you.
+
+### 2. Find your numeric Telegram user_id
+
+Talk to [@userinfobot](https://t.me/userinfobot) — it replies with your
+numeric `id`. Save it.
+
+### 3. Write `~/.memex/bot.config.json`
+
+```json
+{
+  "telegram_bot_token": "1234567890:ABCdef...",
+  "allowlist_user_ids": [123456789],
+  "voice_enabled": true,
+  "nexara_api_key": "nx-..."
+}
+```
+
+- `telegram_bot_token` — required.
+- `allowlist_user_ids` — required. Only these Telegram user_ids can talk to
+  the bot; everyone else gets a polite reject. The bot is single-user.
+- `nexara_api_key` — optional; only needed for voice transcription.
+- `voice_enabled` — defaults to `true` if `nexara_api_key` is set,
+  otherwise off. Set explicitly to `false` to disable even with a key.
+
+### 4. Run it
+
+Foreground (debug):
+```sh
+npx memex-bot
+```
+
+Or as a launchd autostart agent (macOS):
+```sh
+npx memex-bot install
+```
+
+Then send a test message to your bot. Within a few seconds:
+1. A JSON file appears in `~/.memex/inbox/`.
+2. The memex MCP server's inbox watcher imports it.
+3. It's searchable via `memex_search` and visible in `memex_recent`.
+
+### CLI
+
+```
+memex-bot                run foreground
+memex-bot install        register macOS LaunchAgent
+memex-bot uninstall      remove LaunchAgent (config preserved)
+memex-bot restart        reload after a config edit
+memex-bot status         show installed/running/offset/last-activity
+memex-bot logs           tail -f the bot log
+```
+
+## Bot commands
+
+| Command            | What it does                                            |
+|--------------------|---------------------------------------------------------|
+| `/help` or `/start`| Print usage                                             |
+| `/search <query>`  | Top-3 FTS5 matches across all memex sources             |
+| `/recent`          | 5 most recent captured messages, any source             |
+
+Anything else is captured as text. Unknown slash-commands are too — so a
+typo never silently swallows your thought.
+
+## Offline behavior
+
+**The bot is local-only — no cloud relay.** When your laptop is asleep or
+offline:
+
+- Telegram buffers updates ~24 hours server-side. The bot picks them up on
+  next poll.
+- For longer gaps, **export the bot chat from Telegram Desktop** and drop
+  the resulting `result.json` into `~/.memex/inbox/`. The `UNIQUE`
+  constraint dedupes against anything already captured, so it's safe to
+  re-import overlapping ranges.
+
+This is a deliberate design choice: cloud relays would break memex's
+local-first wedge for what amounts to a convenience feature. If you need
+guaranteed delivery for a 3-week trip, plan for the manual export step.
+
+## Files & paths
+
+| Thing                  | Path                                                            |
+|------------------------|-----------------------------------------------------------------|
+| Config                 | `~/.memex/bot.config.json`                                      |
+| Inbox JSONs            | `~/.memex/inbox/bot-<ts>-<msg_id>.json` → archived after import |
+| Voice OGGs             | `~/.memex/data/conversations/telegram/media/<msg_id>.oga`       |
+| Update offset state    | `~/.memex/data/bot-state.json`                                  |
+| Log                    | `~/.memex/data/bot.log`                                         |
+| LaunchAgent plist (mac)| `~/Library/LaunchAgents/com.parallelclaw.memex.bot.plist`       |
+
+## Architecture notes
+
+- **No webhook** — long-polling via `getUpdates` only. No public URL, no
+  HTTPS, no port forwarding. Works behind any NAT.
+- **No new ingest code path** — bot writes files; the existing inbox
+  watcher in `server.js` parses them.
+- **Read-only DB access** for `/search` and `/recent`. The bot opens
+  `memex.db` in `readonly` mode; WAL allows concurrent readers alongside
+  the running MCP server.
+- **No new dependencies.** Native `fetch` and `FormData` (Node 18+, which
+  memex already requires) handle Telegram and Nexara HTTP. `better-sqlite3`
+  was already in the parent `package.json`.
+
+## Out of scope (for now)
+
+- Webhook mode
+- Cloud relay / always-on infrastructure
+- Multi-user (bot serves exactly one TG user_id)
+- Rich UI inside bot (button-based memory browser)
+- LLM auto-summarization (would break memex's verbatim principle)
+- Tag/category system (FTS5 + recency boost is enough for discovery)
+- URL fetching (paste link → ingest cleaned HTML)
+- Periodic reminders ("you haven't captured anything in 7 days")

package/bot/config.js

@@ -0,0 +1,66 @@
+/**
+ * Bot config loader. Reads ~/.memex/bot.config.json (or $MEMEX_DIR/bot.config.json).
+ *
+ * Required:   telegram_bot_token, allowlist_user_ids[]
+ * Optional:   nexara_api_key, voice_enabled, inbox_path, media_path, db_path
+ *
+ * Voice support is auto-disabled if no nexara_api_key is set, regardless of
+ * the voice_enabled flag.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const HOME = homedir();
+const MEMEX_DIR = process.env.MEMEX_DIR || join(HOME, '.memex');
+export const BOT_CONFIG_PATH = join(MEMEX_DIR, 'bot.config.json');
+
+const EXAMPLE = `{
+  "telegram_bot_token": "<get from @BotFather>",
+  "allowlist_user_ids": [<your numeric Telegram user_id — get from @userinfobot>],
+  "voice_enabled": true,
+  "nexara_api_key": "nx-..."
+}`;
+
+export function loadBotConfig() {
+  if (!existsSync(BOT_CONFIG_PATH)) {
+    const err = new Error(
+      `bot config not found at ${BOT_CONFIG_PATH}\n\n` +
+      `Create it with:\n  ${BOT_CONFIG_PATH}\n\n` +
+      `Example contents:\n${EXAMPLE}`
+    );
+    err.code = 'NO_CONFIG';
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(BOT_CONFIG_PATH, 'utf-8'));
+  } catch (e) {
+    throw new Error(`failed to parse ${BOT_CONFIG_PATH}: ${e.message}`);
+  }
+
+  if (!parsed.telegram_bot_token || typeof parsed.telegram_bot_token !== 'string') {
+    throw new Error('bot.config.json: telegram_bot_token (string) is required');
+  }
+  if (!Array.isArray(parsed.allowlist_user_ids) || parsed.allowlist_user_ids.length === 0) {
+    throw new Error('bot.config.json: allowlist_user_ids[] (numeric TG user id(s)) is required');
+  }
+
+  const allowlist = parsed.allowlist_user_ids.map((x) => Number(x));
+  if (allowlist.some((x) => !Number.isFinite(x))) {
+    throw new Error('bot.config.json: allowlist_user_ids must be numbers');
+  }
+
+  const nexaraKey = parsed.nexara_api_key || null;
+  return {
+    telegram_bot_token: parsed.telegram_bot_token,
+    allowlist_user_ids: allowlist,
+    nexara_api_key: nexaraKey,
+    voice_enabled: parsed.voice_enabled !== false && !!nexaraKey,
+    inbox_path: parsed.inbox_path || join(MEMEX_DIR, 'inbox'),
+    media_path: parsed.media_path || join(MEMEX_DIR, 'data', 'conversations', 'telegram', 'media'),
+    db_path: parsed.db_path || join(MEMEX_DIR, 'data', 'memex.db'),
+    state_path: parsed.state_path || join(MEMEX_DIR, 'data', 'bot-state.json'),
+  };
+}

package/bot/inbox.js

@@ -0,0 +1,153 @@
+/**
+ * Build a minimal Telegram-Desktop-export JSON snippet for one captured
+ * message and write it atomically to the memex inbox.
+ *
+ * The shape mirrors what `importTelegram` (server.js) expects:
+ *   {
+ *     personal_information: { user_id: "<me>" },
+ *     chats: { list: [{ id, name, type, messages: [oneMsg] }] }
+ *   }
+ *
+ * One file per message. The conversation_id derived by the parser is
+ * `tg-<chat.id>`. We set chat.id to the string `memex-bot-<userId>` (NOT
+ * the bare Telegram user_id) so the resulting conversation_id is
+ * `tg-memex-bot-<userId>` — distinct from any real Telegram chat.id and,
+ * critically, distinct from "Saved Messages" exports (which Telegram
+ * Desktop emits with chat.id == your own user_id, so a synthetic prefix
+ * here is the only thing keeping the two streams from merging).
+ *
+ * Every captured message — typed, forwarded, voice-transcribed — lands
+ * in this same dedicated thread.
+ *
+ * Idempotency is automatic: each message uses Telegram's stable msg.id,
+ * and `messages` has UNIQUE(source, conversation_id, msg_id). Reprocessing
+ * the same update is a no-op at the DB layer.
+ */
+
+import { mkdirSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CHAT_NAME = 'Memex Bot';
+
+/**
+ * Write a single message to the inbox. Returns the absolute path written.
+ *
+ * @param {object} opts
+ * @param {string} opts.inboxPath  - directory to write into
+ * @param {number|string} opts.userId - the bot owner's Telegram user_id (becomes chat.id and from_id seed)
+ * @param {object} opts.message    - the constructed TG-export message object (id, type, date, date_unixtime, from, from_id, text, [forwarded_from], [media_path], …)
+ */
+export function writeInboxMessage({ inboxPath, userId, message }) {
+  if (!inboxPath) throw new Error('writeInboxMessage: inboxPath required');
+  if (userId === undefined || userId === null) throw new Error('writeInboxMessage: userId required');
+  if (!message || !message.id) throw new Error('writeInboxMessage: message.id required');
+
+  mkdirSync(inboxPath, { recursive: true });
+
+  const payload = {
+    personal_information: { user_id: String(userId) },
+    chats: {
+      list: [
+        {
+          // Synthetic chat.id keeps the bot thread separate from any real
+          // Telegram chat (including Saved Messages, which uses the bare
+          // user_id). Resulting conversation_id is `tg-memex-bot-<userId>`.
+          id: `memex-bot-${userId}`,
+          name: CHAT_NAME,
+          type: 'personal_chat',
+          messages: [message],
+        },
+      ],
+    },
+  };
+
+  const ts = parseInt(message.date_unixtime, 10) || Math.floor(Date.now() / 1000);
+  const fileName = `bot-${ts}-${message.id}.json`;
+  const targetPath = join(inboxPath, fileName);
+  const tmpPath = targetPath + '.tmp';
+
+  try {
+    writeFileSync(tmpPath, JSON.stringify(payload, null, 2));
+    renameSync(tmpPath, targetPath);
+  } catch (e) {
+    try { unlinkSync(tmpPath); } catch (_) {}
+    throw e;
+  }
+  return targetPath;
+}
+
+/**
+ * Convert a Telegram getUpdates `update.message` into the export-format
+ * message object expected by the parser.
+ *
+ * Forwards: prepend `↪ Forwarded from <name>:` to text so it's searchable
+ * via FTS5; also keep `forwarded_from` on the record for archival round-trip
+ * (parser ignores it but the JSON lives forever in ~/.memex/data/conversations).
+ *
+ * Voice: caller passes `textOverride` (the Nexara transcription) and
+ * `mediaPath` (where the OGG was saved).
+ *
+ * @param {object} opts
+ * @param {object} opts.tgMessage     - raw Telegram message
+ * @param {number|string} opts.userId - bot owner's user_id (used as from_id)
+ * @param {string} [opts.textOverride] - replace text (used for voice transcripts)
+ * @param {string} [opts.mediaPath]   - absolute path to saved media (informational)
+ */
+export function tgUpdateToExportMessage({ tgMessage, userId, textOverride, mediaPath }) {
+  const ts = tgMessage.date || Math.floor(Date.now() / 1000);
+  const isoDate = new Date(ts * 1000).toISOString().replace(/\.\d{3}Z$/, '');
+
+  const fwd = tgMessage.forward_from || tgMessage.forward_from_chat;
+  let forwardedName = null;
+  if (fwd) {
+    if (tgMessage.forward_from) {
+      const f = tgMessage.forward_from;
+      forwardedName = [f.first_name, f.last_name].filter(Boolean).join(' ') || f.username || `user${f.id}`;
+    } else {
+      const c = tgMessage.forward_from_chat;
+      forwardedName = c.title || c.username || `chat${c.id}`;
+    }
+  } else if (tgMessage.forward_sender_name) {
+    forwardedName = tgMessage.forward_sender_name;
+  }
+
+  // Resolve text payload from possible sources.
+  let text;
+  if (typeof textOverride === 'string') {
+    text = textOverride;
+  } else if (typeof tgMessage.text === 'string') {
+    text = tgMessage.text;
+  } else if (typeof tgMessage.caption === 'string') {
+    text = tgMessage.caption;
+  } else {
+    text = '';
+  }
+
+  if (forwardedName && text) {
+    text = `↪ Forwarded from ${forwardedName}:\n\n${text}`;
+  } else if (forwardedName && !text) {
+    text = `↪ Forwarded from ${forwardedName}: (no text)`;
+  }
+
+  const msg = {
+    id: tgMessage.message_id,
+    type: 'message',
+    date: isoDate,
+    date_unixtime: String(ts),
+    from: 'me',
+    from_id: `user${userId}`,
+    text,
+  };
+
+  if (forwardedName) {
+    msg.forwarded_from = forwardedName;
+  }
+  if (mediaPath) {
+    msg.media_path = mediaPath;
+    msg.media_type = 'voice_message';
+  }
+  if (tgMessage.reply_to_message?.message_id) {
+    msg.reply_to_message_id = tgMessage.reply_to_message.message_id;
+  }
+  return msg;
+}

package/bot/index.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * memex-bot — Telegram capture bot for memex.
+ *
+ * The bot is a separate process. It writes Telegram-Desktop-export-format
+ * JSON snippets into ~/.memex/inbox/, where memex's existing inbox watcher
+ * picks them up. Zero new ingest code path.
+ *
+ * CLI usage:
+ *   memex-bot                  # run in foreground (debug / launchctl ProgramArguments)
+ *   memex-bot serve            # explicit foreground (alias)
+ *   memex-bot install          # register macOS LaunchAgent (autostart on login)
+ *   memex-bot uninstall        # unload + remove LaunchAgent (config preserved)
+ *   memex-bot status           # show daemon state, last activity, offset
+ *   memex-bot logs             # tail -f the daemon log
+ *   memex-bot restart          # reload LaunchAgent after config edit
+ *
+ * Config:
+ *   ~/.memex/bot.config.json — token, allowlist, optional Nexara key
+ *
+ * Offline behavior:
+ *   When the laptop is off, Telegram buffers updates ~24h server-side and
+ *   the bot catches up on next poll. Beyond that, export the bot chat from
+ *   Telegram Desktop and drop result.json into ~/.memex/inbox/ — UNIQUE
+ *   constraint dedupes safely.
+ */
+
+import { homedir, platform } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync,
+  appendFileSync, statSync,
+} from 'node:fs';
+import { execSync, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { loadBotConfig, BOT_CONFIG_PATH } from './config.js';
+import { BotRunner } from './poll.js';
+
+const HOME = homedir();
+const MEMEX_DIR = process.env.MEMEX_DIR || join(HOME, '.memex');
+const DATA = join(MEMEX_DIR, 'data');
+const LOG_PATH = join(DATA, 'bot.log');
+
+const LAUNCH_LABEL = 'com.parallelclaw.memex.bot';
+const PLIST_PATH = join(HOME, 'Library', 'LaunchAgents', `${LAUNCH_LABEL}.plist`);
+
+mkdirSync(DATA, { recursive: true });
+
+function log(...args) {
+  const line = `[${new Date().toISOString()}] ${args.map(String).join(' ')}\n`;
+  process.stderr.write(line);
+  try { appendFileSync(LOG_PATH, line); } catch (_) {}
+}
+
+const subcommand = process.argv[2];
+
+if (subcommand === '--help' || subcommand === '-h') {
+  console.log(`memex-bot — Telegram capture bot for memex memory
+
+run modes:
+  memex-bot                  run in foreground (default; same as 'serve')
+  memex-bot serve            explicit foreground
+  memex-bot install          register macOS LaunchAgent (autostart on login)
+  memex-bot uninstall        unload and remove LaunchAgent (config preserved)
+  memex-bot restart          restart the LaunchAgent (after config changes)
+  memex-bot status           show daemon health, offset, last activity
+  memex-bot logs             tail the daemon log
+
+config:
+  ${BOT_CONFIG_PATH}
+
+paths:
+  log:   ${LOG_PATH}
+  plist: ${PLIST_PATH}`);
+  process.exit(0);
+}
+
+const handlers = {
+  install: cmdInstall,
+  uninstall: cmdUninstall,
+  status: cmdStatus,
+  logs: cmdLogs,
+  restart: cmdRestart,
+  serve: cmdServe,
+};
+
+if (subcommand && !subcommand.startsWith('-')) {
+  const handler = handlers[subcommand];
+  if (!handler) {
+    console.error(`unknown command: ${subcommand}`);
+    console.error(`usage: memex-bot [serve|install|uninstall|restart|status|logs]`);
+    process.exit(2);
+  }
+  handler();
+} else {
+  cmdServe();
+}
+
+// -------------------- CLI handlers --------------------
+
+function cmdServe() {
+  let config;
+  try { config = loadBotConfig(); }
+  catch (e) {
+    console.error(e.message);
+    process.exit(e.code === 'NO_CONFIG' ? 2 : 1);
+  }
+  const runner = new BotRunner({ config, log });
+
+  let shuttingDown = false;
+  function shutdown(sig) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    log(`received ${sig}, shutting down`);
+    runner.stop();
+    setTimeout(() => process.exit(0), 1500);
+  }
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+  log('memex-bot starting');
+  runner.start().catch((e) => {
+    log(`fatal: ${e.stack || e.message}`);
+    process.exit(1);
+  });
+}
+
+function cmdInstall() {
+  if (platform() !== 'darwin') {
+    console.error('install: macOS-only for now (LaunchAgent). Linux: nohup memex-bot &');
+    process.exit(1);
+  }
+
+  // Validate config exists before installing — otherwise the daemon would
+  // crashloop the moment launchd starts it.
+  try { loadBotConfig(); }
+  catch (e) {
+    console.error(`Cannot install — config not ready:\n\n${e.message}`);
+    process.exit(2);
+  }
+
+  const nodePath = process.execPath;
+  const scriptPath = resolve(fileURLToPath(import.meta.url));
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCH_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath}</string>
+    <string>${scriptPath}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ProcessType</key><string>Background</string>
+  <key>LowPriorityIO</key><true/>
+  <key>Nice</key><integer>5</integer>
+  <key>StandardOutPath</key><string>${join(DATA, 'bot.launchd.out.log')}</string>
+  <key>StandardErrorPath</key><string>${join(DATA, 'bot.launchd.err.log')}</string>
+  <key>WorkingDirectory</key><string>${resolve(scriptPath, '..', '..')}</string>
+</dict>
+</plist>
+`;
+
+  mkdirSync(join(HOME, 'Library', 'LaunchAgents'), { recursive: true });
+  try { execSync(`launchctl unload ${JSON.stringify(PLIST_PATH)}`, { stdio: 'ignore' }); } catch (_) {}
+  writeFileSync(PLIST_PATH, plist);
+  try {
+    execSync(`launchctl load ${JSON.stringify(PLIST_PATH)}`, { stdio: 'inherit' });
+  } catch (e) {
+    console.error(`launchctl load failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log(`✓ memex-bot installed and running`);
+  console.log(`  plist:   ${PLIST_PATH}`);
+  console.log(`  log:     ${LOG_PATH}`);
+  console.log(`  config:  ${BOT_CONFIG_PATH}`);
+  console.log('');
+  console.log(`Send a test message to your bot — it should appear in ~/.memex/inbox/`);
+  console.log(`within ~5s, then in memex.db within another ~2s.`);
+  console.log('');
+  console.log(`status: npx memex-bot status`);
+  console.log(`logs:   npx memex-bot logs`);
+  process.exit(0);
+}
+
+function cmdUninstall() {
+  if (platform() !== 'darwin') {
+    console.error('uninstall: macOS-only for now.');
+    process.exit(1);
+  }
+  if (!existsSync(PLIST_PATH)) {
+    console.log(`memex-bot was not installed (nothing to remove).`);
+    process.exit(0);
+  }
+  try { execSync(`launchctl unload ${JSON.stringify(PLIST_PATH)}`, { stdio: 'ignore' }); } catch (_) {}
+  try { unlinkSync(PLIST_PATH); } catch (_) {}
+  console.log(`✓ memex-bot uninstalled`);
+  console.log(`\nConfig preserved at ${BOT_CONFIG_PATH}.`);
+  console.log(`To reinstall: npx memex-bot install`);
+  process.exit(0);
+}
+
+function cmdRestart() {
+  if (platform() !== 'darwin') {
+    console.error('restart: macOS-only for now.');
+    process.exit(1);
+  }
+  if (!existsSync(PLIST_PATH)) {
+    console.error('memex-bot is not installed (no LaunchAgent plist found).');
+    console.error('Run: npx memex-bot install');
+    process.exit(1);
+  }
+  try { execSync(`launchctl unload ${JSON.stringify(PLIST_PATH)}`, { stdio: 'ignore' }); } catch (_) {}
+  try {
+    execSync(`launchctl load ${JSON.stringify(PLIST_PATH)}`, { stdio: 'ignore' });
+  } catch (e) {
+    console.error('launchctl load failed:', e.message);
+    process.exit(1);
+  }
+  console.log(`✓ memex-bot restarted`);
+  process.exit(0);
+}
+
+function cmdStatus() {
+  const installed = existsSync(PLIST_PATH);
+  let runningPid = null;
+  if (installed) {
+    try {
+      const out = execSync(`launchctl list | grep ${LAUNCH_LABEL}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+      const m = out.match(/^(\d+|-)\s+(\d+|-)\s+\S+/m);
+      if (m && m[1] !== '-') runningPid = parseInt(m[1], 10);
+    } catch (_) {}
+  }
+
+  console.log('memex-bot status\n');
+
+  if (installed) {
+    console.log(`  daemon:   installed (${PLIST_PATH})`);
+  } else {
+    console.log(`  daemon:   NOT installed`);
+    console.log(`            enable autostart with: memex-bot install`);
+  }
+  console.log(`  process:  ${runningPid ? `running (PID ${runningPid})` : 'not running'}`);
+
+  // Config probe
+  if (existsSync(BOT_CONFIG_PATH)) {
+    try {
+      const cfg = loadBotConfig();
+      console.log(`  config:   ✓ ${BOT_CONFIG_PATH}`);
+      console.log(`            allowlist: ${cfg.allowlist_user_ids.join(', ')}`);
+      console.log(`            voice:     ${cfg.voice_enabled ? 'enabled' : 'disabled'}`);
+      console.log(`            inbox:     ${cfg.inbox_path}`);
+    } catch (e) {
+      console.log(`  config:   ✗ ${BOT_CONFIG_PATH} — ${e.message.split('\n')[0]}`);
+    }
+  } else {
+    console.log(`  config:   ✗ missing at ${BOT_CONFIG_PATH}`);
+  }
+
+  // Offset state
+  let offsetInfo = '(none)';
+  let lastSeen = null;
+  try {
+    const cfg = existsSync(BOT_CONFIG_PATH) ? loadBotConfig() : null;
+    if (cfg && existsSync(cfg.state_path)) {
+      const s = JSON.parse(readFileSync(cfg.state_path, 'utf-8'));
+      offsetInfo = `last update_id: ${s.lastUpdateId}`;
+      const ageMs = Date.now() - statSync(cfg.state_path).mtimeMs;
+      const min = Math.floor(ageMs / 60000);
+      lastSeen = min < 1 ? 'just now' : (min < 60 ? `${min} min ago` : `${Math.floor(min / 60)}h ${min % 60}m ago`);
+    }
+  } catch (_) {}
+  console.log(`  state:    ${offsetInfo}`);
+  if (lastSeen) console.log(`  last activity: ${lastSeen}`);
+
+  console.log('');
+  console.log(`  log:      ${LOG_PATH}`);
+  process.exit(0);
+}
+
+function cmdLogs() {
+  if (!existsSync(LOG_PATH)) {
+    console.error(`no log file at ${LOG_PATH} — bot never started?`);
+    process.exit(1);
+  }
+  const tail = spawn('tail', ['-n', '50', '-f', LOG_PATH], { stdio: 'inherit' });
+  process.on('SIGINT', () => { tail.kill('SIGINT'); process.exit(0); });
+  tail.on('exit', (code) => process.exit(code || 0));
+}