claude-memory-admin 1.3.0 → 1.4.0

package/README.md

@@ -97,8 +97,17 @@ project is to the cliff, and makes it quick to get back under it.
 - **Graph** the wikilinks between memories. Hovering dims everything that is not
   a neighbour, which is the only practical way to read a dense cluster.
 - **Health**: orphans, dangling pointers, broken wikilinks, files linked only
-  mid-sentence, `name` fields that disagree with the filename. An orphan can be
-  given the `MEMORY.md` bullet it is missing without leaving the page.
+  mid-sentence, `name` fields that disagree with the filename, two files claiming
+  one `name`, a file bulleted twice, a blank `description`, a `type` outside the
+  four documented ones, a memory that is frontmatter and little else, a hook that
+  only restates the description it points at, a heading with nothing under it, and
+  entries that spill onto a second line. An orphan can be given the `MEMORY.md`
+  bullet it is missing without leaving the page.
+- **Every count is visible before you click.** Each tab carries a badge, coloured
+  amber for something to tidy and red for something actively broken, and the
+  sidebar gives each store a dot of its worst severity - memory, instructions and
+  settings together. Which project is in trouble is the first thing the app tells
+  you, not something you find by opening eight tabs each.
 - **Dates you can trust.** Claude Code stamps `modified` into frontmatter, but
   only on files that already have some, and never adds frontmatter to a file
   without it. Anything falling back to the file's mtime is labelled, because
@@ -178,6 +187,11 @@ It also finds the failures that leave a file silently doing nothing:
 - A markdown file sitting in `~/.claude` that nothing in the chain reaches. It
   looks load-bearing and loads nothing, which is what happens when the import
   that pulled it in is deleted or its content is inlined.
+- One file reached by two chains - your `~/.claude/CLAUDE.md` and the project's
+  own both importing it, say. Both copies load, and you pay for the content twice
+  every session.
+- A `CLAUDE.md` or rule file that is empty apart from its frontmatter. It costs a
+  read and contributes no instruction.
 
 Backticks are respected, so a `` `@README` `` in your prose is not reported as an
 import, and neither is an email address.
@@ -200,6 +214,26 @@ This is re-derived from the documented resolution rules rather than reported by
 Claude Code, and the tab says so. Run `/context` in a session for the ground
 truth, or the `InstructionsLoaded` hook to log exactly what loaded and why.
 
+## The one check that reads your code
+
+Every check above reads `memory/` and the `CLAUDE.md` chain, and nothing else.
+One more is available and **off by default**, because it reads the project itself:
+it takes the paths a memory names in a code span and asks whether anything in the
+repository still matches them. A memory whose `Foo.cs` was renamed two months ago
+still reads as authoritative, and nothing else on this page can tell.
+
+Turn it on from the Health tab, per store; the choice is remembered in the browser
+and nothing is written to disk. It walks the project once, skipping `.git`,
+`node_modules`, build output and the like, and matches by suffix - a memory that
+says `Infrastructure/Reporting/Foo.cs` for a file that really lives under
+`services/argus/src` is right, and resolving that against the repository root
+alone reported seven real paths in ten as missing. Only a token with a real source
+extension is treated as a claim about a file, because memories are also full of
+HTTP routes and type names that no file was ever going to match.
+
+It is a pointer, not a verdict, and the tab says so: a file that moved reads the
+same as one the memory never got right.
+
 ## Which settings are actually in force
 
 Five files can set the keys this tool cares about, and the one everybody edits,
@@ -274,6 +308,10 @@ claude-memory-admin --root /tmp/memory-snapshot
 ## Safety
 
 - Binds `127.0.0.1`; no telemetry, no network calls.
+- 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
+  looked up in an index built from the project itself.
 - Every write target must resolve to a plain `.md` file inside that project's own
   `memory/` directory. `..`, absolute paths and subdirectories are refused.
 - One exception, and only when you ask for it: **Remember path** writes
@@ -320,6 +358,8 @@ ready to serve and never builds anything. After editing the source, run
 | `src/stores.mjs` | Store discovery: the user scope, auto memory and the three agent scopes |
 | `src/instructions.mjs` | CLAUDE.md chain, `@` imports and rules resolution |
 | `src/parse.mjs` | `MEMORY.md` and frontmatter parsers, wikilinks |
+| `src/checks.mjs` | The consistency checks, as pure functions over parsed data |
+| `src/pathcheck.mjs` | The opt-in check of paths a memory names, against the repo |
 | `src/model.mjs` | Joins index, files, graph and health into one model |
 | `src/stats.mjs` | Load-limit accounting and overlap detection |
 | `src/search.mjs` | Full-text search across every store |

package/package.json

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

package/public/app.mjs

@@ -17,8 +17,14 @@ const state = {
   pruneSort: 'oldest',
   pruneSelection: new Set(),
   indexView: localStorage.getItem('memoryIndexView') === 'source' ? 'source' : 'rendered',
+  aux: { instructions: null, settings: null },
+  pathCheck: null,
 };
 
