@empirical-gauzza/cli 1.0.34 → 1.0.36

package/lib/auth.js

@@ -6,7 +6,7 @@ const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { log, warn, uiQuestion, uiDim, uiLink, ask } = require('./ui');
-const { readJsonIfExists, writeFile, ensureDir, quotePowerShellArg, runResolvedCommand } = require('./fsUtils');
+const { readJsonIfExists, writeFile, ensureDir, quotePowerShellArg, runResolvedCommand, runPowerShell } = require('./fsUtils');
 const { httpGet, httpJson, httpForm } = require('./http');
 const { getEnv, parseFlag, parseOption } = require('./env');
 const {
@@ -81,17 +81,26 @@ async function oauthPreflight(baseMcpUrl) {
   }
 }
 
+/** Best-effort browser launch. Returns true when the launcher ran, false when it could not. */
 function openBrowser(url) {
+  let result;
   if (process.platform === 'win32') {
-    const script = `Start-Process ${quotePowerShellArg(url)}`;
-    spawnSync('pwsh', ['-NoProfile', '-Command', script], { stdio: 'ignore' });
+    // runPowerShell falls back from pwsh to powershell.exe; the old hardcoded `pwsh` silently
+    // did nothing on a stock Windows install (2026-09-23, real user report).
+    result = runPowerShell(`Start-Process ${quotePowerShellArg(url)}`, { stdio: 'ignore' });
   } else if (process.platform === 'darwin') {
-    spawnSync('open', [url], { stdio: 'ignore' });
+    result = spawnSync('open', [url], { stdio: 'ignore' });
   } else {
-    spawnSync('xdg-open', [url], { stdio: 'ignore' });
+    result = spawnSync('xdg-open', [url], { stdio: 'ignore' });
   }
+  return Boolean(result) && !result.error && result.status === 0;
 }
 
