claude-memory-admin 1.5.2 → 1.7.0

package/public/views/worklist.mjs

@@ -0,0 +1,33 @@
+const COST_KINDS = new Set(['long-hook', 'hook-repeats-description', 'empty-section', 'index-continuation']);
+
+function rankOf(kind, severity) {
+  if (kind === 'past-cutoff') return 0;
+  if (severity === 'bad') return 1;
+  if (COST_KINDS.has(kind)) return 2;
+  if (kind === 'overlap') return 4;
+  return 3;
+}
+
+export function buildWorklist(store) {
+  if (!store || !store.stats) return [];
+  const items = [];
+  const { index } = store.stats;
+
+  for (const entry of index.cutoff?.droppedEntries ?? []) {
+    items.push({ kind: 'past-cutoff', severity: 'bad', entry });
+  }
+  for (const hook of index.longHooks) {
+    items.push({ kind: 'long-hook', severity: 'warn', hook });
+  }
+  for (const item of store.health.issues) {
+    if (item.kind === 'long-hooks') continue;
+    items.push(item);
+  }
+  for (const pair of store.duplicates) {
+    items.push({ kind: 'overlap', severity: 'warn', pair });
+  }
+
+  return items
+    .map((item) => ({ ...item, rank: rankOf(item.kind, item.severity) }))
+    .sort((a, b) => a.rank - b.rank);
+}

package/server.mjs

@@ -16,6 +16,7 @@ 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 { findRtk, rtkReport } from './src/rtk.mjs';
 import { sessionsWithSummaries, transcriptDir } from './src/sessions.mjs';
 import {
   addIndexEntry,
@@ -217,6 +218,7 @@ async function handleApi(req, res, url) {
       rootSource: origin.path === ROOT ? origin.source : 'flag',
       rootFile: origin.path === ROOT ? origin.file : null,
       rootWarning: origin.invalid,
+      tools: [findRtk()],
       stores: listStores(ROOT),
     });
   }
@@ -276,6 +278,13 @@ async function handleApi(req, res, url) {
     return sendJson(res, 200, sessionsWithSummaries(slugDir, { projectDir: storeProjectDir(store) }));
   }
 
+  if (action === 'tools/rtk' && req.method === 'GET') {
+    const rtk = findRtk();
+    if (!rtk.found) throw new Error('rtk is not installed, or not on the PATH this server was started with.');
+    const report = await rtkReport(storeProjectDir(store));
+    return sendJson(res, 200, { ...report, path: rtk.path });
+  }
+
   if (action === 'settings' && req.method === 'GET') {
     return sendJson(res, 200, settingsReport({ projectDir: storeProjectDir(store) }));
   }

package/src/rtk.mjs

