@hasna/mementos 0.9.0 → 0.10.0

package/README.md

@@ -8,8 +8,11 @@ Agents save, recall, search, and share memories across sessions. Memories are sc
 
 ```bash
 bun add -g @hasna/mementos
+mementos init
 ```
 
+That's it. `init` registers the MCP with Claude Code, installs the session stop hook, and configures the server to start automatically on login.
+
 ## Quick Start
 
 ```bash
@@ -27,6 +30,9 @@ mementos inject --format compact --project-id <id>
 
 # Get stats
 mementos stats
+
+# Check everything is working
+mementos doctor
 ```
 
 ## MCP Server
@@ -34,6 +40,10 @@ mementos stats
 ### Install into Claude Code (recommended)
 
 ```bash
+# One-command setup (MCP + stop hook + auto-start):
+mementos init
+
+# Or just the MCP server:
 mementos mcp --claude
 # Or manually:
 claude mcp add --transport stdio --scope user mementos -- mementos-mcp

package/dist/cli/index.js

@@ -7443,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();
@@ -8121,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);
@@ -8564,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) {
@@ -9418,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": {
@@ -9464,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",

package/dist/mcp/index.js

@@ -11124,7 +11124,33 @@ server.tool("memory_session_list", "List session memory extraction jobs.", {
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
   }
 });
+async function ensureRestServerRunning() {
+  try {
+    const res = await fetch("http://127.0.0.1:19428/api/memories?limit=0", {
+      signal: AbortSignal.timeout(500)
+    });
+    if (res.ok || res.status === 200)
+      return;
+  } catch {}
+  const proc = Bun.spawn(["mementos-serve"], {
+    detached: true,
+    stdout: Bun.file("/tmp/mementos.log"),
+    stderr: Bun.file("/tmp/mementos.log")
+  });
+  proc.unref();
+  for (let i = 0;i < 6; i++) {
+    await new Promise((r) => setTimeout(r, 500));
+    try {
+      const res = await fetch("http://127.0.0.1:19428/api/memories?limit=0", {
+        signal: AbortSignal.timeout(400)
+      });
+      if (res.ok || res.status === 200)
+        return;
+    } catch {}
+  }
+}
 async function main() {
+  await ensureRestServerRunning();
   loadWebhooksFromDb();
   const transport = new StdioServerTransport;
   await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/mementos",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Universal memory system for AI agents - CLI + MCP server + library API",
   "type": "module",
   "main": "dist/index.js",