claude-memory-admin 1.0.0 → 1.0.1

package/src/settings.mjs

@@ -0,0 +1,151 @@
+// Layered reads of Claude Code's settings files.
+//
+// Several keys this tool cares about - autoMemoryDirectory, autoMemoryEnabled -
+// can be set in any settings scope, and the scope that wins is not the one you
+// would guess: managed policy beats everything, and the user file everyone
+// actually edits is the weakest of the five. Reading only ~/.claude/settings.json
+// silently shows the wrong store to anyone who set the key anywhere else.
+//
+// Precedence, strongest first:
+//   managed policy  ->  --settings  ->  .claude/settings.local.json
+//               ->  .claude/settings.json  ->  ~/.claude/settings.json
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const USER_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+
+/** Default when nothing sets cleanupPeriodDays; transcripts older than this are swept. */
+export const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
+
+function managedDir() {
+  if (process.platform === 'darwin') return '/Library/Application Support/ClaudeCode';
+  if (process.platform === 'win32') return 'C:\\Program Files\\ClaudeCode';
+  return '/etc/claude-code';
+}
+
+/**
+ * Managed policy settings: the main file plus the managed-settings.d drop-in
+ * directory, which organisations use to compose policy from several files.
+ */
+export function managedSettingsFiles() {
+  const dir = managedDir();
+  const files = [path.join(dir, 'managed-settings.json')];
+  let dropIns;
+  try {
+    dropIns = fs.readdirSync(path.join(dir, 'managed-settings.d'));
+  } catch {
+    dropIns = [];
+  }
+  for (const name of dropIns.filter((n) => n.endsWith('.json')).sort()) {
+    files.push(path.join(dir, 'managed-settings.d', name));
+  }
+  return files;
+}
+
+function readJson(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    // Absent, unreadable, or not valid JSON. Claude Code would ignore it too.
+    return null;
+  }
+}
+
+/**
+ * Every settings file that exists and parses, strongest first, each tagged with
+ * the scope it came from so the UI can name the file a value came from rather
+ * than leaving the user to guess which of five files is in charge.
+ *
+ * `projectDir` is the directory a session would run in. This tool browses every
+ * project at once and is not itself a session, so callers pass either the launch
+ * cwd (for the store location, which is decided before any project is chosen) or
+ * a specific project's resolved path (for that project's auto memory state).
+ */
+export function settingsLayers({ projectDir = null, settingsFile = null } = {}) {
+  const candidates = [];
+  for (const file of managedSettingsFiles()) candidates.push({ scope: 'managed', file });
+  if (settingsFile) candidates.push({ scope: 'settings-flag', file: settingsFile });
+  if (projectDir) {
+    candidates.push({ scope: 'local', file: path.join(projectDir, '.claude', 'settings.local.json') });
+    candidates.push({ scope: 'project', file: path.join(projectDir, '.claude', 'settings.json') });
+  }
+  candidates.push({ scope: 'user', file: USER_SETTINGS });
+
+  const layers = [];
+  for (const candidate of candidates) {
+    const data = readJson(candidate.file);
+    if (data) layers.push({ ...candidate, data });
+  }
+  return layers;
+}
+
+/** First layer that defines `key`, or null. Layers are already in precedence order. */
+export function lookup(layers, key) {
+  for (const layer of layers) {
+    if (Object.prototype.hasOwnProperty.call(layer.data, key)) {
+      return { value: layer.data[key], scope: layer.scope, file: layer.file };
+    }
+  }
+  return null;
+}
+
+export function expandHome(value) {
+  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+/**
+ * Where the auto memory store lives, per settings.
+ *
+ * The documented contract is "an absolute path or a `~/`-prefixed path". A value
+ * that is neither is reported rather than quietly ignored: the alternative is
+ * showing someone the default store while their setting points elsewhere, which
+ * is the exact failure this function exists to prevent.
+ *
+ * Returns { path, scope, file } when set, { invalid, ... } when set but
+ * unusable, or null when no layer sets it.
+ */
+export function resolveMemoryDirectory(options = {}) {
+  const found = lookup(settingsLayers(options), 'autoMemoryDirectory');
+  if (!found) return null;
+
+  const raw = typeof found.value === 'string' ? found.value.trim() : '';
+  if (!raw) return null;
+  if (!raw.startsWith('/') && !raw.startsWith('~/') && !/^[A-Za-z]:[\\/]/.test(raw)) {
+    return { ...found, raw, path: null, invalid: 'not an absolute or ~/ path' };
+  }
+  return { ...found, raw, path: expandHome(raw), invalid: null };
+}
+
+/**
+ * Whether auto memory is on for a project, and what decided it.
+ *
+ * A project with auto memory off has a store that will never grow again, which
+ * on disk is indistinguishable from a project Claude has simply not learned
+ * anything about yet. Without a resolved project path there is no project or
+ * local layer to read, so the answer is unknown rather than assumed.
+ */
+export function autoMemoryState({ projectDir = null } = {}) {
+  const env = process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY;
+  if (env && env !== '0' && env !== 'false') {
+    return { enabled: false, setBy: 'CLAUDE_CODE_DISABLE_AUTO_MEMORY', scope: 'env', known: true };
+  }
+
+  const found = lookup(settingsLayers({ projectDir }), 'autoMemoryEnabled');
+  if (found && typeof found.value === 'boolean') {
+    return { enabled: found.value, setBy: found.file, scope: found.scope, known: true };
+  }
+  // Default is true, but without a project path the project and local layers
+  // were never consulted, so "on" here is an assumption and is labelled one.
+  return { enabled: true, setBy: null, scope: 'default', known: Boolean(projectDir) };
+}
+
+/** Retention period for session transcripts. Memory files are excluded from the sweep. */
+export function cleanupPeriodDays(options = {}) {
+  const found = lookup(settingsLayers(options), 'cleanupPeriodDays');
+  const value = Number(found?.value);
+  return Number.isFinite(value) && value >= 1 ? value : DEFAULT_CLEANUP_PERIOD_DAYS;
+}

package/src/stats.mjs

@@ -26,16 +26,107 @@ export const INDEX_BYTE_LIMIT = 25 * 1024;
 export const LONG_HOOK_CHARS = 200;
 
 /**
- * The text that actually counts against the limits. Claude Code strips YAML
- * frontmatter and block-level HTML comments before loading the index, so
- * measuring the raw file would overstate the size.
+ * The text that actually counts against the limits, plus a map from each line of
+ * it back to the line it came from in the raw file.
+ *
+ * Claude Code strips YAML frontmatter and block-level HTML comments before
+ * loading the index, so measuring the raw file would overstate the size. That
+ * stripping is also why a position in the loaded text is not a line number in
+ * the file: to draw the cutoff where the user can see it, the removed spans have
+ * to be tracked rather than just discarded.
  */
+export function loadedIndex(indexText) {
+  if (!indexText) return { text: '', rawLineFor: [] };
+
+  const removed = [];
+  const frontmatter = indexText.match(/^---\n[\s\S]*?\n---\n?/);
+  const base = frontmatter ? frontmatter[0].length : 0;
+  if (frontmatter) removed.push([0, base]);
+
+  // Matched on the post-frontmatter text, exactly as the stripping itself is, so
+  // the `m` anchors land on the same line starts.
+  for (const match of indexText.slice(base).matchAll(/^[ \t]*<!--[\s\S]*?-->[ \t]*\n?/gm)) {
+    removed.push([base + match.index, base + match.index + match[0].length]);
+  }
+
+  removed.sort((a, b) => a[0] - b[0]);
+  const kept = [];
+  let cursor = 0;
+  for (const [start, end] of removed) {
+    if (start > cursor) kept.push([cursor, start]);
+    cursor = Math.max(cursor, end);
+  }
+  if (cursor < indexText.length) kept.push([cursor, indexText.length]);
+
+  const rawLineStarts = [0];
+  for (let i = 0; i < indexText.length; i++) {
+    if (indexText[i] === '\n') rawLineStarts.push(i + 1);
+  }
+  const rawLineAt = (offset) => {
+    let low = 0;
+    let high = rawLineStarts.length - 1;
+    while (low < high) {
+      const mid = (low + high + 1) >> 1;
+      if (rawLineStarts[mid] <= offset) low = mid;
+      else high = mid - 1;
+    }
+    return low;
+  };
+
+  // One raw offset per surviving character, which is what makes the line map a
+  // lookup rather than a second parse that could disagree with the first.
+  const offsets = [];
+  for (const [start, end] of kept) {
+    for (let i = start; i < end; i++) offsets.push(i);
+  }
+
+  const rawLineFor = [];
+  if (offsets.length) rawLineFor.push(rawLineAt(offsets[0]));
+  for (let i = 0; i < offsets.length - 1; i++) {
+    if (indexText[offsets[i]] === '\n') rawLineFor.push(rawLineAt(offsets[i + 1]));
+  }
+
+  return { text: kept.map(([start, end]) => indexText.slice(start, end)).join(''), rawLineFor };
+}
+
+/** The loaded text alone, for callers that do not need the line map. */
 export function loadedIndexText(indexText) {
-  if (!indexText) return '';
-  let text = indexText;
-  const frontmatter = text.match(/^---\n[\s\S]*?\n---\n?/);
-  if (frontmatter) text = text.slice(frontmatter[0].length);
-  return text.replace(/^[ \t]*<!--[\s\S]*?-->[ \t]*\n?/gm, '');
+  return loadedIndex(indexText).text;
+}
+
+/**
+ * Where the index stops being loaded, and which entries fall past it.
+ *
+ * The percentage on the meter says an index is too big; this says which memories
+ * Claude can no longer see, which is the thing you can act on. Both are derived
+ * from the same loaded text, so they cannot disagree.
+ */
+function findCutoff(loaded, entries) {
+  const lines = loaded.text.split('\n');
+  let bytes = 0;
+  let byteCut = Infinity;
+  for (let i = 0; i < lines.length; i++) {
+    // Every line but the last carries its newline.
+    bytes += Buffer.byteLength(lines[i], 'utf8') + (i < lines.length - 1 ? 1 : 0);
+    if (bytes > INDEX_BYTE_LIMIT) { byteCut = i; break; }
+  }
+  const lineCut = loaded.rawLineFor.length > INDEX_LINE_LIMIT ? INDEX_LINE_LIMIT : Infinity;
+
+  const loadedLine = Math.min(lineCut, byteCut);
+  if (!Number.isFinite(loadedLine)) return null;
+
+  const rawLine = loaded.rawLineFor[loadedLine];
+  if (rawLine === undefined) return null;
+
+  return {
+    loadedLine,
+    rawLine,
+    by: lineCut <= byteCut ? 'lines' : 'bytes',
+    droppedLines: loaded.rawLineFor.length - loadedLine,
+    droppedEntries: entries
+      .filter((entry) => entry.index >= rawLine)
+      .map((entry) => ({ index: entry.index, file: entry.file, title: entry.title })),
+  };
 }
 
 export function indexStats(indexText, entries) {
@@ -44,12 +135,13 @@ export function indexStats(indexText, entries) {
       bytes: 0, lines: 0, tokens: 0, entryCount: 0, longHooks: [], longestHook: 0,
       lineLimit: INDEX_LINE_LIMIT, byteLimit: INDEX_BYTE_LIMIT,
       linePercent: 0, bytePercent: 0, worstPercent: 0, level: 'ok', overLimit: false, nearLimit: false,
+      cutoff: null,
     };
   }
 
-  const loaded = loadedIndexText(indexText);
-  const lines = loaded.split('\n').filter((line, i, all) => i < all.length - 1 || line.length > 0).length;
-  const bytes = Buffer.byteLength(loaded, 'utf8');
+  const loaded = loadedIndex(indexText);
+  const lines = loaded.rawLineFor.length;
+  const bytes = Buffer.byteLength(loaded.text, 'utf8');
 
   const longHooks = entries
     .filter((entry) => entry.hook.length > LONG_HOOK_CHARS)
@@ -64,7 +156,7 @@ export function indexStats(indexText, entries) {
     bytes,
     lines,
     rawBytes: Buffer.byteLength(indexText, 'utf8'),
-    tokens: estimateTokens(loaded),
+    tokens: estimateTokens(loaded.text),
     entryCount: entries.length,
     longHooks,
     longestHook: entries.reduce((max, e) => Math.max(max, e.hook.length), 0),
@@ -77,6 +169,7 @@ export function indexStats(indexText, entries) {
     overLimit: lines > INDEX_LINE_LIMIT || bytes > INDEX_BYTE_LIMIT,
     nearLimit: worstPercent >= 75,
     level: worstPercent > 100 ? 'over' : worstPercent >= 75 ? 'near' : 'ok',
+    cutoff: findCutoff(loaded, entries),
   };
 }
 

package/src/stores.mjs

@@ -0,0 +1,146 @@
+// Discovery of every memory store on the machine, of both kinds Claude Code
+// keeps.
+//
+// Auto memory is one store per project under the projects root. Subagents with a
+// `memory:` field in their frontmatter get their own directories as well, in one
+// of three scopes, and those hold exactly the same thing: a MEMORY.md index, a
+// topic file per memory, the same 200-line/25KB load limit and the same
+// instruction to keep the index short. So they are the same object here, and
+// everything downstream - parsing, the meter, the graph, health, prune, trash -
+// works on them without knowing which kind it has.
+//
+// The project-scoped agent directories live inside repositories, which this tool
+// only knows about because it already recovers each project's real path from the
+// session transcripts. Nothing here guesses at a path that was not confirmed
+// somewhere else first.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { listProjects, memoryDir, projectsRoot, shortLabel } from './projects.mjs';
+
+export const AGENT_USER_DIR = path.join(os.homedir(), '.claude', 'agent-memory');
+export const AGENT_PROJECT_DIR = path.join('.claude', 'agent-memory');
+export const AGENT_LOCAL_DIR = path.join('.claude', 'agent-memory-local');
+
+export const STORE_KINDS = {
+  auto: { label: 'Project', scope: null },
+  'agent-user': { label: 'Subagent', scope: 'user' },
+  'agent-project': { label: 'Subagent', scope: 'project' },
+  'agent-local': { label: 'Subagent', scope: 'local' },
+};
+
+/**
+ * A store id is opaque and URL-safe, and is only ever handed back to us from a
+ * list we produced. Encoding the kind and the location keeps it stable across
+ * restarts without a registry file to keep in sync.
+ */
+function storeId(kind, key) {
+  return `${kind}:${Buffer.from(key, 'utf8').toString('base64url')}`;
+}
+
+function agentDirs(parent) {
+  let entries;
+  try {
+    entries = fs.readdirSync(parent, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+    .map((entry) => entry.name)
+    .filter((name) => !name.startsWith('.'))
+    .sort();
+}
+
+/** Files in a store directory, excluding the index and the trash folder. */
+function countMemories(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith('.md') && e.name !== 'MEMORY.md')
+      .length;
+  } catch {
+    return 0;
+  }
+}
+
+function agentStore(kind, agentName, dir, projectPath = null) {
+  return {
+    id: storeId(kind, dir),
+    kind,
+    dir,
+    agentName,
+    projectPath,
+    label: agentName,
+    // Which repository a project- or local-scoped agent store belongs to; the
+    // same agent can have a different memory in every checkout.
+    sublabel: projectPath ? shortLabel(projectPath) : 'all projects',
+    memoryCount: countMemories(dir),
+    hasMemoryDir: true,
+    hasIndex: fs.existsSync(path.join(dir, 'MEMORY.md')),
+  };
+}
+
+/**
+ * Subagent memory directories, across all three scopes. Both roots are
+ * parameters rather than constants so this is a total function of where it is
+ * told to look, which is also what makes it testable without a real home dir.
+ */
+export function listAgentStores({ userDir = AGENT_USER_DIR, projectPaths = [] } = {}) {
+  const stores = [];
+
+  for (const name of agentDirs(userDir)) {
+    stores.push(agentStore('agent-user', name, path.join(userDir, name)));
+  }
+
+  // A repository can be reached through more than one project entry (a worktree
+  // and its root), so the same directory must not be listed twice.
+  const seen = new Set();
+  for (const projectPath of projectPaths) {
+    if (!projectPath || !path.isAbsolute(projectPath) || seen.has(projectPath)) continue;
+    seen.add(projectPath);
+    for (const [kind, relative] of [['agent-project', AGENT_PROJECT_DIR], ['agent-local', AGENT_LOCAL_DIR]]) {
+      const parent = path.join(projectPath, relative);
+      for (const name of agentDirs(parent)) {
+        stores.push(agentStore(kind, name, path.join(parent, name), projectPath));
+      }
+    }
+  }
+
+  return stores.sort((a, b) => b.memoryCount - a.memoryCount
+    || a.label.localeCompare(b.label)
+    || a.sublabel.localeCompare(b.sublabel));
+}
+
+/** An auto-memory project, in the shape the rest of the app expects of a store. */
+function autoStore(project, root) {
+  return {
+    ...project,
+    id: storeId('auto', project.slug),
+    kind: 'auto',
+    dir: memoryDir(root, project.slug),
+    sublabel: null,
+  };
+}
+
+/**
+ * Every store, auto memory first. Agent stores are found under the project paths
+ * auto memory already resolved, so a repository this tool has never seen a
+ * session for contributes nothing.
+ */
+export function listStores(root = projectsRoot()) {
+  const projects = listProjects(root);
+  const projectPaths = projects
+    .filter((project) => project.pathExists)
+    .flatMap((project) => [project.path, ...(project.workingDirs || [])]);
+
+  return [
+    ...projects.map((project) => autoStore(project, root)),
+    ...listAgentStores({ projectPaths }),
+  ];
+}
+
+/** Resolve an id against the discovered list, so only real stores are ever addressed. */
+export function findStore(root, id) {
+  return listStores(root).find((store) => store.id === id) || null;
+}