@hasna/mementos 0.8.0 → 0.10.0

package/dist/cli/index.js

@@ -2520,7 +2520,30 @@ var init_database = __esm(() => {
   CREATE INDEX IF NOT EXISTS idx_webhook_hooks_type ON webhook_hooks(type);
   CREATE INDEX IF NOT EXISTS idx_webhook_hooks_enabled ON webhook_hooks(enabled);
   INSERT OR IGNORE INTO _migrations (id) VALUES (10);
-  `
+  `,
+    `
+CREATE TABLE IF NOT EXISTS session_memory_jobs (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  agent_id TEXT,
+  project_id TEXT,
+  source TEXT NOT NULL DEFAULT 'manual' CHECK(source IN ('claude-code','codex','manual','open-sessions')),
+  status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','processing','completed','failed')),
+  transcript TEXT NOT NULL,
+  chunk_count INTEGER NOT NULL DEFAULT 0,
+  memories_extracted INTEGER NOT NULL DEFAULT 0,
+  error TEXT,
+  metadata TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  started_at TEXT,
+  completed_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_session_memory_jobs_status ON session_memory_jobs(status);
+CREATE INDEX IF NOT EXISTS idx_session_memory_jobs_agent ON session_memory_jobs(agent_id);
+CREATE INDEX IF NOT EXISTS idx_session_memory_jobs_project ON session_memory_jobs(project_id);
+CREATE INDEX IF NOT EXISTS idx_session_memory_jobs_session ON session_memory_jobs(session_id);
+INSERT OR IGNORE INTO _migrations (id) VALUES (13);
+`
   ];
 });
 
@@ -6345,6 +6368,408 @@ var init_synthesis2 = __esm(() => {
   init_metrics();
 });
 
