claude-memory-admin 1.10.0 → 1.10.2

package/README.md

@@ -108,9 +108,25 @@ safety net and not a place you browse.
   `~/.claude/settings.json`. A value that is neither absolute nor `~/`-prefixed
   is reported rather than quietly ignored.
 - **Whether Claude is still writing.** A project with `autoMemoryEnabled` off, or
-  `CLAUDE_CODE_DISABLE_AUTO_MEMORY` set, has a store that will never grow again,
-  which on disk is indistinguishable from one Claude has not learned anything
-  about yet. The project header says which it is, and names the file that decided.
+  `CLAUDE_CODE_DISABLE_AUTO_MEMORY` set - in the environment or in the `env`
+  block of any settings layer - has a store that will never grow again, which on
+  disk is indistinguishable from one Claude has not learned anything about yet.
+  The project header says which it is, and names the file that decided.
+- **Which subagent still asks for its memory.** A subagent store exists because
+  some agent file carried a `memory: user | project | local` field, and it stays
+  exactly where it is after that field moves to another scope or is removed. Each
+  store is shown next to the definition that declares it - from `agents/` in the
+  user scope and in each repository - and one that nothing declares any more is
+  marked `orphan`, one whose agent moved scope `moved`. Because subagent memory
+  is part of auto memory, turning auto memory off marks every one of them
+  `inert`: the `memory:` field stops having any effect, and the agent starts with
+  no memory instructions and no file tools at all.
+- **A config directory that is not `~/.claude`.** `CLAUDE_CONFIG_DIR` moves the
+  projects root, the agent definitions, the agent memory, the user `CLAUDE.md` and
+  rules, and the settings file together, and all of them are read from wherever it
+  points. The Environment tab names the directory and says whether the environment
+  or the default chose it. A `~/` written by hand is expanded here rather than left
+  to the shell, because `cmd` and PowerShell do not expand it.
 - **Search across every project**: names, descriptions, bodies and index hooks,
   with snippets and match highlighting. Press `/` to jump to it.
 - **Read each memory** with its frontmatter as structured metadata and
@@ -291,15 +307,22 @@ five and shows, per key, the value that wins and the ones it shadows, struck
 through, each labelled with the file it came from:
 
 `autoMemoryEnabled`, `autoMemoryDirectory`, `claudeMdExcludes` and
-`cleanupPeriodDays`, plus `CLAUDE_CODE_DISABLE_AUTO_MEMORY` when it is set in the
-environment, where it outranks every file.
+`cleanupPeriodDays`, plus `CLAUDE_CODE_DISABLE_AUTO_MEMORY` wherever it is set:
+in the environment, where it outranks every file, or in the `env` block of any of
+the five, which a session exports before it starts and which reading `process.env`
+alone would miss. `CLAUDE_CONFIG_DIR` is named here too, since it decides where
+all five of those files are looked for in the first place.
 
 It also names the failures that are otherwise silent:
 
 - A settings file that exists but is not valid JSON. Claude Code ignores the
   whole file, so every value in it is doing nothing, and nothing says so.
 - A file that parses but is not an object, or cannot be read at all.
-- An `autoMemoryDirectory` that is neither absolute nor `~/`-prefixed.
+- An `autoMemoryDirectory` that is neither absolute nor `~/`-prefixed. A Windows
+  path is accepted on any platform, because a settings file is routinely shared
+  between machines.
+- A `CLAUDE_CONFIG_DIR` that is not absolute, which Claude Code would not accept
+  either: the default is used and the fact is reported rather than swallowed.
 - A value Claude Code accepts the key of but not the number, like a
   `cleanupPeriodDays` below 1: it shows what is written *and* what applies.
 
@@ -453,6 +476,13 @@ claude-memory-admin --root /tmp/memory-snapshot
 ## Safety
 
 - Binds `127.0.0.1`; no telemetry, no network calls.
