claude-memory-admin 1.3.0 → 1.5.0

package/src/model.mjs

@@ -15,6 +15,9 @@ 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, sessionChecks } from './checks.mjs';
+import { listSessions, originSession, retention, transcriptDir } from './sessions.mjs';
+import { rememberedPath } from './pathcache.mjs';
 
 export const TRASH_DIR = '.trash';
 
@@ -94,9 +97,30 @@ function buildResolver(memories) {
   return (target) => byName.get(target) || byStem.get(target) || null;
 }
 
+function provenance(memory, resolveOrigin) {
+  const sessionId = memory.metadata?.originSessionId;
+  if (typeof sessionId !== 'string' || !sessionId) return null;
+  const session = resolveOrigin ? resolveOrigin(sessionId) : null;
+  return { sessionId, present: Boolean(session), modified: session ? session.modified : null };
+}
+
+function sessionContext(store) {
+  const slugDir = transcriptDir(store);
+  if (!slugDir) return { slugDir: null, retention: null, resolveOrigin: null, remembered: false };
+
+  const projectDir = store.pathExists ? store.path : null;
+  return {
+    slugDir,
+    retention: retention(listSessions(slugDir), { projectDir }),
+    resolveOrigin: (sessionId) => originSession(slugDir, sessionId),
+    remembered: Boolean(store.slug && rememberedPath(store.slug)),
+  };
+}
+
 export function buildStore(store) {
   const { dir } = store;
   const hasMemoryDir = fs.existsSync(dir);
+  const sessions = sessionContext(store);
 
   const indexRaw = readIfExists(path.join(dir, 'MEMORY.md'));
   const index = indexRaw === null ? null : parseIndex(indexRaw);
@@ -138,6 +162,7 @@ export function buildStore(store) {
       : referencedFiles.has(memory.file)
         ? 'referenced'
         : 'orphan';
+    memory.origin = provenance(memory, sessions.resolveOrigin);
   }
 
   const existingFiles = new Set(files);
@@ -173,8 +198,17 @@ export function buildStore(store) {
     ...(health.longHooks.length
       ? [{ kind: 'long-hooks', severity: 'warn', count: health.longHooks.length, longest: health.longHooks[0] }]
       : []),
+    ...memoryChecks(memories, index),
+    ...sessionChecks(store, memories, sessions.retention, {
+      remembered: sessions.remembered,
+      resolveOrigin: sessions.resolveOrigin,
+    }),
   ];
+  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,
@@ -203,6 +237,16 @@ export function buildStore(store) {
     },
     duplicates: findDuplicates(memories),
     trash: listTrash(dir),
+    sessions: sessions.retention
+      ? {
+          count: sessions.retention.count,
+          bytes: sessions.retention.bytes,
+          retentionDays: sessions.retention.days,
+          evidenceExpiresInDays: sessions.retention.evidenceExpiresInDays,
+          expiringCount: sessions.retention.expiringCount,
+          remembered: sessions.remembered,
+        }
+      : null,
   };
 }
 
