memex-mvp 0.10.8 → 0.10.10

package/ingest.js

@@ -293,6 +293,21 @@ async function cmdInstall() {
   console.log('');
   console.log(`config: ${CONFIG_PATH} (auto-created on first edit)`);
   console.log(`status: npx memex-sync status`);
+
+  // v0.10.10: surface the new web dashboard so manual installers actually
+  // discover it. (curl-bash flow has its own [Y/n] prompt in install.sh —
+  // it suppresses this output via `>/dev/null 2>&1`, so this callout is
+  // for the `memex-sync install` direct-call path only.)
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('🌐 NEW in v0.10.8: open your memory in a browser');
+  console.log('');
+  console.log('  memex web --open');
+  console.log('');
+  console.log('5 pages, read-only, localhost-only. Every captured');
+  console.log('conversation, verbatim — not summarized. Ctrl+C to stop.');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
   process.exit(0);
 }
 

package/lib/cli/index.js

@@ -150,20 +150,41 @@ function maybePrintTelegramTip(opts = {}, currentSubcommand = '') {
 async function afterCommand(opts = {}, currentSubcommand = '') {
   if (opts.json) return;
   if (currentSubcommand === 'telegram') return;
+  if (currentSubcommand === 'web') return;     // web command holds the loop; tip would never print anyway
+  // `context` output IS the SessionStart hook payload — it gets injected
+  // verbatim into Claude Code's session header. Tips would corrupt that
+  // (and bust the --budget-tokens cap that the hook contract relies on).
+  if (currentSubcommand === 'context') return;
   if (process.env.MEMEX_TIP_SUPPRESS === '1') return;
   try {
-    const { listPending } = await import('../telegram-pending.js');
-    const list = listPending();
-    if (!list || list.length === 0) return;
     const notify = await import('../telegram-notify.js');
     const state = notify.loadNotifyState();
-    if (!notify.cliTipDue(state)) return;
-    const showTitles = state.notifications.show_titles !== false;
-    const tip = notify.formatTelegramTip(list, { showTitles });
-    if (tip) {
-      console.log(tip);
-      notify.markCliTipShown(state);
-      notify.saveNotifyState(state);
+
+    // Channel B priority: TG-pending tip first (it's actionable — there's
+    // a real export waiting). Dashboard tip is "nice to know", so only
+    // show it when the TG channel has nothing to surface.
+    const { listPending } = await import('../telegram-pending.js');
+    const list = listPending();
+    const hasPending = list && list.length > 0;
+
+    if (hasPending && notify.cliTipDue(state)) {
+      const showTitles = state.notifications.show_titles !== false;
+      const tip = notify.formatTelegramTip(list, { showTitles });
+      if (tip) {
+        console.log(tip);
+        notify.markCliTipShown(state);
+        notify.saveNotifyState(state);
+        return;
+      }
+    }
+
+    if (!hasPending && notify.dashboardTipDue(state)) {
+      const tip = notify.formatDashboardTip();
+      if (tip) {
+        console.log(c.dim(tip));
+        notify.markDashboardTipShown(state);
+        notify.saveNotifyState(state);
+      }
     }
   } catch (_) {
     /* never break a command because of a tip */
@@ -1707,7 +1728,10 @@ Examples:
   memex web --port 9000                  custom port
   memex web --public --token s3cret      bind on 0.0.0.0 with bearer auth
 `);
-      return;
+      // Help path: exit cleanly so the caller (server.js) doesn't fall through
+      // to MCP-mode init, and Node doesn't warn about an unsettled top-level
+      // await waiting on an HTTP server that was never started.
+      process.exit(0);
     }
     else if (a.startsWith('--')) {
       console.error(`Unknown flag: ${a}`);
@@ -1734,7 +1758,24 @@ Examples:
 
   const { startServer } = await import('../web/index.js');
   await startServer(opts);
-  // startServer keeps the process alive on its own http server.
+
+  // First successful start ever → silence the discovery tip forever.
+  // User has clearly found the feature; no need to keep nagging.
+  try {
+    const notify = await import('../telegram-notify.js');
+    const state = notify.loadNotifyState();
+    if (!state.dashboard_ever_opened) {
+      notify.markDashboardEverOpened(state);
+      notify.saveNotifyState(state);
+    }
+  } catch (_) { /* never break server start on notify-state write */ }
+
+  // The HTTP server now holds the event loop open. Park on an unsettled
+  // promise so cmdWeb never returns to the dispatcher — that way server.js
+  // doesn't reach process.exit(0) below or fall through to MCP-mode init.
+  // (Required because `await runCli(...)` would otherwise resolve as soon
+  // as startServer's listen-callback fires.)
+  await new Promise(() => {});
 }
 
 // =============================================================

package/lib/telegram-notify.js

@@ -47,6 +47,13 @@ const DEFAULT_STATE = () => ({
   version: 1,
   cli_tip_last_shown_at: null,
   notif_shown_for_ids: [],
+  // v0.10.10: dashboard discovery throttle. Three-strike pattern so the tip
+  // appears on a few different terminal sessions in the first days after
+  // install, then quiets down. Becomes permanently silent once the user
+  // actually opens the dashboard at least once.
+  dashboard_tip_shown_count: 0,
+  dashboard_tip_last_shown_at: null,
+  dashboard_ever_opened: false,
   notifications: {
     enabled: false,    // privacy-first: opt-in for macOS notification
     show_titles: false, // even when on, don't leak chat names by default
@@ -105,6 +112,49 @@ export function markCliTipShown(state, now = new Date()) {
   return state;
 }
 
+// ---------------------- Dashboard discovery tip (v0.10.10) ----------------------
+
+/**
+ * Whether the "try memex web" tip should fire on the next CLI command.
+ *
+ *   - Hard-stop once the user has actually run `memex web` (any duration)
+ *   - Cap at maxShows (default 3) total reveals
+ *   - Cooldown cooldownHours (default 12) between reveals so it doesn't
+ *     stack with the TG-pending tip on the same minute
+ */
+export function dashboardTipDue(state, opts = {}) {
+  const { maxShows = 3, cooldownHours = 12 } = opts;
+  if (state.dashboard_ever_opened) return false;
+  if ((state.dashboard_tip_shown_count || 0) >= maxShows) return false;
+  if (!state.dashboard_tip_last_shown_at) return true;
+  const last = Date.parse(state.dashboard_tip_last_shown_at);
+  if (isNaN(last)) return true;
+  return Date.now() - last >= cooldownHours * ONE_HOUR_MS;
+}
+
+export function markDashboardTipShown(state, now = new Date()) {
+  state.dashboard_tip_shown_count = (state.dashboard_tip_shown_count || 0) + 1;
+  state.dashboard_tip_last_shown_at = now.toISOString();
+  return state;
+}
+
+/**
+ * Permanently silence the dashboard tip — call this the first time the user
+ * actually runs `memex web`. They've discovered it; no need to keep nagging.
+ */
+export function markDashboardEverOpened(state) {
+  state.dashboard_ever_opened = true;
+  return state;
+}
+
+/**
+ * The tip text itself. Plain string (no ANSI) — the caller decides whether
+ * to dim it. Returns null if there is genuinely nothing to say (defensive).
+ */
+export function formatDashboardTip() {
+  return '💡 New: try `memex web --open` — browse your memory in a browser (read-only, localhost only).';
+}
+
 // ---------------------- Notification dedup ----------------------
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memex-mvp",
-  "version": "0.10.8",
+  "version": "0.10.10",
   "description": "Local-first MCP server for cross-agent AI memory. One SQLite + FTS5 corpus across Claude Code, Cowork, Cursor, Continue, Zed, Obsidian, and Telegram — passively captured, verbatim, searchable from any MCP-compatible client.",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -64,31 +64,23 @@ import { runCli, CLI_SUBCOMMAND_NAMES } from './lib/cli/index.js';
 //
 // This runs BEFORE any DB/watcher side-effects so the CLI doesn't open
 // the DB in write mode unnecessarily.
-// We use a labelled async IIFE so we can `break` (or just fall through)
-// without abusing top-level `return`, which is illegal in ESM modules.
 {
   const sub = process.argv[2];
   if (sub && CLI_SUBCOMMAND_NAMES.includes(sub)) {
+    // For long-running subs (currently only `web`), cmdWeb parks on an
+    // unsettled promise after starting the HTTP server, so this `await`
+    // never resolves and process.exit below is never reached. For one-shot
+    // subs (search, recent, telegram, …), runCli returns and we exit here.
     await runCli(sub, process.argv.slice(3));
-    // 'web' is a long-running server — exiting here would kill it the moment
-    // startServer's listen-callback resolves. Let the HTTP server hold the
-    // event loop open instead.
-    if (sub !== 'web') process.exit(0);
-  } else if (sub && !sub.startsWith('-')) {
+    process.exit(0);
+  }
+  if (sub && !sub.startsWith('-')) {
     // Unknown positional subcommand — fail fast with help, don't drift
     // into MCP mode (which would just hang waiting for stdin).
     console.error(`Unknown subcommand: ${sub}`);
     console.error(`Run 'memex --help' for usage.`);
     process.exit(2);
   }
-  // For 'web': fall through to the rest of server.js so it keeps running.
-  // Actually no — the rest of server.js initializes MCP mode (stdin handler,
-  // DB watchers). For 'web' we DON'T want that. Sentinel-exit instead:
-  if (sub === 'web') {
-    // Server is listening — nothing more for this process to do.
-    // Just sit on the event loop until the HTTP server is closed.
-    await new Promise(() => {});
-  }
   // No args (or only flags we don't recognize) → MCP mode
 }
 

package/skills/install-memex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: install-memex
 description: Make Claude, Cursor, Cline, Continue, and Zed remember every AI conversation forever — one local SQLite corpus shared across all of them. Installs memex (local-first MCP server) in ~60 seconds via curl one-liner. Includes auto-capture daemon for Claude Code / Cowork / Cursor / Obsidian; v0.10 Telegram auto-detect (export from Desktop → memex stages it → AI proactively asks which to import, privacy-first per-chat consent); v0.8 SessionStart hook for the Brian Chesky moment ("Claude already knows what you were doing"); URL / Perplexity / AI chat share capture via memex_store_document. 18 MCP tools, no cloud, no account, verbatim storage. Use when the user says "install memex", "set up memex", "add memory to my AI", "make my agent remember across sessions", "сохрани мои чаты", or similar.
-version: 1.4.0
+version: 1.4.1
 metadata:
   openclaw:
     emoji: "📚"
@@ -290,15 +290,19 @@ If the user declines Telegram setup ("not now" / "skip"): say "OK, I'll skip Tel
 
 Tell the user to fully quit and reopen the MCP client (Cmd+Q on macOS) so it picks up the new memex tools.
 
-After restart, suggest they try any of:
+**🌟 FIRST, STRONGLY RECOMMEND THIS (v0.10.8+):** offer to run `memex web --open` for them right now. It's the single most magical post-install moment — a local browser tab opens at `http://127.0.0.1:8765` with 5 pages showing every conversation memex has captured, dialogue rendered as chat-bubbles, full-text searchable. Verbatim — not AI-summarized. Read-only, localhost-only, Ctrl+C to stop. Phrase it naturally, e.g.:
+
+> "I can open a local web dashboard that lets you actually *see* what memex captured — every message, in chat-bubble form, searchable. It's just a browser tab on `localhost:8765`. Run it now? It's a way better demo than asking me search queries blind."
+
+Then run `memex web --open` (in a backgrounded shell if your shell wrapper supports it — otherwise tell the user to run it themselves in another terminal). Wait for them to react before continuing.
+
+**After that, suggest other ways to confirm end-to-end:**
 - "show me what memex has in memory" → triggers `memex_overview`
 - "what projects has memex captured" → triggers `memex_list_projects`
 - "search memex for [recent topic]" → triggers `memex_search`
 - "save https://en.wikipedia.org/wiki/As_We_May_Think to memex" → triggers `memex_store_document` and teaches the user that URL-saving exists (v0.6+)
 - **Open Claude Code in any project the user worked on recently** — the SessionStart auto-context (v0.8+) should kick in and Claude will mention prior work _before_ the user types anything. This is the "Brian Chesky moment" — the magical-first-impression of memex.
-
 - **(if Telegram was set up)** `memex telegram check` — confirms daemon's Telegram-Downloads watcher is active and shows the user's full capture pipeline state.
-- **(v0.10.8+)** `memex web --open` — opens the local read-only web dashboard at `http://127.0.0.1:8765`. 5 pages: corpus stats, FTS5-searchable conversations list, verbatim chat-bubble transcripts, pending Telegram review with checkboxes, settings/daemon status. Useful for the user to *see* their memory with their own eyes — and a strong demo moment ("look at the actual messages verbatim, not an AI summary"). Localhost-only by default; Ctrl+C to stop.
 
 These confirm everything works end-to-end.