claude-memory-admin 1.0.0

package/src/parse.mjs

@@ -0,0 +1,255 @@
+// Parsers for the on-disk memory format.
+//
+// These are written against the real data in ~/.claude/projects rather than the
+// idealised format, because three properties of the real files break the obvious
+// implementations:
+//
+//   1. MEMORY.md is not a flat index. It mixes index bullets with `#` headings,
+//      free-prose bullets, indented sub-bullets, and links embedded mid-sentence.
+//   2. The hook separator is an em dash in most projects but " - " in projects
+//      that have opted out of em dashes. A regex anchored on `—` silently drops
+//      every entry in those projects.
+//   3. Frontmatter has exactly one level of nesting (`metadata:`), so a flat
+//      `key: value` reader loses `metadata.type` -- the field the UI keys on.
+
+/** A top-level `- [Title](file.md) — hook` bullet. Indent is captured, not assumed. */
+const INDEX_LINE = /^(\s*)-[ \t]+\[([^\]]*)\]\(([^)\s]+\.md)\)[ \t]*(.*)$/;
+
+/** Any markdown link to a .md file, wherever it appears (including mid-sentence). */
+const MD_LINK = /\[([^\]]*)\]\(([^)\s]+\.md)\)/g;
+
+/** `[[name]]` or `[[name|alias]]`. */
+const WIKILINK = /\[\[([^\]|]+)(?:\|([^\]]*))?\]\]/g;
+
+/** Leading hook separator: em dash, en dash, hyphen or colon. */
+const HOOK_SEP = /^[ \t]*(?:—|–|-|:)[ \t]*/;
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+
+/**
+ * Minimal YAML reader for frontmatter: scalars at the root plus one level of
+ * nesting. Anything it does not understand is skipped rather than guessed at,
+ * and the raw block is kept by the caller so nothing is ever rewritten from it.
+ */
+function readYaml(lines) {
+  const data = {};
+  const nestedKeys = new Set();
+  let parent = null;
+
+  for (const raw of lines) {
+    const withoutComment = raw.trimStart().startsWith('#') ? '' : raw;
+    if (!withoutComment.trim()) continue;
+
+    const match = withoutComment.match(/^([ \t]*)([A-Za-z0-9_.\-]+):[ \t]*(.*)$/);
+    if (!match) continue;
+
+    const [, indent, key, rest] = match;
+    const value = unquote(rest);
+
+    if (indent.length === 0) {
+      if (value === '') {
+        // Might open a nested block, or might just be an empty scalar. Decided
+        // after the loop, once we know whether anything nested under it.
+        data[key] = {};
+        parent = key;
+      } else {
+        data[key] = value;
+        parent = null;
+      }
+    } else if (parent !== null) {
+      if (typeof data[parent] !== 'object' || data[parent] === null) data[parent] = {};
+      data[parent][key] = value;
+      nestedKeys.add(parent);
+    }
+  }
+
+  // An empty scalar that never got children is a string, not an object.
+  for (const [key, value] of Object.entries(data)) {
+    if (value && typeof value === 'object' && !nestedKeys.has(key)) data[key] = '';
+  }
+  return data;
+}
+
+/**
+ * Split frontmatter from body. Scans for the closing `---` on its own line
+ * rather than splitting on '---', which would break on any horizontal rule in
+ * the body.
+ */
+export function parseFrontmatter(text) {
+  const lines = text.split('\n');
+  if (lines.length === 0 || lines[0].trim() !== '---') {
+    return { data: {}, raw: '', body: text, hasFrontmatter: false };
+  }
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    return { data: {}, raw: '', body: text, hasFrontmatter: false };
+  }
+
+  const block = lines.slice(1, end);
+  return {
+    data: readYaml(block),
+    raw: block.join('\n'),
+    body: lines.slice(end + 1).join('\n').replace(/^\n+/, ''),
+    hasFrontmatter: true,
+  };
+}
+
+/** Every `[[wikilink]]` in a body, in order, de-duplicated. */
+export function extractWikilinks(body) {
+  const found = [];
+  const seen = new Set();
+  for (const match of body.matchAll(WIKILINK)) {
+    const target = match[1].trim();
+    if (!target || seen.has(target)) continue;
+    seen.add(target);
+    found.push({ target, alias: match[2]?.trim() || null });
+  }
+  return found;
+}
+
+/**
+ * Parse MEMORY.md into a line-addressed model.
+ *
+ * Every line is preserved verbatim so the file can be rewritten byte-for-byte.
+ * Lines are classified, never rewritten:
+ *   - `index`     a top-level `- [Title](file.md)` bullet
+ *   - `heading`   a `#`-prefixed line, used to group entries in the UI
+ *   - `text`      everything else, including prose and nested bullets
+ * `links` additionally records every .md link anywhere in the file, which is how
+ * a file referenced only mid-sentence is told apart from a genuine orphan.
+ */
+export function parseIndex(text) {
+  const lines = text.split('\n');
+  const entries = [];
+  const links = [];
+  const parsedLines = [];
+  let section = null;
+
+  lines.forEach((line, i) => {
+    const heading = line.match(/^(#{1,6})[ \t]+(.*)$/);
+    if (heading) {
+      section = heading[2].trim();
+      parsedLines.push({ index: i, kind: 'heading', text: line, level: heading[1].length, section });
+    } else {
+      const indexMatch = line.match(INDEX_LINE);
+      // Only an unindented bullet is an index entry. An indented one is a
+      // sub-bullet of surrounding prose and must not be treated as a pointer.
+      if (indexMatch && indexMatch[1] === '') {
+        const [, , title, file, tail] = indexMatch;
+        entries.push({
+          index: i,
+          title: title.trim(),
+          file: file.trim(),
+          hook: tail.replace(HOOK_SEP, '').trim(),
+          section,
+          text: line,
+        });
+        parsedLines.push({ index: i, kind: 'index', text: line, file: file.trim(), section });
+      } else {
+        parsedLines.push({ index: i, kind: 'text', text: line, section });
+      }
+    }
+
+    for (const link of line.matchAll(MD_LINK)) {
+      links.push({ index: i, label: link[1], file: link[2].trim(), text: line });
+    }
+  });
+
+  const indexedFiles = new Set(entries.map((e) => e.file));
+  return {
+    lines,
+    parsedLines,
+    entries,
+    links,
+    // Links that are not index bullets, e.g. a mention inside a prose sentence.
+    inlineLinks: links.filter((l) => !entries.some((e) => e.index === l.index)),
+    indexedFiles,
+    referencedFiles: new Set(links.map((l) => l.file)),
+  };
+}
+
+/**
+ * Remove index bullets pointing at `fileOrFiles`, plus the more-indented
+ * continuation lines that belong to them. Every other byte is untouched.
+ * Returns the new text and the removed lines with their ORIGINAL indices.
+ *
+ * Several files are handled in one pass on purpose: removing them one at a time
+ * would shift the line numbers under each subsequent removal, and the recorded
+ * indices would no longer describe the file we started from.
+ */
+export function removeIndexEntries(text, fileOrFiles) {
+  const files = new Set([].concat(fileOrFiles));
+  const parsed = parseIndex(text);
+  const targets = parsed.entries.filter((e) => files.has(e.file));
+  if (targets.length === 0) return { text, removed: [] };
+
+  const drop = new Set();
+  for (const entry of targets) {
+    drop.add(entry.index);
+    // Continuation lines: indented, non-blank, until the next unindented line.
+    for (let i = entry.index + 1; i < parsed.lines.length; i++) {
+      const line = parsed.lines[i];
+      if (!line.trim()) break;
+      if (!/^[ \t]/.test(line)) break;
+      drop.add(i);
+    }
+  }
+
+  const removed = [...drop].sort((a, b) => a - b).map((i) => ({ index: i, text: parsed.lines[i] }));
+  const kept = parsed.lines.filter((_, i) => !drop.has(i));
+  return { text: kept.join('\n'), removed };
+}
+
+/** Remove a single line by index, guarded by the text the caller expected to find. */
+export function removeLine(text, index, expectedText) {
+  const lines = text.split('\n');
+  if (index < 0 || index >= lines.length) {
+    throw new Error(`Line ${index} is out of range`);
+  }
+  if (typeof expectedText === 'string' && lines[index] !== expectedText) {
+    throw new Error('MEMORY.md changed since this was loaded - reload and try again');
+  }
+  const removed = [{ index, text: lines[index] }];
+  lines.splice(index, 1);
+  return { text: lines.join('\n'), removed };
+}
+
+/** Re-insert previously removed lines at their original indices. */
+export function insertLines(text, removed) {
+  const lines = text.split('\n');
+  for (const entry of [...removed].sort((a, b) => a.index - b.index)) {
+    const at = Math.min(entry.index, lines.length);
+    lines.splice(at, 0, entry.text);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Turn `[[target]]` into plain text wherever it appears, leaving the sentence
+ * around it intact. `[[target|alias]]` collapses to the alias.
+ * Used to clear links whose target no longer exists.
+ */
+export function unwrapWikilink(text, target) {
+  let count = 0;
+  const pattern = new RegExp(WIKILINK.source, 'g');
+  const out = text.replace(pattern, (match, name, alias) => {
+    if (name.trim() !== target) return match;
+    count += 1;
+    return (alias || name).trim();
+  });
+  return { text: out, count };
+}

package/src/projects.mjs

@@ -0,0 +1,190 @@
+// Discovery of project directories under the Claude projects root, and the
+// recovery of their real filesystem paths.
+//
+// Directory names are slugified cwds ("-Users-me-repos-Blog"), and the
+// slugification is lossy: a literal dash in a folder name is indistinguishable
+// from a path separator. So decoding the slug is a fallback, not the primary
+// method. The reliable source is the session transcripts sitting next to the
+// memory dir, whose JSONL lines carry the true `cwd`.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const DEFAULT_ROOT = path.join(os.homedir(), '.claude', 'projects');
+const USER_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+
+function expandHome(value) {
+  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+/**
+ * Claude Code lets `autoMemoryDirectory` in settings.json move the memory store
+ * somewhere else entirely. Honour it, or this tool would confidently show an
+ * empty store to anyone who has set it.
+ */
+export function configuredMemoryDirectory() {
+  try {
+    const settings = JSON.parse(fs.readFileSync(USER_SETTINGS, 'utf8'));
+    const configured = settings?.autoMemoryDirectory;
+    if (typeof configured === 'string' && configured.trim()) return expandHome(configured.trim());
+  } catch {
+    // No settings file, or not readable/parseable: fall through to the default.
+  }
+  return null;
+}
+
+export function projectsRoot() {
+  if (process.env.MEMORY_ROOT) return expandHome(process.env.MEMORY_ROOT);
+  return configuredMemoryDirectory() || DEFAULT_ROOT;
+}
+
+/** Read the first chunk of a file without pulling a multi-megabyte transcript into memory. */
+function readHead(file, bytes = 131072) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(bytes);
+    const read = fs.readSync(fd, buf, 0, bytes, 0);
+    return buf.subarray(0, read).toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function findTranscripts(dir, depth = 2) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+      try {
+        out.push({ file: full, mtime: fs.statSync(full).mtimeMs });
+      } catch { /* raced with a delete */ }
+    } else if (entry.isDirectory() && depth > 0 && entry.name !== 'memory') {
+      out.push(...findTranscripts(full, depth - 1));
+    }
+  }
+  return out;
+}
+
+/** Pull `cwd` out of the newest transcripts. Authoritative when present. */
+function cwdFromTranscripts(dir) {
+  const transcripts = findTranscripts(dir).sort((a, b) => b.mtime - a.mtime);
+  for (const { file } of transcripts.slice(0, 3)) {
+    let head;
+    try {
+      head = readHead(file);
+    } catch {
+      continue;
+    }
+    for (const line of head.split('\n')) {
+      if (!line.includes('"cwd"')) continue;
+      try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed?.cwd === 'string' && parsed.cwd.startsWith('/')) return parsed.cwd;
+      } catch {
+        // Truncated final line of the chunk, or a non-object line. Skip it.
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Best-effort slug decode, used only when there is no transcript to read.
+ * Candidates are verified against the filesystem so a wrong guess is reported
+ * as unresolved rather than presented as fact.
+ */
+function decodeSlug(slug) {
+  const body = slug.replace(/^-/, '');
+  const candidates = [
+    '/' + body.replace(/--/g, '/.').replace(/-/g, '/'),
+    '/' + body.replace(/-/g, '/'),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) return { path: candidate, verified: true };
+    } catch { /* unreadable path */ }
+  }
+  return { path: candidates[0], verified: false };
+}
+
+export function resolveProjectPath(dir, slug) {
+  const fromTranscript = cwdFromTranscripts(dir);
+  if (fromTranscript) {
+    return {
+      path: fromTranscript,
+      resolvedBy: 'transcript',
+      exists: fs.existsSync(fromTranscript),
+    };
+  }
+  const decoded = decodeSlug(slug);
+  if (decoded.verified) {
+    return { path: decoded.path, resolvedBy: 'slug', exists: true };
+  }
+  // Nothing confirmed the guess, so show the slug rather than a path that
+  // looks authoritative and is probably wrong.
+  return { path: slug, resolvedBy: 'unresolved', exists: false, guess: decoded.path };
+}
+
+/** A short label for the sidebar: the last two path segments. */
+export function shortLabel(fullPath) {
+  const parts = fullPath.split('/').filter(Boolean);
+  return parts.slice(-2).join('/') || fullPath;
+}
+
+export function memoryDir(root, slug) {
+  return path.join(root, slug, 'memory');
+}
+
+/** List memory filenames, excluding the index itself and the trash folder. */
+export function listMemoryFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.md') && e.name !== 'MEMORY.md')
+    .map((e) => e.name)
+    .sort();
+}
+
+/** Every project dir under the root, whether or not it has memory. */
+export function listProjects(root = projectsRoot()) {
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const slug = e.name;
+      const dir = path.join(root, slug);
+      const mem = memoryDir(root, slug);
+      const hasMemoryDir = fs.existsSync(mem);
+      const resolved = resolveProjectPath(dir, slug);
+      const files = hasMemoryDir ? listMemoryFiles(mem) : [];
+      return {
+        slug,
+        path: resolved.path,
+        label: shortLabel(resolved.path),
+        resolvedBy: resolved.resolvedBy,
+        pathExists: resolved.exists,
+        hasMemoryDir,
+        hasIndex: hasMemoryDir && fs.existsSync(path.join(mem, 'MEMORY.md')),
+        memoryCount: files.length,
+      };
+    })
+    .sort((a, b) => b.memoryCount - a.memoryCount || a.label.localeCompare(b.label));
+}