@@ -0,0 +1,179 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const BINARY = 'rtk';
+const TIMEOUT_MS = 15000;
+const MAX_BUFFER = 4 * 1024 * 1024;
+const DISCOVER_DAYS = 30;
+const DISCOVER_LIMIT = 10;
+const MISSED_LIMIT = 12;
+const TREND_DAYS = 30;
+
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const text = (value) => (typeof value === 'string' ? value : '');
+const pct = (part, whole) => (whole > 0 ? (part / whole) * 100 : 0);
+
+function candidateNames(env) {
+  if (process.platform !== 'win32') return [BINARY];
+  const exts = text(env.PATHEXT || '.EXE').split(';').filter(Boolean);
+  return exts.map((ext) => BINARY + ext.toLowerCase());
+}
+
+export function findRtk(env = process.env) {
+  const dirs = text(env.PATH).split(path.delimiter).filter(Boolean);
+  const names = candidateNames(env);
+  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);
+        return { id: BINARY, found: true, path: candidate };
+      } catch {
+        continue;
+      }
+    }
+  }
+  return { id: BINARY, found: false, path: null };
+}
+
+function runRtk(args, { cwd, timeout = TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    const options = { cwd, timeout, maxBuffer: MAX_BUFFER, windowsHide: true, encoding: 'utf8' };
+    execFile(BINARY, args, options, (err, stdout, stderr) => {
+      if (!err) return resolve(stdout);
+      if (err.code === 'ENOENT') return reject(new Error('rtk is not on this process PATH'));
+      if (err.killed) return reject(new Error(`rtk ${args[0]} was still running after ${timeout}ms and was stopped`));
+      const detail = text(stderr || stdout).trim().split('\n')[0];
+      return reject(new Error(detail ? `rtk ${args[0]} failed: ${detail}` : `rtk ${args[0]} exited ${err.code}`));
+    });
+  });
+}
+
+function parseJson(raw, label) {
+  try {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== 'object') throw new Error('not an object');
+    return value;
+  } catch {
+    throw new Error(`rtk ${label} did not answer with JSON`);
+  }
+}
+
+function summaryOf(raw) {
+  const summary = raw && typeof raw.summary === 'object' && raw.summary ? raw.summary : {};
+  return {
+    commands: num(summary.total_commands),
+    input: num(summary.total_input),
+    output: num(summary.total_output),
+    saved: num(summary.total_saved),
+    savedPct: num(summary.avg_savings_pct),
+    totalMs: num(summary.total_time_ms),
+    avgMs: num(summary.avg_time_ms),
+  };
+}
+
+function daysOf(raw) {
+  const list = raw && Array.isArray(raw.daily) ? raw.daily : [];
+  return list
+    .filter((day) => day && typeof day === 'object')
+    .map((day) => ({
+      date: text(day.date),
+      commands: num(day.commands),
+      input: num(day.input_tokens),
+      saved: num(day.saved_tokens),
+      savedPct: num(day.savings_pct),
+    }))
+    .filter((day) => day.date);
+}
+
+function windowOf(days, count) {
+  const recent = days.slice(-count);
+  const totals = recent.reduce((sum, day) => ({
+    commands: sum.commands + day.commands,
+    input: sum.input + day.input,
+    saved: sum.saved + day.saved,
+  }), { commands: 0, input: 0, saved: 0 });
+  return {
+    days: count,
+    active: recent.length,
+    commands: totals.commands,
+    saved: totals.saved,
+    savedPct: pct(totals.saved, totals.input),
+  };
+}
+
+function discoverOf(raw) {
+  const commands = num(raw.total_commands);
+  const alreadyRtk = num(raw.already_rtk);
+  const supported = Array.isArray(raw.supported) ? raw.supported : [];
+  const missed = supported
+    .filter((item) => item && typeof item === 'object')
+    .map((item) => ({
+      command: text(item.command),
+      count: num(item.count),
+      equivalent: text(item.rtk_equivalent),
+      category: text(item.category),
+      savedTokens: num(item.estimated_savings_tokens),
+      savedPct: num(item.estimated_savings_pct),
+    }))
+    .filter((item) => item.command)
+    .sort((a, b) => b.savedTokens - a.savedTokens);
+
+  return {
+    sessionsScanned: num(raw.sessions_scanned),
+    commands,
+    alreadyRtk,
+    adoptionPct: pct(alreadyRtk, commands),
+    sinceDays: num(raw.since_days) || DISCOVER_DAYS,
+    missedTotal: missed.length,
+    missed: missed.slice(0, MISSED_LIMIT),
+  };
+}
+
+function usableDir(dir) {
+  if (!dir) return null;
+  try {
+    return fs.statSync(dir).isDirectory() ? dir : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function rtkReport(projectDir, { run = runRtk, home = os.homedir() } = {}) {
+  const errors = [];
+  const step = async (label, work) => {
+    try {
+      return await work();
+    } catch (err) {
+      errors.push({ step: label, message: err.message });
+      return null;
+    }
+  };
+
+  const dir = usableDir(projectDir);
+
+  const [version, machine, project, discover] = await Promise.all([
+    step('version', async () => text(await run(['--version'], { cwd: home })).trim().replace(/^rtk\s+/, '')),
+    step('gain', async () => parseJson(await run(['gain', '-a', '--format', 'json'], { cwd: home }), 'gain')),
+    dir ? step('gain --project', async () => parseJson(await run(['gain', '-p', '--format', 'json'], { cwd: dir }), 'gain --project')) : null,
+    dir ? step('discover', async () => parseJson(
+      await run(['discover', '--format', 'json', '-s', String(DISCOVER_DAYS), '-l', String(DISCOVER_LIMIT)], { cwd: dir }),
+      'discover',
+    )) : null,
+  ]);
+
+  const days = daysOf(machine);
+
+  return {
+    tool: BINARY,
+    version: version || null,
+    projectDir: dir,
+    machine: machine ? { ...summaryOf(machine), days, window: windowOf(days, TREND_DAYS) } : null,
+    project: project ? summaryOf(project) : null,
+    discover: discover ? discoverOf(discover) : null,
+    errors,
+  };
+}

package/public/views/health.mjs

@@ -1,21 +0,0 @@
-import * as ui from '/ui.mjs';
-import { node } from '/dom.mjs';
-import { state } from '/state.mjs';
-import { renderIssue } from '/views/issue.mjs';
-import { renderPathCheck } from '/views/path-check.mjs';
-
-export 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.' }),
-    ]));
-  } else {
-    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);
-}