@@ -218,6 +262,7 @@ export function buildProject(root, slug) {
     kind: 'auto',
     dir: memoryDir(root, slug),
     path: resolved.path,
+    pathExists: resolved.exists,
     label: shortLabel(resolved.path),
     resolvedBy: resolved.resolvedBy,
     // The decode that could not be confirmed, offered as a starting point when

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/projects.mjs

@@ -51,12 +51,16 @@ export function projectsRoot() {
   return resolveRoot().path;
 }
 
+// The escalation ladder for reading the head of a transcript: the small read
+// almost always suffices and the large one is the fallback.
+export const HEAD_READS = [16384, 131072];
+
 /**
  * Read the head of a file without pulling a multi-megabyte transcript into
  * memory. The `cwd` field shows up within the first few lines in practice, so
  * the small read almost always suffices and the large one is a fallback.
  */
-function readHead(file, bytes) {
+export function readHead(file, bytes) {
   const fd = fs.openSync(file, 'r');
   try {
     const buf = Buffer.alloc(bytes);
@@ -90,7 +94,7 @@ function findTranscripts(dir, depth = 2) {
 
 /** The first `cwd` in one transcript, escalating the read only if the small one missed. */
 function cwdInTranscript(file) {
-  for (const size of [16384, 131072]) {
+  for (const size of HEAD_READS) {
     let head;
     try {
       head = readHead(file, size);

package/src/sessions.mjs

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { HEAD_READS, readHead } from './projects.mjs';
+import { cleanupPeriodDays } from './settings.mjs';
+import { ageInDays } from './stats.mjs';
+
+export const EXPIRY_WARNING_DAYS = 7;
+export const PROMPT_TITLE_CHARS = 80;
+export const PROMPT_PREVIEW_CHARS = 400;
+
+const SESSION_ID = /^[0-9a-fA-F][0-9a-fA-F-]{7,63}$/;
+const SELF_DESCRIBING_KEYS = ['slug', 'gitBranch', 'model', 'version', 'cwd'];
+const WRAPPED_BY_CLAUDE_CODE = /^<(local-command-[a-z]+|command-(message|name|args)|system-reminder)>/;
+
+const isSubagentTranscript = (name) => name.startsWith('agent-');
+const isSessionTranscript = (name) => name.endsWith('.jsonl') && !isSubagentTranscript(name);
+
+export function listSessions(slugDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(slugDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const sessions = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !isSessionTranscript(entry.name)) continue;
+    const file = path.join(slugDir, entry.name);
+    let stat;
+    try {
+      stat = fs.statSync(file);
+    } catch {
+      continue;
+    }
+    sessions.push({
+      id: entry.name.replace(/\.jsonl$/, ''),
+      file,
+      bytes: stat.size,
+      modified: new Date(stat.mtimeMs).toISOString(),
+      modifiedMs: stat.mtimeMs,
+    });
+  }
+  return sessions.sort((a, b) => b.modifiedMs - a.modifiedMs);
+}
+
+function promptText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return null;
+  const joined = content
+    .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join(' ');
+  return joined || null;
+}
+
+function absorbRecord(record, found) {
+  if (!record || typeof record !== 'object') return;
+
+  if (record.type === 'ai-title' && typeof record.aiTitle === 'string' && record.aiTitle) {
+    found.aiTitle = record.aiTitle;
+  }
+  for (const key of SELF_DESCRIBING_KEYS) {
+    const value = typeof record[key] === 'string' ? record[key] : record.message?.[key];
+    if (found[key] === null && typeof value === 'string' && value) found[key] = value;
+  }
+  if (found.prompt === null && record.type === 'user' && !record.isSidechain) {
+    const text = promptText(record.message?.content)?.trim();
+    if (text && !WRAPPED_BY_CLAUDE_CODE.test(text)) found.prompt = text;
+  }
+}
+
+function absorbChunk(head, found) {
+  for (const line of head.split('\n')) {
+    if (!line.startsWith('{')) continue;
+    try {
+      absorbRecord(JSON.parse(line), found);
+    } catch {
+      continue;
+    }
+  }
+}
+
+function condense(text, chars) {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > chars ? `${flat.slice(0, chars - 1)}…` : flat;
+}
+
+export function sessionSummary(file, { bytes = null } = {}) {
+  const found = { aiTitle: null, slug: null, gitBranch: null, model: null, version: null, cwd: null, prompt: null };
+
+  let size = bytes;
+  if (size === null) {
+    try {
+      size = fs.statSync(file).size;
+    } catch {
+      size = 0;
+    }
+  }
+
+  for (const read of HEAD_READS) {
+    let head;
+    try {
+      head = readHead(file, read);
+    } catch {
+      break;
+    }
+    absorbChunk(head, found);
+    if (found.aiTitle || size <= read) break;
+  }
+
+  const titleFrom = found.aiTitle ? 'ai-title' : found.slug ? 'slug' : found.prompt ? 'prompt' : null;
+  const title = found.aiTitle
+    || found.slug
+    || (found.prompt ? condense(found.prompt, PROMPT_TITLE_CHARS) : null);
+
+  return {
+    title,
+    titleFrom,
+    slug: found.slug,
+    gitBranch: found.gitBranch,
+    model: found.model,
+    version: found.version,
+    cwd: found.cwd,
+    prompt: found.prompt ? condense(found.prompt, PROMPT_PREVIEW_CHARS) : null,
+  };
+}
+
+export function retention(sessions, { projectDir = null, now = Date.now() } = {}) {
+  const days = cleanupPeriodDays(projectDir ? { projectDir } : {});
+  const dated = sessions.map((session) => {
+    const ageDays = ageInDays(session.modified, now);
+    return { ...session, ageDays, expiresInDays: ageDays === null ? null : Math.max(0, days - ageDays) };
+  });
+  const remaining = dated.map((session) => session.expiresInDays).filter((value) => value !== null);
+
+  return {
+    days,
+    dateFrom: 'mtime',
+    sessions: dated,
+    count: dated.length,
+    bytes: dated.reduce((sum, session) => sum + session.bytes, 0),
+    evidenceExpiresInDays: remaining.length ? Math.max(...remaining) : null,
+    expiringCount: remaining.filter((value) => value <= EXPIRY_WARNING_DAYS).length,
+  };
+}
+
+export function originSession(slugDir, sessionId) {
+  if (typeof sessionId !== 'string' || !SESSION_ID.test(sessionId)) return null;
+  const file = path.join(slugDir, `${sessionId}.jsonl`);
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile()) return null;
+  return { id: sessionId, file, bytes: stat.size, modified: new Date(stat.mtimeMs).toISOString() };
+}
+
+export function transcriptDir(store) {
+  return store && store.kind === 'auto' && store.dir ? path.dirname(store.dir) : null;
+}
+
+export function sessionsWithSummaries(slugDir, { projectDir = null, now = Date.now() } = {}) {
+  const report = retention(listSessions(slugDir), { projectDir, now });
+  return {
+    ...report,
+    sessions: report.sessions.map((session) => ({
+      ...session,
+      ...sessionSummary(session.file, { bytes: session.bytes }),
+    })),
+  };
+}

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}`,