+- Runs on macOS, Linux and Windows. Line endings are the part of that which is not
+  cosmetic: a `MEMORY.md` saved by a Windows editor is CRLF, and a carriage return
+  is not something JavaScript's `.` matches, so a file like that once parsed as if
+  it were empty - no index entries, no frontmatter, every memory an orphan. It is
+  read correctly now, and a rewrite ends its lines the way it found them: a file
+  that came back half CRLF and half LF would show every line as changed in git, on
+  a change you never made.
 - Reads only `~/.claude/projects`, the agent memory directories and the `CLAUDE.md`
   chain, unless you switch on the path check above, which then also walks that one
   project's directory. It only ever reads: no path a memory names is opened, only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-admin",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Browse, audit and prune the auto memory Claude Code keeps under ~/.claude/projects",
   "keywords": [
     "claude",

package/public/ui.mjs

@@ -277,6 +277,8 @@ export const contextTags = 'mb-1 flex flex-wrap gap-1.5';
 export const contextFile = 'font-mono text-2xs break-words text-fg';
 export const contextSize = 'font-mono text-2xs whitespace-nowrap text-fg-subtle';
 export const contextRowButton = 'flex w-full cursor-pointer items-baseline justify-between gap-3.5 border-0 border-b border-line bg-transparent px-1 py-1.5 text-left transition-colors last:border-b-0 hover:bg-surface-sunken';
+export const contextRowStatic = 'flex w-full items-baseline justify-between gap-3.5 border-0 border-b border-line px-1 py-1.5 text-left last:border-b-0';
+export const toolMissingBody = 'mb-2.5 px-1';
 export const contextCaret = 'mr-1.5 inline-block font-mono text-2xs text-fg-subtle';
 export const contextBody = 'mb-1.5 max-h-[28rem] overflow-y-auto rounded-md border border-line bg-surface-sunken px-3.5 py-2.5';
 

package/public/views/cost.mjs

@@ -18,8 +18,37 @@ const AGENT_PROBLEMS = {
   'name-mismatch': 'Name and filename disagree',
   'unknown-model': 'Unrecognised model',
   'unknown-effort': 'Unrecognised effort',
+  'unknown-memory-scope': 'Unrecognised memory scope',
 };
 
+function memoryLine(agent, stores) {
+  if (!agent.memory) {
+    const stale = stores.filter((store) => store.agentName === agent.name && !store.linked);
+    if (!stale.length) return null;
+    return node('div', { class: ui.agentTools }, [
+      node('span', { class: ui.badge('warn'), text: 'no memory:' }),
+      node('span', {
+        text: ` this agent declares no memory scope, but ${stale.length === 1 ? 'a directory it once wrote' : `${stale.length} directories it once wrote`} ${stale.length === 1 ? 'is' : 'are'} still on disk and nothing loads ${stale.length === 1 ? 'it' : 'them'}.`,
+      }),
+    ]);
+  }
+
+  const mine = stores.filter((store) => store.agentName === agent.name && store.linked);
+  const inert = mine.some((store) => store.inert);
+  const count = mine.reduce((sum, store) => sum + store.memoryCount, 0);
+
+  const parts = [
+    node('span', { class: ui.scopeBadge(agent.memory), text: `memory: ${agent.memory}` }),
+  ];
+  if (inert) parts.push(node('span', { class: ui.badge('warn'), text: 'inert' }));
+  parts.push(node('span', {
+    text: mine.length
+      ? ` ${count} ${count === 1 ? 'memory' : 'memories'} in ${mine.length === 1 ? 'its store' : `${mine.length} stores`}${inert ? ', frozen while auto memory is off' : ''}.`
+      : ' no store yet - the directory appears the first time it saves something.',
+  }));
+  return node('div', { class: ui.agentTools }, parts);
+}
+
 const show = (value) => (value === undefined || value === null ? 'unset' : JSON.stringify(value));
 
 const optionText = (option) => (option.note ? `${option.label} (${option.note})` : option.label);
@@ -79,7 +108,12 @@ async function saveAgent(file, field, value) {
       body: JSON.stringify({ file, field, value }),
     });
     if (state.storeId !== id) return;