package/public/views/prune.mjs

@@ -1,191 +0,0 @@
-import * as ui from '/ui.mjs';
-import { node } from '/dom.mjs';
-import { state } from '/state.mjs';
-import { paint } from '/bus.mjs';
-import { formatAge } from '/parts.mjs';
-import { selectMemory } from '/store.mjs';
-import { openBulkDeleteDialog } from '/dialogs/bulk-delete.mjs';
-import { openMergeDialog } from '/dialogs/merge.mjs';
-import { openMoveDialog } from '/dialogs/move.mjs';
-import { openHookEditor } from '/dialogs/hook-editor.mjs';
-
-const PRUNE_SORTS = {
-  oldest: { label: 'oldest first', compare: (a, b) => (b.ageDays ?? -1) - (a.ageDays ?? -1) },
-  largest: { label: 'largest first', compare: (a, b) => b.bytes - a.bytes },
-  unlinked: { label: 'least linked', compare: (a, b) => a.inbound.length - b.inbound.length || (b.ageDays ?? 0) - (a.ageDays ?? 0) },
-  name: { label: 'by name', compare: (a, b) => a.name.localeCompare(b.name) },
-};
-
-function renderBudget(container) {
-  const { index } = state.store.stats;
-  const percent = Math.min(100, index.worstPercent);
-  const level = index.level;
-
-  const note = index.level === 'over'
-    ? 'Over the limit. Everything past the cutoff is dropped when the session loads it, so those entries are effectively invisible to Claude right now.'
-    : index.level === 'near'
-      ? 'Approaching the limit. Once MEMORY.md passes it, everything after the cutoff stops being loaded at all.'
-      : 'Comfortably inside the limit. MEMORY.md is loaded at the start of every session.';
-
-  if (index.cutoff) {
-    const dropped = index.cutoff.droppedEntries;
-    const box = node('div', { class: ui.cutSummary });
-    box.append(node('div', { class: ui.cutSummaryHead, text: dropped.length
-      ? `${dropped.length} ${dropped.length === 1 ? 'memory is' : 'memories are'} past the cutoff and not loaded`
-      : `${index.cutoff.droppedLines} lines are past the cutoff and not loaded` }));
-    box.append(node('p', { class: ui.note, text: `MEMORY.md stops loading at line ${index.cutoff.rawLine + 1}, bounded by ${index.cutoff.by}. Claude cannot see anything below it.` }));
-    for (const entry of dropped.slice(0, 20)) {
-      box.append(node('div', { class: ui.issue(true) }, [
-        node('div', { class: ui.issueBody }, [
-          node('div', { class: ui.issueTitle, text: entry.title || entry.file }),
-          node('div', { class: ui.issueDetail, text: `MEMORY.md line ${entry.index + 1} · ${entry.file}` }),
-        ]),
-        node('button', { class: ui.buttonSmall, text: 'Open', onclick: () => selectMemory(entry.file) }),
-        node('button', { class: ui.buttonPrimarySmall, text: 'Move up', onclick: () => openMoveDialog(entry) }),
-      ]));
-    }
-    if (dropped.length > 20) {
-      box.append(node('p', { class: ui.note, text: `${dropped.length - 20} more not listed.` }));
-    }
-    container.append(box);
-  }
-
-  container.append(node('div', { class: ui.meter }, [
-    node('div', { class: ui.meterTop }, [
-      node('span', { class: ui.meterValue, text: `${Math.round(index.worstPercent)}%` }),
-      node('span', { class: ui.meterUnit, text: `of the MEMORY.md load limit, currently bounded by ${index.limitedBy}` }),
-    ]),
-    node('div', { class: ui.meterBar }, [
-      node('div', { class: ui.meterFill(level), style: `width:${percent.toFixed(1)}%` }),
-    ]),
-    node('p', { class: ui.meterNote, text: note }),
-    node('div', { class: ui.meterFacts }, [
-      node('span', {}, [node('b', { class: ui.meterFactValue, text: `${index.lines} / ${index.lineLimit}` }), document.createTextNode(' lines')]),
-      node('span', {}, [node('b', { class: ui.meterFactValue, text: `${(index.bytes / 1024).toFixed(1)} / ${index.byteLimit / 1024} KB` }), document.createTextNode(' loaded size')]),
-      node('span', {}, [node('b', { class: ui.meterFactValue, text: String(index.entryCount) }), document.createTextNode(' index entries')]),
-      node('span', {}, [node('b', { class: ui.meterFactValue, text: `~${index.tokens.toLocaleString()}` }), document.createTextNode(' tokens, every session')]),
-    ]),
-    node('p', { class: ui.meterNote, text: 'Claude Code loads the first 200 lines or 25KB of MEMORY.md, whichever comes first, and drops the rest. Topic files are only read when Claude follows a link, so detail belongs in them and MEMORY.md should stay one line per entry.' }),
-  ]));
-}
-
-export function renderPrune(container) {
-  const project = state.store;
-  renderBudget(container);
-
-  if (!project.memories.length) {
-    container.append(node('p', { class: ui.note, text: 'Nothing to prune - this project has no memories.' }));
-    return;
-  }
-
-  const selected = state.pruneSelection;
-  const bar = node('div', { class: ui.pruneBar });
-  const sort = node('select', { class: ui.select });
-  for (const [key, config] of Object.entries(PRUNE_SORTS)) {
-    sort.append(node('option', { value: key, text: config.label, selected: key === state.pruneSort ? '' : null }));
-  }
-  sort.value = state.pruneSort;
-  sort.onchange = () => { state.pruneSort = sort.value; paint('tab'); };
-
-  const count = node('span', { class: ui.note });
-  const deleteButton = node('button', { class: ui.buttonDangerSmall });
-  const clearButton = node('button', { class: ui.buttonSmall, text: 'Clear selection' });
-
-  bar.append(node('span', { class: ui.sectionLabel, text: 'Prune' }), sort, node('span', { class: ui.pruneSpacer }), count, clearButton, deleteButton);
-  container.append(bar);
-
-  const list = node('div');
-  const ordered = [...project.memories].sort(PRUNE_SORTS[state.pruneSort].compare);
-  const rows = [];
-  for (const memory of ordered) {
-    const box = node('input', { type: 'checkbox', class: ui.checkbox });
-    box.checked = selected.has(memory.file);
-    const row = node('label', { class: ui.pruneRow(box.checked) }, [
-      box,
-      node('span', { class: ui.pruneMain }, [
-        node('span', { class: ui.pruneName, text: memory.name }),
-        node('span', { class: ui.pruneDesc, text: memory.description || memory.file }),
-      ]),
-      node('span', { class: ui.pruneFacts }, [
-        node('span', { class: ui.pruneFact((memory.ageDays ?? 0) > 180), text: formatAge(memory.ageDays) }),
-        node('span', { text: `${(memory.bytes / 1024).toFixed(1)}K` }),
-        node('span', { class: ui.pruneFact(!memory.inbound.length), text: `${memory.inbound.length} in` }),
-        node('span', { class: ui.pruneFact(memory.status !== 'indexed'), text: memory.status }),
-      ]),
-    ]);
-    box.addEventListener('change', () => {
-      if (box.checked) selected.add(memory.file); else selected.delete(memory.file);
-      row.className = ui.pruneRow(box.checked);
-      updateBar();
-    });
-    rows.push({ box, memory });
-    list.append(row);
-  }
-  container.append(list);
-
-  function updateBar() {
-    count.textContent = selected.size ? `${selected.size} selected` : '';
-    deleteButton.textContent = `Delete ${selected.size || ''}`.trim();
-    deleteButton.disabled = selected.size === 0;
-  }
-  clearButton.onclick = () => {
-    selected.clear();
-    paint('tab');
-  };
-  deleteButton.onclick = () => openBulkDeleteDialog([...selected]);
-  updateBar();
-
-  const { longHooks } = project.stats.index;
-  if (longHooks.length) {
-    container.append(node('div', { class: ui.sectionLabel, text: `Long index hooks · ${longHooks.length}` }));
-    container.append(node('p', { class: ui.noteTight, text: 'The hook is the text after the dash in MEMORY.md. It is loaded every session, so a 400-character hook costs more than the memory it points at. Shortening these is the cheapest win.' }));
-    for (const hook of longHooks.slice(0, 12)) {
-      const row = node('div', { class: ui.issue(false) });
-      const editButton = node('button', { class: ui.buttonPrimarySmall, text: 'Edit hook' });
-      row.append(
-        node('div', { class: ui.issueBody }, [
-          node('div', { class: ui.issueTitle, text: `${hook.hookLength} chars: ${hook.title}` }),
-          node('div', { class: ui.issueDetail, text: `MEMORY.md line ${hook.index + 1} · ${hook.file}` }),
-        ]),
-        node('button', { class: ui.buttonSmall, text: 'Open', onclick: () => selectMemory(hook.file) }),
-        editButton,
-      );
-      editButton.onclick = () => openHookEditor(row, hook.index);
-      container.append(row);
-    }
-  }
-
-  if (project.duplicates.length) {
-    container.append(node('div', { class: ui.sectionLabel, text: `Possible overlap · ${project.duplicates.length}` }));
-    container.append(node('p', { class: ui.noteTight, text: 'Ranked by how much rare vocabulary these pairs share. This is a hint, not a verdict - open both and decide whether one covers the other.' }));
-    for (const pair of project.duplicates) {
-      container.append(node('div', { class: ui.dupe }, [
-        node('div', { class: ui.dupeHead }, [
-          node('span', { class: ui.dupeScore, text: `${pair.score}%` }),
-          node('span', { text: `shared: ${pair.shared.join(', ')}` }),
-        ]),
-        node('div', { class: ui.dupePair }, [
-          ...[pair.a, pair.b].map((side) => node('div', {
-            class: ui.dupeSide,
-            onclick: () => selectMemory(side.file),
-          }, [
-            node('div', { class: ui.dupeSideName, text: side.name }),
-            node('div', { class: ui.dupeSideDesc, text: side.description || side.file }),
-          ])),
-        ]),
-        node('div', { class: ui.dupeActions }, [
-          node('button', {
-            class: ui.buttonSmall,
-            text: `Merge into ${pair.a.name}`,
-            onclick: () => openMergeDialog(pair.a.file, pair.b.file),
-          }),
-          node('button', {
-            class: ui.buttonSmall,
-            text: `Merge into ${pair.b.name}`,
-            onclick: () => openMergeDialog(pair.b.file, pair.a.file),
-          }),
-        ]),
-      ]));
-    }
-  }
-}

