@empirical-gauzza/cli 1.0.35 → 1.0.37

package/lib/usageCommands.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// `empirical usage`: memory, blueprint installs this month, and Empirical Tokens (spec 8.4).
+// Reads GET /api/v1/billing/me. The Empirical Tokens line appears only while they are enforced
+// for this account, so the command stays dark until rollout. A missing or null
+// empiricalTokenUsage, or any mode other than 'enforce', is hidden.
+const { httpJson, printApiError } = require('./http');
+const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { log } = require('./ui');
+const { resetLabel } = require('./empiricalTokensFormat');
+
+const fmt = (n) => Number(n).toLocaleString('en-US');
+
+function empiricalTokensLine(usage) {
+  if (!usage || usage.mode !== 'enforce') return null;
+  // An admin account has no limit: the server sends unlimited true with null granted and remaining.
+  if (usage.unlimited) return `Empirical Tokens: unlimited. ${fmt(usage.spent || 0)} used this month.`;
+  // Free has nothing granted (Writing Voice is paid only): same idea as the portal card, not '0 of 0 left'.
+  if (usage.tier === 'free' && !(Number(usage.granted) + Number(usage.adjust || 0) > 0)) return 'Empirical Tokens: building a writing voice is part of the paid plans.';
+  const reset = resetLabel(usage.resetsAt);
+  return `Empirical Tokens: ${fmt(usage.remaining)} of ${fmt(usage.granted + usage.adjust)} left this month.${reset ? ` Resets ${reset}.` : ''}`;
+}
+
+async function fetchBillingMe(timeoutMs = 0) {
+  const token = requireAccessToken();
+  const url = new URL('/api/v1/billing/me', resolveApiBaseUrl()).toString();
+  const response = await httpJson(url, 'GET', null, buildApiAuthHeaders(token), timeoutMs);
+  return response && response.data ? response.data : response;
+}
+
+async function runUsageCommand(args) {
+  let data;
+  try {
+    data = await fetchBillingMe();
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+  if (args.includes('--json')) {
+    log(JSON.stringify({ memoryUsage: data.memoryUsage, blueprintUsage: data.blueprintUsage, empiricalTokenUsage: data.empiricalTokenUsage && data.empiricalTokenUsage.mode === 'enforce' ? data.empiricalTokenUsage : null }, null, 2));
+    return;
+  }
+  const memory = data.memoryUsage || {};
+  log(memory.unlimited ? `Memory: ${fmt(memory.used)} used (no plan cap).` : `Memory: ${fmt(memory.used)} of ${fmt(memory.limit)} used.`);
+  const installs = data.blueprintUsage || {};
+  const across = typeof installs.accountUsed === 'number' ? ` (${fmt(installs.accountUsed)} across all workspaces)` : '';
+  log(installs.unlimited ? `Blueprint installs this month: ${fmt(installs.used)}${across}.` : `Blueprint installs this month: ${fmt(installs.used)} of ${fmt(installs.limit)}${across}.`);
+  const line = empiricalTokensLine(data.empiricalTokenUsage);
+  if (line) log(line);
+}
+
+module.exports = { runUsageCommand, empiricalTokensLine, fetchBillingMe };

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,33 +1,33 @@
-{
-  "name": "@empirical-gauzza/cli",
-  "version": "1.0.35",
-  "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",
-    "mcp",
-    "agent memory",
-    "ai memory",
-    "claude",
-    "chatgpt",
-    "model context protocol",
-    "persistent memory",
-    "claude-code",
-    "codex",
-    "knowledge base"
-  ],
-  "type": "commonjs",
-  "license": "MIT",
-  "homepage": "https://empirical.gauzza.com/docs/cli-details",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "empirical": "bin/empirical.js"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "gray-matter": "^4.0.3"
-  }
-}
+{
+  "name": "@empirical-gauzza/cli",
+  "version": "1.0.37",
+  "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",
+    "mcp",
+    "agent memory",
+    "ai memory",
+    "claude",
+    "chatgpt",
+    "model context protocol",
+    "persistent memory",
+    "claude-code",
+    "codex",
+    "knowledge base"
+  ],
+  "type": "commonjs",
+  "license": "MIT",
+  "homepage": "https://empirical.gauzza.com/docs/cli-details",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "empirical": "bin/empirical.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  }
+}