memgineering 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -11,6 +11,73 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.7.2] — 2026-08-18
+
+Everyone who runs this CLI is an agent, and an agent can only act on what a
+command actually prints. Three places were telling the user's agent nothing.
+
+### Added
+
+- **Any command run before setup finishes now says so, in markdown, on stderr**
+  — what is missing, the two questions to ask, and the command to run, addressed
+  to the agent rather than to the person. The same text has been in the install
+  script all along and reached nobody: npm swallows lifecycle-script output on
+  `npm i -g`, which is the exact command the README gives. Measured — npm 11.13
+  showed it 0 times without `--foreground-scripts` and once with; npm 12 never.
+  So the CLI says it itself, where nothing can suppress it, and stops saying it
+  the moment the step is done.
+
+  It goes to stderr because stdout under `--json` is one parseable document, and
+  a preamble there would break every caller that parses it.
+
+- **When setup has run and no brain is connected**, the same channel says that
+  instead, with `link` and `init` side by side and a note that an existing folder
+  needs no index and no frontmatter of its own — plain markdown is a brain.
+
+### Changed
+
+- **`setup` now signs in by default**, on both the flag path and the interactive
+  one. It opens no browser: a pairing code is printed for the agent to show its
+  user, and nothing exists on the server until they approve it. `--no-login` is
+  the one flag that says "this machine only", and setup still reports which way
+  it went.
+
+  The old default skipped the account unless asked, to avoid sending anyone to a
+  consent screen they had not chosen. Separating the account from the browser
+  keeps that, and drops what it cost: an install that never mentioned accounts,
+  and a user who discovered weeks later that their memory did not follow them.
+
+### Agent guidance
+
+- `memgineering-setup` now covers the sign-in default, what the pairing code
+  means, and the two ways to hand setup to someone who would rather do it
+  themselves (`--human` in your terminal, `--web` in their browser). **Restart
+  your agent session after upgrading** so the updated guidance loads.
+
+## [0.7.1] — 2026-08-17
+
+### Changed
+
+- **The semantic-search figures 0.7.0 quoted were measured on the set it was
+  tuned against.** An independent set of 70 questions — written by someone
+  reading only the notes and never a search result, with the expected note fixed
+  from what they had just read — scores lower on the same brain and the same
+  server: the right note is in the top five for **72.9%** of them and ranked
+  first for **45.7%**, and for a question asked across a language, **61.1%** and
+  **33.3%**. Text search alone scores 47.1% / 35.7% overall and 5.6% / 0% across
+  a language on that set, so meaning still moves every category it touches, and
+  cross-language remains the largest move either set shows. Both sets are real
+  measurements; only the tuned one had been reported. Expect the lower pair from
+  a question nobody tuned for.
+
+### Fixed
+
+- `recall --help` no longer offers `--detail summary`, `chunks`, and `full` as
+  though a hosted brain could answer them. It now says which two levels a hosted
+  brain does answer, and points at a brain in a folder or `open <handle>` for the
+  deeper ones. The refusal was already correct; the help text described a
+  different product.
+
 ## [0.7.0] — 2026-08-16
 
 Recall reads what a note says, not only what it is called. And the pile of
@@ -181,6 +248,7 @@ that goes one approved change at a time.
   the shape of its answers without changing its name.
 
 ### Fixed
+
 - **`push` now reports the notes it never sent.** A note held back by the name
   deny list or by an ignore rule was dropped before the upload and appeared in
   no summary — a 277-note brain reported `276 note(s) uploaded` and said nothing
@@ -205,7 +273,6 @@ that goes one approved change at a time.
   held each note, instead of pointing at `memgineering reindex` — which reports
   the name and content screens and says nothing about an ignore rule.
 
-
 - **A `supersedes:` written as a single value is no longer ignored.**
   `supersedes: mem-abc` is what somebody writes when one memory replaces one
   other, and it parsed to nothing at all — no relation, no complaint, no way to

package/assets/MEMGINEERING.md

@@ -2,7 +2,7 @@
 name: memgineering
 description: Use whenever the user refers to something they told you before, asks what was decided, tells you something worth keeping, or settles something that should hold next time. The memory lives in their own folder and outlives this session; check it before answering from guesswork, and write to it when you learn something durable.
 type: skill
-version: 0.7.0
+version: 0.7.2
 ---
 
 # memgineering

package/assets/memgineering-setup/SKILL.md

@@ -38,6 +38,24 @@ memgineering setup --agent \
 
 `--dry-run` reports what would change without changing it.
 