-    state.aux.cost = { ...state.aux.cost, agents: data.agents, agentsDirExists: data.agentsDirExists };
+    state.aux.cost = {
+      ...state.aux.cost,
+      agents: data.agents,
+      agentsDirExists: data.agentsDirExists,
+      agentStores: data.agentStores,
+    };
     toast(value === null ? `Cleared ${field} in ${file}` : `${file}: ${field} = ${value}`);
   } catch (err) {
     toast(err.message, { error: true });
@@ -138,21 +172,30 @@ function settingCard(entry, writable) {
   return card;
 }
 
-function agentRow(agent, fields) {
+function agentRow(agent, fields, stores) {
   const row = node('div', { class: ui.agentRow });
 
-  row.append(node('div', { class: ui.agentTop }, [
+  const top = [
     node('span', { class: ui.agentName, text: agent.name }),
-    node('span', { class: ui.agentFile, text: agent.file }),
-  ]));
+    node('span', { class: ui.agentFile, text: agent.projectPath ? `${agent.projectPath}/.claude/agents/${agent.file}` : agent.file }),
+  ];
+  if (agent.scope === 'project') top.push(node('span', { class: ui.scopeBadge('project'), text: 'project' }));
+  row.append(node('div', { class: ui.agentTop }, top));
 
   if (agent.description) row.append(node('p', { class: ui.agentDesc, text: agent.description }));
   if (agent.tools) row.append(node('div', { class: ui.agentTools, text: `tools: ${agent.tools}` }));
 
-  row.append(node('div', { class: ui.agentControls }, [
-    labelled('model', picker(fields.model.options, agent.model, (value) => saveAgent(agent.file, 'model', value))),
-    labelled('effort', picker(fields.effort.options, agent.effort, (value) => saveAgent(agent.file, 'effort', value))),
-  ]));
+  const memory = memoryLine(agent, stores);
+  if (memory) row.append(memory);
+
+  if (agent.writable) {
+    row.append(node('div', { class: ui.agentControls }, [
+      labelled('model', picker(fields.model.options, agent.model, (value) => saveAgent(agent.file, 'model', value))),
+      labelled('effort', picker(fields.effort.options, agent.effort, (value) => saveAgent(agent.file, 'effort', value))),
+    ]));
+  } else {
+    row.append(node('div', { class: ui.agentTools, text: `model: ${agent.model || 'inherit'}, effort: ${agent.effort || 'default'} - read-only, this file lives in a repository.` }));
+  }
 
   for (const problem of agent.problems) {
     row.append(issue(
@@ -181,7 +224,7 @@ function agentsCard(data) {
     return card;
   }
 
-  for (const agent of data.agents) card.append(agentRow(agent, data.agentFields));
+  for (const agent of data.agents) card.append(agentRow(agent, data.agentFields, data.agentStores || []));
   return card;
 }
 

package/public/views/header.mjs

@@ -41,7 +41,7 @@ function segmentVisible(tab, segment, store) {
   }
   if (segment === 'instructions') return global || hasProjectDir(store);
   if (segment === 'cost') return global;
-  if (segment === 'tools') return state.tools.some((tool) => tool.found);
+  if (segment === 'tools') return state.tools.length > 0;
   if (global) return false;
   if (segment === 'sessions') return Boolean(store.sessions?.count);
   return true;

package/public/views/issue.mjs

@@ -258,5 +258,29 @@ export function renderIssue(item, memories) {
     );
   }
 
+  if (item.kind === 'agent-memory-inert') {
+    return issue(
+      'Auto memory is off, so this store is frozen',
+      `subagent memory is part of auto memory${item.setBy ? `, and ${item.setBy} turns it off` : ' and it is turned off'}. The memory: field on ${item.agentName} has no effect while that is the case: the agent starts with no memory instructions and no file tools, so nothing here is read and nothing new is written.`,
+      { bad },
+    );
+  }
+
+  if (item.kind === 'agent-store-orphan') {
+    return issue(
+      'Nothing declares this store any more',
+      `${item.defined ? `${item.agentName} exists but no longer carries a memory: field` : `no agent named ${item.agentName} was found in any scope`}. A store is created by that field and outlives it, so this directory is still holding what it learned and no session will read it again.`,
+      { bad },
+    );
+  }
+
+  if (item.kind === 'agent-store-scope-mismatch') {
+    return issue(
+      `${item.agentName} keeps its memory in the ${item.declaredScope} scope now`,
+      `this store is the ${item.scope} one${item.declaredBy ? `, but ${item.declaredBy} declares memory: ${item.declaredScope}` : ''}. The live store is the ${item.declaredScope} one; this is what the agent wrote before the field changed.`,
+      { bad },
+    );
+  }
+
   return issue(item.kind, JSON.stringify(item));
 }

package/public/views/stores.mjs

@@ -11,6 +11,26 @@ function storeSubtitle(store) {
   return `${scope} · ${store.sublabel}`;
 }
 
+function agentMarker(store) {
+  if (!String(store.kind).startsWith('agent-') || !store.linkage) return null;
+  if (store.inert) {
+    return { text: 'inert', title: `Auto memory is off${store.inertBy ? ` (${store.inertBy})` : ''}, so the memory: field has no effect and this store is frozen.` };
+  }
+  if (store.linked) return null;
+  if (store.declaredScope) {
+    return {
+      text: 'moved',
+      title: `${store.agentName} now declares memory: ${store.declaredScope}, so the live store is elsewhere and this one is stale.`,
+    };
+  }
+  return {
+    text: 'orphan',
+    title: store.defined
+      ? `${store.agentName} exists but declares no memory: field any more, so nothing loads this store.`
+      : `No agent named ${store.agentName} was found in any scope, so nothing loads this store.`,
+  };
+}
+
 function issueTitle(store) {
   const parts = [];
   if (store.issueCount) parts.push(`${store.issueCount} to fix in Cleanup`);
@@ -32,6 +52,7 @@ function storeButton(store) {
   const global = store.kind === 'global';
   const health = !global && !store.hasMemoryDir ? 'none' : store.severity || 'ok';
   const off = store.autoMemory && store.autoMemory.known && !store.autoMemory.enabled;
+  const marker = agentMarker(store);
   const active = state.activeSessions.filter((s) => s.storeId === store.id);
   return node('button', {
     class: ui.storeItem({ active: store.id === state.storeId, empty: !global && !store.hasMemoryDir }),
@@ -43,6 +64,7 @@ function storeButton(store) {
       node('span', { class: ui.storeName, text: store.label }),
       active.length ? node('span', { class: ui.dot('ok'), title: activeTitle(active) }) : null,
       off ? node('span', { class: ui.offMarker, text: 'off', title: 'Auto memory is disabled for this project' }) : null,
+      marker ? node('span', { class: ui.offMarker, text: marker.text, title: marker.title }) : null,
       global ? null : node('span', { class: ui.storeCount, text: store.hasMemoryDir ? String(store.memoryCount) : '-' }),
     ]),
     node('span', { class: ui.storePath, text: storeSubtitle(store) }),

package/public/views/tools.mjs

@@ -15,6 +15,7 @@ const PANELS = {
 };
 
 const installed = () => state.tools.filter((tool) => tool.found && PANELS[tool.id]);
+const missing = () => state.tools.filter((tool) => !tool.found && PANELS[tool.id]);
 
 const openKey = (id) => `toolOpen:${id}`;
 const isOpen = (id) => localStorage.getItem(openKey(id)) === '1';
@@ -126,19 +127,46 @@ function accordion(container, tool, slot) {
   container.append(panel);
 }
 
+function notInstalled(container, tool) {
+  container.append(node('div', { class: ui.contextRowStatic }, [
+    node('div', { class: ui.contextMain }, [
+      node('div', { class: ui.contextFile, text: tool.label }),
+    ]),
+    node('div', { class: ui.contextSize, text: 'not installed' }),
+  ]));
+
+  container.append(node('div', { class: ui.toolMissingBody }, [
+    node('p', { class: ui.noteTight, text: tool.blurb }),
+    node('a', {
+      class: ui.linkButton,
+      href: tool.repo,
+      target: '_blank',
+      rel: 'noopener noreferrer',
+      text: 'View on GitHub \u2197',
+    }),
+  ]));
+}
+
 export function renderTools(container) {
-  const tools = installed();
-  if (!tools.length) return;
+  const found = installed();
+  const absent = missing();
+  if (!found.length && !absent.length) return;
 
-  if (!state.aux.tools && localStorage.getItem(OPT_IN) === '1') start({ remember: false });
-  if (!state.aux.tools) return gate(container, tools);
+  if (found.length && !state.aux.tools && localStorage.getItem(OPT_IN) === '1') start({ remember: false });
+  const opted = Boolean(state.aux.tools);
 
-  container.append(node('div', { class: ui.listBar }, [
+  const bar = [
     node('span', { class: ui.sectionLabelInline, text: 'Companion tools' }),
     node('span', { class: ui.listSpacer }),
-    node('button', { class: ui.buttonSmall, text: 'Re-read', onclick: readAll }),
-    node('button', { class: ui.buttonSmall, text: 'Turn off', onclick: turnOff }),
-  ]));
+  ];
+  if (found.length && opted) {
+    bar.push(node('button', { class: ui.buttonSmall, text: 'Re-read', onclick: readAll }));
+    bar.push(node('button', { class: ui.buttonSmall, text: 'Turn off', onclick: turnOff }));
+  }
+  container.append(node('div', { class: ui.listBar }, bar));
+
+  if (found.length && !opted) gate(container, found);
+  else for (const tool of found) accordion(container, tool, state.aux.tools[tool.id]);
 
-  for (const tool of tools) accordion(container, tool, state.aux.tools[tool.id]);
+  for (const tool of absent) notInstalled(container, tool);
 }

package/server.mjs

@@ -13,7 +13,7 @@ import { buildStore } from './src/model.mjs';
 import { resolveGlobalInstructions, resolveInstructions, summarise } from './src/instructions.mjs';
 import { settingsReport, summariseSettings } from './src/settings.mjs';
 import { costReport, writeUserSetting } from './src/cost.mjs';
-import { AGENTS_DIR, AGENT_FIELDS, agentsDirExists, listAgents, setAgentField } from './src/agents.mjs';
+import { AGENTS_DIR, AGENT_FIELDS, agentsDirExists, listAllAgents, setAgentField } from './src/agents.mjs';
 import { listStores } from './src/stores.mjs';
 import { forgetPath, rememberPath } from './src/pathcache.mjs';
 import { searchAll } from './src/search.mjs';
@@ -140,6 +140,67 @@ const VERSION = (() => {
   }
 })();
 
+/**
+ * Every agent definition on the machine: the user directory plus the agents
+ * directory of each repository auto memory has already resolved a path for.
+ * Nothing here guesses at a repository that was not confirmed somewhere else.
+ */
+function allAgents() {
+  const projectPaths = listStores(ROOT)
+    .filter((store) => store.kind === 'auto' && store.pathExists)
+    .flatMap((store) => [store.path, ...(store.workingDirs || [])]);
+  return listAllAgents({ projectPaths });
+}
+
+/** Each subagent memory store next to the definition that asks for it, for the agents panel. */
+function agentStoreLinks() {
+  return listStores(ROOT)
+    .filter((store) => String(store.kind).startsWith('agent-'))
+    .map((store) => ({
+      id: store.id,
+      kind: store.kind,
+      agentName: store.agentName,
+      projectPath: store.projectPath,
+      memoryCount: store.memoryCount,
+      declaredBy: store.declaredBy ?? null,
+      declaredScope: store.declaredScope ?? null,
+      linked: Boolean(store.linked),
+      defined: Boolean(store.defined),
+      inert: Boolean(store.inert),
+      inertBy: store.inertBy ?? null,
+    }));
+}
+
+/**
+ * Hand the address to whatever opens a URL here, and never let that decide
+ * whether the server runs.
+ *
+ * `start` is a cmd.exe builtin rather than a program, so spawning it by name
+ * fails on Windows; the documented form is `cmd /c start "" <url>`, where the
+ * empty string is the window title `start` would otherwise read the URL as. On
+ * Linux `xdg-open` is simply missing on a minimal install and inside some
+ * containers. Either way the failure arrives as an async 'error' event, which
+ * with no listener is an uncaught exception that would take down a server that
+ * had already printed its address and was working perfectly well.
+ */
+function openBrowser(address) {
+  const [command, args] = process.platform === 'darwin'
+    ? ['open', [address]]
+    : process.platform === 'win32'
+      ? [process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', 'start', '""', address.replace(/&/g, '^&')]]
+      : ['xdg-open', [address]];
+
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on('error', () => {
+      console.log('Could not open a browser automatically - open the address above yourself.');
+    });
+    child.unref();
+  } catch {
+    console.log('Could not open a browser automatically - open the address above yourself.');
+  }
+}
+
 function storeProjectDir(store) {
   // The global store is the user scope itself, which no project owns.
   if (store.kind === 'global') return null;
@@ -331,10 +392,15 @@ async function handleApi(req, res, url) {
   if (action === 'cost' && req.method === 'GET') {
     return sendJson(res, 200, {
       settings: costReport(),
-      agents: listAgents(),
+      // Project-scope definitions come along read-only: an agent with
+      // `memory: project` lives in a repository rather than in the user
+      // directory, and leaving it out would show its memory store as belonging
+      // to no agent at all.
+      agents: allAgents(),
       agentsDir: AGENTS_DIR,
       agentsDirExists: agentsDirExists(),
       agentFields: AGENT_FIELDS,
+      agentStores: agentStoreLinks(),
     });
   }
 
@@ -346,8 +412,13 @@ async function handleApi(req, res, url) {
 
   if (action === 'cost/agent' && req.method === 'POST') {
     const body = await readBody(req);
-    const agents = setAgentField(body.file, body.field, body.value ?? null);
-    return sendJson(res, 200, { agents, agentsDir: AGENTS_DIR, agentsDirExists: agentsDirExists() });
+    setAgentField(body.file, body.field, body.value ?? null);
+    return sendJson(res, 200, {
+      agents: allAgents(),
+      agentsDir: AGENTS_DIR,
+      agentsDirExists: agentsDirExists(),
+      agentStores: agentStoreLinks(),
+    });
   }
 
   if (action === 'delete-preview' && req.method === 'POST') {
@@ -484,10 +555,7 @@ export function startServer({ port, root, open = true } = {}) {
     const address = `http://localhost:${listenPort}`;
     console.log(`Memory Admin  ->  ${address}`);
     console.log(`Reading       ->  ${ROOT}`);
-    if (open && !process.env.NO_OPEN) {
-      const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-      spawn(opener, [address], { stdio: 'ignore', detached: true }).unref();
-    }
+    if (open && !process.env.NO_OPEN) openBrowser(address);
   });
   return server;
 }