open-memex 0.5.0 → 0.6.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.5.0",
+  "version": "0.6.0-alpha.4",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",
@@ -18,7 +18,8 @@
     "cli": "node --experimental-strip-types src/cli.ts",
     "mcp": "node --experimental-strip-types src/mcp.ts",
     "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",

package/scripts/postinstall.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// D50: `npm install -g open-memex` only puts the CLI on PATH — the editor
+// wiring is `init`'s job. postinstall must never prompt (it runs in CI,
+// Docker builds and `npm ci` where stdin isn't a terminal), so this only
+// prints the pointer. Plain JS, no dependencies.
+console.log(
+  "\nopen-memex installed. Run `open-memex init` to wire it into your editors — " +
+    "it auto-detects VS Code, Cursor and opencode.\n",
+);

package/src/cli.ts

@@ -329,8 +329,9 @@ Example:
   open-memex capture --dry-run "remember: we deploy on Fridays"`,
 
   doctor: `Environment health check: Node version, config source, scope resolution,
-storage writability, then boots a real MCP server and runs initialize +
-tools/list against it — all eleven tools must show up.
+storage writability, VS Code MCP enablement (settings.json + system policy),
+then boots a real MCP server and runs initialize + tools/list against it —
+all eleven tools must show up.
 
 Usage: open-memex doctor
 
@@ -377,7 +378,7 @@ Usage:
 Every command has its own help with description and examples:
   open-memex <command> --help   (or -h)
 
-One-command project setup: \`open-memex init\` (or \`npx open-memex@alpha init\`) detects
+One-command project setup: \`open-memex init\` (or \`npx -y open-memex init\`) detects
 your installed editors and wires them all — user-level where the editor supports it
 (VS Code / Cursor MCP config, opencode native plugin), so one init covers every project;
 Visual Studio is included when the project has a solution file (its \`.mcp.json\`
@@ -392,9 +393,9 @@ confirms the detected editors and asks a couple of settings (keyword capture,
 first-turn injection); \`--yes\` accepts all defaults, and non-terminal runs never prompt.
 \`open-memex config set <key> <value>\` changes those settings after install.
 
-Once installed globally (\`npm i -g open-memex@alpha\`) the \`open-memex\` command is
-available directly: \`open-memex mcp\` starts the stdio MCP server (same five
-memory_* tools as the opencode plugin); \`open-memex mcp --print-config <client>\`
+Once installed globally (\`npm i -g open-memex\`) the \`open-memex\` command is
+available directly: \`open-memex mcp\` starts the stdio MCP server (11 tools, a superset of
+the opencode plugin's five memory_* tools); \`open-memex mcp --print-config <client>\`
 prints a copy-paste MCP client config snippet.
 
 Scope defaults to \`project\` (derived from cwd's git remote or path).
@@ -471,7 +472,7 @@ function resolveCliScope(flags: Record<string, string>, project: Scope): Scope {
 }
 
 /** Print a copy-paste MCP client config snippet. Requires a global install
- * (`npm i -g open-memex@alpha`) so the `open-memex` command is on PATH. */
+ * (`npm i -g open-memex`) so the `open-memex` command is on PATH. */
 function printMcpConfig(client: string): never {
   const c = client.toLowerCase();
   // D17: resolve the server command the same way `init` does.
@@ -547,7 +548,7 @@ function printMcpConfig(client: string): never {
   }
   if (!mc.durable) {
     console.error(
-      `\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex@alpha\` for faster startup.`,
+      `\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex\` for faster startup.`,
     );
   }
   process.exit(0);