+// How long the loopback listener waits for the browser to come back. Was 5 minutes; a user who
+// has to find the printed link by hand, log in, and pick a workspace can take longer than that,
+// and once the listener closes the browser lands on a dead 127.0.0.1 port with no explanation.
+const OAUTH_CALLBACK_TIMEOUT_MS = 10 * 60 * 1000;
+
 async function runMcpOAuthFlow(baseUrl) {
   return new Promise((resolve, reject) => {
     const { codeVerifier, codeChallenge } = generatePKCE();
@@ -103,9 +112,9 @@ async function runMcpOAuthFlow(baseUrl) {
       if (server) server.close();
       if (!resolved) {
         resolved = true;
-        reject(new Error('OAuth callback timeout (5 minutes)'));
+        reject(new Error(`OAuth callback timeout (${OAUTH_CALLBACK_TIMEOUT_MS / 60000} minutes). The login link has expired; run the command again to get a fresh one.`));
       }
-    }, 5 * 60 * 1000);
+    }, OAUTH_CALLBACK_TIMEOUT_MS);
 
     server = http.createServer((req, res) => {
       const url = new URL(`http://localhost${req.url}`);
@@ -162,8 +171,14 @@ async function runMcpOAuthFlow(baseUrl) {
       authUrl.searchParams.set('scope', 'memory:read memory:write memory:delete offline_access');
 
       log(uiQuestion('Opening browser for Empirical MCP authentication...'));
-      openBrowser(authUrl.toString());
-      log(uiDim(`If browser doesn't open, visit: ${uiLink(authUrl.toString())}`));
+      const opened = openBrowser(authUrl.toString());
+      if (opened) {
+        log(uiDim(`If browser doesn't open, visit: ${uiLink(authUrl.toString())}`));
+      } else {
+        warn('Could not open a browser automatically. Open this link yourself:');
+        log(uiLink(authUrl.toString()));
+      }
+      log(uiDim(`Waiting up to ${OAUTH_CALLBACK_TIMEOUT_MS / 60000} minutes for the browser to finish...`));
     });
 
     server.on('error', (error) => {
@@ -370,6 +385,19 @@ async function gatherAuthStatus() {
     }
   }
 
+  // What the CLI itself will scope the next memory command to (env, project binding, or the
+  // global selection), beside the server-reported account workspace above. The two can differ,
+  // and when they do this is the field that explains a "[]" recall. Lazy require: workspaceContext
+  // depends on this module.
+  let cliWorkspace = null;
+  try {
+    const { resolveLocalWorkspaceSelection } = require('./workspaceContext');
+    const local = resolveLocalWorkspaceSelection();
+    if (local) cliWorkspace = { workspaceId: local.workspaceId, label: local.label || null, source: local.source, path: local.path };
+  } catch (_error) {
+    cliWorkspace = null;
+  }
+
   return {
     authenticated: Boolean(token) && !error && tokenInfo.expired !== true,
     tokenPresent: tokenInfo.present,
@@ -378,6 +406,7 @@ async function gatherAuthStatus() {
     tokenExpired: tokenInfo.expired,
     user,
     workspaceId,
+    cliWorkspace,
     error
   };
 }

package/lib/constants.js

@@ -298,9 +298,22 @@ Creates a team workspace using your existing plan quota and prints its workspace
 ### Use a workspace
 
     empirical workspace use <number|name|id>
+    empirical workspace use <number|name|id> --global
+    empirical workspace unbind
 
 Friendly alias for \`workspace select\`. It accepts the list number, exact case-insensitive name, or workspace ID.
 
+Inside a git repository, \`use\` binds the workspace to THAT project by writing \`<repo>/.empirical/workspace.json\`; every command run inside the repo uses it, and other repositories are unaffected. \`--global\` sets the machine-wide default instead (the previous behavior). \`--project\` forces a project binding in the current directory even without git. \`unbind\` removes the project binding.
+
+Resolution order for every memory command, first match wins: the \`EMPIRICAL_WORKSPACE_ID\` environment variable, the nearest project binding walking up from the current directory, the global selection, then the server's per-client selection. \`workspace current\` and \`whoami\` print which source applied.
+
+### Query across several workspaces
+
+    empirical memory query --match "<query>" --workspaces "Default Workspace","Project Atlas"
+    empirical memory query --match "<query>" --all-workspaces
+
+\`--workspaces\` accepts list numbers, names, or workspace IDs (comma-separated) and returns one merged, ranked result set with each row's \`workspaceId\`. Paging (\`--cursor\`, offsets) is not available across several workspaces. Without the flag a query is scoped to the single active workspace exactly as before.
+
 ### Share an active workspace
 
     empirical workspace invite create --role writer --expires-in-days 7 --max-uses 3

package/lib/fsUtils.js

@@ -4,11 +4,51 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
+// 2026-09-23: every Windows shell-out used to hardcode `pwsh` (PowerShell 7). Windows ships only
+// Windows PowerShell 5.1 (`powershell.exe`); PowerShell 7 is a separate install most people do
+// not have. A real user on plain Windows hit `spawnSync pwsh ENOENT` on every plugin install AND
+// the browser never opened for OAuth (openBrowser also went through pwsh), so they found the
+// login link late, after the loopback listener had closed. Resolve once per process: prefer
+// pwsh when present, fall back to powershell.exe, and surface a clear error if neither works.
+let resolvedPowerShell;
+function resolvePowerShell() {
+  if (resolvedPowerShell !== undefined) return resolvedPowerShell;
+  const override = String(process.env.EMPIRICAL_POWERSHELL || '').trim();
+  const candidates = override ? [override] : ['pwsh', 'powershell'];
+  for (const candidate of candidates) {
+    const probe = spawnSync(candidate, ['-NoProfile', '-Command', 'exit 0'], { stdio: 'ignore', timeout: 15000 });
+    if (!probe.error && probe.status === 0) {
+      resolvedPowerShell = candidate;
+      return candidate;
+    }
+  }
+  resolvedPowerShell = null;
+  return null;
+}
+
+/**
+ * Runs a PowerShell script on Windows through whichever PowerShell exists. Returns a spawnSync-
+ * shaped result; when no PowerShell can be found the result carries an `error` (never throws),
+ * the same shape spawnSync itself returns for ENOENT, so callers' existing error paths apply.
+ */
+function runPowerShell(script, options = {}) {
+  const shell = resolvePowerShell();
+  if (!shell) {
+    return {
+      status: null,
+      stdout: '',
+      stderr: '',
+      error: new Error('No PowerShell found (tried pwsh and powershell). Install PowerShell 7 or set EMPIRICAL_POWERSHELL to your PowerShell executable.')
+    };
+  }
+  return spawnSync(shell, ['-NoProfile', '-Command', script], options);
+}
+
 function commandExists(cmd) {
   if (process.platform === 'win32') {
     const escaped = cmd.replace(/'/g, "''");
     const script = `if (Get-Command '${escaped}' -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }`;
-    const result = spawnSync('pwsh', ['-NoProfile', '-Command', script], { stdio: 'ignore' });
+    const result = runPowerShell(script, { stdio: 'ignore' });
     return result.status === 0;
   }
   const result = spawnSync('which', [cmd], { stdio: 'ignore' });
@@ -57,7 +97,7 @@ function runResolvedCommand(command, args, options = {}) {
   }
 
   const script = `& ${quotePowerShellArg(command)} ${args.map(quotePowerShellArg).join(' ')}`;
-  return spawnSync('pwsh', ['-NoProfile', '-Command', script], {
+  return runPowerShell(script, {
     encoding: 'utf8',
     ...(input !== undefined ? { input } : { stdio })
   });
@@ -79,6 +119,8 @@ function summarizeProcessOutput(result) {
 }
 
 module.exports = {
+  resolvePowerShell,
+  runPowerShell,
   commandExists,
   ensureDir,
   readUtf8IfExists,

package/lib/help.js

@@ -38,9 +38,11 @@ function showHelp() {
   log('  empirical oauth client show');
   log('  empirical oauth client clear');
   log('  empirical workspace list                     List workspaces you can select, and which one is active');
-  log('  empirical workspace current                  Show the currently active workspace');
+  log('  empirical workspace current                  Show the active workspace and where it comes from (env, project, global)');
   log('  empirical workspace select [<number|name>]   Set the active workspace (prompts if omitted)');
-  log('  empirical workspace use <number|name|id>     Alias for `workspace select`');
+  log('  empirical workspace use <number|name|id>     Alias for `workspace select`. Inside a git repo binds THIS project;');
+  log('                                                --global sets the machine-wide default, --project forces a binding');
+  log('  empirical workspace unbind                   Remove this project\'s workspace binding');
   log('  empirical workspace create <name> [--description <text>]');
   log('                                                Create a new shared team workspace');
   log('  empirical workspace invite create [--role reader|writer|manager] [--expires-in-days <n>] [--max-uses <n>]');

package/lib/installers/nativePlugin.js

@@ -77,9 +77,9 @@ function detectLockHolders(agentId) {
   const names = LOCK_HOLDER_PROCESS_NAMES[agentId] || [];
   if (!names.length) return [];
   try {
-    const { spawnSync } = require('child_process');
+    const { runPowerShell } = require('../fsUtils');
     const script = `Get-Process -Name ${names.join(',')} -ErrorAction SilentlyContinue | Select-Object -ExpandProperty ProcessName -Unique`;
-    const probe = spawnSync('pwsh', ['-NoProfile', '-Command', script], { encoding: 'utf8', timeout: 5000 });
+    const probe = runPowerShell(script, { encoding: 'utf8', timeout: 5000 });
     return String(probe.stdout || '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
   } catch (_error) {
     return [];

package/lib/memoryCommands.js

@@ -59,7 +59,7 @@ const REMIND_STATES = ['pending', 'notified', 'acknowledged', 'cancelled'];
 // the 90-line global help wall bin/empirical.js otherwise short-circuits every --help to.
 
 const MEMORY_SUBCOMMAND_USAGE = {
-  query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--due-before <ISO date>] [--due-after <ISO date>] [--remind-state pending,notified] [--path semantic|list|graph|hebbian] [--hops 1|2] [--pretty] [--format table]',
+  query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--due-before <ISO date>] [--due-after <ISO date>] [--remind-state pending,notified] [--path semantic|list|graph|hebbian] [--hops 1|2] [--workspaces <n|name|id,...>] [--all-workspaces] [--pretty] [--format table]',
   get: 'Usage: empirical memory get --memory-id <id> [--pretty]',
   list: 'Usage: empirical memory list [--category <cat>] [--tags <t1,t2>] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]',
   record: 'Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link] [--author-type user|agent]',
@@ -192,6 +192,56 @@ function printMemoryResolveError(result) {
 
 // ─── Memory subcommands ───────────────────────────────────────────────────────
 
+/**
+ * Turn `--workspaces` selectors (list numbers, names, or ids) into workspace ids using the
+ * per-user listing (/api/v1/users/me/workspaces, the same list `workspace list` prints; number 1
+ * is always the Default Workspace). An id (ws_...) passes through without a lookup. An unknown
+ * name is fatal at the terminal rather than a 403 or an empty answer after the round trip.
+ */
+async function resolveWorkspaceIdsForQuery({ baseUrl, accessToken, selectors = [], all = false }) {
+  const needsListing = all || selectors.some((s) => !/^ws_/.test(s));
+  let options = [];
+  if (needsListing) {
+    const listUrl = new URL('/api/v1/users/me/workspaces', baseUrl).toString();
+    let payload;
+    try {
+      payload = await httpJson(listUrl, 'GET', undefined, buildApiAuthHeaders(accessToken));
+    } catch (error) {
+      printApiError(error);
+      process.exit(1);
+    }
+    options = [
+      ...(payload?.defaultOption ? [payload.defaultOption] : []),
+      ...(Array.isArray(payload?.workspaces) ? payload.workspaces : [])
+    ].filter((o) => o && o.workspaceId);
+  }
+  if (all) return [...new Set(options.map((o) => o.workspaceId))];
+
+  const ids = [];
+  for (const selector of selectors) {
+    if (/^ws_/.test(selector)) { ids.push(selector); continue; }
+    const asNumber = Number(selector);
+    let match = null;
+    if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= options.length) {
+      match = options[asNumber - 1];
+    } else {
+      const lower = selector.toLowerCase();
+      const byLabel = options.filter((o) => String(o.label || '').toLowerCase() === lower || String(o.key || '').toLowerCase() === lower);
+      if (byLabel.length > 1) {
+        warn(`Ambiguous workspace "${selector}". Use its list number or workspace id.`);
+        process.exit(1);
+      }
+      match = byLabel[0] || null;
+    }
+    if (!match) {
+      warn(`Workspace not found: "${selector}". Run \`empirical workspace list\` to see names and numbers.`);
+      process.exit(1);
+    }
+    ids.push(match.workspaceId);
+  }
+  return [...new Set(ids)];
+}
+
 async function runMemoryQuery(args) {
   const match = parseOption(args, '--match', '');
   if (!match) {
@@ -208,6 +258,17 @@ async function runMemoryQuery(args) {
   // --status filters data.status. Both are optional and additive to --tags/--category.
   const tagsAllRaw = parseOption(args, '--tags-all', '');
   const tagsAll = tagsAllRaw ? tagsAllRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
+  // Multi-workspace recall (2026-09-24). --workspaces takes list numbers, names, or ids; names
+  // and numbers are resolved against the same listing `workspace list` prints, so the server
+  // contract stays ids-only. --all-workspaces sends every selectable workspace. Without either
+  // flag the query is scoped to the single active workspace exactly as before.
+  const workspacesRaw = parseOption(args, '--workspaces', '');
+  const workspaceSelectors = workspacesRaw ? workspacesRaw.split(',').map((w) => w.trim()).filter(Boolean) : [];
+  const allWorkspaces = parseFlag(args, '--all-workspaces');
+  if (workspaceSelectors.length && allWorkspaces) {
+    warn('Pass either --workspaces or --all-workspaces, not both.');
+    process.exit(1);
+  }
   const statusRaw = parseOption(args, '--status', '');
   const status = statusRaw ? statusRaw.split(',').map((s) => s.trim()).filter(Boolean) : [];
   const pretty = parseFlag(args, '--pretty');
@@ -278,6 +339,14 @@ async function runMemoryQuery(args) {
   if (category) body.category = category;
   if (tags.length) body.tags = tags;
   if (tagsAll.length) body.tagsAll = tagsAll;
+  if (workspaceSelectors.length || allWorkspaces) {
+    body.workspaceIds = await resolveWorkspaceIdsForQuery({
+      baseUrl,
+      accessToken,
+      selectors: workspaceSelectors,
+      all: allWorkspaces
+    });
+  }
   if (status.length) body.status = status;
   if (dueFilters.dueBefore) body.dueBefore = dueFilters.dueBefore;
   if (dueFilters.dueAfter) body.dueAfter = dueFilters.dueAfter;
@@ -1130,6 +1199,7 @@ module.exports = {
   withCliAnalyticsContext,
   resolveMemoryByQuery,
   printMemoryResolveError,
+  resolveWorkspaceIdsForQuery,
   runMemoryQuery,
   runMemoryGet,
   runMemoryList,

package/lib/workspaceCommands.js

@@ -7,14 +7,31 @@ const { ensureHeadlessToken, resolveAccessToken, buildApiAuthHeaders } = require
 const { readStoredOAuthClient } = require('./oauthClient');
 const { deriveBaseUrlFromMcpUrl } = require('./constants');
 const { withCliAnalyticsContext } = require('./memoryCommands');
-const { readSelectedWorkspace, writeSelectedWorkspace, clearSelectedWorkspace } = require('./workspaceContext');
+const {
+  writeSelectedWorkspace,
+  clearSelectedWorkspace,
+  resolveLocalWorkspaceSelection,
+  findGitRoot,
+  writeProjectWorkspace,
+  clearProjectWorkspace,
+  projectWorkspacePathFor,
+  WORKSPACE_ENV_VAR
+} = require('./workspaceContext');
 
 function isWorkspaceCommand(args) {
   if (args[0] !== 'workspace') return false;
-  if (['list', 'current', 'select', 'use', 'create', 'delete'].includes(args[1])) return true;
+  if (['list', 'current', 'select', 'use', 'unbind', 'create', 'delete'].includes(args[1])) return true;
   return args[1] === 'invite' && ['create', 'list', 'revoke'].includes(args[2]);
 }
 
+function describeSelectionSource(selection) {
+  if (!selection) return '';
+  if (selection.source === 'env') return ` (from ${WORKSPACE_ENV_VAR})`;
+  if (selection.source === 'project') return ` (bound to this project: ${selection.path})`;
+  if (selection.source === 'global') return ' (global CLI selection)';
+  return '';
+}
+
 function workspaceOptions(payload) {
   return [
     ...(payload?.defaultOption ? [{ ...payload.defaultOption, isDefault: true }] : []),
@@ -164,9 +181,11 @@ async function runWorkspaceCommand(args) {
       }
 
       if (action === 'current') {
-        const locallySelected = readSelectedWorkspace();
+        // Same resolver every memory command uses (env, project binding, global file), so what
+        // this prints is what the next `memory query` will actually be scoped to.
+        const locallySelected = resolveLocalWorkspaceSelection();
         if (locallySelected) {
-          log(`Current workspace: ${locallySelected.label || locallySelected.workspaceId}`);
+          log(`Current workspace: ${locallySelected.label || locallySelected.workspaceId}${describeSelectionSource(locallySelected)}`);
           return;
         }
         if (!clientId) {
@@ -185,19 +204,40 @@ async function runWorkspaceCommand(args) {
         return;
       }
 
+      if (action === 'unbind') {
+        const gitRoot = findGitRoot();
+        if (!gitRoot) throw new Error('Not inside a git repository; there is no project binding here to remove.');
+        const removed = clearProjectWorkspace(gitRoot);
+        log(removed
+          ? uiSuccess(`Removed project workspace binding: ${removed}`)
+          : `No project workspace binding at ${projectWorkspacePathFor(gitRoot)}.`);
+        return;
+      }
+
       if (action === 'select' || action === 'use') {
-        requireClientId(clientId);
+        // Where the choice lands (2026-09-24): inside a git repo the default is a PROJECT binding
+        // (<repo>/.empirical/workspace.json, local only, never the server's per-client selection),
+        // so one repo's session cannot re-scope another's. --global keeps the old machine-wide
+        // behavior; --project forces a binding even when git is missing (uses cwd).
+        const wantGlobal = parseFlag(args, '--global');
+        const wantProject = parseFlag(args, '--project');
+        if (wantGlobal && wantProject) throw new Error('Pass either --global or --project, not both.');
+        const gitRoot = wantGlobal ? null : findGitRoot();
+        const projectRoot = wantProject ? (gitRoot || process.cwd()) : gitRoot;
+        const bindToProject = !wantGlobal && Boolean(projectRoot);
+
+        if (!bindToProject) requireClientId(clientId);
         const [payload, teamPayload] = await Promise.all([
           httpJson(listUrl, 'GET', null, authHeaders),
           httpJson(teamBrainsUrl, 'GET', null, authHeaders),
         ]);
-        if (payload.locked) {
+        if (payload.locked && !bindToProject) {
           throw new Error('Workspace is admin-locked for this OAuth client and cannot be changed.');
         }
 
         const options = workspaceOptions(payload);
 
-        let requested = args.slice(2).join(' ').trim();
+        let requested = args.slice(2).filter((arg) => !['--global', '--project'].includes(arg)).join(' ').trim();
         if (!requested && process.stdin.isTTY) {
           log('Select workspace:');
           options.forEach((item, idx) => log(`  ${idx + 1}. ${item.label}`));
@@ -213,6 +253,18 @@ async function runWorkspaceCommand(args) {
         if (target?.ambiguous) throw new Error(`Ambiguous workspace: ${requested}. Use its list number or workspace ID.`);
         if (!target?.selectionKey) throw new Error(`Workspace not found: ${requested}`);
 
+        if (bindToProject) {
+          // The Default Workspace is written explicitly (its personal id), never as "clear": an
+          // explicit binding is the whole point when a sibling session may have changed the global.
+          const workspaceId = target.workspaceId || payload?.defaultOption?.workspaceId || null;
+          if (!workspaceId) throw new Error(`Could not resolve a workspace id for ${target.label || requested}.`);
+          const written = writeProjectWorkspace(projectRoot, { workspaceId, key: target.key || null, label: target.label || null });
+          log(uiSuccess(`Workspace bound to this project: ${target.label || workspaceId}`));
+          log(`  ${written}`);
+          log('  Commands run inside this repository use it. Use --global to change the machine-wide default instead.');
+          return;
+        }
+
         const updateUrl = new URL(`/oauth/clients/${encodedClientId}/workspace-selection`, baseUrl).toString();
         const updated = await httpJson(updateUrl, 'POST', { key: target.selectionKey }, authHeaders);
         if (target.isDefault) {

package/lib/workspaceContext.js

@@ -1,76 +1,176 @@
-'use strict';
-
-const os = require('os');
-const path = require('path');
-const { httpJson } = require('./http');
-const { getEnv } = require('./env');
-const { resolveAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
-const { readStoredOAuthClient } = require('./oauthClient');
-const { readJsonIfExists, writeFile, ensureDir } = require('./fsUtils');
-
-const WORKSPACE_CONTEXT_TIMEOUT_MS = 2000;
-const SELECTED_WORKSPACE_PATH = path.join(os.homedir(), '.empirical', 'workspace-selection.json');
-
-function readSelectedWorkspace() {
-  const value = readJsonIfExists(SELECTED_WORKSPACE_PATH);
-  return value && typeof value.workspaceId === 'string' ? value : null;
-}
-
-function writeSelectedWorkspace(workspace) {
-  ensureDir(path.dirname(SELECTED_WORKSPACE_PATH));
-  writeFile(SELECTED_WORKSPACE_PATH, `${JSON.stringify(workspace, null, 2)}\n`);
-}
-
-function clearSelectedWorkspace() {
-  const fs = require('fs');
-  if (fs.existsSync(SELECTED_WORKSPACE_PATH)) fs.unlinkSync(SELECTED_WORKSPACE_PATH);
-}
-
-async function withSelectedWorkspaceContext(fn) {
-  const stored = readSelectedWorkspace();
-  if (stored?.workspaceId) {
-    const previousWorkspaceId = globalThis.__empiricalCliWorkspaceId || null;
-    globalThis.__empiricalCliWorkspaceId = stored.workspaceId;
-    try {
-      return await fn();
-    } finally {
-      globalThis.__empiricalCliWorkspaceId = previousWorkspaceId;
-    }
-  }
-
-  const accessToken = resolveAccessToken();
-  const clientId = getEnv('EMPIRICAL_CLIENT_ID') || readStoredOAuthClient()?.clientId;
-  if (!accessToken || !clientId) return fn();
-
-  const previousWorkspaceId = globalThis.__empiricalCliWorkspaceId || null;
-  globalThis.__empiricalCliWorkspaceId = null;
-  try {
-    const baseUrl = resolveApiBaseUrl();
-    const currentUrl = new URL(
-      `/oauth/clients/${encodeURIComponent(clientId)}/workspace-selection`,
-      baseUrl
-    ).toString();
-    try {
-      const payload = await httpJson(
-        currentUrl,
-        'GET',
-        null,
-        buildApiAuthHeaders(accessToken),
-        WORKSPACE_CONTEXT_TIMEOUT_MS
-      );
-      globalThis.__empiricalCliWorkspaceId = payload?.current?.workspaceId || null;
-    } catch (_error) {
-      globalThis.__empiricalCliWorkspaceId = null;
-    }
-    return await fn();
-  } finally {
-    globalThis.__empiricalCliWorkspaceId = previousWorkspaceId;
-  }
-}
-
-module.exports = {
-  withSelectedWorkspaceContext,
-  readSelectedWorkspace,
-  writeSelectedWorkspace,
-  clearSelectedWorkspace
-};
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+const { httpJson } = require('./http');
+const { getEnv } = require('./env');
+const { resolveAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { readStoredOAuthClient } = require('./oauthClient');
+const { readJsonIfExists, writeFile, ensureDir } = require('./fsUtils');
+
+const WORKSPACE_CONTEXT_TIMEOUT_MS = 2000;
+const SELECTED_WORKSPACE_PATH = path.join(os.homedir(), '.empirical', 'workspace-selection.json');
+
+// Per-project binding (2026-09-24). The global selection above is one file per machine, so any
+// session in any repo flips it for every other session: a WOB session left the CLI on the WOB team
+// workspace and every tag-scoped recall from an empirical_v2 session returned [] while the memories
+// existed. The unit that actually varies is the project directory, like git config, so a project
+// can pin its workspace in <repo>/.empirical/workspace.json and `use` writes there by default when
+// run inside a git repo. Resolution order, first hit wins: env, project, global, then the server's
+// per-client selection exactly as before. No project file and no env means today's behavior.
+const PROJECT_WORKSPACE_DIRNAME = '.empirical';
+const PROJECT_WORKSPACE_FILENAME = 'workspace.json';
+const WORKSPACE_ENV_VAR = 'EMPIRICAL_WORKSPACE_ID';
+
+function readSelectedWorkspace() {
+  const value = readJsonIfExists(SELECTED_WORKSPACE_PATH);
+  return value && typeof value.workspaceId === 'string' ? value : null;
+}
+
+function writeSelectedWorkspace(workspace) {
+  ensureDir(path.dirname(SELECTED_WORKSPACE_PATH));
+  writeFile(SELECTED_WORKSPACE_PATH, `${JSON.stringify(workspace, null, 2)}\n`);
+}
+
+function clearSelectedWorkspace() {
+  if (fs.existsSync(SELECTED_WORKSPACE_PATH)) fs.unlinkSync(SELECTED_WORKSPACE_PATH);
+}
+
+/**
+ * Nearest <dir>/.empirical/workspace.json walking up from `startDir` to the filesystem root.
+ * Returns { path, value } or null. A malformed file is ignored rather than fatal: a broken
+ * binding must not take the CLI down, it just falls through to the next source.
+ */
+function findProjectWorkspaceFile(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    const candidate = path.join(dir, PROJECT_WORKSPACE_DIRNAME, PROJECT_WORKSPACE_FILENAME);
+    const value = readJsonIfExists(candidate);
+    if (value && typeof value.workspaceId === 'string' && value.workspaceId.trim()) {
+      return { path: candidate, value };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * The git toplevel for `cwd`, or null outside a repo (or without git). Used to decide where
+ * `workspace use` writes by default and where the project binding lives.
+ */
+function findGitRoot(cwd = process.cwd()) {
+  try {
+    const out = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8'
+    });
+    const root = String(out || '').trim();
+    return root ? path.resolve(root) : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function projectWorkspacePathFor(rootDir) {
+  return path.join(rootDir, PROJECT_WORKSPACE_DIRNAME, PROJECT_WORKSPACE_FILENAME);
+}
+
+function writeProjectWorkspace(rootDir, workspace) {
+  const filePath = projectWorkspacePathFor(rootDir);
+  ensureDir(path.dirname(filePath));
+  writeFile(filePath, `${JSON.stringify({ ...workspace, boundAt: new Date().toISOString() }, null, 2)}\n`);
+  return filePath;
+}
+
+function clearProjectWorkspace(rootDir) {
+  const filePath = projectWorkspacePathFor(rootDir);
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+    return filePath;
+  }
+  return null;
+}
+
+/**
+ * The single answer to "which workspace does this CLI invocation act on", before asking the
+ * server. Every memory command and `workspace current` read this, so reads and writes can never
+ * disagree again. Returns { workspaceId, label, key, source, path } or null when nothing local
+ * is set (the caller then falls back to the server's per-client selection).
+ */
+function resolveLocalWorkspaceSelection({ cwd = process.cwd(), env = process.env } = {}) {
+  const fromEnv = String(env[WORKSPACE_ENV_VAR] || '').trim();
+  if (fromEnv) {
+    return { workspaceId: fromEnv, label: null, key: null, source: 'env', path: WORKSPACE_ENV_VAR };
+  }
+  const project = findProjectWorkspaceFile(cwd);
+  if (project) {
+    const { workspaceId, label = null, key = null } = project.value;
+    return { workspaceId: workspaceId.trim(), label, key, source: 'project', path: project.path };
+  }
+  const global = readSelectedWorkspace();
+  if (global) {
+    return { workspaceId: global.workspaceId, label: global.label || null, key: global.key || null, source: 'global', path: SELECTED_WORKSPACE_PATH };
+  }
+  return null;
+}
+
+async function withSelectedWorkspaceContext(fn) {
+  const local = resolveLocalWorkspaceSelection();
+  if (local?.workspaceId) {
+    const previousWorkspaceId = globalThis.__empiricalCliWorkspaceId || null;
+    globalThis.__empiricalCliWorkspaceId = local.workspaceId;
+    try {
+      return await fn();
+    } finally {
+      globalThis.__empiricalCliWorkspaceId = previousWorkspaceId;
+    }
+  }
+
+  const accessToken = resolveAccessToken();
+  const clientId = getEnv('EMPIRICAL_CLIENT_ID') || readStoredOAuthClient()?.clientId;
+  if (!accessToken || !clientId) return fn();
+
+  const previousWorkspaceId = globalThis.__empiricalCliWorkspaceId || null;
+  globalThis.__empiricalCliWorkspaceId = null;
+  try {
+    const baseUrl = resolveApiBaseUrl();
+    const currentUrl = new URL(
+      `/oauth/clients/${encodeURIComponent(clientId)}/workspace-selection`,
+      baseUrl
+    ).toString();
+    try {
+      const payload = await httpJson(
+        currentUrl,
+        'GET',
+        null,
+        buildApiAuthHeaders(accessToken),
+        WORKSPACE_CONTEXT_TIMEOUT_MS
+      );
+      globalThis.__empiricalCliWorkspaceId = payload?.current?.workspaceId || null;
+    } catch (_error) {
+      globalThis.__empiricalCliWorkspaceId = null;
+    }
+    return await fn();
+  } finally {
+    globalThis.__empiricalCliWorkspaceId = previousWorkspaceId;
+  }
+}
+
+module.exports = {
+  withSelectedWorkspaceContext,
+  resolveLocalWorkspaceSelection,
+  readSelectedWorkspace,
+  writeSelectedWorkspace,
+  clearSelectedWorkspace,
+  findProjectWorkspaceFile,
+  findGitRoot,
+  projectWorkspacePathFor,
+  writeProjectWorkspace,
+  clearProjectWorkspace,
+  WORKSPACE_ENV_VAR,
+  SELECTED_WORKSPACE_PATH
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empirical-gauzza/cli",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "description": "Persistent cross-tool memory for AI agents. Give Claude Code, Codex, Copilot, Cursor, and ChatGPT one shared memory: save project context once, recall it everywhere via CLI or MCP.",
   "keywords": [
     "memory",