package/public/views/trash.mjs

@@ -1,37 +0,0 @@
-import * as ui from '/ui.mjs';
-import { node } from '/dom.mjs';
-import { state } from '/state.mjs';
-import { restoreFromTrash } from '/store.mjs';
-
-const INDEX_EDIT_LABELS = {
-  hook: 'MEMORY.md hook shortened',
-  move: 'MEMORY.md entry moved',
-  add: 'MEMORY.md entry added',
-};
-
-export function renderTrash(container) {
-  const trash = state.store.trash;
-  if (!trash.length) {
-    container.append(node('p', { class: ui.note, text: 'Nothing in the trash. Deleted memories land here and can be restored.' }));
-    return;
-  }
-  for (const record of trash) {
-    const when = String(record.deletedAt).replace('T', ' ').replace(/\..*$/, '');
-    const detail = record.kind === 'wikilink'
-      ? `unlinked in ${record.sourceFile} · ${when}`
-      : record.kind === 'index-edit'
-        ? `${INDEX_EDIT_LABELS[record.op] || 'MEMORY.md edited'} · ${when}`
-        : record.kind === 'merge'
-          ? `merged into ${record.into} · ${when} · ${record.backups?.length || 0} file(s) rewritten`
-          : `${record.files.length} file(s)${record.indexTrashedFile ? ' + MEMORY.md' : ''} · ${when} · ${record.removedLines?.length || 0} index line(s) removed`;
-    container.append(node('div', { class: ui.issue(!record.present) }, [
-      node('div', { class: ui.issueBody }, [
-        node('div', { class: ui.issueTitle, text: record.label || record.id }),
-        node('div', { class: ui.issueDetail, text: record.present ? detail : `${detail}, backup missing, cannot restore` }),
-      ]),
-      record.present
-        ? node('button', { class: ui.buttonPrimarySmall, text: 'Restore', onclick: () => restoreFromTrash(record.id) })
-        : null,
-    ]));
-  }
-}