+**The account is the default, and the browser is not.** `setup --agent` starts a
+sign-in on its own: it prints a short pairing code and returns immediately,
+opening nothing. Show the user the code — they approve it in their browser while
+you keep working, and the next command picks the token up. Nothing exists on the
+server until they approve.
+
+`--no-login` is how someone says "this machine only". Offer it, do not assume it:
+a brain that lives in a folder here cannot follow them to their phone or their
+next laptop, and that is discovered weeks later, by which time the notes are in
+the wrong place. Ask which they want in one sentence before you run anything.
+
+**If they would rather set it up themselves**, hand them a screen instead of
+doing it: `setup --human` draws a checkbox list in your terminal, and
+`setup --web` opens a page in their own browser (`--web --print-url` when you
+cannot open one for them). Both ask the same questions `--agent` takes from
+flags, and `--web` is the one to reach for when the user is not reading your
+terminal at all.
+
 **Ask before setting policy for them.** Auto-update means the tool updates
 itself; `--hook on` means note summaries and their standing rules reach an agent
 unasked. Recommend both, but they are theirs to decide.

package/dist/index.js

@@ -4962,17 +4962,35 @@ async function runSignInStep(opts) {
   if (summary.pendingUserCode) return { status: "pending", userCode: summary.pendingUserCode };
   if (opts.login === false) return { status: "skipped" };
   if (opts.dryRun) {
-    const wouldAsk = opts.interactive || opts.login === true;
-    return wouldAsk ? { status: "would-start" } : { status: "skipped" };
+    return { status: "would-start" };
+  }
+  if (!opts.interactive && opts.login === void 0) {
+    try {
+      const { pending, opened } = await beginSignIn({ browser: false });
+      return {
+        status: "started",
+        userCode: pending.user_code,
+        verificationUrl: pending.verification_url,
+        opened
+      };
+    } catch (err) {
+      return {
+        status: "unavailable",
+        because: err instanceof MemgError ? err.message : String(err)
+      };
+    }
   }
-  if (!opts.interactive && opts.login !== true) return { status: "skipped" };
   if (opts.interactive) {
     printHuman(c.bold("\nmemgineering \u2014 setup\n"));
     const { wants } = await prompts2({
       type: "toggle",
       name: "wants",
       message: "Sign in to a memgineering account first?",
-      initial: false,
+      // Default yes, to match the non-interactive path. Someone at a prompt can
+      // see both answers and press either; the default is which one costs them
+      // nothing to accept, and syncing is the one they cannot add retroactively
+      // to notes they have already written somewhere else.
+      initial: true,
       active: "sign in",
       inactive: "later"
     });
@@ -12424,7 +12442,10 @@ init_errors();
 init_vault();
 init_ui();
 function recallCommand() {
-  return new Command18("recall").description("recall memory cards for a question").argument("<query>", "what you want to remember").option("--vault <path>", "which brain to search").option("--local", "search the brain on this machine, even when signed in to a hosted one").option("--scope <scope>", "restrict to one scope").option("--limit <n>", "max cards", (v) => parseInt(v, 10), 8).option("--detail <level>", "title | card | summary | chunks | full (default: card)").option("--depth <depth>", "exact | standard (default: standard, which also searches bodies)").option("--budget <tokens>", "max estimated size of the answer", (v) => parseInt(v, 10)).action(
+  return new Command18("recall").description("recall memory cards for a question").argument("<query>", "what you want to remember").option("--vault <path>", "which brain to search").option("--local", "search the brain on this machine, even when signed in to a hosted one").option("--scope <scope>", "restrict to one scope").option("--limit <n>", "max cards", (v) => parseInt(v, 10), 8).option(
+    "--detail <level>",
+    "title | card | summary | chunks | full (default: card) \u2014 a hosted brain answers title and card only; deeper needs a brain in a folder, or `open <handle>`"
+  ).option("--depth <depth>", "exact | standard (default: standard, which also searches bodies)").option("--budget <tokens>", "max estimated size of the answer", (v) => parseInt(v, 10)).action(
     async (query, opts) => {
       const detail = parseDetail(opts.detail, "card");
       const depth = parseDepth(opts.depth);
@@ -14083,13 +14104,83 @@ function whoamiCommand() {
   });
 }
 
+// src/lib/next-step.ts
+init_config();
+function isSetUp(cfg) {
+  return Object.keys(cfg.system.installed).length > 0;
+}
+var FINISH_SETUP = `## memgineering is installed. It is NOT set up yet.
+
+**TO THE AGENT READING THIS** \u2014 finish it now, in this same turn. Do not print
+these commands for your user and stop: they are yours to run.
+
+Ask them TWO short questions, in their language, then run setup yourself.
+
+1. **Where should the memory live?**
+   "Just on this machine, or synced to an account so every device and every
+   tool you use sees the same brain?"
+
+   - this machine \u2192 add \`--no-login\`
+   - synced (default) \u2192 no extra flag
+
+2. **Who picks the rest of the settings?**
+   "Shall I set it up, or would you rather choose on a screen?"
+
+   - you do it \u2192 \`memgineering setup --agent\`
+   - they choose \u2192 \`memgineering setup --web\`
+
+\`\`\`bash
+memgineering setup --agent          # synced, you answer the rest
+memgineering setup --agent --no-login   # this machine only
+memgineering setup --web            # they answer on a screen
+\`\`\`
+
+Signing in prints a short code \u2014 show it to them and they approve it in the
+browser. Setup does not wait, and the next command collects the token, so you
+keep going in the same turn.
+
+Then read \`memgineering-setup\` for what to do with the brain it points at.`;
+var CONNECT_A_BRAIN = `## memgineering is set up, and no brain is connected.
+
+**TO THE AGENT READING THIS** \u2014 a brain is a folder of markdown notes. Until one
+is connected there is nothing to recall and nowhere to remember. Pick with your
+user, then run it yourself:
+
+\`\`\`bash
+memgineering link <their-notes-folder>   # they already keep notes
+memgineering init <path>                 # they do not \u2014 creates one, laid out
+\`\`\`
+
+\`link\` reports what would be stored before anything is indexed. An existing
+folder needs no index and no frontmatter of its own \u2014 plain markdown is a brain.
+
+Then run \`memgineering onboard\`: it prints what to ask so the brain knows whose
+it is. A brain whose \`01_BASE/\` is still template text answers almost nothing.
+
+Read \`memgineering-setup\` for accounts and which of their tools this reaches.`;
+function nextStepFor(cfg) {
+  if (!isSetUp(cfg)) return { id: "finish_setup", markdown: FINISH_SETUP };
+  if (cfg.brain.brains.length === 0 && cfg.brain.cloud === void 0) {
+    return { id: "connect_a_brain", markdown: CONNECT_A_BRAIN };
+  }
+  return null;
+}
+async function currentNextStep() {
+  try {
+    return nextStepFor(await loadConfig());
+  } catch {
+    return null;
+  }
+}
+
 // src/program.ts
 init_ui();
 init_brand();
 function buildProgram() {
-  const program = new Command27("memgineering").version(VERSION).description("memgineering \u2014 one memory for the AI you connect").option("--json", "emit JSON to stdout instead of markdown", false).hook("preAction", (thisCommand) => {
+  const program = new Command27("memgineering").version(VERSION).description("memgineering \u2014 one memory for the AI you connect").option("--json", "emit JSON to stdout instead of markdown", false).hook("preAction", async (thisCommand, actionCommand) => {
     const opts = thisCommand.optsWithGlobals();
     if (opts.json || process.env[BRAND.jsonEnvVar] === "1") setJsonMode(true);
+    await announceNextStep(actionCommand.name());
   });
   configureGroupedHelp(program);
   program.addCommand(recallCommand());
@@ -14126,6 +14217,16 @@ function buildProgram() {
   makeParseErrorsActionable(program);
   return program;
 }
+var WITHOUT_NEXT_STEP = /* @__PURE__ */ new Set(["setup", "login", "logout", "whoami", "update", "guard"]);
+async function announceNextStep(commandName) {
+  if (WITHOUT_NEXT_STEP.has(commandName)) return;
+  const step = await currentNextStep();
+  if (step === null) return;
+  process.stderr.write(`
+${step.markdown}
+
+`);
+}
 function makeParseErrorsActionable(program) {
   const decorate = (cmd) => {
     cmd.showSuggestionAfterError(true);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "memgineering",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "private": false,
-  "description": "One memory for the AI you connect. Recall, remember, and revise a brain your agents share \u2014 stored in your own folder.",
+  "description": "One memory for the AI you connect. Recall, remember, and revise a brain your agents share — stored in your own folder.",
   "license": "Apache-2.0",
   "homepage": "https://memgineering.com",
   "repository": {

package/scripts/postinstall.mjs

@@ -42,8 +42,8 @@ if (process.env['npm_config_global'] === 'true') {
       '       "Just on this machine, or synced to an account so every device',
       '        and every tool you use sees the same brain?"',
       '',
-      '       this machine  ->  no extra flag',
-      '       synced        ->  add  --login',
+      '       this machine  ->  add  --no-login',
+      '       synced        ->  no extra flag, this is the default',
       '',
       '  2. Who picks the rest of the settings?',
       '       "Shall I set it up, or would you rather choose on a screen?"',
@@ -51,14 +51,16 @@ if (process.env['npm_config_global'] === 'true') {
       '       you do it     ->  memgineering setup --agent',
       '       they choose   ->  memgineering setup --web',
       '',
-      'So: `memgineering setup --agent --login`, or `--agent`, or `--web',
-      '--login`, or `--web`. Question 1 matters most — WITHOUT `--login`,',
-      'setup makes a folder on this machine and never mentions accounts, and',
-      'the user finds out later that their memory does not follow them.',
+      'So: `memgineering setup --agent`, or `--agent --no-login`, or `--web`.',
+      'Question 1 matters most — WITH `--no-login`, setup makes a folder on this',
+      'machine and never mentions accounts again, and the user finds out later',
+      'that their memory does not follow them.',
       '',
-      '`--login` prints a short code: show it to them and they approve it in',
-      'the browser. Setup does not wait, and the next command collects the',
-      'token, so you keep going in the same turn.',
+      'The default prints a short code and opens nothing: show the code to them',
+      'and they approve it in the browser. Setup does not wait, and the next',
+      'command collects the token, so you keep going in the same turn.',
+      '',
+      'Then read the `memgineering-setup` skill for what to do with the brain.',
       '',
     ].join('\n'),
   );