+// src/db/session-jobs.ts
+var exports_session_jobs = {};
+__export(exports_session_jobs, {
+  updateSessionJob: () => updateSessionJob,
+  listSessionJobs: () => listSessionJobs,
+  getSessionJob: () => getSessionJob,
+  getNextPendingJob: () => getNextPendingJob,
+  createSessionJob: () => createSessionJob
+});
+function parseJobRow(row) {
+  return {
+    id: row["id"],
+    session_id: row["session_id"],
+    agent_id: row["agent_id"] || null,
+    project_id: row["project_id"] || null,
+    source: row["source"],
+    status: row["status"],
+    transcript: row["transcript"],
+    chunk_count: row["chunk_count"],
+    memories_extracted: row["memories_extracted"],
+    error: row["error"] || null,
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    created_at: row["created_at"],
+    started_at: row["started_at"] || null,
+    completed_at: row["completed_at"] || null
+  };
+}
+function createSessionJob(input, db) {
+  const d = db || getDatabase();
+  const id = uuid();
+  const timestamp = now();
+  const source = input.source ?? "manual";
+  const metadata = JSON.stringify(input.metadata ?? {});
+  d.run(`INSERT INTO session_memory_jobs
+      (id, session_id, agent_id, project_id, source, status, transcript, chunk_count, memories_extracted, metadata, created_at)
+     VALUES (?, ?, ?, ?, ?, 'pending', ?, 0, 0, ?, ?)`, [
+    id,
+    input.session_id,
+    input.agent_id ?? null,
+    input.project_id ?? null,
+    source,
+    input.transcript,
+    metadata,
+    timestamp
+  ]);
+  return getSessionJob(id, d);
+}
+function getSessionJob(id, db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT * FROM session_memory_jobs WHERE id = ?").get(id);
+  if (!row)
+    return null;
+  return parseJobRow(row);
+}
+function listSessionJobs(filter, db) {
+  const d = db || getDatabase();
+  const conditions = [];
+  const params = [];
+  if (filter?.agent_id) {
+    conditions.push("agent_id = ?");
+    params.push(filter.agent_id);
+  }
+  if (filter?.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filter.project_id);
+  }
+  if (filter?.status) {
+    conditions.push("status = ?");
+    params.push(filter.status);
+  }
+  if (filter?.session_id) {
+    conditions.push("session_id = ?");
+    params.push(filter.session_id);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = filter?.limit ?? 20;
+  const offset = filter?.offset ?? 0;
+  const rows = d.query(`SELECT * FROM session_memory_jobs ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`).all(...params, limit, offset);
+  return rows.map(parseJobRow);
+}
+function updateSessionJob(id, updates, db) {
+  const d = db || getDatabase();
+  const setClauses = [];
+  const params = [];
+  if (updates.status !== undefined) {
+    setClauses.push("status = ?");
+    params.push(updates.status);
+  }
+  if (updates.chunk_count !== undefined) {
+    setClauses.push("chunk_count = ?");
+    params.push(updates.chunk_count);
+  }
+  if (updates.memories_extracted !== undefined) {
+    setClauses.push("memories_extracted = ?");
+    params.push(updates.memories_extracted);
+  }
+  if ("error" in updates) {
+    setClauses.push("error = ?");
+    params.push(updates.error ?? null);
+  }
+  if ("started_at" in updates) {
+    setClauses.push("started_at = ?");
+    params.push(updates.started_at ?? null);
+  }
+  if ("completed_at" in updates) {
+    setClauses.push("completed_at = ?");
+    params.push(updates.completed_at ?? null);
+  }
+  if (setClauses.length === 0)
+    return getSessionJob(id, d);
+  params.push(id);
+  d.run(`UPDATE session_memory_jobs SET ${setClauses.join(", ")} WHERE id = ?`, params);
+  return getSessionJob(id, d);
+}
+function getNextPendingJob(db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT * FROM session_memory_jobs WHERE status = 'pending' ORDER BY created_at ASC LIMIT 1").get();
+  if (!row)
+    return null;
+  return parseJobRow(row);
+}
+var init_session_jobs = __esm(() => {
+  init_database();
+});
+
+// src/lib/session-processor.ts
+function chunkTranscript(transcript, chunkSize = 2000, overlap = 200) {
+  if (!transcript || transcript.length === 0)
+    return [];
+  if (transcript.length <= chunkSize)
+    return [transcript];
+  const chunks = [];
+  let start = 0;
+  while (start < transcript.length) {
+    const end = Math.min(start + chunkSize, transcript.length);
+    chunks.push(transcript.slice(start, end));
+    if (end === transcript.length)
+      break;
+    start += chunkSize - overlap;
+  }
+  return chunks;
+}
+async function extractMemoriesFromChunk(chunk, context, db) {
+  const provider = providerRegistry.getAvailable();
+  if (!provider)
+    return 0;
+  try {
+    const extracted = await provider.extractMemories(SESSION_EXTRACTION_USER_TEMPLATE(chunk, context.sessionId), {
+      sessionId: context.sessionId,
+      agentId: context.agentId,
+      projectId: context.projectId
+    });
+    let savedCount = 0;
+    const sourceTag = context.source ? `source:${context.source}` : "source:manual";
+    for (const memory of extracted) {
+      if (!memory.content || !memory.content.trim())
+        continue;
+      try {
+        createMemory({
+          key: memory.content.slice(0, 120).replace(/\s+/g, "-").toLowerCase(),
+          value: memory.content,
+          category: memory.category,
+          scope: memory.suggestedScope ?? "shared",
+          importance: memory.importance,
+          tags: [
+            ...memory.tags,
+            "session-extracted",
+            sourceTag,
+            `session:${context.sessionId}`
+          ],
+          source: "auto",
+          agent_id: context.agentId,
+          project_id: context.projectId,
+          session_id: context.sessionId,
+          metadata: {
+            auto_extracted: true,
+            session_source: context.source ?? "manual",
+            extracted_at: new Date().toISOString(),
+            reasoning: memory.reasoning
+          }
+        }, "merge", db);
+        savedCount++;
+      } catch {}
+    }
+    return savedCount;
+  } catch {
+    try {
+      const fallbacks = providerRegistry.getFallbacks();
+      for (const fallback of fallbacks) {
+        try {
+          const extracted = await fallback.extractMemories(SESSION_EXTRACTION_USER_TEMPLATE(chunk, context.sessionId), {
+            sessionId: context.sessionId,
+            agentId: context.agentId,
+            projectId: context.projectId
+          });
+          let savedCount = 0;
+          const sourceTag = context.source ? `source:${context.source}` : "source:manual";
+          for (const memory of extracted) {
+            if (!memory.content || !memory.content.trim())
+              continue;
+            try {
+              createMemory({
+                key: memory.content.slice(0, 120).replace(/\s+/g, "-").toLowerCase(),
+                value: memory.content,
+                category: memory.category,
+                scope: memory.suggestedScope ?? "shared",
+                importance: memory.importance,
+                tags: [
+                  ...memory.tags,
+                  "session-extracted",
+                  sourceTag,
+                  `session:${context.sessionId}`
+                ],
+                source: "auto",
+                agent_id: context.agentId,
+                project_id: context.projectId,
+                session_id: context.sessionId,
+                metadata: {
+                  auto_extracted: true,
+                  session_source: context.source ?? "manual",
+                  extracted_at: new Date().toISOString(),
+                  reasoning: memory.reasoning
+                }
+              }, "merge", db);
+              savedCount++;
+            } catch {}
+          }
+          if (savedCount > 0)
+            return savedCount;
+        } catch {
+          continue;
+        }
+      }
+    } catch {}
+    return 0;
+  }
+}
+async function processSessionJob(jobId, db) {
+  const result = {
+    jobId,
+    chunksProcessed: 0,
+    memoriesExtracted: 0,
+    errors: []
+  };
+  let job;
+  try {
+    job = getSessionJob(jobId, db);
+    if (!job) {
+      result.errors.push(`Job not found: ${jobId}`);
+      return result;
+    }
+  } catch (e) {
+    result.errors.push(`Failed to fetch job: ${String(e)}`);
+    return result;
+  }
+  try {
+    updateSessionJob(jobId, { status: "processing", started_at: new Date().toISOString() }, db);
+  } catch (e) {
+    result.errors.push(`Failed to mark job as processing: ${String(e)}`);
+    return result;
+  }
+  const chunks = chunkTranscript(job.transcript);
+  try {
+    updateSessionJob(jobId, { chunk_count: chunks.length }, db);
+  } catch {}
+  let totalMemories = 0;
+  for (let i = 0;i < chunks.length; i++) {
+    const chunk = chunks[i];
+    try {
+      const count = await extractMemoriesFromChunk(chunk, {
+        sessionId: job.session_id,
+        agentId: job.agent_id ?? undefined,
+        projectId: job.project_id ?? undefined,
+        source: job.source
+      }, db);
+      totalMemories += count;
+      result.chunksProcessed++;
+    } catch (e) {
+      result.errors.push(`Chunk ${i} failed: ${String(e)}`);
+    }
+  }
+  result.memoriesExtracted = totalMemories;
+  try {
+    if (result.errors.length > 0 && result.chunksProcessed === 0) {
+      updateSessionJob(jobId, {
+        status: "failed",
+        error: result.errors.join("; "),
+        completed_at: new Date().toISOString(),
+        memories_extracted: totalMemories,
+        chunk_count: chunks.length
+      }, db);
+    } else {
+      updateSessionJob(jobId, {
+        status: "completed",
+        completed_at: new Date().toISOString(),
+        memories_extracted: totalMemories,
+        chunk_count: chunks.length
+      }, db);
+    }
+  } catch (e) {
+    result.errors.push(`Failed to update job status: ${String(e)}`);
+  }
+  return result;
+}
+var SESSION_EXTRACTION_USER_TEMPLATE = (chunk, sessionId) => `Extract memories from this session chunk (session: ${sessionId}):
+
+${chunk}
+
+Return JSON array: [{"key": "...", "value": "...", "category": "knowledge|fact|preference|history", "importance": 1-10, "tags": [...]}]`;
+var init_session_processor = __esm(() => {
+  init_memories();
+  init_registry();
+  init_session_jobs();
+});
+
+// src/lib/session-queue.ts
+var exports_session_queue = {};
+__export(exports_session_queue, {
+  startSessionQueueWorker: () => startSessionQueueWorker,
+  getSessionQueueStats: () => getSessionQueueStats,
+  enqueueSessionJob: () => enqueueSessionJob
+});
+function enqueueSessionJob(jobId) {
+  _pendingQueue.add(jobId);
+  if (!_isProcessing) {
+    _processNext();
+  }
+}
+function getSessionQueueStats() {
+  try {
+    const db = getDatabase();
+    const rows = db.query("SELECT status, COUNT(*) as count FROM session_memory_jobs GROUP BY status").all();
+    const stats = {
+      pending: 0,
+      processing: 0,
+      completed: 0,
+      failed: 0
+    };
+    for (const row of rows) {
+      if (row.status === "pending")
+        stats.pending = row.count;
+      else if (row.status === "processing")
+        stats.processing = row.count;
+      else if (row.status === "completed")
+        stats.completed = row.count;
+      else if (row.status === "failed")
+        stats.failed = row.count;
+    }
+    return stats;
+  } catch {
+    return {
+      pending: _pendingQueue.size,
+      processing: _isProcessing ? 1 : 0,
+      completed: 0,
+      failed: 0
+    };
+  }
+}
+function startSessionQueueWorker() {
+  if (_workerStarted)
+    return;
+  _workerStarted = true;
+  setInterval(() => {
+    _processNext();
+  }, 5000);
+}
+async function _processNext() {
+  if (_isProcessing)
+    return;
+  let jobId;
+  if (_pendingQueue.size > 0) {
+    jobId = [..._pendingQueue][0];
+    _pendingQueue.delete(jobId);
+  } else {
+    try {
+      const job = getNextPendingJob();
+      if (job)
+        jobId = job.id;
+    } catch {
+      return;
+    }
+  }
+  if (!jobId)
+    return;
+  _isProcessing = true;
+  try {
+    await processSessionJob(jobId);
+  } catch {} finally {
+    _isProcessing = false;
+    if (_pendingQueue.size > 0) {
+      _processNext();
+    }
+  }
+}
+var _pendingQueue, _isProcessing = false, _workerStarted = false;
+var init_session_queue = __esm(() => {
+  init_database();
+  init_session_jobs();
+  init_session_processor();
+  _pendingQueue = new Set;
+});
+
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
@@ -7018,6 +7443,236 @@ function resolveKeyOrId(keyOrId, opts, globalOpts) {
   return null;
 }
 program2.name("mementos").description("Universal memory system for AI agents").version(getPackageVersion()).option("--project <path>", "Project path for scoping").option("--json", "Output as JSON").option("--format <fmt>", "Output format: compact, json, csv, yaml").option("--agent <name>", "Agent name or ID").option("--session <id>", "Session ID");
