parallelclaw 1.0.0

package/lib/config.js

@@ -0,0 +1,220 @@
+/**
+ * memex configuration: ~/.memex/config.json
+ *
+ * Schema:
+ *   {
+ *     sources: {
+ *       claude_code:   true | false,
+ *       claude_cowork: true | false,
+ *       cursor:        true | false,
+ *       obsidian: true | false | { enabled: bool, vaults: string[] }
+ *     }
+ *   }
+ *
+ * Behavior:
+ *   - File missing → defaults below (everything ON if its data exists). Preserves
+ *     backward compat for users who installed before config was a thing.
+ *   - File present but partial → merged with defaults.
+ *   - Env var MEMEX_OBSIDIAN_VAULTS overrides config.sources.obsidian.vaults
+ *     (useful for cron/scripts without touching the file).
+ *
+ * CLI source names accept both "claude-code" and "claude_code" forms;
+ * normalizeSourceName() canonicalises to underscore (matches JSON keys).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+
+const HOME = homedir();
+const MEMEX_DIR = process.env.MEMEX_DIR || join(HOME, '.memex');
+export const CONFIG_PATH = join(MEMEX_DIR, 'config.json');
+
+export const KNOWN_SOURCES = ['claude_code', 'claude_cowork', 'cursor', 'obsidian', 'openclaw'];
+
+/** What the daemon does when no config file exists — preserve current behavior. */
+export const DEFAULT_CONFIG = Object.freeze({
+  sources: {
+    claude_code: true,
+    claude_cowork: true,
+    cursor: true,
+    obsidian: { enabled: true, vaults: [] }, // empty vaults → autodetect
+    openclaw: true, // v0.10.14+: auto-capture from ~/.openclaw/agents/main/sessions/
+  },
+  search: {
+    // Half-life in days for the temporal recency boost in memex_search.
+    // Score = bm25 * exp(-age_days / half_life). 30d ≈ recent week dominates,
+    // month-old halved, 3-month-old in long tail. Set to 0 to disable.
+    half_life_days: 30,
+  },
+});
+
+/**
+ * Origin = this node's identity stamped onto every LOCALLY-captured row
+ * (v0.14 provenance). Sanitised to [a-z0-9-] (max 24) so callers may bake it
+ * into prepared SQL as a literal. Resolution order:
+ *   1. MEMEX_ORIGIN env (tests, plugins, one-off overrides)
+ *   2. config.json `origin` (set once; users rename their node here)
+ *   3. short hostname — derived AND persisted, so a later hostname change
+ *      doesn't silently fork the node's identity.
+ * Rows arriving via SYNC keep the origin they were stamped with at capture —
+ * never the local one. Pre-provenance rows stay NULL ("unknown era").
+ */
+export function sanitizeOrigin(value) {
+  const s = String(value || '').split('.')[0].toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24);
+  return s || null;
+}
+
+export function getOrigin(config) {
+  const fromEnv = sanitizeOrigin(process.env.MEMEX_ORIGIN);
+  if (fromEnv) return fromEnv;
+  const cfg = config || loadConfig();
+  const fromCfg = sanitizeOrigin(cfg.origin);
+  if (fromCfg) return fromCfg;
+  const derived = sanitizeOrigin(hostname()) || 'node';
+  cfg.origin = derived;
+  try { saveConfig(cfg); } catch (_) { /* read-only env — still usable */ }
+  return derived;
+}
+
+/** Returns the configured default half-life (days) for recency boost. 0 disables. */
+export function getSearchHalfLifeDays(config) {
+  const v = config && config.search && config.search.half_life_days;
+  if (typeof v !== 'number' || !isFinite(v) || v < 0) return 30;
+  return v;
+}
+
+/**
+ * Normalise a CLI source name. Accepts "claude-code", "claude_code", "code"
+ * (alias), "cowork" (alias). Returns canonical name or null.
+ */
+export function normalizeSourceName(input) {
+  if (!input) return null;
+  const s = String(input).toLowerCase().replace(/-/g, '_');
+  const aliases = {
+    code: 'claude_code',
+    cowork: 'claude_cowork',
+  };
+  const canonical = aliases[s] || s;
+  return KNOWN_SOURCES.includes(canonical) ? canonical : null;
+}
+
+export function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) return clone(DEFAULT_CONFIG);
+  let raw;
+  try { raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); }
+  catch (_) { return clone(DEFAULT_CONFIG); }
+  return mergeWithDefaults(raw, DEFAULT_CONFIG);
+}
+
+export function saveConfig(config) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  const tmp = CONFIG_PATH + '.tmp';
+  writeFileSync(tmp, JSON.stringify(config, null, 2));
+  renameSync(tmp, CONFIG_PATH);
+}
+
+/**
+ * Is a given named source enabled?
+ *   - boolean → that
+ *   - object with .enabled → that
+ *   - undefined → default-on
+ */
+export function isSourceEnabled(name, config) {
+  const v = config.sources && config.sources[name];
+  if (v === undefined || v === null) return true;
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'object' && 'enabled' in v) return !!v.enabled;
+  return true;
+}
+
+/** Mutate config to set source enabled/disabled. Preserves nested structure for obsidian. */
+export function setSourceEnabled(name, enabled, config) {
+  if (!config.sources) config.sources = {};
+  const existing = config.sources[name];
+  if (typeof existing === 'object' && existing !== null) {
+    existing.enabled = !!enabled;
+  } else {
+    config.sources[name] = !!enabled;
+  }
+}
+
+/** Get configured Obsidian vault list (config + env var). Returns absolute paths. */
+export function obsidianVaultsFromConfig(config) {
+  const out = [];
+  const fromConfig = config.sources && config.sources.obsidian;
+  if (fromConfig && typeof fromConfig === 'object' && Array.isArray(fromConfig.vaults)) {
+    for (const v of fromConfig.vaults) out.push(expandTilde(v));
+  }
+  const fromEnv = (process.env.MEMEX_OBSIDIAN_VAULTS || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map(expandTilde);
+  // Dedup, env wins
+  return [...new Set([...fromEnv, ...out])];
+}
+
+export function addObsidianVault(path, config) {
+  const abs = resolve(expandTilde(path));
+  if (!config.sources) config.sources = {};
+  if (!config.sources.obsidian || typeof config.sources.obsidian !== 'object') {
+    config.sources.obsidian = { enabled: true, vaults: [] };
+  }
+  if (!Array.isArray(config.sources.obsidian.vaults)) {
+    config.sources.obsidian.vaults = [];
+  }
+  if (!config.sources.obsidian.vaults.includes(abs)) {
+    config.sources.obsidian.vaults.push(abs);
+  }
+  return abs;
+}
+
+export function removeObsidianVault(path, config) {
+  const abs = resolve(expandTilde(path));
+  const obs = config.sources && config.sources.obsidian;
+  if (!obs || typeof obs !== 'object' || !Array.isArray(obs.vaults)) return false;
+  const before = obs.vaults.length;
+  obs.vaults = obs.vaults.filter((v) => resolve(expandTilde(v)) !== abs);
+  return obs.vaults.length !== before;
+}
+
+// -------------------- Internal helpers --------------------
+function clone(o) {
+  return JSON.parse(JSON.stringify(o));
+}
+
+function mergeWithDefaults(parsed, defaults) {
+  const out = clone(defaults);
+  if (!parsed || typeof parsed !== 'object') return out;
+  if (parsed.sources && typeof parsed.sources === 'object') {
+    for (const key of KNOWN_SOURCES) {
+      if (key in parsed.sources) out.sources[key] = parsed.sources[key];
+    }
+  }
+  if (parsed.search && typeof parsed.search === 'object') {
+    if (typeof parsed.search.half_life_days === 'number') {
+      out.search.half_life_days = parsed.search.half_life_days;
+    }
+  }
+  // v0.11.11 experimental sync — passthrough whatever lives under "sync".
+  // The lib/sync/config.js module owns the shape and defaults; we just
+  // make sure round-tripping the file doesn't drop it on the floor.
+  if (parsed.sync && typeof parsed.sync === 'object') {
+    out.sync = parsed.sync;
+  }
+  // v0.14 provenance — this node's identity (see getOrigin). A plain string
+  // key; must survive load/save round-trips or the node forks identity.
+  if (typeof parsed.origin === 'string' && parsed.origin) {
+    out.origin = parsed.origin;
+  }
+  return out;
+}
+
+function expandTilde(p) {
+  if (!p) return p;
+  if (p === '~' || p === '~/') return HOME;
+  if (p.startsWith('~/')) return join(HOME, p.slice(2));
+  return p;
+}

package/lib/db-init.js

@@ -0,0 +1,158 @@
+/**
+ * Schema-init for memex.db, factored out of server.js so the daemon
+ * (memex-sync install) and any other entry point can create the DB
+ * idempotently before the MCP server is ever spawned.
+ *
+ * Why: on a clean machine the MCP server is the first writer that opens
+ * the DB. If a user runs `memex-sync install` + `memex-sync scan` then
+ * tries `memex overview` BEFORE restarting their MCP client, the CLI
+ * (which opens the DB in read-only mode) errors with "memex.db not
+ * found". Fix: have the daemon initialise the DB at install-time —
+ * empty tables, but openable.
+ *
+ * Public:
+ *   initializeDb(dbPath) → Database
+ *      Opens the DB (creating the file if missing), runs every migration
+ *      in the right order, and returns the better-sqlite3 handle. Caller
+ *      is responsible for closing it.
+ *
+ * Idempotent — safe to call against an existing DB with content. Every
+ * CREATE / ALTER / DROP+CREATE is wrapped to swallow "already exists"
+ * style errors.
+ */
+
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import Database from 'better-sqlite3';
+
+/**
+ * Create or open ~/.memex/data/memex.db, apply all schema migrations,
+ * return the handle. Same code path that server.js used to run inline
+ * — extracted so memex-sync (and tests, and tooling) can run it too.
+ */
+export function initializeDb(dbPath) {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+
+  // Base tables + indices + FTS5 virtual table. CREATE IF NOT EXISTS
+  // makes this safe against existing DBs.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS messages (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      source          TEXT NOT NULL,
+      conversation_id TEXT NOT NULL,
+      msg_id          TEXT,
+      role            TEXT,
+      sender          TEXT,
+      text            TEXT,
+      ts              INTEGER,
+      metadata        TEXT,
+      UNIQUE(source, conversation_id, msg_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_messages_ts ON messages(ts);
+    CREATE INDEX IF NOT EXISTS idx_messages_conv ON messages(conversation_id);
+    CREATE INDEX IF NOT EXISTS idx_messages_source ON messages(source);
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+      text, sender, conversation_id, source,
+      content=messages, content_rowid=id,
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
+    CREATE TABLE IF NOT EXISTS conversations (
+      conversation_id TEXT PRIMARY KEY,
+      source          TEXT NOT NULL,
+      title           TEXT,
+      first_ts        INTEGER,
+      last_ts         INTEGER,
+      message_count   INTEGER DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS imports (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_name       TEXT,
+      source          TEXT,
+      imported_at     INTEGER,
+      message_count   INTEGER
+    );
+  `);
+
+  // ALTER-style migrations — these run idempotently by swallowing the
+  // "duplicate column" error. Same set + same order as server.js.
+  const safeAlter = (sql) => {
+    try { db.exec(sql); }
+    catch (err) {
+      if (!String(err.message).includes('duplicate column name')) throw err;
+    }
+  };
+  safeAlter(`ALTER TABLE conversations ADD COLUMN archived_at INTEGER`);
+  safeAlter(`ALTER TABLE conversations ADD COLUMN parent_conversation_id TEXT`);
+  safeAlter(`ALTER TABLE conversations ADD COLUMN project_path TEXT`);
+  safeAlter(`ALTER TABLE conversations ADD COLUMN pending_parent_uuid TEXT`);
+  safeAlter(`ALTER TABLE messages ADD COLUMN edited_at INTEGER`);
+  safeAlter(`ALTER TABLE messages ADD COLUMN uuid TEXT`);
+  // v0.11 — channel-aware routing for OpenClaw + future multi-channel sources.
+  // Values used today:
+  //   'telegram'    — Telegram message captured via OpenClaw (or native TG export)
+  //   'kimi-web'    — Kimi web chat through OpenClaw
+  //   'system'      — OpenClaw's own diagnostic / Exec output
+  //   NULL          — channel not detected / source has no channel concept
+  //                   (Claude Code, Cowork, Cursor, Obsidian — all NULL)
+  safeAlter(`ALTER TABLE messages ADD COLUMN channel TEXT`);
+  // v0.14 — provenance: WHICH NODE captured this row. Stamped at capture time
+  // (lib/config.js getOrigin — sanitised hostname / config `origin`), carried
+  // verbatim over sync like `channel`. NULL = pre-provenance era or unknown.
+  // In a synced mesh, two nodes' captures can share source AND conversation_id
+  // (e.g. two OpenClaw instances bridging the same Telegram account) — origin
+  // is the only way to tell whose row it is. See SYNC.md backlog #6.
+  safeAlter(`ALTER TABLE messages ADD COLUMN origin TEXT`);
+
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_parent ON conversations(parent_conversation_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_project
+             ON conversations(project_path) WHERE project_path IS NOT NULL`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_messages_uuid
+             ON messages(uuid) WHERE uuid IS NOT NULL`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_messages_channel
+             ON messages(channel) WHERE channel IS NOT NULL`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_messages_origin
+             ON messages(origin) WHERE origin IS NOT NULL`);
+
+  // Pre-0.4 imports tables could have duplicate rows from re-running the
+  // server. Collapse before installing the UNIQUE index.
+  db.exec(`
+    DELETE FROM imports
+     WHERE id NOT IN (
+       SELECT MAX(id) FROM imports GROUP BY file_name, source, message_count
+     )
+  `);
+  db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_imports_unique
+             ON imports(file_name, source, message_count)`);
+
+  // FTS5 triggers (rewritten 0.6) — exclude role IN ('boundary','summary')
+  // from messages_fts so synthetic compaction summaries don't double-count
+  // against the original raw turns. Drop+create is idempotent.
+  db.exec(`
+    DROP TRIGGER IF EXISTS messages_fts_ai;
+    DROP TRIGGER IF EXISTS messages_fts_ad;
+    DROP TRIGGER IF EXISTS messages_fts_au;
+    CREATE TRIGGER messages_fts_ai AFTER INSERT ON messages
+      WHEN new.role NOT IN ('boundary', 'summary')
+    BEGIN
+      INSERT INTO messages_fts(rowid, text, sender, conversation_id, source)
+      VALUES (new.id, new.text, new.sender, new.conversation_id, new.source);
+    END;
+    CREATE TRIGGER messages_fts_ad AFTER DELETE ON messages BEGIN
+      DELETE FROM messages_fts WHERE rowid = old.id;
+    END;
+    CREATE TRIGGER messages_fts_au AFTER UPDATE ON messages BEGIN
+      DELETE FROM messages_fts WHERE rowid = old.id;
+      INSERT INTO messages_fts(rowid, text, sender, conversation_id, source)
+        SELECT new.id, new.text, new.sender, new.conversation_id, new.source
+         WHERE new.role NOT IN ('boundary', 'summary');
+    END;
+  `);
+
+  return db;
+}

package/lib/hook/install.js

@@ -0,0 +1,268 @@
+/**
+ * Claude Code SessionStart hook installer for memex auto-context.
+ *
+ * When the user opens a new Claude Code session, Claude Code looks at
+ * ~/.claude/settings.json for `hooks.SessionStart` entries and runs each
+ * command before showing the user the first prompt. The stdout of those
+ * commands gets injected into Claude's context as a system message.
+ *
+ * Memex's hook calls `memex context` which outputs a markdown summary of
+ * recent memex activity relevant to the current pwd. End result: Claude
+ * "knows" what you were doing in this project without you having to ask.
+ *
+ * Idempotency: install operations are safe to re-run. We detect our entry
+ * by command-string match — if any SessionStart hook command starts with
+ * MEMEX_COMMAND_MARKER, we treat it as ours and don't add another.
+ *
+ * Atomicity: we always write to a .tmp file first, then rename. Never
+ * touch the user's existing hooks for other tools.
+ *
+ * Cross-client: only Claude Code and OpenClaw have SessionStart natively.
+ * For Cursor, fallback strategies (MCP resource, skills,
+ * system prompt) are tracked separately — not part of this module.
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  existsSync,
+  mkdirSync,
+} from 'node:fs';
+import { execSync } from 'node:child_process';
+
+const HOME = homedir();
+const CLAUDE_DIR = join(HOME, '.claude');
+const SETTINGS_PATH = join(CLAUDE_DIR, 'settings.json');
+
+// Command marker — every memex hook command starts with this. Used to
+// detect our own entry for idempotency / uninstall, without collision
+// risk against other tools' hooks (gstack, custom user hooks, etc.).
+const MEMEX_COMMAND_MARKER = 'memex context';
+
+/**
+ * Returns the absolute path to the `memex` binary that should be used in
+ * the hook command. Tries multiple strategies in order:
+ *   1. `which memex` (npm-global install)
+ *   2. process.execPath + this module's known location (current invocation)
+ *   3. fallback to bare "memex" (relies on PATH at hook execution time)
+ *
+ * Returns the resolved path string.
+ */
+export function resolveMemexBinPath() {
+  try {
+    const which = execSync('which memex', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (which && existsSync(which)) return which;
+  } catch (_) {}
+  // Fallback: rely on PATH at hook-execution time. Claude Code loads
+  // user shell environment for hooks, so PATH usually works.
+  return 'memex';
+}
+
+/**
+ * Read ~/.claude/settings.json safely. Returns:
+ *   { exists: bool, valid: bool, data: object, raw: string|null }
+ */
+export function readSettings() {
+  if (!existsSync(SETTINGS_PATH)) {
+    return { exists: false, valid: true, data: {}, raw: null };
+  }
+  try {
+    const raw = readFileSync(SETTINGS_PATH, 'utf-8');
+    const data = JSON.parse(raw);
+    return { exists: true, valid: true, data, raw };
+  } catch (e) {
+    return {
+      exists: true,
+      valid: false,
+      data: {},
+      raw: null,
+      error: e.message,
+    };
+  }
+}
+
+/**
+ * Find our memex SessionStart hook entry in the parsed settings.
+ * Returns { found: bool, index: number, command: string|null }.
+ *
+ * Claude Code's hooks schema (as of 2026):
+ *   settings.hooks.SessionStart = [
+ *     { matcher: "...", hooks: [{ type: "command", command: "..." }] }
+ *   ]
+ *
+ * We treat an outer entry as "ours" if any of its inner hooks has a
+ * command string containing MEMEX_COMMAND_MARKER.
+ */
+export function findMemexHookEntry(settings) {
+  const sessionStart = settings?.hooks?.SessionStart;
+  if (!Array.isArray(sessionStart)) {
+    return { found: false, index: -1, command: null };
+  }
+  for (let i = 0; i < sessionStart.length; i++) {
+    const entry = sessionStart[i];
+    const inner = entry?.hooks;
+    if (!Array.isArray(inner)) continue;
+    for (const h of inner) {
+      if (typeof h?.command === 'string' && h.command.includes(MEMEX_COMMAND_MARKER)) {
+        return { found: true, index: i, command: h.command };
+      }
+    }
+  }
+  return { found: false, index: -1, command: null };
+}
+
+/**
+ * Add the memex SessionStart hook entry to ~/.claude/settings.json.
+ *
+ * Idempotent: if a memex entry already exists, no-op (returns
+ * alreadyPresent: true). If the user has OTHER SessionStart hooks (e.g.
+ * from gstack), they are preserved untouched — we only append our entry
+ * to the array.
+ *
+ * Returns:
+ *   { installed: bool, alreadyPresent: bool, settingsPath: str,
+ *     command: str, error: str|null }
+ */
+export function installHook(opts = {}) {
+  const binPath = opts.binPath || resolveMemexBinPath();
+  const command = `${binPath} context`;
+
+  const settings = readSettings();
+  if (settings.exists && !settings.valid) {
+    return {
+      installed: false,
+      alreadyPresent: false,
+      settingsPath: SETTINGS_PATH,
+      command,
+      error: `Could not parse ${SETTINGS_PATH}: ${settings.error}. Fix the file manually first.`,
+    };
+  }
+
+  const data = settings.data || {};
+  const existing = findMemexHookEntry(data);
+  if (existing.found) {
+    return {
+      installed: false,
+      alreadyPresent: true,
+      settingsPath: SETTINGS_PATH,
+      command: existing.command,
+      error: null,
+    };
+  }
+
+  // Build our entry. Use ".*" matcher (match any session) and the standard
+  // {type: "command", command: ...} inner hook shape.
+  const memexEntry = {
+    matcher: '.*',
+    hooks: [{ type: 'command', command }],
+  };
+
+  // Defensive nested-set: never clobber adjacent keys
+  if (!data.hooks) data.hooks = {};
+  if (!Array.isArray(data.hooks.SessionStart)) data.hooks.SessionStart = [];
+  data.hooks.SessionStart.push(memexEntry);
+
+  // Atomic write — temp file + rename
+  try {
+    mkdirSync(CLAUDE_DIR, { recursive: true });
+    const tmpPath = SETTINGS_PATH + '.tmp';
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    renameSync(tmpPath, SETTINGS_PATH);
+  } catch (e) {
+    return {
+      installed: false,
+      alreadyPresent: false,
+      settingsPath: SETTINGS_PATH,
+      command,
+      error: `Failed to write ${SETTINGS_PATH}: ${e.message}`,
+    };
+  }
+
+  return {
+    installed: true,
+    alreadyPresent: false,
+    settingsPath: SETTINGS_PATH,
+    command,
+    error: null,
+  };
+}
+
+/**
+ * Remove the memex SessionStart hook entry. Preserves all other hooks.
+ *
+ * Returns: { removed: bool, wasPresent: bool, error: str|null }
+ */
+export function uninstallHook() {
+  const settings = readSettings();
+  if (!settings.exists) {
+    return { removed: false, wasPresent: false, error: null };
+  }
+  if (!settings.valid) {
+    return {
+      removed: false,
+      wasPresent: false,
+      error: `Could not parse ${SETTINGS_PATH}: ${settings.error}`,
+    };
+  }
+
+  const data = settings.data;
+  const existing = findMemexHookEntry(data);
+  if (!existing.found) {
+    return { removed: false, wasPresent: false, error: null };
+  }
+
+  // Remove our entry from the SessionStart array
+  data.hooks.SessionStart.splice(existing.index, 1);
+
+  // Cleanup empty containers — don't leave behind `hooks: {SessionStart: []}`
+  // detritus if memex was the only hook.
+  if (data.hooks.SessionStart.length === 0) delete data.hooks.SessionStart;
+  if (data.hooks && Object.keys(data.hooks).length === 0) delete data.hooks;
+
+  try {
+    const tmpPath = SETTINGS_PATH + '.tmp';
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    renameSync(tmpPath, SETTINGS_PATH);
+  } catch (e) {
+    return {
+      removed: false,
+      wasPresent: true,
+      error: `Failed to write ${SETTINGS_PATH}: ${e.message}`,
+    };
+  }
+
+  return { removed: true, wasPresent: true, error: null };
+}
+
+/**
+ * Inspect current hook status. Returns:
+ *   { installed: bool, settingsPath: str, command: str|null,
+ *     otherSessionStartHooks: number, settingsExists: bool,
+ *     settingsValid: bool }
+ */
+export function getHookStatus() {
+  const settings = readSettings();
+  const result = {
+    installed: false,
+    settingsPath: SETTINGS_PATH,
+    command: null,
+    otherSessionStartHooks: 0,
+    settingsExists: settings.exists,
+    settingsValid: settings.valid,
+  };
+  if (!settings.exists || !settings.valid) return result;
+
+  const sessionStart = settings.data?.hooks?.SessionStart || [];
+  const found = findMemexHookEntry(settings.data);
+  result.installed = found.found;
+  result.command = found.command;
+  result.otherSessionStartHooks = found.found
+    ? sessionStart.length - 1
+    : sessionStart.length;
+  return result;
+}
+
+export { MEMEX_COMMAND_MARKER, SETTINGS_PATH };