@@ -555,7 +556,28 @@ function printMcpConfig(client: string): never {
 
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
-  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") usage(0);
+  if (!cmd) {
+    // D50: fresh machine + interactive terminal → offer init instead of bare usage.
+    // Non-interactive (CI/scripts/pipes) prints usage exactly as before.
+    const { offerFirstRunInit } = await import("./first-run.ts");
+    const outcome = await offerFirstRunInit(async () => {
+      // Re-exec `open-memex init` as a child with inherited stdio instead of
+      // calling initProject() in-process: the offer's readline already
+      // consumed stdin's buffer, and a second readline on the same stream
+      // would see EOF on burst input instead of the user's next answers.
+      const { spawnSync } = await import("node:child_process");
+      const r = spawnSync(
+        process.execPath,
+        [...process.execArgv, fileURLToPath(import.meta.url), "init"],
+        { stdio: "inherit" },
+      );
+      if (r.error) throw r.error;
+      if ((r.status ?? 1) !== 0) process.exit(r.status ?? 1);
+    });
+    if (outcome !== "initialized") usage(0);
+    return;
+  }
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") usage(0);
 
   if (cmd === "--version" || cmd === "-v") {
     // package.json sits two levels above this file in both layouts
@@ -724,7 +746,7 @@ async function main() {
     return;
   }
 
-  // `mcp` starts the stdio MCP server (same tools as the opencode plugin).
+  // `mcp` starts the stdio MCP server (11 tools; the opencode plugin exposes 5).
   // Branched before db() — runMcpServer() does its own init, and stdout must
   // stay clean for the MCP protocol.
   if (cmd === "mcp") {

package/src/distill-agents.ts

@@ -68,12 +68,13 @@ export function distillAgentsMarkdown(opts: DistillAgentsOptions): string {
   }
   // D43 — §3.5 memory-hygiene footer (double insurance for opencode users,
   // who never see the MCP handshake / init instructions): teach the agent
-  // reading this AGENTS.md to propose distilled captures at checkpoints.
+  // reading this AGENTS.md to propose distilled captures when a task ends
+  // (D53: the checkpoint mechanism is gone).
   lines.push(`### Memory hygiene (open-memex)`);
   lines.push(``);
   lines.push(
-    `- At checkpoints (session start, end of a work chunk, after the user commits),`,
-    `  distill the session: propose 1–3 short memories capturing the useful`,
+    `- When you finish a task the user would describe in one sentence, distill`,
+    `  the session: propose 1–3 short memories capturing the useful`,
     `  conclusion — what was learned or decided, how an issue was resolved, what`,
     `  to avoid, where the authoritative doc lives — not the raw transcript.`,
     `  Save nothing without user approval.`,

package/src/doctor.ts

@@ -3,8 +3,9 @@
 // Read-only except that paths() and the MCP handshake may create the (empty)
 // data directories, exactly like a normal `open-memex mcp` start would.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.ts";
 import { paths } from "./paths.ts";
@@ -158,9 +159,145 @@ function mcpCheck(): Promise<Check> {
   });
 }
 
+/** Parse JSON tolerating line/block comments plus trailing commas
+ * (VS Code's settings.json is JSONC). Health-check grade, not a full parser. */
+function parseLenientJson(raw: string): Record<string, unknown> {
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    /* fall through to comment stripping */
+  }
+  let out = "";
+  let i = 0;
+  let inStr = false;
+  let esc = false;
+  while (i < raw.length) {
+    const c = raw[i];
+    const n = raw[i + 1];
+    if (inStr) {
+      out += c;
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inStr = true;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && n === "/") {
+      while (i < raw.length && raw[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && n === "*") {
+      i += 2;
+      while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  out = out.replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(out) as Record<string, unknown>;
+}
+
+function vscodeSettingsPath(): string | null {
+  const home = os.homedir();
+  if (process.platform === "win32") {
+    const appdata = process.env.APPDATA;
+    return appdata ? path.join(appdata, "Code", "User", "settings.json") : null;
+  }
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "Code", "User", "settings.json");
+  }
+  return path.join(home, ".config", "Code", "User", "settings.json");
+}
+
+/** True when a Windows system policy disables MCP (value name contains "mcp",
+ * data is 0/0x0/false). Checks HKLM and HKCU policy keys. */
+function windowsMcpPolicyDisabled(): string | null {
+  if (process.platform !== "win32") return null;
+  for (const hive of ["HKLM", "HKCU"]) {
+    try {
+      const stdout = execFileSync(
+        "reg",
+        ["query", `${hive}\\SOFTWARE\\Policies\\Microsoft\\VSCode`],
+        { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] },
+      ) as string;
+      for (const line of stdout.split("\n")) {
+        const m = line.match(/^\s{2,}(\S+)\s+REG_\w+\s+(\S+)/);
+        if (m && /mcp/i.test(m[1]) && /^(0x0|0|false)$/i.test(m[2])) {
+          return `${hive}\\SOFTWARE\\Policies\\Microsoft\\VSCode!${m[1]}`;
+        }
+      }
+    } catch {
+      /* policy key absent — no policy */
+    }
+  }
+  return null;
+}
+
+function settingsMcpDisabled(file: string): boolean {
+  try {
+    const parsed = parseLenientJson(fs.readFileSync(file, "utf8"));
+    return parsed["chat.mcp.enabled"] === false;
+  } catch {
+    return false; // unreadable file: don't claim anything
+  }
+}
+
+/** VS Code ignores MCP server entries entirely when MCP is switched off —
+ * either in settings.json or, on managed machines, by system policy. */
+function vscodeMcpCheck(): Check {
+  const name = "vscode-mcp";
+  const policyHit = windowsMcpPolicyDisabled();
+  if (policyHit) {
+    return {
+      name,
+      ok: false,
+      detail:
+        `MCP is disabled by system policy (${policyHit}) — managed by your organization. ` +
+        `VS Code will ignore open-memex's MCP entry on this machine.`,
+    };
+  }
+  const files: string[] = [];
+  const user = vscodeSettingsPath();
+  if (user) files.push(user);
+  const ws = path.join(process.cwd(), ".vscode", "settings.json");
+  if (!files.includes(ws)) files.push(ws);
+  const found: string[] = [];
+  const disabled: string[] = [];
+  for (const f of files) {
+    if (!fs.existsSync(f)) continue;
+    found.push(f);
+    if (settingsMcpDisabled(f)) disabled.push(f);
+  }
+  if (disabled.length > 0) {
+    return {
+      name,
+      ok: false,
+      detail:
+        `chat.mcp.enabled is false in ${disabled.join(", ")} — VS Code will not load ` +
+        `MCP servers. Set it to true (or ask IT if the setting shows as managed).`,
+    };
+  }
+  return {
+    name,
+    ok: true,
+    detail:
+      found.length > 0
+        ? `MCP enabled (checked ${found.join(", ")})`
+        : "VS Code settings not found on this machine — nothing to check",
+  };
+}
+
 export async function runDoctor(): Promise<boolean> {
   console.log("open-memex doctor");
-  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck()];
+  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), vscodeMcpCheck()];
   checks.push(await mcpCheck());
   let allOk = true;
   for (const c of checks) {

package/src/first-run.ts

@@ -0,0 +1,96 @@
+/**
+ * D50: first-run init offer. `npm install -g open-memex` only puts the CLI on
+ * PATH — the editor wiring is `init`'s job, and a clean reinstall wipes it.
+ * When bare `open-memex` runs on a machine where init never completed, offer
+ * to run it instead of just printing usage.
+ *
+ * The "asked" state is a marker file at the data root (`init` writes it on
+ * success, a declined offer writes it too), so the question is asked exactly
+ * once. `uninstall` removes it — unwiring is the reverse of init, so the next
+ * bare run offers to wire again. The marker is a dotfile: export builds from
+ * DB rows, never by walking the data root, so it can't leak into bundles.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { dataRootPath } from "./paths.ts";
+
+const MARKER = ".init.json";
+
+export type FirstRunState = "initialized" | "declined";
+
+export function firstRunMarkerPath(root: string = dataRootPath()): string {
+  return path.join(root, MARKER);
+}
+
+/** True when init has neither run nor been declined on this machine. */
+export function isFirstRun(root?: string): boolean {
+  return !fs.existsSync(firstRunMarkerPath(root ?? dataRootPath()));
+}
+
+/** Record the outcome — best effort; a missing marker just asks again next time. */
+export function markFirstRunDone(state: FirstRunState): void {
+  const file = firstRunMarkerPath();
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ v: 1, state, at: new Date().toISOString() }) + "\n");
+  } catch {
+    /* ignore */
+  }
+}
+
+export function clearFirstRunMarker(): void {
+  try {
+    fs.rmSync(firstRunMarkerPath(), { force: true });
+  } catch {
+    /* ignore */
+  }
+}
+
+export interface TtyProbe {
+  stdinTTY: boolean | undefined;
+  stdoutTTY: boolean | undefined;
+}
+
+/** Pure decision, kept separate for tests: prompt only on an interactive
+ *  terminal — scripts, CI and piped runs never get the question. */
+export function shouldOfferFirstRun(
+  tty: TtyProbe = { stdinTTY: process.stdin.isTTY, stdoutTTY: process.stdout.isTTY },
+  firstRun: boolean = isFirstRun(),
+): boolean {
+  return firstRun && !!tty.stdinTTY && !!tty.stdoutTTY;
+}
+
+function askYesNo(question: string): Promise<boolean> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (ans) => {
+      rl.close();
+      resolve(!/^\s*(n|no)\s*$/i.test(ans));
+    });
+  });
+}
+
+export type FirstRunOutcome = "initialized" | "declined" | "skipped";
+
+/**
+ * Bare-`open-memex` first-run flow. `runInit` is injected so tests don't need
+ * the real init. Returns "skipped" when there's nothing to ask (already set
+ * up, or non-interactive) — the caller then prints usage as before.
+ */
+export async function offerFirstRunInit(
+  runInit: () => Promise<void>,
+): Promise<FirstRunOutcome> {
+  if (!shouldOfferFirstRun()) return "skipped";
+  console.log(
+    `It looks like open-memex hasn't been set up on this machine yet.\n` +
+      "`open-memex init` wires it into your editors (auto-detects VS Code, Cursor and opencode).\n",
+  );
+  if (await askYesNo("Run it now? [Y/n] ")) {
+    await runInit();
+    return "initialized";
+  }
+  markFirstRunDone("declined");
+  console.log("No problem — run `open-memex init` any time.");
+  return "declined";
+}