package/src/search.mjs

@@ -0,0 +1,127 @@
+// Full-text search across every project's memory.
+//
+// The whole store is a few hundred kilobytes, so this scans it directly on each
+// query rather than maintaining an index that could go stale.
+
+import { buildProject } from './model.mjs';
+import { listProjects } from './projects.mjs';
+
+const FIELD_WEIGHT = { name: 6, description: 3, hook: 2, body: 1 };
+
+function fold(text) {
+  return String(text || '').toLowerCase();
+}
+
+/** Character offsets of every occurrence of `term` in `haystack`. */
+function positions(haystack, term) {
+  const found = [];
+  let at = haystack.indexOf(term);
+  while (at !== -1 && found.length < 20) {
+    found.push(at);
+    at = haystack.indexOf(term, at + term.length);
+  }
+  return found;
+}
+
+/** A short excerpt around the first hit, with the match marked by offsets. */
+function snippet(body, term, radius = 90) {
+  const at = fold(body).indexOf(term);
+  if (at === -1) return null;
+  const start = Math.max(0, at - radius);
+  const end = Math.min(body.length, at + term.length + radius);
+  return {
+    text: (start > 0 ? '…' : '') + body.slice(start, end).replace(/\s+/g, ' ').trim() + (end < body.length ? '…' : ''),
+    term,
+  };
+}
+
+/**
+ * Search one project's already-built model. Every term must appear somewhere in
+ * a memory for it to match, so extra words narrow rather than widen - which is
+ * what people expect from a search box.
+ */
+export function searchProject(project, terms) {
+  const results = [];
+
+  for (const memory of project.memories) {
+    const fields = {
+      name: fold(memory.name),
+      description: fold(memory.description),
+      hook: fold(memory.entry?.hook || ''),
+      body: fold(memory.body),
+    };
+
+    let score = 0;
+    const matchedFields = new Set();
+    const everyTermPresent = terms.every((term) => {
+      let present = false;
+      for (const [field, text] of Object.entries(fields)) {
+        const hits = positions(text, term);
+        if (hits.length) {
+          present = true;
+          matchedFields.add(field);
+          score += FIELD_WEIGHT[field] * Math.min(hits.length, 3);
+        }
+      }
+      return present;
+    });
+    if (!everyTermPresent) continue;
+
+    // Prefer the most specific field for the excerpt.
+    const first = terms[0];
+    const excerpt = snippet(memory.body, first)
+      || (memory.description ? { text: memory.description, term: first } : null);
+
+    results.push({
+      slug: project.slug,
+      projectLabel: project.label,
+      file: memory.file,
+      name: memory.name,
+      description: memory.description,
+      type: memory.type,
+      status: memory.status,
+      score,
+      fields: [...matchedFields],
+      snippet: excerpt,
+    });
+  }
+
+  // Index lines that mention the terms but whose file did not match, so a hit in
+  // MEMORY.md prose is still findable.
+  const indexHits = [];
+  if (project.index) {
+    for (const line of project.index.lines) {
+      const text = fold(line.text);
+      if (!line.text.trim()) continue;
+      if (!terms.every((term) => text.includes(term))) continue;
+      if (line.kind === 'index' && results.some((r) => r.file === line.file)) continue;
+      indexHits.push({ slug: project.slug, projectLabel: project.label, index: line.index, text: line.text, kind: line.kind, file: line.file || null });
+    }
+  }
+
+  return { results: results.sort((a, b) => b.score - a.score), indexHits };
+}
+
+/** Search every project under `root`. */
+export function searchAll(root, query, { limit = 200 } = {}) {
+  const terms = fold(query).split(/\s+/).filter(Boolean);
+  if (!terms.length) return { terms, total: 0, projects: [] };
+
+  const projects = [];
+  let total = 0;
+  for (const listed of listProjects(root)) {
+    if (!listed.hasMemoryDir) continue;
+    const project = buildProject(root, listed.slug);
+    const { results, indexHits } = searchProject(project, terms);
+    if (!results.length && !indexHits.length) continue;
+    total += results.length;
+    projects.push({
+      slug: listed.slug,
+      label: project.label,
+      results: results.slice(0, limit),
+      indexHits: indexHits.slice(0, 20),
+    });
+  }
+
+  return { terms, total, projects: projects.sort((a, b) => b.results.length - a.results.length) };
+}