@empirical-gauzza/cli 1.0.28 → 1.0.29

package/bin/empirical.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 

package/lib/installers/hooks.js

@@ -110,37 +110,125 @@ function main() {
     process.exit(0);
   }
 
-  var result = runMemoryQuery([
-    'memory', 'query',
-    '--match', 'project context, conventions, recent decisions, user preferences',
-    '--top-k', '8'
-  ]);
-
-  if (!result || result.status !== 0 || !result.stdout) {
-    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
-    process.exit(0);
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
   }
 
-  var results;
-  try {
-    results = JSON.parse(result.stdout);
-  } catch (e) {
-    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-    process.exit(0);
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
+  }
+
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
+  }
+
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : 'project context, conventions, recent decisions, user preferences';
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
   }
 
-  if (!Array.isArray(results) || results.length === 0) {
+  if (todos.length === 0 && context.length === 0) {
     appendLog('memory query returned zero results');
     process.exit(0);
   }
 
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
   appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
 
-  var lines = results.slice(0, 8).map(function (r) {
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
     var category = r && r.category ? r.category : 'memory';
-    var summary = r && r.summary ? r.summary : '';
-    return '- [' + category + '] ' + summary;
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
   });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
 
   console.log('Empirical memory context for this session:\\n' + lines.join('\\n'));
   process.exit(0);
@@ -259,40 +347,126 @@ function main() {
     process.exit(0);
   }
 
-  var result = runMemoryQuery([
-    'memory', 'query',
-    '--match', 'project context, conventions, recent decisions, user preferences',
-    '--top-k', '8'
-  ]);
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
+  }
 
-  if (!result || result.status !== 0 || !result.stdout) {
-    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
-    emitContext('');
-    process.exit(0);
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
   }
 
-  var results;
-  try {
-    results = JSON.parse(result.stdout);
-  } catch (e) {
-    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-    emitContext('');
-    process.exit(0);
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
+  }
+
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : 'project context, conventions, recent decisions, user preferences';
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
   }
 
-  if (!Array.isArray(results) || results.length === 0) {
+  if (todos.length === 0 && context.length === 0) {
     appendLog('memory query returned zero results');
     emitContext('');
     process.exit(0);
   }
 
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
   appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
 
-  var lines = results.slice(0, 8).map(function (r) {
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
     var category = r && r.category ? r.category : 'memory';
-    var summary = r && r.summary ? r.summary : '';
-    return '- [' + category + '] ' + summary;
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
   });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
 
   console.log(JSON.stringify({
     hookSpecificOutput: {
@@ -400,38 +574,124 @@ function main() {
     process.exit(0);
   }
 
-  var result = runMemoryQuery([
-    'memory', 'query',
-    '--match', 'project context, conventions, recent decisions, user preferences',
-    '--top-k', '8'
-  ]);
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
+  }
 
-  if (!result || result.status !== 0 || !result.stdout) {
-    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
-    console.log('{}');
-    process.exit(0);
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
   }
 
-  var results;
-  try {
-    results = JSON.parse(result.stdout);
-  } catch (e) {
-    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-    console.log('{}');
-    process.exit(0);
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
   }
 
-  if (!Array.isArray(results) || results.length === 0) {
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : 'project context, conventions, recent decisions, user preferences';
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
+  }
+
+  if (todos.length === 0 && context.length === 0) {
     appendLog('memory query returned zero results');
     console.log('{}');
     process.exit(0);
   }
 
-  var lines = results.slice(0, 8).map(function (r) {
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
     var category = r && r.category ? r.category : 'memory';
-    var summary = r && r.summary ? r.summary : '';
-    return '- [' + category + '] ' + summary;
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
   });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
 
   // Logged only - Copilot's sessionStart event has no field that surfaces this to the model.
   appendLog('memory query returned ' + results.length + ' result(s) (session-start has no output channel to inject them, logged only): ' + lines.join(' | '));
@@ -840,7 +1100,7 @@ function installClaudeHooks(pluginNames) {
   for (const matcher of ['startup', 'resume', 'compact']) {
     settings.hooks.SessionStart.push({
       matcher,
-      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 15 }]
+      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 25 }]
     });
   }
 
@@ -969,7 +1229,7 @@ function installCodexHooks(pluginNames) {
   for (const matcher of ['startup', 'resume']) {
     hooksFile.hooks.SessionStart.push({
       matcher,
-      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommandWindows, timeout: 15 }]
+      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommandWindows, timeout: 25 }]
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empirical-gauzza/cli",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "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",