claude-memory-admin 1.10.1 → 1.11.0

package/src/settings.mjs

@@ -11,10 +11,15 @@
 //               ->  .claude/settings.json  ->  ~/.claude/settings.json
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
-export const USER_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+import { configPath, configSource, expandHome, fixedProjectDirName, isAbsolutePath } from './config.mjs';
+
+export const USER_SETTINGS = configPath('settings.json');
+
+// Re-exported because this is where every caller has always imported it from,
+// and because settings values are the main thing that arrives `~/`-prefixed.
+export { expandHome };
 
 /** Default when nothing sets cleanupPeriodDays; transcripts older than this are swept. */
 export const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
@@ -24,6 +29,7 @@ export const SETTINGS_SEVERITY = {
   unreadable: 'bad',
   'not-object': 'bad',
   'invalid-auto-memory-directory': 'bad',
+  'invalid-config-dir': 'bad',
 };
 
 export function summariseSettings(problems) {
@@ -149,11 +155,6 @@ export function lookupPath(layers, keyPath) {
   return null;
 }
 
-export function expandHome(value) {
-  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
-  return value;
-}
-
 /**
  * Where the auto memory store lives, per settings.
  *
@@ -171,12 +172,55 @@ export function resolveMemoryDirectory(options = {}) {
 
   const raw = typeof found.value === 'string' ? found.value.trim() : '';
   if (!raw) return null;
-  if (!raw.startsWith('/') && !raw.startsWith('~/') && !/^[A-Za-z]:[\\/]/.test(raw)) {
+  // Accepted on every platform, not only the one this is running on: a settings
+  // file is routinely shared between machines, and a Windows path read on macOS
+  // is a path this tool cannot open but must still report as intentional.
+  const rooted = raw.startsWith('~/') || raw.startsWith('~\\')
+    || isAbsolutePath(raw, 'win32') || isAbsolutePath(raw, 'linux');
+  if (!rooted) {
     return { ...found, raw, path: null, invalid: 'not an absolute or ~/ path' };
   }
   return { ...found, raw, path: expandHome(raw), invalid: null };
 }
 
+export const DISABLE_AUTO_MEMORY = 'CLAUDE_CODE_DISABLE_AUTO_MEMORY';
+
+/** The env-var convention Claude Code uses: set, and not "0" or "false". */
+function truthyEnv(value) {
+  if (value === null || value === undefined) return false;
+  const text = String(value).trim();
+  return Boolean(text) && text !== '0' && text !== 'false';
+}
+
+/**
+ * CLAUDE_CODE_DISABLE_AUTO_MEMORY, from either place it can be set.
+ *
+ * The process environment is the obvious one, but settings files carry an `env`
+ * block whose entries a session exports before it starts, so the same switch is
+ * equally settable in any of the five layers. Reading only process.env reported
+ * auto memory as on for anyone who had turned it off in a file - the reverse of
+ * what this tool is for.
+ */
+export function disableAutoMemoryEnv({ layers = null, projectDir = null, env = process.env } = {}) {
+  const raw = env[DISABLE_AUTO_MEMORY];
+  if (truthyEnv(raw)) {
+    return { disabling: true, value: raw, scope: 'env', file: null };
+  }
+
+  const found = lookupPath(layers || settingsLayers({ projectDir }), ['env', DISABLE_AUTO_MEMORY]);
+  if (found && truthyEnv(found.value)) {
+    return { disabling: true, value: found.value, scope: found.scope, file: found.file };
+  }
+
+  const value = raw ?? (found ? found.value : null);
+  return {
+    disabling: false,
+    value: value === undefined ? null : value,
+    scope: raw !== undefined && raw !== null ? 'env' : found?.scope ?? null,
+    file: raw !== undefined && raw !== null ? null : found?.file ?? null,
+  };
+}
+
 /**
  * Whether auto memory is on for a project, and what decided it.
  *
@@ -186,12 +230,14 @@ export function resolveMemoryDirectory(options = {}) {
  * local layer to read, so the answer is unknown rather than assumed.
  */
 export function autoMemoryState({ projectDir = null } = {}) {
-  const env = process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY;
-  if (env && env !== '0' && env !== 'false') {
-    return { enabled: false, setBy: 'CLAUDE_CODE_DISABLE_AUTO_MEMORY', scope: 'env', known: true };
+  const layers = settingsLayers({ projectDir });
+
+  const disabled = disableAutoMemoryEnv({ layers });
+  if (disabled.disabling) {
+    return { enabled: false, setBy: disabled.file || DISABLE_AUTO_MEMORY, scope: disabled.scope, known: true };
   }
 
-  const found = lookup(settingsLayers({ projectDir }), 'autoMemoryEnabled');
+  const found = lookup(layers, 'autoMemoryEnabled');
   if (found && typeof found.value === 'boolean') {
     return { enabled: found.value, setBy: found.file, scope: found.scope, known: true };
   }
@@ -263,8 +309,8 @@ export function settingsReport(options = {}) {
   const cleanup = keys.find((entry) => entry.key === 'cleanupPeriodDays');
   cleanup.normalized = cleanupPeriodDays(options);
 
-  const raw = process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY;
-  const disabling = Boolean(raw && raw !== '0' && raw !== 'false');
+  const disable = disableAutoMemoryEnv({ layers: reads.filter((read) => read.status === 'ok') });
+  const config = configSource();
 
   const problems = layers
     .filter((layer) => layer.status !== 'ok' && layer.status !== 'absent')
@@ -276,6 +322,16 @@ export function settingsReport(options = {}) {
       detail: layer.error,
     }));
 
+  if (config.invalid) {
+    problems.push({
+      kind: 'invalid-config-dir',
+      severity: SETTINGS_SEVERITY['invalid-config-dir'],
+      scope: 'env',
+      file: null,
+      detail: config.invalid,
+    });
+  }
+
   const directory = resolveMemoryDirectory(options);
   if (directory && directory.invalid) {
     problems.push({
@@ -292,9 +348,19 @@ export function settingsReport(options = {}) {
     layers,
     keys,
     env: {
-      name: 'CLAUDE_CODE_DISABLE_AUTO_MEMORY',
-      value: raw ?? null,
-      overrides: disabling ? 'autoMemoryEnabled' : null,
+      name: DISABLE_AUTO_MEMORY,
+      value: disable.value,
+      scope: disable.scope,
+      file: disable.file,
+      overrides: disable.disabling ? 'autoMemoryEnabled' : null,
+    },
+    configDir: {
+      name: 'CLAUDE_CONFIG_DIR',
+      path: config.path,
+      source: config.source,
+      value: config.raw,
+      invalid: config.invalid,
+      fixedProjectDirName: fixedProjectDirName(),
     },
     problems,
   };

package/src/stores.mjs

@@ -15,11 +15,13 @@
 // somewhere else first.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { listAllAgents, MEMORY_SCOPES } from './agents.mjs';
+import { canonicalPath, configDir, configPath, DEFAULT_CONFIG_DIR_NAME } from './config.mjs';
 import { listProjects, memoryDir, projectsRoot, shortLabel } from './projects.mjs';
+import { autoMemoryState } from './settings.mjs';
 
-export const AGENT_USER_DIR = path.join(os.homedir(), '.claude', 'agent-memory');
+export const AGENT_USER_DIR = configPath('agent-memory');
 export const AGENT_PROJECT_DIR = path.join('.claude', 'agent-memory');
 export const AGENT_LOCAL_DIR = path.join('.claude', 'agent-memory-local');
 
@@ -96,10 +98,15 @@ export function listAgentStores({ userDir = AGENT_USER_DIR, projectPaths = [] }
 
   // A repository can be reached through more than one project entry (a worktree
   // and its root), so the same directory must not be listed twice.
+  // Keyed on the canonical form: Windows and a default macOS volume are
+  // case-insensitive, so two spellings of one repository are one repository and
+  // would otherwise contribute the same agent store twice.
   const seen = new Set();
   for (const projectPath of projectPaths) {
-    if (!projectPath || !path.isAbsolute(projectPath) || seen.has(projectPath)) continue;
-    seen.add(projectPath);
+    if (!projectPath || !path.isAbsolute(projectPath)) continue;
+    const key = canonicalPath(projectPath);
+    if (seen.has(key)) continue;
+    seen.add(key);
     for (const [kind, relative] of [['agent-project', AGENT_PROJECT_DIR], ['agent-local', AGENT_LOCAL_DIR]]) {
       const parent = path.join(projectPath, relative);
       for (const name of agentDirs(parent)) {
@@ -113,6 +120,60 @@ export function listAgentStores({ userDir = AGENT_USER_DIR, projectPaths = [] }
     || a.sublabel.localeCompare(b.sublabel));
 }
 
+/**
+ * Join each subagent store to the definition that asks for it.
+ *
+ * A store directory on its own says nothing about whether a session still loads
+ * it: the `memory:` field in an agent file is what creates one, and that field
+ * can be changed to another scope or removed entirely without the directory it
+ * created ever going away. So the store is annotated with what the definitions
+ * actually say, and the cleanup checks in src/checks.mjs read those annotations
+ * rather than re-deriving them.
+ *
+ * The one rule that outranks all of it: subagent memory is part of auto memory,
+ * so when auto memory is off the `memory:` field has no effect at all - the
+ * agent launches with no memory instructions and no file tools, and every store
+ * on the machine is frozen where it stands.
+ */
+export function linkAgentStores(stores, agents, { autoMemory = null } = {}) {
+  const byName = new Map();
+  for (const agent of agents || []) {
+    const key = agent.name.toLowerCase();
+    if (!byName.has(key)) byName.set(key, []);
+    byName.get(key).push(agent);
+  }
+
+  return stores.map((store) => {
+    if (!store.kind.startsWith('agent-')) return store;
+
+    const candidates = (byName.get(store.agentName.toLowerCase()) || []).filter((agent) => {
+      // A project-scope definition only speaks for stores in its own repository.
+      if (agent.scope !== 'project' || !store.projectPath) return true;
+      return canonicalPath(agent.projectPath) === canonicalPath(store.projectPath);
+    });
+
+    const declaring = candidates.find((agent) => MEMORY_SCOPES[agent.memory] === store.kind) || null;
+    const other = declaring ? null : candidates.find((agent) => agent.memory) || null;
+    const inert = autoMemory ? autoMemory.enabled === false : false;
+
+    return {
+      ...store,
+      // Marks that the join actually ran. A store that was never linked knows
+      // nothing about its definitions, and "nothing is declared" and "nobody
+      // asked" have to stay distinguishable or the checks below report an
+      // orphan every time a caller builds a store on its own.
+      linkage: true,
+      declaredBy: declaring ? declaring.file : other ? other.file : null,
+      declaredScope: declaring ? declaring.memory : other ? other.memory : null,
+      declaringScope: declaring ? declaring.scope : other ? other.scope : null,
+      defined: candidates.length > 0,
+      linked: Boolean(declaring),
+      inert,
+      inertBy: inert ? autoMemory.setBy : null,
+    };
+  });
+}
+
 /** An auto-memory project, in the shape the rest of the app expects of a store. */
 function autoStore(project, root) {
   return {
@@ -133,8 +194,7 @@ function autoStore(project, root) {
  * `hasMemoryDir` false is what keeps it out of full-text search, which skips
  * stores without one, and out of everything else that reads memory files.
  */
-function globalStore(home) {
-  const dir = path.join(home, '.claude');
+function globalStore(dir) {
   return {
     id: storeId('global', dir),
     kind: 'global',
@@ -154,19 +214,26 @@ function globalStore(home) {
  * found under the project paths auto memory already resolved, so a repository this
  * tool has never seen a session for contributes nothing.
  *
- * `home` is a parameter because the global entry is about the real home directory
- * rather than the memory root, which --root can point somewhere else entirely.
+ * The config directory is a parameter because the global entry is about where
+ * Claude Code keeps its own files rather than about the memory root, which
+ * --root can point somewhere else entirely. `home` is the older spelling of the
+ * same idea and still accepted, since a home directory names exactly one config
+ * directory when CLAUDE_CONFIG_DIR is not set.
  */
-export function listStores(root = projectsRoot(), { home = os.homedir() } = {}) {
+export function listStores(root = projectsRoot(), { home = null, dir = null, agents = null } = {}) {
+  const global = dir || (home ? path.join(home, DEFAULT_CONFIG_DIR_NAME) : configDir());
   const projects = listProjects(root);
   const projectPaths = projects
     .filter((project) => project.pathExists)
     .flatMap((project) => [project.path, ...(project.workingDirs || [])]);
 
+  const agentStores = listAgentStores({ projectPaths });
+  const definitions = agents || listAllAgents({ projectPaths });
+
   return [
-    globalStore(home),
+    globalStore(global),
     ...projects.map((project) => autoStore(project, root)),
-    ...listAgentStores({ projectPaths }),
+    ...linkAgentStores(agentStores, definitions, { autoMemory: autoMemoryState() }),
   ];
 }
 

package/src/toolrun.mjs

@@ -9,20 +9,25 @@ export const num = (value) => (typeof value === 'number' && Number.isFinite(valu
 export const text = (value) => (typeof value === 'string' ? value : '');
 export const pct = (part, whole) => (whole > 0 ? (part / whole) * 100 : 0);
 
-function candidateNames(binary, env) {
-  if (process.platform !== 'win32') return [binary];
-  return text(env.PATHEXT || '.EXE').split(';').filter(Boolean).map((ext) => binary + ext.toLowerCase());
+function candidateNames(binary, env, platform) {
+  if (platform !== 'win32') return [binary];
+  return text(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((ext) => binary + ext.toLowerCase());
 }
 
-export function findBinary(binary, env = process.env) {
+export function findBinary(binary, env = process.env, platform = process.platform) {
+  // PATH is split on this process's delimiter, not the target platform's, since
+  // the PATH being searched is the one this process actually has.
   const dirs = text(env.PATH).split(path.delimiter).filter(Boolean);
-  const names = candidateNames(binary, env);
+  const names = candidateNames(binary, env, platform);
   for (const dir of dirs) {
     for (const name of names) {
       const candidate = path.join(dir, name);
       try {
         if (!fs.statSync(candidate).isFile()) continue;
-        fs.accessSync(candidate, fs.constants.X_OK);
+        // Windows has no execute bit, and Node answers X_OK there from the
+        // file's existence alone. Asking for it is meaningless rather than
+        // harmless: it is the check that would reject a perfectly good .cmd.
+        if (platform !== 'win32') fs.accessSync(candidate, fs.constants.X_OK);
         return { found: true, path: candidate };
       } catch {
         continue;
@@ -32,10 +37,45 @@ export function findBinary(binary, env = process.env) {
   return { found: false, path: null };
 }
 
-export function runBinary(binary, args, { cwd, timeout = TIMEOUT_MS } = {}) {
+/**
+ * How to actually start a program on Windows.
+ *
+ * npm installs `rtk` and `ccusage` as `rtk.cmd`, and a batch file is not a
+ * program: execFile refuses to run one outright, and would not find it by bare
+ * name in the first place, since only the shell applies PATHEXT. So the resolved
+ * file is handed to cmd.exe the way Node's own shell support does - `/d /s /c`
+ * with one pre-quoted command string and verbatim arguments - and the arguments
+ * are quoted here rather than trusted to survive a second round of parsing.
+ */
+export function windowsInvocation(binary, args, env = process.env) {
+  const found = findBinary(binary, env, 'win32');
+  const target = found.found ? found.path : binary;
+  if (!/\.(cmd|bat)$/i.test(target)) return { file: target, args, options: {} };
+
+  const quote = (value) => `"${String(value).replace(/"/g, '""')}"`;
+  const command = [target, ...args].map(quote).join(' ');
+  return {
+    file: env.COMSPEC || 'cmd.exe',
+    args: ['/d', '/s', '/c', command],
+    options: { windowsVerbatimArguments: true },
+  };
+}
+
+export function runBinary(binary, args, { cwd, timeout = TIMEOUT_MS, env = process.env } = {}) {
   return new Promise((resolve, reject) => {
-    const options = { cwd, timeout, maxBuffer: MAX_BUFFER, windowsHide: true, encoding: 'utf8' };
-    execFile(binary, args, options, (err, stdout, stderr) => {
+    const invocation = process.platform === 'win32'
+      ? windowsInvocation(binary, args, env)
+      : { file: binary, args, options: {} };
+
+    const options = {
+      cwd,
+      timeout,
+      maxBuffer: MAX_BUFFER,
+      windowsHide: true,
+      encoding: 'utf8',
+      ...invocation.options,
+    };
+    execFile(invocation.file, invocation.args, options, (err, stdout, stderr) => {
       if (!err) return resolve(stdout);
       if (err.code === 'ENOENT') return reject(new Error(`${binary} is not on this process PATH`));
       if (err.killed) return reject(new Error(`${binary} ${args[0]} was still running after ${timeout}ms and was stopped`));