package/src/init.ts

@@ -7,6 +7,7 @@ import { createInterface } from "node:readline/promises";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { DEFAULT_CONFIG, saveConfig } from "./config.ts";
 import { projectRoot } from "./paths.ts";
+import { markFirstRunDone, clearFirstRunMarker } from "./first-run.ts";
 
 const MARKER = "<!-- open-memex -->";
 
@@ -51,54 +52,70 @@ const INSTRUCTIONS = `${MARKER}
 > Applies only when the \`open-memex\` MCP server is available in this session
 > (the \`memory_*\` tools exist). Otherwise ignore this section.
 
-You have a local memory MCP server (\`open-memex\`) with eleven tools:
-\`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`, \`memory_forget\`,
-\`memory_status\`, \`memory_submit\`, \`memory_propose\`, \`memory_promote\`, \`memory_resolve\`,
-\`memory_pr_status\`.
-
-- BE PROACTIVE. When the user shares something worth remembering across sessions
-  (a decision, a preference, a project convention, a fix and its cause), call
-  \`memory_add\` without being asked. Keep each memory to one self-contained statement.
-- At checkpoints (session start, end of a work chunk, after the user commits, after
-  any memory_* action), DISTILL the session: propose 1–3 short memories capturing the
-  useful conclusion — what was learned or decided, how an issue was resolved, what to
-  avoid, where the authoritative doc lives — not the raw transcript. Save NOTHING the
-  user did not approve; on approval call \`memory_add\` with source "inference" at the
-  confirmed scope. If the knowledge already lives in project docs, save a \`reference\`
-  memory pointing at the doc instead of copying it. Long-form notes are fine ONLY when
-  the user explicitly asks to save one.
-- Before asking the user about past decisions, conventions, or preferences they may
-  have told you before, call \`memory_search\` first — try a few keyword variants
-  (including the user's own language) when the first search comes up empty.
-- Memories default to this project's scope; use the \`personal\` scope for facts about
-  the user that hold across all projects. When a saved fact becomes outdated, call
-  \`memory_supersede\` instead of adding a duplicate.
+You have a local memory MCP server (\`open-memex\`). Its tools are
+\`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`,
+\`memory_forget\`, \`memory_status\`, \`memory_submit\`, \`memory_propose\`,
+\`memory_promote\`, \`memory_resolve\`, \`memory_pr_status\` — always call them by
+these full names.
+
+- The server tells you when project outbox drafts are waiting for review — in
+  tool results. At session start, call \`memory_status\` once to check. When
+  drafts are waiting, summarize them (one line each) and ask the user which
+  ones to sync into the repo; sync NOTHING the user did not name. If you
+  already asked about these drafts this session, don't ask again. When the
+  server reports none waiting, do nothing.
+- BE PROACTIVE about facts the user states directly: when the user shares a
+  decision, preference, project convention, or fix-and-cause worth remembering
+  across sessions, call \`memory_add\` without being asked. Keep each memory to
+  one self-contained statement, and add a brief "(noted in memory)" so the
+  user sees it worked.
+- For conclusions YOU infer (the user never stated them): when you finish a
+  task the user would describe in one sentence, consider distilling the
+  session — if there is something worth keeping,
+  propose 1–3 short memories capturing the useful conclusion (what was learned
+  or decided, how an issue was resolved, what to avoid, where the authoritative
+  doc lives — not the raw transcript), each with its proposed scope. Save
+  NOTHING the user did not approve; on approval call \`memory_add\` with source
+  "inference" at the approved scope. If the knowledge already lives in project
+  docs, save it as type "reference" pointing at the doc instead of copying it.
+  Long-form notes are fine ONLY when the user explicitly asks to save one.
+- Before asking the user about past decisions, conventions, or preferences
+  they may have told you before, call \`memory_search\` first — try a few
+  keyword variants (including the user's own language) when the first search
+  comes up empty.
+- Memories default to this project's scope; use the \`personal\` scope for facts
+  about the user that hold across all projects. When a saved fact becomes
+  outdated, call \`memory_supersede\` (find the old memory's id with
+  \`memory_search\` first) instead of adding a duplicate.
 
 ## Syncing project memories for review (D26)
 
-Project memories you save land in a local outbox first — they are NOT in git yet.
-Syncing them into the repo for review is an explicit, user-approved step:
-
-- At session start, when you finish a meaningful chunk of work, after the user
-  commits (git commit), and after any memory_* action completes, call
-  \`memory_status\`. If the outbox has drafts, summarize them (one line each) and ask
-  the user which ones to sync. Sync NOTHING the user did not name.
-- When the user says "sync memory" (or "同步记忆"), treat it as a request to run
-  the sync flow above: call \`memory_status\`, summarize the outbox drafts, and ask
-  which ones to sync.
-- When the user approves, call \`memory_submit\` with the approved ids. It copies
-  the drafts into the repo as \`proposed\`, commits locally on the CURRENT branch,
-  and prints the push + PR commands. It NEVER creates a branch on its own.
+Project memories you save land in a local outbox first — they are NOT in git
+yet. Syncing them into the repo for review is an explicit, user-approved step:
+
+- When the server reports drafts waiting for review, call \`memory_status\` to
+  see them. Summarize the drafts (one line each) and ask the user which ones
+  to sync. Sync NOTHING the user did not name.
+- When the user says "sync memory" (or "同步记忆"), run the sync
+  flow above: call \`memory_status\`, summarize the outbox drafts, and ask which
+  ones to sync. ALWAYS use the \`memory_status\` tool for this — never browse
+  the memory data directory directly.
+- When the user approves, call \`memory_submit\` with the approved ids. It
+  copies the drafts into the current project's \`.ai/open-memex/\` directory as
+  \`proposed\` and commits locally on the CURRENT branch. It NEVER creates a
+  branch on its own.
 - After the submit, ask ONE follow-up: "want me to create a branch + push +
-  open the PR, or will you handle it yourself?" A "yes, you do it" answer covers
-  the whole chain — branch creation, push, PR creation — do NOT re-ask at each
-  step. If the user says they will do it themselves, hand them the printed
-  push/PR commands and do nothing. NEVER create branches, push, or open PRs
-  without their explicit approval.
-- Base branch for the memory PR defaults to the branch you are on; the user may
-  redirect it to the integration branch (main) for branch-independent knowledge.
-- If anything conflicts (same id with different content, push rejected), STOP and
-  let the user judge — never overwrite.
+  open the PR, or will you handle it yourself?" A "yes, you do it" answer
+  covers the whole chain — branch creation, push, PR creation — do NOT re-ask
+  at each step. If the user says they will do it themselves, hand them the
+  printed push/PR commands and do nothing. NEVER create branches, push, or open
+  PRs without their explicit approval.
+- If the user wants the memories reviewed on a separate branch, create the
+  branch first (the commit comes along), then push and open the PR. The PR base
+  defaults to the branch submit ran on; \`--base\` overrides it (e.g. \`main\` for
+  branch-independent knowledge).
+- If anything conflicts (same id with different content, push rejected), STOP
+  and let the user judge — never overwrite.
 - After the PR merges, call \`memory_pr_status\` (with \`apply\` when the user
   approves) to map the PR's review state back onto each memory — merged means
   \`published\`, an approval means \`approved\` (credited to the reviewer).
@@ -720,6 +737,11 @@ export async function initProject(opts: {
     writeInstructions(root, scope, clients.find((c) => c !== "opencode")!);
   }
   console.log(`\nDone. Reload your editor window to start the open-memex MCP server.`);
+  // D51: close the init→first-use gap — one concrete next step so a new user
+  // sees what "it works" looks like instead of stopping at "it's wired".
+  console.log(`  Next step: \`open-memex add "standup is at 9:30"\` — then ask your agent what it remembers.`);
+  // D50: init completed — the bare-`open-memex` first-run offer won't ask again.
+  markFirstRunDone("initialized");
 }
 
 // ---------------------------------------------------------------------------
@@ -909,4 +931,7 @@ export async function uninstallProject(opts: {
       : "\nDone. Nothing to remove — no open-memex wiring found.",
   );
   console.log("Your memories are untouched (uninstall never deletes data).");
+  // D50: unwiring is the reverse of init — drop the first-run marker so the
+  // next bare `open-memex` offers to wire again.
+  if (changed > 0) clearFirstRunMarker();
 }