+program2.command("init").description("One-command setup: register MCP, install stop hook, configure auto-start").action(async () => {
+  const { platform } = process;
+  const home = homedir2();
+  const isMac = platform === "darwin";
+  console.log("");
+  console.log(chalk.bold("  mementos \u2014 setting up your memory layer"));
+  console.log("");
+  async function run(cmd) {
+    try {
+      const proc = Bun.spawn(cmd, {
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      const [out, err, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited
+      ]);
+      return { ok: exitCode === 0, output: (out + err).trim() };
+    } catch (e) {
+      return { ok: false, output: e instanceof Error ? e.message : String(e) };
+    }
+  }
+  let mcpAlreadyInstalled = false;
+  let mcpError = null;
+  try {
+    const list = await run(["claude", "mcp", "list"]);
+    if (list.output.includes("mementos")) {
+      mcpAlreadyInstalled = true;
+    } else {
+      const add = await run([
+        "claude",
+        "mcp",
+        "add",
+        "--transport",
+        "stdio",
+        "--scope",
+        "user",
+        "mementos",
+        "--",
+        "mementos-mcp"
+      ]);
+      if (!add.ok) {
+        mcpError = add.output || "unknown error";
+      }
+    }
+  } catch (e) {
+    mcpError = e instanceof Error ? e.message : String(e);
+  }
+  if (mcpAlreadyInstalled) {
+    console.log(chalk.dim("  \xB7 MCP already registered"));
+  } else if (mcpError) {
+    console.log(chalk.red(`  \u2717 Failed to register MCP: ${mcpError}`));
+    console.log(chalk.dim("    (Is Claude Code installed? Try: claude mcp add --transport stdio --scope user mementos -- mementos-mcp)"));
+  } else {
+    console.log(chalk.green("  \u2713 MCP server registered with Claude Code"));
+  }
+  const hooksDir = join3(home, ".claude", "hooks");
+  const hookDest = join3(hooksDir, "mementos-stop-hook.ts");
+  const settingsPath = join3(home, ".claude", "settings.json");
+  const hookCommand = `bun ${hookDest}`;
+  let hookAlreadyInstalled = false;
+  let hookError = null;
+  try {
+    let settings = {};
+    if (existsSync3(settingsPath)) {
+      try {
+        settings = JSON.parse(readFileSync2(settingsPath, "utf-8"));
+      } catch {
+        settings = {};
+      }
+    }
+    const hooksObj = settings["hooks"] || {};
+    const stopHooks = hooksObj["Stop"] || [];
+    const alreadyHasMementos = stopHooks.some((entry) => entry.hooks?.some((h) => h.command && h.command.includes("mementos")));
+    if (alreadyHasMementos) {
+      hookAlreadyInstalled = true;
+    } else {
+      if (!existsSync3(hooksDir)) {
+        mkdirSync3(hooksDir, { recursive: true });
+      }
+      if (!existsSync3(hookDest)) {
+        const packageDir = dirname3(dirname3(fileURLToPath(import.meta.url)));
+        const candidatePaths = [
+          join3(packageDir, "scripts", "hooks", "claude-stop-hook.ts"),
+          join3(packageDir, "..", "scripts", "hooks", "claude-stop-hook.ts"),
+          join3(home, ".bun", "install", "global", "node_modules", "@hasna", "mementos", "scripts", "hooks", "claude-stop-hook.ts")
+        ];
+        let hookSourceFound = false;
+        for (const src of candidatePaths) {
+          if (existsSync3(src)) {
+            copyFileSync(src, hookDest);
+            hookSourceFound = true;
+            break;
+          }
+        }
+        if (!hookSourceFound) {
+          const inlineHook = `#!/usr/bin/env bun
+const MEMENTOS_URL = process.env["MEMENTOS_URL"] ?? "http://localhost:19428";
+const MEMENTOS_AGENT = process.env["MEMENTOS_AGENT"];
+
+async function main() {
+  let stdinData = "";
+  try {
+    for await (const chunk of Bun.stdin.stream()) {
+      stdinData += new TextDecoder().decode(chunk);
+    }
+  } catch { /* stdin may be closed */ }
+
+  if (!stdinData.trim()) return;
+
+  let payload: unknown;
+  try { payload = JSON.parse(stdinData); } catch { return; }
+
+  try {
+    await fetch(\`\${MEMENTOS_URL}/api/sessions/ingest\`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        transcript: payload,
+        agent: MEMENTOS_AGENT,
+        source: "claude-stop-hook",
+      }),
+      signal: AbortSignal.timeout(5000),
+    });
+  } catch { /* server not running \u2014 silently skip */ }
+}
+
+main().catch(() => {});
+`;
+          writeFileSync2(hookDest, inlineHook, "utf-8");
+        }
+      }
+      const newStopEntry = {
+        matcher: "",
+        hooks: [{ type: "command", command: hookCommand }]
+      };
+      hooksObj["Stop"] = [...stopHooks, newStopEntry];
+      settings["hooks"] = hooksObj;
+      writeFileSync2(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+    }
+  } catch (e) {
+    hookError = e instanceof Error ? e.message : String(e);
+  }
+  if (hookAlreadyInstalled) {
+    console.log(chalk.dim("  \xB7 Stop hook already installed"));
+  } else if (hookError) {
+    console.log(chalk.red(`  \u2717 Failed to install stop hook: ${hookError}`));
+  } else {
+    console.log(chalk.green("  \u2713 Stop hook installed (sessions \u2192 memories)"));
+  }
+  let autoStartAlreadyInstalled = false;
+  let autoStartError = null;
+  if (!isMac) {
+    console.log(chalk.dim(`  \xB7 Auto-start skipped (not macOS \u2014 platform: ${platform})`));
+  } else {
+    const plistPath = join3(home, "Library", "LaunchAgents", "com.hasna.mementos.plist");
+    const plistContent = `<?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>com.hasna.mementos</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>-c</string>
+    <string>PATH="$HOME/.bun/bin:$PATH" mementos-serve</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardErrorPath</key>
+  <string>/tmp/mementos.log</string>
+  <key>StandardOutPath</key>
+  <string>/tmp/mementos.log</string>
+</dict>
+</plist>
+`;
+    try {
+      if (existsSync3(plistPath)) {
+        autoStartAlreadyInstalled = true;
+      } else {
+        const launchAgentsDir = join3(home, "Library", "LaunchAgents");
+        if (!existsSync3(launchAgentsDir)) {
+          mkdirSync3(launchAgentsDir, { recursive: true });
+        }
+        writeFileSync2(plistPath, plistContent, "utf-8");
+      }
+    } catch (e) {
+      autoStartError = e instanceof Error ? e.message : String(e);
+    }
+    if (autoStartAlreadyInstalled) {
+      console.log(chalk.dim("  \xB7 Auto-start already configured"));
+    } else if (autoStartError) {
+      console.log(chalk.red(`  \u2717 Failed to configure auto-start: ${autoStartError}`));
+    } else {
+      console.log(chalk.green("  \u2713 Auto-start configured (starts on login)"));
+    }
+    if (!autoStartAlreadyInstalled && !autoStartError) {
+      const plistPath2 = join3(home, "Library", "LaunchAgents", "com.hasna.mementos.plist");
+      const loadResult = await run(["launchctl", "load", plistPath2]);
+      if (!loadResult.ok) {
+        console.log(chalk.dim(`  \xB7 launchctl load: ${loadResult.output || "already loaded"}`));
+      }
+    }
+  }
+  let serverRunning = false;
+  try {
+    const res = await fetch("http://127.0.0.1:19428/api/health", {
+      signal: AbortSignal.timeout(1500)
+    });
+    serverRunning = res.ok;
+  } catch {}
+  if (serverRunning) {
+    console.log(chalk.green("  \u2713 Server running on http://127.0.0.1:19428"));
+  } else {
+    console.log(chalk.dim("  \xB7 Server not yet running \u2014 it will start automatically on next login"));
+    console.log(chalk.dim("    (Or start it now: mementos-serve)"));
+  }
+  console.log("");
+  console.log(chalk.bold("  You're all set. Restart Claude Code to activate."));
+  console.log("");
+  console.log("  Quick start:");
+  console.log(`    ${chalk.cyan('mementos save "my-preference" "I prefer bun over npm"')}`);
+  console.log(`    ${chalk.cyan("mementos list")}`);
+  console.log(`    ${chalk.cyan("mementos doctor")}`);
+  console.log("");
+});
 program2.command("save <key> <value>").description("Save a memory (create or upsert)").option("-c, --category <cat>", "Category: preference, fact, knowledge, history").option("-s, --scope <scope>", "Scope: global, shared, private").option("--importance <n>", "Importance 1-10", parseInt).option("--tags <tags>", "Comma-separated tags").option("--summary <text>", "Brief summary").option("--ttl <duration>", "Time-to-live: 30s, 5m, 2h, 1d, 1w, or milliseconds").option("--source <src>", "Source: user, agent, system, auto, imported").option("--template <name>", "Apply a template: correction, preference, decision, learning").action((key, value, opts) => {
   try {
     const globalOpts = program2.opts();
@@ -7696,7 +8351,7 @@ program2.command("clean").description("Remove expired memories and enforce quota
     handleError(e);
   }
 });
-program2.command("init <name>").description("Register an agent (returns ID)").option("-d, --description <text>", "Agent description").option("-r, --role <role>", "Agent role").option("-p, --project <id>", "Lock agent to a project (sets active_project_id)").action((name, opts) => {
+program2.command("register-agent <name>").alias("init-agent").description("Register an agent (returns ID)").option("-d, --description <text>", "Agent description").option("-r, --role <role>", "Agent role").option("-p, --project <id>", "Lock agent to a project (sets active_project_id)").action((name, opts) => {
   try {
     const globalOpts = program2.opts();
     const agent = registerAgent(name, undefined, opts.description, opts.role, opts.project);
@@ -8139,6 +8794,51 @@ program2.command("doctor").description("Diagnose common issues with the mementos
   } catch {
     checks.push({ name: "REST server", status: "warn", detail: "Could not check REST server" });
   }
+  try {
+    const mcpProc = Bun.spawn(["claude", "mcp", "list"], { stdout: "pipe", stderr: "pipe" });
+    const [mcpOut, , mcpExit] = await Promise.all([
+      new Response(mcpProc.stdout).text(),
+      new Response(mcpProc.stderr).text(),
+      mcpProc.exited
+    ]);
+    if (mcpExit === 0 && mcpOut.includes("mementos")) {
+      checks.push({ name: "MCP server", status: "ok", detail: "registered with Claude Code" });
+    } else if (mcpExit !== 0) {
+      checks.push({ name: "MCP server", status: "warn", detail: "claude not installed or not accessible" });
+    } else {
+      checks.push({ name: "MCP server", status: "warn", detail: "not registered  \u2192  run: mementos init" });
+    }
+  } catch {
+    checks.push({ name: "MCP server", status: "warn", detail: "could not check (is claude CLI installed?)" });
+  }
+  try {
+    const settingsFilePath = join3(homedir2(), ".claude", "settings.json");
+    if (existsSync3(settingsFilePath)) {
+      const settings = JSON.parse(readFileSync2(settingsFilePath, "utf-8"));
+      const hooksObj = settings["hooks"] || {};
+      const stopHooks = hooksObj["Stop"] || [];
+      const hasMementos = stopHooks.some((e) => e.hooks?.some((h) => h.command && h.command.includes("mementos")));
+      checks.push({
+        name: "Stop hook",
+        status: hasMementos ? "ok" : "warn",
+        detail: hasMementos ? "installed (sessions \u2192 memories)" : "not installed  \u2192  run: mementos init"
+      });
+    } else {
+      checks.push({ name: "Stop hook", status: "warn", detail: "~/.claude/settings.json not found  \u2192  run: mementos init" });
+    }
+  } catch {
+    checks.push({ name: "Stop hook", status: "warn", detail: "could not check stop hook" });
+  }
+  if (process.platform === "darwin") {
+    const plistFilePath = join3(homedir2(), "Library", "LaunchAgents", "com.hasna.mementos.plist");
+    checks.push({
+      name: "Auto-start",
+      status: existsSync3(plistFilePath) ? "ok" : "warn",
+      detail: existsSync3(plistFilePath) ? "configured (starts on login)" : "not configured  \u2192  run: mementos init"
+    });
+  } else {
+    checks.push({ name: "Auto-start", status: "ok", detail: `n/a on ${process.platform}` });
+  }
   outputDoctorResults(globalOpts, checks);
 });
 function outputDoctorResults(globalOpts, checks) {
@@ -8993,7 +9693,7 @@ function diffLines(oldText, newText) {
   }
 }
 program2.command("completions <shell>").description("Output shell completion script (bash, zsh, fish)").action((shell) => {
-  const commands = "save recall list update forget search stats export import clean inject context pin unpin archive versions stale doctor tail diff init agents projects bulk completions config backup restore report profile mcp";
+  const commands = "init setup save recall list update forget search stats export import clean inject context pin unpin archive versions stale doctor tail diff register-agent agents projects bulk completions config backup restore report profile mcp";
   const commandList = commands.split(" ");
   switch (shell.toLowerCase()) {
     case "bash": {
@@ -9039,7 +9739,8 @@ compdef _mementos mementos`);
         doctor: "Check database health",
         tail: "Watch recent memories",
         diff: "Show memory changes",
-        init: "Initialize a new database",
+        init: "One-command onboarding setup (MCP + hook + auto-start)",
+        "register-agent": "Register an agent (returns ID)",
         agents: "Manage agents",
         projects: "Manage projects",
         bulk: "Bulk operations",
@@ -9993,4 +10694,86 @@ synthesisCmd.command("rollback <runId>").description("Roll back a synthesis run"
     console.log(chalk.red(`  Errors: ${result.errors.join(", ")}`));
   }
 });
+var sessionCmd = program2.command("session").description("Session auto-memory \u2014 ingest session transcripts for memory extraction");
+sessionCmd.command("ingest <transcriptFile>").description("Ingest a session transcript file for memory extraction").option("--session-id <id>", "Session ID (default: auto-generated)").option("--agent <id>", "Agent ID").option("--project <id>", "Project ID").option("--source <source>", "Source (claude-code, codex, manual, open-sessions)", "manual").action(async (transcriptFile, opts) => {
+  const { readFileSync: readFileSync3 } = await import("fs");
+  const { createSessionJob: createSessionJob2 } = await Promise.resolve().then(() => (init_session_jobs(), exports_session_jobs));
+  const { enqueueSessionJob: enqueueSessionJob2 } = await Promise.resolve().then(() => (init_session_queue(), exports_session_queue));
+  const transcript = readFileSync3(transcriptFile, "utf-8");
+  const sessionId = opts.sessionId ?? `cli-${Date.now()}`;
+  const job = createSessionJob2({
+    session_id: sessionId,
+    transcript,
+    source: opts.source,
+    agent_id: opts.agent,
+    project_id: opts.project
+  });
+  enqueueSessionJob2(job.id);
+  console.log(chalk.green(`\u2713 Session queued: ${chalk.cyan(job.id)}`));
+  console.log(`  Session: ${sessionId}`);
+  console.log(`  Length:  ${transcript.length} chars`);
+});
+sessionCmd.command("status <jobId>").description("Check status of a session extraction job").action(async (jobId) => {
+  const { getSessionJob: getSessionJob2 } = await Promise.resolve().then(() => (init_session_jobs(), exports_session_jobs));
+  const job = getSessionJob2(jobId);
+  if (!job) {
+    console.error(chalk.red(`Job not found: ${jobId}`));
+    process.exit(1);
+  }
+  const statusColor = job.status === "completed" ? chalk.green : job.status === "failed" ? chalk.red : chalk.yellow;
+  console.log(`${chalk.cyan(job.id)} [${statusColor(job.status)}]`);
+  console.log(`  Session:   ${job.session_id}`);
+  console.log(`  Chunks:    ${job.chunk_count}`);
+  console.log(`  Extracted: ${job.memories_extracted} memories`);
+  if (job.error)
+    console.log(chalk.red(`  Error: ${job.error}`));
+});
+sessionCmd.command("list").description("List session extraction jobs").option("--agent <id>", "Filter by agent").option("--project <id>", "Filter by project").option("--status <status>", "Filter by status").option("--limit <n>", "Max results", "20").action(async (opts) => {
+  const { listSessionJobs: listSessionJobs2 } = await Promise.resolve().then(() => (init_session_jobs(), exports_session_jobs));
+  const jobs = listSessionJobs2({
+    agent_id: opts.agent,
+    project_id: opts.project,
+    status: opts.status,
+    limit: parseInt(opts.limit)
+  });
+  if (jobs.length === 0) {
+    console.log(chalk.gray("No session jobs found."));
+    return;
+  }
+  for (const job of jobs) {
+    const statusColor = job.status === "completed" ? chalk.green : job.status === "failed" ? chalk.red : chalk.yellow;
+    console.log(`${chalk.cyan(job.id.slice(0, 8))} [${statusColor(job.status)}] ${job.memories_extracted} memories | ${job.created_at.slice(0, 10)}`);
+  }
+});
+sessionCmd.command("setup-hook").description("Install mementos session hook into Claude Code or Codex").option("--claude", "Install Claude Code stop hook").option("--codex", "Install Codex session hook").option("--show", "Print hook script instead of installing").action(async (opts) => {
+  const { resolve: resolve4 } = await import("path");
+  const hookPath = resolve4(import.meta.dirname, "../../scripts/hooks");
+  if (opts.claude) {
+    const script = `${hookPath}/claude-stop-hook.ts`;
+    if (opts.show) {
+      const { readFileSync: readFileSync3 } = await import("fs");
+      console.log(readFileSync3(script, "utf-8"));
+      return;
+    }
+    console.log(chalk.bold("Claude Code stop hook installation:"));
+    console.log("");
+    console.log("Add to your .claude/settings.json:");
+    console.log(chalk.cyan(JSON.stringify({
+      hooks: {
+        Stop: [{ matcher: "", hooks: [{ type: "command", command: `bun ${script}` }] }]
+      }
+    }, null, 2)));
+    console.log("");
+    console.log(`Or run: ${chalk.cyan(`claude hooks add Stop "bun ${script}"`)}`);
+  } else if (opts.codex) {
+    const script = `${hookPath}/codex-stop-hook.ts`;
+    console.log(chalk.bold("Codex session hook installation:"));
+    console.log("");
+    console.log("Add to ~/.codex/config.toml:");
+    console.log(chalk.cyan(`[hooks]
+session_end = "bun ${script}"`));
+  } else {
+    console.log("Usage: mementos session setup-hook --claude | --codex");
+  }
+});
 program2.parse(process.argv);