+const RANK = { ok: 0, warn: 1, bad: 2 };
+const worst = (...severities) => severities.reduce((a, b) => (RANK[b] > RANK[a] ? b : a), 'ok');
+const worstSeverity = (items) => (!items.length ? 'ok' : items.some((item) => item.severity === 'bad') ? 'bad' : 'warn');
+
 const el = (id) => document.getElementById(id);
 
 async function api(path, options) {
@@ -88,16 +94,25 @@ function storeSubtitle(store) {
   return `${scope} · ${store.sublabel}`;
 }
 
+function issueTitle(store) {
+  const parts = [];
+  if (store.issueCount) parts.push(`${store.issueCount} in Health`);
+  if (store.context) parts.push(`${store.context} in Context`);
+  if (store.settings) parts.push(`${store.settings} in Settings`);
+  if (store.kind === 'auto' && store.resolvedBy === 'unresolved') {
+    parts.push('Real path could not be resolved - showing the raw folder name');
+  }
+  return parts.length ? `${store.dir}\n${parts.join(', ')}` : store.dir;
+}
+
 function storeButton(store) {
   const global = store.kind === 'global';
-  const health = global ? 'ok' : store.memoryCount === 0 ? 'none' : 'ok';
+  const health = !global && !store.hasMemoryDir ? 'none' : store.severity || 'ok';
   const off = store.autoMemory && store.autoMemory.known && !store.autoMemory.enabled;
   return node('button', {
     class: ui.storeItem({ active: store.id === state.storeId, empty: !global && !store.hasMemoryDir }),
     onclick: () => openStore(store.id),
-    title: store.kind === 'auto' && store.resolvedBy === 'unresolved'
-      ? 'Real path could not be resolved - showing the raw folder name'
-      : store.dir,
+    title: issueTitle(store),
   }, [
     node('span', { class: ui.storeRow }, [
       node('span', { class: ui.dot(health) }),
@@ -155,17 +170,32 @@ function renderTabs() {
     if (global && tab.id !== 'context') continue;
     if (!global && tab.id === 'context' && !hasProjectDir) continue;
     let badge = null;
+    let tone = 'neutral';
     if (tab.id === 'memories') badge = String(state.store.memories.length);
-    if (tab.id === 'health' && state.store.health.issueCount) badge = String(state.store.health.issueCount);
     if (tab.id === 'trash' && state.store.trash.length) badge = String(state.store.trash.length);
-    if (tab.id === 'prune' && state.store.stats.index.overTarget) badge = '!';
+    if (tab.id === 'health' && state.store.health.issueCount) {
+      badge = String(state.store.health.issueCount);
+      tone = state.store.health.severity;
+    }
+    if (tab.id === 'prune' && state.store.stats.index.level !== 'ok') {
+      badge = '!';
+      tone = state.store.stats.index.level === 'over' ? 'bad' : 'warn';
+    }
+    if (tab.id === 'context' && state.aux.instructions?.problems.length) {
+      badge = String(state.aux.instructions.problems.length);
+      tone = worstSeverity(state.aux.instructions.problems);
+    }
+    if (tab.id === 'settings' && state.aux.settings?.problems.length) {
+      badge = String(state.aux.settings.problems.length);
+      tone = worstSeverity(state.aux.settings.problems);
+    }
 
     container.append(node('button', {
       class: ui.tab(state.tab === tab.id),
       onclick: () => { state.tab = tab.id; renderTabs(); renderTab(); },
     }, [
       document.createTextNode(tab.label),
-      badge ? node('span', { class: ui.tabBadge(tab.id === 'health' || tab.id === 'prune'), text: badge }) : null,
+      badge ? node('span', { class: ui.tabBadge(tone), text: badge }) : null,
     ]));
   }
 }
@@ -395,18 +425,22 @@ const CONTEXT_PROBLEMS = {
   'long-claude-md': (p) => [`${p.lines} lines, over the 200-line guidance`, `${p.file} - long files cost context every session and reduce adherence`],
   'agents-md-not-imported': (p) => ['AGENTS.md is not loaded', `${p.file} exists, but Claude Code reads CLAUDE.md. Import it with @AGENTS.md, or symlink it.`],
   'unreferenced-user-file': (p) => ['Nothing in the chain reaches this file', `${p.file} sits next to CLAUDE.md and loads nothing. Import it with @${p.file.split('/').pop()}, or delete it.`],
+  'duplicate-load': (p) => [`Loaded ${p.count} times: ${p.file}`, `reached from ${[...new Set(p.via)].join(' and ')} - every copy is read into context, so you pay ~${p.wastedTokens.toLocaleString()} extra tokens a session`],
+  'empty-instruction-file': (p) => ['Loads, but says nothing', `${p.file} is empty apart from its frontmatter, so it costs a read and contributes no instruction`],
 };
 
 async function renderContext(container) {
-  container.append(node('p', { class: ui.note, text: 'Reading instruction files…' }));
-  let data;
-  try {
-    data = await api(`/api/stores/${encodeURIComponent(state.storeId)}/instructions`);
-  } catch (err) {
-    container.textContent = '';
-    return container.append(node('p', { class: ui.note, text: err.message }));
+  let data = state.aux.instructions;
+  if (!data) {
+    container.append(node('p', { class: ui.note, text: 'Reading instruction files…' }));
+    try {
+      data = await api(`/api/stores/${encodeURIComponent(state.storeId)}/instructions`);
+    } catch (err) {
+      container.textContent = '';
+      return container.append(node('p', { class: ui.note, text: err.message }));
+    }
+    if (state.tab !== 'context') return;
   }
-  if (state.tab !== 'context') return;
   container.textContent = '';
 
   const global = state.store.kind === 'global';
@@ -434,8 +468,7 @@ async function renderContext(container) {
     for (const problem of data.problems) {
       const describe = CONTEXT_PROBLEMS[problem.kind];
       const [title, detail] = describe ? describe(problem) : [problem.kind, problem.file || ''];
-      const bad = problem.kind === 'missing' || problem.kind === 'invalid-glob' || problem.kind === 'glob-budget';
-      container.append(node('div', { class: ui.issue(bad) }, [
+      container.append(node('div', { class: ui.issue(problem.severity === 'bad') }, [
         node('div', { class: ui.issueBody }, [
           node('div', { class: ui.issueTitle, text: title }),
           node('div', { class: ui.issueDetail, text: detail }),
@@ -506,18 +539,135 @@ function issue(title, detail, { bad = false, action, secondary } = {}) {
   ]);
 }
 
+function storeHasProjectDir() {
+  return state.store.kind === 'auto'
+    ? state.store.resolvedBy !== 'unresolved'
+    : Boolean(state.store.projectPath);
+}
+
+const pathCheckKey = () => `pathCheck:${state.storeId}`;
+
+async function fetchPathCheck() {
+  const id = state.storeId;
+  let next;
+  try {
+    next = { running: false, data: await api(`/api/stores/${encodeURIComponent(id)}/path-check`) };
+  } catch (err) {
+    next = { running: false, error: err.message };
+  }
+  if (state.storeId !== id) return;
+  state.pathCheck = next;
+  if (state.tab === 'health') renderTab();
+}
+
+function startPathCheck({ remember = true } = {}) {
+  if (remember) localStorage.setItem(pathCheckKey(), '1');
+  state.pathCheck = { running: true };
+  fetchPathCheck();
+}
+
+function runPathCheck() {
+  startPathCheck();
+  renderTab();
+}
+
+function stopPathCheck() {
+  localStorage.removeItem(pathCheckKey());
+  state.pathCheck = null;
+  renderTab();
+}
+
+function renderPathCheck(container) {
+  if (!storeHasProjectDir()) return;
+
+  if (!state.pathCheck && localStorage.getItem(pathCheckKey()) === '1') {
+    startPathCheck({ remember: false });
+  }
+  const check = state.pathCheck;
+
+  const head = node('div', { class: ui.issue(false) });
+  const body = node('div', { class: ui.issueBody });
+
+  if (!check) {
+    body.append(
+      node('div', { class: ui.issueTitle, text: 'Paths named in memories are not being checked' }),
+      node('div', { class: ui.issueDetail, text: 'Every other check on this tab reads only memory/. This one reads the project itself, to find memories naming files that no longer exist. It stays off until you ask, and is remembered per store.' }),
+    );
+    head.append(body, node('button', { class: ui.buttonSmall, text: 'Check against the repo', onclick: () => runPathCheck() }));
+    return container.append(head);
+  }
+
+  if (check.running) {
+    body.append(node('div', { class: ui.issueTitle, text: 'Checking paths against the repo…' }));
+    head.append(body);
+    return container.append(head);
+  }
+
+  if (check.error) {
+    body.append(
+      node('div', { class: ui.issueTitle, text: 'Path check could not run' }),
+      node('div', { class: ui.issueDetail, text: check.error }),
+    );
+    head.append(body, node('button', { class: ui.buttonSmall, text: 'Turn off', onclick: () => stopPathCheck() }));
+    return container.append(head);
+  }
+
+  const { checked, capped, missing, indexed, truncated } = check.data;
+  const scanned = `${indexed.toLocaleString()} files and folders scanned${truncated ? ', stopped at the index limit' : ''}`;
+  body.append(
+    node('div', { class: ui.issueTitle, text: missing.length
+      ? `${missing.length} of ${checked} paths named in memories match no file in the project`
+      : `All ${checked} paths named in memories still match a file` }),
+    node('div', { class: ui.issueDetail, text: capped
+      ? `${scanned}; stopped after the first ${checked} paths, so there may be more`
+      : scanned }),
+  );
+  if (missing.length) {
+    body.append(node('div', { class: ui.issueDetail, text: 'A pointer rather than a verdict: a file that moved reads the same as one the memory never got right.' }));
+  }
+  head.append(
+    body,
+    node('button', { class: ui.buttonSmall, text: 'Turn off', onclick: () => stopPathCheck() }),
+    node('button', { class: ui.buttonSmall, text: 'Re-check', onclick: () => runPathCheck() }),
+  );
+  container.append(head);
+
+  for (const item of missing) container.append(renderIssue(item, state.store.memories));
+}
+
 function renderHealth(container) {
   const { health, memories } = state.store;
+
   if (!health.issues.length) {
     container.append(node('div', { class: ui.card }, [
       node('p', { class: ui.okLine, text: '\u2713 No consistency problems found.' }),
       node('p', { class: ui.noteTight, text: 'Every memory file is referenced by MEMORY.md, every pointer resolves, and every [[wikilink]] finds its target.' }),
     ]));
-    return;
+  } else {
+    for (const item of health.issues) container.append(renderIssue(item, memories));
   }
 
-  for (const item of health.issues) {
-    container.append(renderIssue(item, memories));
+  container.append(node('div', { class: ui.sectionLabel, text: 'Beyond the memory directory' }));
+  renderPathCheck(container);
+}
+
+function goToTab(id) {
+  state.tab = id;
+  renderTabs();
+  renderTab();
+}
+
+async function removeIndexLine(lineIndex, expectedText, done) {
+  if (!confirm(`Remove line ${lineIndex + 1} from MEMORY.md?\n\n${expectedText}`)) return;
+  try {
+    await api(`/api/stores/${encodeURIComponent(state.storeId)}/index-line/delete`, {
+      method: 'POST',
+      body: JSON.stringify({ lineIndex, expectedText }),
+    });
+    toast(done);
+    await openStore(state.storeId, { keepTab: true });
+  } catch (err) {
+    toast(err.message, { error: true });
   }
 }
 
@@ -533,19 +683,7 @@ function renderIssue(item, memories) {
         bad,
         action: {
           label: 'Remove pointer',
-          run: async () => {
-            if (!confirm(`Remove line ${entry.index + 1} from MEMORY.md?\n\n${entry.text}`)) return;
-            try {
-              await api(`/api/stores/${encodeURIComponent(state.storeId)}/index-line/delete`, {
-                method: 'POST',
-                body: JSON.stringify({ lineIndex: entry.index, expectedText: entry.text }),
-              });
-              toast('Pointer removed');
-              await openStore(state.storeId, { keepTab: true });
-            } catch (err) {
-              toast(err.message, { error: true });
-            }
-          },
+          run: () => removeIndexLine(entry.index, entry.text, 'Pointer removed'),
         },
       },
     );
@@ -627,16 +765,104 @@ function renderIssue(item, memories) {
     return issue(
       `${item.count} index hook${item.count === 1 ? '' : 's'} over 200 characters`,
       `longest is ${item.longest.hookLength} chars on "${item.longest.title}" - hooks load every session, so these are the cheapest thing to trim.`,
+      {
+        bad,
+        action: { label: 'Open Prune', run: () => goToTab('prune') },
+      },
+    );
+  }
+
+  if (item.kind === 'duplicate-name') {
+    return issue(
+      `Two memories claim the name "${item.name}"`,
+      `${item.files.join(', ')} - every [[${item.name}]] resolves to ${item.reachable}, so the other one cannot be linked at all.`,
+      {
+        bad,
+        secondary: { label: 'Open first', run: () => selectMemory(item.files[0]) },
+        action: { label: 'Open second', run: () => selectMemory(item.files[1]) },
+      },
+    );
+  }
+
+  if (item.kind === 'duplicate-index-entry') {
+    return issue(
+      `Listed twice in MEMORY.md: ${item.file}`,
+      `lines ${item.lines.map((line) => line + 1).join(' and ')} - one memory, two index lines, both loaded every session.`,
       {
         bad,
         action: {
-          label: 'Open Prune',
-          run: () => { state.tab = 'prune'; renderTabs(); renderTab(); },
+          label: 'Remove duplicate',
+          run: () => removeIndexLine(item.removable.index, item.removable.text, 'Duplicate removed'),
         },
       },
     );
   }
 
+  if (item.kind === 'missing-description') {
+    return issue(
+      `No description: ${item.file}`,
+      'The description is what a memory is recalled by, so this one is found on its name alone.',
+      { bad, action: { label: 'Open', run: () => selectMemory(item.file) } },
+    );
+  }
+
+  if (item.kind === 'unknown-type') {
+    return issue(
+      `Unrecognised type: ${item.file}`,
+      `type: "${item.type}" - expected one of user, feedback, project, reference.`,
+      { bad, action: { label: 'Open', run: () => selectMemory(item.file) } },
+    );
+  }
+
+  if (item.kind === 'empty-body') {
+    const memory = memories.find((m) => m.file === item.file);
+    return issue(
+      `Almost nothing in it: ${item.file}`,
+      `"${memory?.name || item.file}" has ${item.chars} characters of body - it costs an index line every session and says nothing.`,
+      {
+        bad,
+        secondary: { label: 'Open', run: () => selectMemory(item.file) },
+        action: { label: 'Delete', run: () => openDeleteDialog(item.file) },
+      },
+    );
+  }
+
+  if (item.kind === 'hook-repeats-description') {
+    return issue(
+      `Hook repeats the description: ${item.file}`,
+      `MEMORY.md line ${item.index + 1} - ${item.hookLength} characters restating what the file's own description already says. Only the hook loads every session.`,
+      {
+        bad,
+        secondary: { label: 'Open', run: () => selectMemory(item.file) },
+        action: { label: 'Open Prune', run: () => goToTab('prune') },
+      },
+    );
+  }
+
+  if (item.kind === 'empty-section') {
+    return issue(
+      `Empty section in MEMORY.md: "${item.section}"`,
+      `line ${item.index + 1} - the heading has no entries under it, and headings count against the 200-line budget too.`,
+      { bad, action: { label: 'Open MEMORY.md', run: () => goToTab('index') } },
+    );
+  }
+
+  if (item.kind === 'stale-path') {
+    return issue(
+      `No file matches ${item.token}`,
+      `named by "${item.name || item.file}"`,
+      { bad, action: { label: 'Open', run: () => selectMemory(item.file) } },
+    );
+  }
+
+  if (item.kind === 'index-continuation') {
+    return issue(
+      `${item.count} index ${item.count === 1 ? 'entry spills' : 'entries spill'} onto extra lines`,
+      `${item.extraLines} extra line${item.extraLines === 1 ? '' : 's'} of the 200-line budget - the guidance is one line per entry, with the detail in the topic file.`,
+      { bad, action: { label: 'Open MEMORY.md', run: () => goToTab('index') } },
+    );
+  }
+
   return issue(item.kind, JSON.stringify(item));
 }
 
@@ -662,15 +888,17 @@ const SETTINGS_PROBLEMS = {
 const show = (value) => (value === undefined ? 'unset' : JSON.stringify(value));
 
 async function renderSettings(container) {
-  container.append(node('p', { class: ui.note, text: 'Reading settings files…' }));
-  let data;
-  try {
-    data = await api(`/api/stores/${encodeURIComponent(state.storeId)}/settings`);
-  } catch (err) {
-    container.textContent = '';
-    return container.append(node('p', { class: ui.note, text: err.message }));
+  let data = state.aux.settings;
+  if (!data) {
+    container.append(node('p', { class: ui.note, text: 'Reading settings files…' }));
+    try {
+      data = await api(`/api/stores/${encodeURIComponent(state.storeId)}/settings`);
+    } catch (err) {
+      container.textContent = '';
+      return container.append(node('p', { class: ui.note, text: err.message }));
+    }
+    if (state.tab !== 'settings') return;
   }
-  if (state.tab !== 'settings') return;
   container.textContent = '';
 
   container.append(node('p', { class: ui.noteTight, text: 'What Claude Code would read for this store, in precedence order: managed policy first, then project and local settings, then your user file. This tab is read-only — it reports what is configured, it never changes it.' }));
@@ -684,7 +912,7 @@ async function renderSettings(container) {
     for (const problem of data.problems) {
       const describe = SETTINGS_PROBLEMS[problem.kind];
       const [title, detail] = describe ? describe(problem) : [problem.kind, problem.file || ''];
-      container.append(node('div', { class: ui.issue(true) }, [
+      container.append(node('div', { class: ui.issue(problem.severity === 'bad') }, [
         node('div', { class: ui.issueBody }, [
           node('div', { class: ui.issueTitle, text: title }),
           node('div', { class: ui.issueDetail, text: detail }),
@@ -1743,9 +1971,22 @@ async function reloadStores() {
   const data = await api('/api/stores');
   state.stores = data.stores;
   renderStores();
+  sweepIssues();
   return data;
 }
 
+async function sweepIssues() {
+  let data;
+  try {
+    data = await api('/api/stores/issues');
+  } catch {
+    return;
+  }
+  const bySummary = new Map(data.stores.map((summary) => [summary.id, summary]));
+  for (const store of state.stores) Object.assign(store, bySummary.get(store.id) || {});
+  renderStores();
+}
+
 function renderStoreHeader() {
   const store = state.store;
   el('project-title').textContent = store.label;
@@ -1799,6 +2040,8 @@ function renderStoreHeader() {
 async function openStore(id, { keepTab = false } = {}) {
   if (id !== state.storeId) state.pruneSelection.clear();
   state.storeId = id;
+  state.aux = { instructions: null, settings: null };
+  state.pathCheck = null;
   if (!keepTab) {
     const opening = state.stores.find((store) => store.id === id);
     state.tab = opening && opening.kind === 'global' ? 'context' : 'memories';
@@ -1819,12 +2062,34 @@ async function openStore(id, { keepTab = false } = {}) {
   renderStoreHeader();
 
   const listed = state.stores.find((store) => store.id === id);
-  if (listed) listed.memoryCount = state.store.memories.length;
+  if (listed) {
+    listed.memoryCount = state.store.memories.length;
+    listed.issueCount = state.store.health.issueCount;
+    listed.severity = worst(state.store.health.severity, listed.context ? 'warn' : 'ok', listed.settings ? 'warn' : 'ok');
+  }
   renderStores();
 
   renderView();
   renderTabs();
   renderTab();
+
+  Promise.all([
+    api(`/api/stores/${encodeURIComponent(id)}/instructions`).catch(() => null),
+    api(`/api/stores/${encodeURIComponent(id)}/settings`).catch(() => null),
+  ]).then(([instructions, settings]) => {
+    if (state.storeId !== id) return;
+    state.aux = { instructions, settings };
+    renderTabs();
+    if (!listed) return;
+    listed.context = instructions ? instructions.problems.length : 0;
+    listed.settings = settings ? settings.problems.length : 0;
+    listed.severity = worst(
+      state.store.health.severity,
+      instructions ? worstSeverity(instructions.problems) : 'ok',
+      settings ? worstSeverity(settings.problems) : 'ok',
+    );
+    renderStores();
+  });
 }
 
 function applyCollapsed() {

package/public/ui.mjs

@@ -44,7 +44,7 @@ export const storeCount = 'font-mono text-2xs text-fg-subtle';
 export const storePath = 'block truncate font-mono text-2xs text-fg-subtle';
 
 const dotBase = 'inline-block size-1.5 flex-none rounded-full';
-const dotTone = { ok: 'bg-ok', warn: 'bg-warn', none: 'bg-line-strong' };
+const dotTone = { ok: 'bg-ok', warn: 'bg-warn', bad: 'bg-danger', none: 'bg-line-strong' };
 export const dot = (tone) => cx(dotBase, pick(dotTone, tone, 'none'));
 
 export const offMarker = 'rounded-sm bg-warn-surface px-1 py-px font-mono text-2xs uppercase tracking-widest text-warn';
@@ -75,6 +75,7 @@ const badgeBase = 'flex-none rounded-sm px-1.5 py-px font-mono text-2xs lowercas
 const badgeTone = {
   neutral: 'bg-surface-sunken text-fg-muted',
   warn: 'bg-warn-surface text-warn',
+  bad: 'bg-danger-surface text-danger',
   ok: 'bg-ok-surface text-ok',
   project: 'bg-type-project-surface text-type-project',
   feedback: 'bg-type-feedback-surface text-type-feedback',
@@ -90,7 +91,7 @@ export const badge = (tone = 'neutral') => cx(badgeBase, pick(badgeTone, tone, '
 const SCOPE_TONE = { managed: 'managed', user: 'scopeUser', project: 'scopeProject', local: 'scopeLocal' };
 export const scopeBadge = (scope) => badge(SCOPE_TONE[scope] ?? 'neutral');
 export const typeBadge = (type) => badge(badgeTone[type] ? type : 'neutral');
-export const tabBadge = (warn) => cx('ml-1.5', badge(warn ? 'warn' : 'neutral'));
+export const tabBadge = (tone = 'neutral') => cx('ml-1.5', badge(tone));
 
 export const split = 'grid grid-cols-1 items-start gap-6 xl:grid-cols-[minmax(280px,380px)_1fr]';
 export const detailPane = 'xl:sticky xl:top-4 xl:max-h-[calc(100vh-9rem)] xl:overflow-y-auto';

package/server.mjs

@@ -10,11 +10,12 @@ import { spawn } from 'node:child_process';
 
 import { projectsRoot, resolveRoot } from './src/projects.mjs';
 import { buildStore } from './src/model.mjs';
-import { resolveGlobalInstructions, resolveInstructions } from './src/instructions.mjs';
-import { settingsReport } from './src/settings.mjs';
+import { resolveGlobalInstructions, resolveInstructions, summarise } from './src/instructions.mjs';
+import { settingsReport, summariseSettings } from './src/settings.mjs';
 import { listStores } from './src/stores.mjs';
 import { forgetPath, rememberPath } from './src/pathcache.mjs';
 import { searchAll } from './src/search.mjs';
+import { verifyPaths } from './src/pathcheck.mjs';
 import {
   addIndexEntry,
   addIndexEntryPreview,
@@ -153,13 +154,56 @@ function emptyModel(store) {
     index: null,
     memories: [],
     graph: { nodes: [], edges: [], dangling: [] },
-    health: { orphans: [], referencedOnly: [], danglingIndex: [], danglingWikilinks: [], nameMismatches: [], missingFrontmatter: [], longHooks: [], issues: [], issueCount: 0 },
+    health: { orphans: [], referencedOnly: [], danglingIndex: [], danglingWikilinks: [], nameMismatches: [], missingFrontmatter: [], longHooks: [], issues: [], issueCount: 0, severity: 'ok' },
     stats: null,
     duplicates: [],
     trash: [],
   };
 }
 
+const WORST = { ok: 0, warn: 1, bad: 2 };
+const worst = (...severities) => severities.reduce((a, b) => (WORST[b] > WORST[a] ? b : a), 'ok');
+
+/**
+ * Counts only, for every store at once, so the sidebar can say which project is
+ * in trouble before anything is opened. The full models are an order of
+ * magnitude larger and none of them is needed to draw a dot.
+ */
+function issueSweep() {
+  return listStores(ROOT).map((store) => {
+    const summary = { id: store.id, issueCount: 0, severity: 'ok', context: 0, settings: 0 };
+
+    if (store.kind !== 'global') {
+      try {
+        const { health } = buildStore(store);
+        summary.issueCount = health.issueCount;
+        summary.severity = health.severity;
+      } catch { /* a store that cannot be read has nothing to report */ }
+    }
+
+    const projectDir = storeProjectDir(store);
+    try {
+      const instructions = store.kind === 'global'
+        ? summarise(resolveGlobalInstructions().problems)
+        : projectDir ? summarise(resolveInstructions(projectDir).problems) : null;
+      if (instructions) {
+        summary.context = instructions.count;
+        summary.severity = worst(summary.severity, instructions.severity);
+      }
+    } catch { /* unreadable instruction chain is reported by the tab itself */ }
+
+    if (projectDir) {
+      try {
+        const settings = summariseSettings(settingsReport({ projectDir }).problems);
+        summary.settings = settings.count;
+        summary.severity = worst(summary.severity, settings.severity);
+      } catch { /* likewise */ }
+    }
+
+    return summary;
+  });
+}
+
 async function handleApi(req, res, url) {
   const segments = url.pathname.split('/').filter(Boolean); // ['api', 'projects', ...]
 
@@ -180,6 +224,12 @@ async function handleApi(req, res, url) {
     return sendJson(res, 200, searchAll(ROOT, url.searchParams.get('q') || ''));
   }
 
+  // Ahead of requireStore, which would otherwise read "issues" as a store id.
+  // Real ids always carry a "kind:" prefix, so the two can never collide.
+  if (segments.length === 3 && segments[1] === 'stores' && segments[2] === 'issues' && req.method === 'GET') {
+    return sendJson(res, 200, { stores: issueSweep() });
+  }
+
   if (segments[1] !== 'stores' || segments.length < 3) {
     return sendJson(res, 404, { error: 'Unknown endpoint' });
   }
@@ -205,6 +255,18 @@ async function handleApi(req, res, url) {
     return sendJson(res, 200, resolveInstructions(projectDir));
   }
 
+  // Opt-in, and the only read this app makes into a project's own tree. Refused
+  // outright when nothing resolved a project directory, so a store can never be
+  // talked into stat-ing a path it has no business knowing about.
+  if (action === 'path-check' && req.method === 'GET') {
+    const projectDir = storeProjectDir(store);
+    if (!projectDir) {
+      return sendJson(res, 400, { error: 'This store is not tied to a project directory, so there is nothing to check paths against.' });
+    }
+    const { memories } = buildStore(store);
+    return sendJson(res, 200, verifyPaths(projectDir, memories));
+  }
+
   if (action === 'settings' && req.method === 'GET') {
     return sendJson(res, 200, settingsReport({ projectDir: storeProjectDir(store) }));
   }

package/src/checks.mjs

@@ -0,0 +1,187 @@
+import path from 'node:path';
+import { parseFrontmatter } from './parse.mjs';
+
+export const VALID_TYPES = ['user', 'feedback', 'project', 'reference'];
+export const EMPTY_BODY_CHARS = 40;
+export const EMPTY_INSTRUCTION_CHARS = 10;
+export const HOOK_ECHO_OVERLAP = 0.9;
+
+const VALID_TYPE_SET = new Set(VALID_TYPES);
+
+const significantChars = (text) => String(text || '').replace(/\s+/g, '').length;
+
+const wordSet = (text) => new Set(String(text || '').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+
+function overlap(left, right) {
+  if (!left.size || !right.size) return 0;
+  let shared = 0;
+  for (const word of left) if (right.has(word)) shared += 1;
+  return shared / (left.size + right.size - shared);
+}
+
+function groupBy(items, key) {
+  const groups = new Map();
+  for (const item of items) {
+    const id = key(item);
+    if (!groups.has(id)) groups.set(id, []);
+    groups.get(id).push(item);
+  }
+  return groups;
+}
+
+export function checkDuplicateNames(memories) {
+  return [...groupBy(memories, (memory) => memory.name)]
+    .filter(([, group]) => group.length > 1)
+    .map(([name, group]) => ({
+      kind: 'duplicate-name',
+      severity: 'bad',
+      name,
+      files: group.map((memory) => memory.file),
+      reachable: group[0].file,
+    }));
+}
+
+export function checkMissingDescription(memories) {
+  return memories
+    .filter((memory) => memory.hasFrontmatter && !memory.description.trim())
+    .map((memory) => ({ kind: 'missing-description', severity: 'warn', file: memory.file, name: memory.name }));
+}
+
+export function checkUnknownType(memories) {
+  return memories
+    .filter((memory) => memory.hasFrontmatter && !VALID_TYPE_SET.has(memory.type))
+    .map((memory) => ({ kind: 'unknown-type', severity: 'warn', file: memory.file, type: memory.type }));
+}
+
+export function checkEmptyBody(memories) {
+  return memories
+    .filter((memory) => significantChars(memory.body) < EMPTY_BODY_CHARS)
+    .map((memory) => ({
+      kind: 'empty-body',
+      severity: 'warn',
+      file: memory.file,
+      name: memory.name,
+      chars: significantChars(memory.body),
+    }));
+}
+
+export function checkHookRepeatsDescription(memories) {
+  return memories
+    .filter((memory) => memory.entry && memory.entry.hook && memory.description)
+    .filter((memory) => overlap(wordSet(memory.entry.hook), wordSet(memory.description)) >= HOOK_ECHO_OVERLAP)
+    .map((memory) => ({
+      kind: 'hook-repeats-description',
+      severity: 'warn',
+      file: memory.file,
+      index: memory.entry.index,
+      text: memory.entry.text,
+      hookLength: memory.entry.hook.length,
+    }));
+}
+
+export function checkDuplicateIndexEntry(index) {
+  if (!index) return [];
+  return [...groupBy(index.entries, (entry) => entry.file)]
+    .filter(([, group]) => group.length > 1)
+    .map(([file, group]) => {
+      const last = group[group.length - 1];
+      return {
+        kind: 'duplicate-index-entry',
+        severity: 'bad',
+        file,
+        lines: group.map((entry) => entry.index),
+        removable: { index: last.index, text: last.text },
+      };
+    });
+}
+
+export function checkEmptySection(index) {
+  if (!index) return [];
+  const lines = index.parsedLines;
+  const empty = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const heading = lines[i];
+    if (heading.kind !== 'heading') continue;
+
+    let hasEntry = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      const line = lines[j];
+      if (line.kind === 'heading' && line.level <= heading.level) break;
+      if (line.kind === 'index') { hasEntry = true; break; }
+    }
+    if (!hasEntry) empty.push({ kind: 'empty-section', severity: 'warn', section: heading.section, index: heading.index });
+  }
+  return empty;
+}
+
+export function checkIndexContinuation(index) {
+  if (!index) return [];
+
+  const spilling = [];
+  for (const entry of index.entries) {
+    let extra = 0;
+    for (let i = entry.index + 1; i < index.lines.length; i++) {
+      const line = index.lines[i];
+      if (!line.trim() || !/^[ \t]/.test(line)) break;
+      extra += 1;
+    }
+    if (extra) spilling.push({ file: entry.file, title: entry.title, index: entry.index, extraLines: extra });
+  }
+  if (!spilling.length) return [];
+
+  return [{
+    kind: 'index-continuation',
+    severity: 'warn',
+    count: spilling.length,
+    extraLines: spilling.reduce((sum, entry) => sum + entry.extraLines, 0),
+    entries: spilling,
+  }];
+}
+
+export function checkDuplicateLoad(files) {
+  const loadable = files.filter((item) => item.kind !== 'managed-settings');
+  return [...groupBy(loadable, (item) => path.resolve(item.file))]
+    .filter(([, group]) => group.length > 1)
+    .map(([, group]) => ({
+      kind: 'duplicate-load',
+      severity: 'warn',
+      file: group[0].file,
+      scope: group[0].scope,
+      count: group.length,
+      via: group.map((item) => item.importedBy || item.file),
+      wastedTokens: (group[0].tokens || 0) * (group.length - 1),
+    }));
+}
+
+export function checkEmptyInstructionFile(files) {
+  const seen = new Set();
+  const empty = [];
+
+  for (const item of files) {
+    if (item.kind === 'managed-settings') continue;
+    const resolved = path.resolve(item.file);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    if (significantChars(parseFrontmatter(item.text).body) >= EMPTY_INSTRUCTION_CHARS) continue;
+    empty.push({ kind: 'empty-instruction-file', severity: 'warn', file: item.file, scope: item.scope });
+  }
+  return empty;
+}
+
+export function memoryChecks(memories, index) {
+  return [
+    ...checkDuplicateNames(memories),
+    ...checkDuplicateIndexEntry(index),
+    ...checkMissingDescription(memories),
+    ...checkUnknownType(memories),
+    ...checkEmptyBody(memories),
+    ...checkHookRepeatsDescription(memories),
+    ...checkEmptySection(index),
+    ...checkIndexContinuation(index),
+  ];
+}
+
+export function instructionChecks(files) {
+  return [...checkDuplicateLoad(files), ...checkEmptyInstructionFile(files)];
+}

package/src/instructions.mjs

@@ -18,6 +18,7 @@ import path from 'node:path';
 import { parseFrontmatter } from './parse.mjs';
 import { estimateTokens } from './stats.mjs';
 import { lookup, settingsLayers } from './settings.mjs';
+import { instructionChecks } from './checks.mjs';
 
 /** Claude Code's own guidance for a CLAUDE.md. Guidance, not a cutoff. */
 export const CLAUDE_MD_TARGET_LINES = 200;
@@ -28,6 +29,38 @@ export const MAX_IMPORT_DEPTH = 4;
 /** A rule's whole `paths:` list shares this budget of expanded patterns. */
 export const BRACE_PATTERN_BUDGET = 1000;
 
+export const INSTRUCTION_SEVERITY = {
+  missing: 'bad',
+  'invalid-glob': 'bad',
+  'glob-budget': 'bad',
+  cycle: 'warn',
+  'too-deep': 'warn',
+  external: 'warn',
+  'long-claude-md': 'warn',
+  'agents-md-not-imported': 'warn',
+  'unreferenced-user-file': 'warn',
+  'duplicate-load': 'warn',
+  'empty-instruction-file': 'warn',
+};
+
+export function summarise(problems) {
+  const list = problems || [];
+  return {
+    count: list.length,
+    severity: list.some((problem) => INSTRUCTION_SEVERITY[problem.kind] === 'bad')
+      ? 'bad'
+      : list.length ? 'warn' : 'ok',
+  };
+}
+
+function stampSeverity(resolved) {
+  for (const problem of resolved.problems) {
+    problem.severity = INSTRUCTION_SEVERITY[problem.kind] || 'warn';
+  }
+  resolved.problems.sort((a, b) => (a.severity === 'bad' ? 0 : 1) - (b.severity === 'bad' ? 0 : 1));
+  return resolved;
+}
+
 function managedClaudeMd() {
   if (process.platform === 'darwin') return '/Library/Application Support/ClaudeCode/CLAUDE.md';
   if (process.platform === 'win32') return 'C:\\Program Files\\ClaudeCode\\CLAUDE.md';
@@ -431,6 +464,8 @@ function finalize(candidates, { projectDir, excludes }) {
     }
   }
 
+  problems.push(...instructionChecks(loaded));
+
   const unconditional = loaded.filter((item) => !item.conditional);
   return {
     projectDir,
@@ -503,7 +538,7 @@ export function resolveInstructions(projectDir) {
     resolved.problems.push({ kind: 'agents-md-not-imported', file: agentsFile, scope: 'project' });
   }
 
-  return resolved;
+  return stampSeverity(resolved);
 }
 
 /**
@@ -521,5 +556,5 @@ export function resolveGlobalInstructions({ home = os.homedir(), settingsFile =
   const layers = settingsLayers(settingsFile ? { settingsFile } : {});
   const resolved = finalize(userCandidates(home, layers), { projectDir: null, excludes: readExcludes(layers) });
   resolved.problems.push(...unreferencedUserFiles(home, resolved.files));
-  return resolved;
+  return stampSeverity(resolved);
 }

package/src/model.mjs

@@ -15,6 +15,7 @@ import { parseIndex, parseFrontmatter, extractWikilinks } from './parse.mjs';
 import { listMemoryFiles, memoryDir, resolveProjectPath, shortLabel } from './projects.mjs';
 import { autoMemoryState } from './settings.mjs';
 import { ageInDays, estimateTokens, findDuplicates, indexStats } from './stats.mjs';
+import { memoryChecks } from './checks.mjs';
 
 export const TRASH_DIR = '.trash';
 
@@ -173,8 +174,13 @@ export function buildStore(store) {
     ...(health.longHooks.length
       ? [{ kind: 'long-hooks', severity: 'warn', count: health.longHooks.length, longest: health.longHooks[0] }]
       : []),
+    ...memoryChecks(memories, index),
   ];
+  health.issues.sort((a, b) => (a.severity === 'bad' ? 0 : 1) - (b.severity === 'bad' ? 0 : 1));
   health.issueCount = health.issues.length;
+  health.severity = health.issues.some((item) => item.severity === 'bad')
+    ? 'bad'
+    : health.issues.length ? 'warn' : 'ok';
 
   return {
     ...store,

package/src/pathcheck.mjs

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const MAX_PATH_CHECKS = 200;
+export const MAX_INDEXED_FILES = 60000;
+
+export const SKIP_DIRS = new Set([
+  '.git', 'node_modules', 'bin', 'obj', 'dist', 'build', 'out', 'target', 'vendor',
+  '.next', '.nuxt', '.svelte-kit', '.venv', 'venv', '__pycache__', '.gradle', '.idea',
+  'Pods', 'DerivedData', 'coverage', '.turbo', '.cache', '.angular', '.parcel-cache',
+]);
+
+const CODE_SPAN = /`([^`\n]+)`/g;
+const SOURCE_EXT = /\.(mjs|cjs|jsx?|tsx?|json|jsonc|md|mdx|css|scss|less|html|vue|svelte|py|rb|go|rs|java|kt|swift|cs|fs|php|sh|zsh|ya?ml|toml|xml|sql|proto|lock|gradle|csproj|sln)$/i;
+const BARE_EXTENSION = /^\.[A-Za-z0-9]+$/;
+const LINE_SUFFIX = /:\d+(?:[-:]\d+)?$/;
+const GLOB_OR_SHELL = /[*?{}[\]()<>|$=!"'\\]/;
+
+function candidate(raw) {
+  let token = raw.trim();
+  if (!token || /\s/.test(token)) return null;
+  if (token.includes('://') || token.startsWith('@')) return null;
+  if (GLOB_OR_SHELL.test(token)) return null;
+
+  token = token.replace(LINE_SUFFIX, '').replace(/[.,;:]+$/, '').replace(/\/+$/, '');
+  if (token.startsWith('./')) token = token.slice(2);
+  if (!token || token.startsWith('/') || token.startsWith('~')) return null;
+  if (token.split('/').includes('..')) return null;
+  if (token.includes('...') || token.length > 200) return null;
+  if (BARE_EXTENSION.test(token)) return null;
+  if (!SOURCE_EXT.test(token)) return null;
+  if (token.split('/').some((segment) => SKIP_DIRS.has(segment))) return null;
+
+  return token;
+}
+
+export function pathCandidates(body) {
+  const found = new Set();
+  for (const match of String(body || '').matchAll(CODE_SPAN)) {
+    const token = candidate(match[1]);
+    if (token) found.add(token);
+  }
+  return [...found];
+}
+
+export function indexProject(root, { skipDirs = SKIP_DIRS, limit = MAX_INDEXED_FILES } = {}) {
+  const byLastSegment = new Map();
+  let count = 0;
+  let truncated = false;
+
+  const walk = (dir, prefix) => {
+    if (truncated) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (count >= limit) {
+        truncated = true;
+        return;
+      }
+      if (skipDirs.has(entry.name)) continue;
+
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      count += 1;
+      if (!byLastSegment.has(entry.name)) byLastSegment.set(entry.name, []);
+      byLastSegment.get(entry.name).push(relative);
+
+      if (entry.isDirectory()) walk(path.join(dir, entry.name), relative);
+    }
+  };
+
+  walk(root, '');
+  return { byLastSegment, count, truncated };
+}
+
+function resolvesInProject(index, token) {
+  const matches = index.byLastSegment.get(token.split('/').pop());
+  if (!matches) return false;
+  if (!token.includes('/')) return true;
+  return matches.some((relative) => relative === token || relative.endsWith(`/${token}`));
+}
+
+export function verifyPaths(projectDir, memories) {
+  const root = path.resolve(projectDir);
+  const index = indexProject(root);
+  const missing = [];
+  let checked = 0;
+  let capped = false;
+
+  for (const memory of memories) {
+    for (const token of pathCandidates(memory.body)) {
+      if (checked >= MAX_PATH_CHECKS) {
+        capped = true;
+        break;
+      }
+      checked += 1;
+      if (!resolvesInProject(index, token)) {
+        missing.push({ kind: 'stale-path', severity: 'warn', file: memory.file, name: memory.name, token });
+      }
+    }
+    if (capped) break;
+  }
+
+  return { projectDir: root, checked, capped, indexed: index.count, truncated: index.truncated, missing };
+}

package/src/settings.mjs

@@ -19,6 +19,21 @@ export const USER_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json')
 /** Default when nothing sets cleanupPeriodDays; transcripts older than this are swept. */
 export const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
 
+export const SETTINGS_SEVERITY = {
+  unparseable: 'bad',
+  unreadable: 'bad',
+  'not-object': 'bad',
+  'invalid-auto-memory-directory': 'bad',
+};
+
+export function summariseSettings(problems) {
+  const list = problems || [];
+  return {
+    count: list.length,
+    severity: list.some((problem) => problem.severity === 'bad') ? 'bad' : list.length ? 'warn' : 'ok',
+  };
+}
+
 function managedDir() {
   if (process.platform === 'darwin') return '/Library/Application Support/ClaudeCode';
   if (process.platform === 'win32') return 'C:\\Program Files\\ClaudeCode';
@@ -226,12 +241,19 @@ export function settingsReport(options = {}) {
 
   const problems = layers
     .filter((layer) => layer.status !== 'ok' && layer.status !== 'absent')
-    .map((layer) => ({ kind: layer.status, scope: layer.scope, file: layer.file, detail: layer.error }));
+    .map((layer) => ({
+      kind: layer.status,
+      severity: SETTINGS_SEVERITY[layer.status] || 'warn',
+      scope: layer.scope,
+      file: layer.file,
+      detail: layer.error,
+    }));
 
   const directory = resolveMemoryDirectory(options);
   if (directory && directory.invalid) {
     problems.push({
       kind: 'invalid-auto-memory-directory',
+      severity: SETTINGS_SEVERITY['invalid-auto-memory-directory'],
       scope: directory.scope,
       file: directory.file,
       detail: `"${directory.raw}" is ${directory.invalid}`,