@monoes/monomindcli 1.10.29 → 1.10.30

package/.claude/helpers/utils/micro-agents.cjs

@@ -0,0 +1,338 @@
+'use strict';
+// Extracted from hook-handler.cjs — micro-agent trigger scanner and knowledge base helpers.
+
+const path = require('path');
+const fs = require('fs');
+
+const { _openMonographDb } = require('./monograph.cjs');
+
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function safeRequire(modulePath) {
+  try {
+    if (fs.existsSync(modulePath)) {
+      const origLog = console.log;
+      const origError = console.error;
+      console.log = () => {};
+      console.error = () => {};
+      try {
+        const mod = require(modulePath);
+        return mod;
+      } finally {
+        console.log = origLog;
+        console.error = origError;
+      }
+    }
+  } catch (e) { /* silently fail */ }
+  return null;
+}
+
+// ── MicroAgent Trigger Scanner ────────────────────────────────────────────────
+
+function _triggerExtractYamlValue(raw) {
+  var v = raw.trim();
+  if (v.startsWith('"') && v.endsWith('"')) {
+    v = v.slice(1, -1).replace(/\\\\/g, '\\');
+  } else if (v.startsWith("'") && v.endsWith("'")) {
+    v = v.slice(1, -1);
+  }
+  return v;
+}
+
+function _triggerFinalize(partial, agentSlug) {
+  return { pattern: partial.pattern, mode: partial.mode || 'inject', priority: partial.priority || 0, agentSlug: agentSlug };
+}
+
+function _triggerExtractFromFrontmatter(content, agentSlug) {
+  var fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return [];
+  var block = fmMatch[1];
+  var triggers = [];
+  var lines = block.split('\n');
+  var inTriggers = false;
+  var cur = null;
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i];
+    var trimmed = line.trim();
+    var indent = line.length - line.trimStart().length;
+    if (trimmed === 'triggers:' || trimmed.startsWith('triggers:')) { inTriggers = true; continue; }
+    if (inTriggers && indent === 0 && /^[a-zA-Z]/.test(trimmed)) {
+      inTriggers = false;
+      if (cur && cur.pattern) triggers.push(_triggerFinalize(cur, agentSlug));
+      cur = null; continue;
+    }
+    if (!inTriggers) continue;
+    if (trimmed.startsWith('- pattern:')) {
+      if (cur && cur.pattern) triggers.push(_triggerFinalize(cur, agentSlug));
+      cur = { pattern: _triggerExtractYamlValue(trimmed.replace(/^- pattern:\s*/, '')), agentSlug: agentSlug };
+    } else if (cur && trimmed.startsWith('mode:')) {
+      var mv = _triggerExtractYamlValue(trimmed.replace(/^mode:\s*/, ''));
+      if (mv === 'inject' || mv === 'takeover') cur.mode = mv;
+    } else if (cur && trimmed.startsWith('priority:')) {
+      var pv = parseInt(trimmed.replace(/^priority:\s*/, ''), 10);
+      if (!isNaN(pv)) cur.priority = pv;
+    }
+  }
+  if (cur && cur.pattern) triggers.push(_triggerFinalize(cur, agentSlug));
+  return triggers;
+}
+
+function _triggerCollectMdFiles(dir) {
+  var results = [];
+  try {
+    var entries = fs.readdirSync(dir);
+    for (var i = 0; i < entries.length; i++) {
+      var full = path.join(dir, entries[i]);
+      try {
+        var st = fs.lstatSync(full);
+        if (st.isDirectory()) results = results.concat(_triggerCollectMdFiles(full));
+        else if (entries[i].endsWith('.md')) results.push(full);
+      } catch (e) {}
+    }
+  } catch (e) {}
+  return results;
+}
+
+function _triggerBuildIndex(agentDir) {
+  var patterns = [];
+  var files = _triggerCollectMdFiles(agentDir);
+  for (var i = 0; i < files.length; i++) {
+    var content;
+    try { content = fs.readFileSync(files[i], 'utf-8'); } catch (e) { continue; }
+    var slug = files[i].split('/').pop().replace(/\.md$/i, '').toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    patterns = patterns.concat(_triggerExtractFromFrontmatter(content, slug));
+  }
+  return patterns;
+}
+
+function scanMicroAgentTriggers(prompt) {
+  if (!prompt || typeof prompt !== 'string') return { matches: [], injectAgents: [] };
+  var indexPath = path.join(CWD, '.monomind', 'trigger-index.json');
+  var agentDir = path.join(CWD, '.claude', 'agents');
+  var patterns = [];
+  var cacheLoaded = false;
+
+  try {
+    if (fs.existsSync(indexPath)) {
+      var idx = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+      var age = Date.now() - new Date(idx.builtAt || 0).getTime();
+      if (age < 3600000 && Array.isArray(idx.patterns)) {
+        patterns = idx.patterns;
+        cacheLoaded = true;
+      }
+    }
+  } catch (e) {}
+
+  if (!cacheLoaded) {
+    patterns = _triggerBuildIndex(agentDir);
+    try {
+      fs.mkdirSync(path.join(CWD, '.monomind'), { recursive: true });
+      fs.writeFileSync(indexPath, JSON.stringify({ patterns: patterns, builtAt: new Date().toISOString(), totalAgentsScanned: patterns.length }));
+    } catch (e) {}
+  }
+
+  patterns.sort(function(a, b) { return (b.priority || 0) - (a.priority || 0); });
+
+  var matches = [];
+  var seen = {};
+  for (var i = 0; i < patterns.length; i++) {
+    var p = patterns[i];
+    if (p.mode !== 'inject' && p.mode !== 'takeover') continue;
+    if (seen[p.agentSlug]) continue;
+    try {
+      var re = new RegExp(p.pattern, 'i');
+      var m = re.exec(prompt);
+      if (m) {
+        seen[p.agentSlug] = true;
+        matches.push({ agentSlug: p.agentSlug, mode: p.mode, matchedText: m[0] });
+        if (p.mode === 'takeover') {
+          return { matches: matches, takeoverAgent: p.agentSlug, injectAgents: [] };
+        }
+      }
+    } catch (e) {}
+  }
+  return { matches: matches, injectAgents: matches.map(function(m) { return m.agentSlug; }) };
+}
+
+// ── Knowledge Base ────────────────────────────────────────────────────────────
+
+var _KNOWLEDGE_STOPWORDS = new Set(['the','and','or','but','if','in','on','to','is','it','be','do','of','for','not','at','by','as','we','us','an','a','i']);
+
+function _buildKnowledgeSearchFn(knowledgeDir) {
+  return async function(query, opts) {
+    var chunksFile = path.join(knowledgeDir, 'chunks.jsonl');
+    if (!fs.existsSync(chunksFile)) return [];
+    var lines;
+    try {
+      lines = fs.readFileSync(chunksFile, 'utf-8').trim().split('\n').filter(Boolean);
+    } catch (e) { return []; }
+
+    var ns = (opts && opts.namespace) || null;
+    var limit = (opts && opts.limit) || 10;
+    var minScore = (opts && opts.minScore != null) ? opts.minScore : 0.3;
+    var queryTerms = query.toLowerCase().split(/\s+/).filter(function(t) { return t.length >= 2 && !_KNOWLEDGE_STOPWORDS.has(t); });
+    if (queryTerms.length === 0) return [];
+
+    var results = [];
+    for (var i = 0; i < lines.length; i++) {
+      try {
+        var chunk = JSON.parse(lines[i]);
+        if (ns && chunk.namespace !== ns) continue;
+        var textLower = (chunk.text || '').toLowerCase();
+        var matchCount = queryTerms.filter(function(t) { return textLower.includes(t); }).length;
+        var score = matchCount / queryTerms.length;
+        if (score >= minScore) {
+          results.push({ key: chunk.chunkId, value: chunk.text, score: score, metadata: chunk.metadata || {} });
+        }
+      } catch (e) {}
+    }
+    results.sort(function(a, b) { return b.score - a.score; });
+    return results.slice(0, limit);
+  };
+}
+
+function _autoIndexKnowledge(knowledgeDir) {
+  var crypto = require('crypto');
+  var sources = [
+    { filePath: path.join(CWD, 'CLAUDE.md'), label: 'project-instructions' },
+    { filePath: path.join(CWD, 'docs/todo.md'), label: 'project-todo' },
+    { filePath: path.join(CWD, 'CLAUDE.local.md'), label: 'local-instructions' },
+  ];
+
+  var hashInput = '';
+  for (var i = 0; i < sources.length; i++) {
+    try {
+      if (fs.existsSync(sources[i].filePath)) {
+        var st = fs.statSync(sources[i].filePath);
+        hashInput += sources[i].filePath + ':' + st.size + ':' + st.mtimeMs + ';';
+      }
+    } catch (e) {}
+  }
+  try {
+    var statsForHash = JSON.parse(fs.readFileSync(path.join(CWD, '.monomind', 'graph', 'stats.json'), 'utf-8'));
+    hashInput += 'monograph:' + (statsForHash.builtAt || 0) + ';';
+  } catch(e) {}
+
+  var contentHash = crypto.createHash('md5').update(hashInput).digest('hex');
+  var chunksFile = path.join(knowledgeDir, 'chunks.jsonl');
+  var hashFile = path.join(knowledgeDir, '.index-hash');
+  var existingHash = '';
+  try { existingHash = fs.readFileSync(hashFile, 'utf-8').trim(); } catch (e) {}
+
+  var existingChunkCount = 0;
+  try { if (fs.existsSync(chunksFile)) { existingChunkCount = fs.readFileSync(chunksFile, 'utf-8').trim().split('\n').filter(Boolean).length; } } catch (e) {}
+  if (existingHash === contentHash && existingChunkCount > 0) return 0;
+
+  var newLines = [];
+  for (var si = 0; si < sources.length; si++) {
+    var src = sources[si];
+    try {
+      if (!fs.existsSync(src.filePath)) continue;
+      var content = fs.readFileSync(src.filePath, 'utf-8');
+      var sections = content.split(/\n{2,}|\n(?=#{1,3} )/);
+      for (var ci = 0; ci < sections.length; ci++) {
+        var text = sections[ci].trim();
+        if (text.length < 40 || text.length > 3000) continue;
+        var chunkId = crypto.createHash('md5').update(src.filePath + ':' + ci).digest('hex').slice(0, 16);
+        newLines.push(JSON.stringify({
+          chunkId: chunkId,
+          namespace: 'knowledge:shared',
+          text: text,
+          metadata: { filePath: src.filePath, label: src.label, chunkIndex: ci }
+        }));
+      }
+    } catch (e) {}
+  }
+
+  // Inject monograph graph summary as a knowledge chunk (reads from monograph.db).
+  try {
+    var mgDbPath = path.join(CWD, '.monomind', 'monograph.db');
+    var legacyStats = path.join(CWD, '.monomind', 'graph', 'stats.json');
+    var legacyGraph = path.join(CWD, '.monomind', 'graph', 'graph.json');
+
+    var summaryText = null;
+    var summaryMeta = {};
+
+    if (fs.existsSync(mgDbPath)) {
+      try {
+        var sumDb = _openMonographDb();
+        if (sumDb) {
+          try {
+            var nodeC = sumDb.prepare('SELECT COUNT(*) AS c FROM nodes').get().c;
+            var edgeC = sumDb.prepare('SELECT COUNT(*) AS c FROM edges').get().c;
+            var topNodes = sumDb.prepare(
+              'SELECT n.name, n.label, n.file_path, ' +
+              '(SELECT COUNT(*) FROM edges WHERE source_id=n.id OR target_id=n.id) AS deg ' +
+              'FROM nodes n WHERE n.file_path IS NOT NULL AND n.file_path != "" ORDER BY deg DESC LIMIT 15'
+            ).all();
+            var typeRows = sumDb.prepare(
+              'SELECT label, COUNT(*) AS c FROM nodes GROUP BY label ORDER BY c DESC LIMIT 8'
+            ).all();
+            var typeStr = typeRows.map(function(r) { return r.label + ':' + r.c; }).join(', ');
+            summaryText = [
+              'MONOGRAPH KNOWLEDGE GRAPH SUMMARY',
+              'Source: monograph.db | Nodes: ' + nodeC + ' | Edges: ' + edgeC,
+              '',
+              'TOP GOD NODES (highest connectivity — start exploration here):',
+              topNodes.map(function(n) {
+                return '  ' + n.name + ' [' + n.label + '] — ' + (n.file_path || '') + ' (degree: ' + n.deg + ')';
+              }).join('\n'),
+              '',
+              'NODE TYPE DISTRIBUTION: ' + typeStr,
+              '',
+              'Before grepping or globbing, prefer:',
+              '  mcp__monomind__monograph_suggest({ task: "<your task>" }) — ranked relevant files',
+              '  mcp__monomind__monograph_query({ q: "<symbol|keyword>" }) — BM25 search with file:line',
+              '  mcp__monomind__monograph_impact({ name: "<file>" }) — upstream + downstream blast radius',
+            ].join('\n');
+            summaryMeta = { label: 'monograph-graph-summary', source: 'monograph.db', nodes: nodeC, edges: edgeC };
+          } catch (e) { /* keep summaryText if partial */ }
+        }
+      } catch (e) { /* fall through to legacy */ }
+    }
+
+    if (!summaryText && fs.existsSync(legacyStats) && fs.existsSync(legacyGraph)) {
+      try {
+        var lStats = JSON.parse(fs.readFileSync(legacyStats, 'utf-8'));
+        var lGraphStat = fs.statSync(legacyGraph);
+        if (lGraphStat.size < 10 * 1024 * 1024) {
+          var lGraph = JSON.parse(fs.readFileSync(legacyGraph, 'utf-8'));
+          var lNodes = Array.isArray(lGraph.nodes) ? lGraph.nodes : [];
+          summaryText = 'MONOGRAPH KNOWLEDGE GRAPH SUMMARY (legacy JSON)\n' +
+            'Nodes: ' + (lStats.nodes || lNodes.length) + ' | Edges: ' + (lStats.edges || 0) + '\n' +
+            'Use mcp__monomind__monograph_suggest to find files relevant to your task.';
+          summaryMeta = { label: 'monograph-graph-summary', source: 'legacy-json', builtAt: lStats.builtAt };
+        }
+      } catch (e) { /* ignore */ }
+    }
+
+    if (summaryText) {
+      var chunkId2 = crypto.createHash('md5').update('monograph-graph-summary').digest('hex').slice(0, 16);
+      newLines.push(JSON.stringify({
+        chunkId: chunkId2,
+        namespace: 'knowledge:shared',
+        text: summaryText,
+        metadata: summaryMeta
+      }));
+    }
+  } catch (e) { /* graph not available yet */ }
+
+  try {
+    fs.mkdirSync(knowledgeDir, { recursive: true });
+    fs.writeFileSync(chunksFile, newLines.length > 0 ? newLines.join('\n') + '\n' : '', 'utf-8');
+    fs.writeFileSync(hashFile, contentHash, 'utf-8');
+  } catch (e) {}
+  return newLines.length;
+}
+
+module.exports = {
+  safeRequire,
+  _triggerExtractYamlValue,
+  _triggerFinalize,
+  _triggerExtractFromFrontmatter,
+  _triggerCollectMdFiles,
+  _triggerBuildIndex,
+  scanMicroAgentTriggers,
+  _buildKnowledgeSearchFn,
+  _autoIndexKnowledge,
+};

package/.claude/helpers/utils/monograph.cjs

@@ -0,0 +1,349 @@
+'use strict';
+// Extracted from hook-handler.cjs — monograph graph helpers.
+// All functions are stateless except for the module-level DB cache.
+
+const path = require('path');
+const fs = require('fs');
+
+const { _getRecentEdits } = require('./telemetry.cjs');
+
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function _requireMonograph() {
+  var candidates = [
+    path.join(CWD, 'node_modules/.pnpm/node_modules/@monoes/monograph'),
+    path.join(CWD, 'packages/node_modules/.pnpm/node_modules/@monoes/monograph'),
+    path.join(CWD, 'node_modules/@monoes/monograph'),
+  ];
+  for (var i = 0; i < candidates.length; i++) {
+    try { if (fs.existsSync(candidates[i])) return require(candidates[i]); } catch(e) {}
+  }
+  try { return require('@monoes/monograph'); } catch(e) {}
+  return null;
+}
+
+// Memoized at module scope — opening monograph.db can take 7-10s.
+// Callers MUST NOT close the returned handle.
+var _cachedMonographDb = undefined;
+function _openMonographDb() {
+  if (_cachedMonographDb !== undefined) return _cachedMonographDb;
+  try {
+    var dbPath = path.join(CWD, '.monomind', 'monograph.db');
+    if (!fs.existsSync(dbPath)) { _cachedMonographDb = null; return null; }
+    var mod = _requireMonograph();
+    if (!mod || !mod.openDb) { _cachedMonographDb = null; return null; }
+    _cachedMonographDb = mod.openDb(dbPath);
+    return _cachedMonographDb;
+  } catch (e) { _cachedMonographDb = null; return null; }
+}
+
+function getMonographSuggestions(taskText, limit) {
+  if (!taskText || typeof taskText !== 'string') return [];
+  var db = _openMonographDb();
+  if (!db) return [];
+  try {
+    var words = String(taskText).toLowerCase().match(/[a-z][a-z0-9_-]{3,}/g) || [];
+    var stop = { 'this':1,'that':1,'with':1,'from':1,'have':1,'into':1,'their':1,'what':1,'when':1,'where':1,'which':1,'should':1,'would':1,'could':1,'make':1,'just':1,'also':1,'them':1,'they':1,'will':1,'been':1,'were':1,'because':1,'about':1,'does':1,'work':1,'else':1,'more':1,'some':1,'like':1,'need':1,'want':1,'used':1,'using':1,'please':1,'thanks':1,'good':1,'great':1,'nice':1,'thing':1,'things':1,'better':1,'again':1,'first':1,'then':1,'only':1,'even':1 };
+    var uniq = {};
+    for (var i = 0; i < words.length; i++) if (!stop[words[i]]) uniq[words[i]] = 1;
+    var keys = Object.keys(uniq).slice(0, 8);
+    var isSymbolLookup = taskText.length <= 30 && /^[a-zA-Z0-9_\-./:]+$/.test(taskText.trim());
+    if (keys.length === 0) return [];
+    if (keys.length < 2 && !isSymbolLookup) return [];
+
+    var ftsQuery = keys.map(function(k){ return '"' + k.replace(/"/g, '') + '"'; }).join(' OR ');
+    var lim = Math.max(1, limit || 5);
+    var rows = [];
+    try {
+      rows = db.prepare(
+        'SELECT n.id, n.name, n.label, n.file_path AS file, ' +
+        'bm25(nodes_fts) AS bm25_score, ' +
+        '(SELECT COUNT(*) FROM edges WHERE source_id=n.id OR target_id=n.id) AS deg, ' +
+        'CASE n.label WHEN \'File\' THEN 3 WHEN \'Function\' THEN 3 WHEN \'Class\' THEN 3 ' +
+        '             WHEN \'Method\' THEN 2 WHEN \'Interface\' THEN 2 ELSE 1 END AS label_rank ' +
+        'FROM nodes_fts f JOIN nodes n ON f.rowid = n.rowid ' +
+        'WHERE nodes_fts MATCH ? AND n.file_path IS NOT NULL AND n.file_path != \'\' ' +
+        'AND n.label NOT IN (\'Concept\') ' +
+        'AND n.name NOT LIKE \'(%\' AND n.name NOT LIKE \'%=>%\' AND n.name != \'function\' ' +
+        'AND length(n.name) >= 3 ' +
+        'ORDER BY label_rank DESC, bm25_score ASC, deg DESC LIMIT ?'
+      ).all(ftsQuery, lim);
+    } catch (e) {
+      var likeFrag = keys.map(function(){ return 'lower(n.name) LIKE ?'; }).join(' OR ');
+      var likeArgs = keys.map(function(k){ return '%' + k + '%'; });
+      var stmt = db.prepare(
+        'SELECT n.id, n.name, n.label, n.file_path AS file, ' +
+        '(SELECT COUNT(*) FROM edges WHERE source_id=n.id OR target_id=n.id) AS deg ' +
+        'FROM nodes n WHERE (' + likeFrag + ') AND n.file_path IS NOT NULL AND n.file_path != \'\' ' +
+        'AND n.label NOT IN (\'Concept\') ' +
+        'ORDER BY deg DESC LIMIT ?'
+      );
+      rows = stmt.all.apply(stmt, likeArgs.concat([lim]));
+    }
+    return rows || [];
+  } catch (e) { return []; }
+  finally { /* db is shared/cached; do not close */ }
+}
+
+function getMonographNeighbors(filePath) {
+  if (!filePath) return null;
+  var db = _openMonographDb();
+  if (!db) return null;
+  try {
+    var rel = filePath;
+    if (filePath.indexOf(CWD) === 0) rel = filePath.slice(CWD.length + 1);
+    var node = db.prepare(
+      'SELECT id, name FROM nodes WHERE label=\'File\' AND (file_path=? OR file_path=? OR name=? OR name=?) LIMIT 1'
+    ).get(filePath, rel, filePath, rel);
+    if (!node) return null;
+
+    var imports = db.prepare(
+      'SELECT DISTINCT n.name FROM edges e JOIN nodes n ON e.target_id = n.id ' +
+      'WHERE e.source_id=? AND e.relation IN (\'IMPORTS\',\'CALLS\',\'DEPENDS_ON\',\'CONTAINS\',\'DEFINES\') ' +
+      'AND n.file_path IS NOT NULL AND n.file_path != \'\' LIMIT 6'
+    ).all(node.id).map(function(r){ return r.name; });
+    var importedBy = db.prepare(
+      'SELECT DISTINCT n.name FROM edges e JOIN nodes n ON e.source_id = n.id ' +
+      'WHERE e.target_id=? AND e.relation IN (\'IMPORTS\',\'CALLS\',\'DEPENDS_ON\',\'CONTAINS\',\'DEFINES\') ' +
+      'AND n.file_path IS NOT NULL AND n.file_path != \'\' LIMIT 6'
+    ).all(node.id).map(function(r){ return r.name; });
+
+    return { imports: imports, importedBy: importedBy };
+  } catch (e) { return null; }
+  finally { /* db is shared/cached; do not close */ }
+}
+
+var _TOKEN_PER_EVENT = {
+  monograph_call:  300,
+  grep_call:      2000,
+  glob_call:       800,
+  bash_grep_call: 2000,
+  bash_find_call:  800,
+};
+var _DOLLAR_PER_1M_TOKENS = 3.0;
+
+function _recordGraphTelemetry(event) {
+  try {
+    var metricsDir = path.join(CWD, '.monomind', 'metrics');
+    var f = path.join(metricsDir, 'graph-usage.json');
+    fs.mkdirSync(metricsDir, { recursive: true });
+    var d = {};
+    try { d = JSON.parse(fs.readFileSync(f, 'utf-8')); } catch (e) {}
+    if (typeof d !== 'object' || d === null) d = {};
+    d[event] = (d[event] || 0) + 1;
+    if (event === 'monograph_call') {
+      var saved = (_TOKEN_PER_EVENT.grep_call - _TOKEN_PER_EVENT.monograph_call);
+      d.tokens_saved = (d.tokens_saved || 0) + saved;
+      d.dollars_saved = ((d.tokens_saved / 1000000) * _DOLLAR_PER_1M_TOKENS);
+    }
+    if (event === 'grep_call' || event === 'bash_grep_call') {
+      var wasted = (_TOKEN_PER_EVENT.grep_call - _TOKEN_PER_EVENT.monograph_call);
+      d.tokens_wasted = (d.tokens_wasted || 0) + wasted;
+    }
+    d.lastUpdated = Date.now();
+    fs.writeFileSync(f, JSON.stringify(d));
+  } catch (e) { /* non-fatal */ }
+}
+
+function _injectCompactGraphMap() {
+  try {
+    var db = _openMonographDb();
+    if (!db) return;
+    try {
+      var nodeC = db.prepare('SELECT COUNT(*) AS c FROM nodes').get().c;
+      var anchors = [];
+      var seenPaths = {};
+
+      var recentEdits = _getRecentEdits();
+      for (var ri = 0; ri < Math.min(recentEdits.length, 5); ri++) {
+        var rfile = recentEdits[ri].file;
+        var rrel = (rfile.indexOf(CWD) === 0) ? rfile.slice(CWD.length + 1) : rfile;
+        try {
+          var rnode = db.prepare(
+            'SELECT n.name, n.label, n.file_path, ' +
+            '(SELECT COUNT(*) FROM edges WHERE source_id=n.id OR target_id=n.id) AS deg ' +
+            'FROM nodes n WHERE n.label=\'File\' AND (n.file_path=? OR n.file_path=?) LIMIT 1'
+          ).get(rfile, rrel);
+          if (rnode && !seenPaths[rnode.file_path]) {
+            seenPaths[rnode.file_path] = 1;
+            anchors.push({ name: rnode.name, label: rnode.label, file_path: rnode.file_path, deg: rnode.deg, tag: '✎' });
+          }
+        } catch (e) { /* ignore */ }
+      }
+
+      if (anchors.length < 8) {
+        var gods = db.prepare(
+          'SELECT n.name, n.label, n.file_path, ' +
+          '(SELECT COUNT(*) FROM edges WHERE source_id=n.id OR target_id=n.id) AS deg ' +
+          'FROM nodes n ' +
+          'WHERE n.label NOT IN (\'Concept\') AND n.file_path IS NOT NULL AND n.file_path != \'\' ' +
+          'AND n.file_path NOT LIKE \'%/node_modules/%\' AND n.file_path NOT LIKE \'%node_modules%\' ' +
+          'AND n.name NOT LIKE \'(%\' AND n.name NOT LIKE \'%=>%\' AND length(n.name) >= 3 ' +
+          'ORDER BY deg DESC LIMIT 15'
+        ).all();
+        for (var gi = 0; gi < gods.length && anchors.length < 8; gi++) {
+          if (!seenPaths[gods[gi].file_path]) {
+            seenPaths[gods[gi].file_path] = 1;
+            anchors.push({ name: gods[gi].name, label: gods[gi].label, file_path: gods[gi].file_path, deg: gods[gi].deg, tag: '' });
+          }
+        }
+      }
+
+      if (anchors.length > 0) {
+        console.log('[COMPACT_GRAPH] ' + nodeC + ' nodes. Session context (✎ = recently edited):');
+        for (var ci = 0; ci < anchors.length; ci++) {
+          var g = anchors[ci];
+          console.log('  ' + (g.tag || ' ') + ' ' + g.name + ' [' + g.label + '] — ' + g.file_path + ' (deg ' + g.deg + ')');
+        }
+        console.log('  Use mcp__monomind__monograph_suggest first when navigating.');
+      }
+    } finally { /* db is shared/cached; do not close */ }
+  } catch (e) {}
+}
+
+function _findAffectedTests(filePath) {
+  if (!filePath) return [];
+  var db = _openMonographDb();
+  if (!db) return [];
+  try {
+    var rel = filePath;
+    if (filePath.indexOf(CWD) === 0) rel = filePath.slice(CWD.length + 1);
+    var rows = db.prepare(
+      'SELECT DISTINCT src.file_path FROM edges e ' +
+      'JOIN nodes src ON e.source_id = src.id ' +
+      'JOIN nodes tgt ON e.target_id = tgt.id ' +
+      'WHERE e.relation IN (\'IMPORTS\',\'CALLS\',\'DEPENDS_ON\') ' +
+      'AND (tgt.file_path = ? OR tgt.file_path = ?) ' +
+      'AND src.file_path IS NOT NULL AND src.file_path != \'\' ' +
+      'AND (src.file_path LIKE \'%test%\' OR src.file_path LIKE \'%.spec.%\' OR src.file_path LIKE \'%__tests__%\') ' +
+      'AND src.file_path NOT LIKE \'%.worktrees%\' ' +
+      'LIMIT 5'
+    ).all(filePath, rel);
+    return rows.map(function(r) { return r.file_path; });
+  } catch (e) { return []; }
+  finally { /* db is shared/cached; do not close */ }
+}
+
+function _maybeRebuildMonograph() {
+  try {
+    var metricsDir = path.join(CWD, '.monomind', 'metrics');
+    fs.mkdirSync(metricsDir, { recursive: true });
+    var f = path.join(metricsDir, 'graph-rebuild.json');
+    var d = {};
+    try { d = JSON.parse(fs.readFileSync(f, 'utf-8')); } catch (_) {}
+    if (typeof d !== 'object' || d === null) d = {};
+    d.writesSinceRebuild = (d.writesSinceRebuild || 0) + 1;
+    d.lastWriteAt = Date.now();
+    var THRESHOLD = 20;
+    var MIN_INTERVAL_MS = 5 * 60 * 1000;
+    var dueByCount = d.writesSinceRebuild >= THRESHOLD;
+    var dueByTime  = !d.lastRebuildAt || (Date.now() - d.lastRebuildAt) > MIN_INTERVAL_MS;
+    if (dueByCount && dueByTime) {
+      d.writesSinceRebuild = 0;
+      d.lastRebuildAt = Date.now();
+      fs.writeFileSync(f, JSON.stringify(d));
+      try {
+        var freshenScript = path.join(CWD, '.claude', 'helpers', 'graphify-freshen.cjs');
+        if (fs.existsSync(freshenScript)) {
+          var spawn = require('child_process').spawn;
+          var child = spawn(process.execPath, [freshenScript], {
+            detached: true,
+            stdio: 'ignore',
+            cwd: CWD,
+          });
+          child.unref();
+        }
+      } catch (_) {}
+    } else {
+      fs.writeFileSync(f, JSON.stringify(d));
+    }
+  } catch (e) { /* non-fatal */ }
+}
+
+// Inject god-node context at session-restore time: logs MONOGRAPH_CONTEXT,
+// writes the god-node chunk into knowledge/chunks.jsonl for semantic recall.
+// Shared between session-restore-handler and any other caller that needs it.
+function injectGodNodesContext(CWD) {
+  try {
+    var mgDbPath = path.join(CWD, '.monomind', 'monograph.db');
+    if (!fs.existsSync(mgDbPath)) return;
+    var db = _openMonographDb();
+    if (!db) return;
+    try {
+      var nodeCount = db.prepare('SELECT COUNT(*) AS c FROM nodes').get().c;
+      var edgeCount = db.prepare('SELECT COUNT(*) AS c FROM edges').get().c;
+      var godNodes = db.prepare(
+        "SELECT n.name, n.label, n.file_path, " +
+        "(SELECT COUNT(*) FROM edges WHERE source_id=n.id OR target_id=n.id) AS deg " +
+        "FROM nodes n " +
+        "WHERE n.label NOT IN ('Concept') " +
+        "AND n.file_path IS NOT NULL AND n.file_path != '' " +
+        "AND n.file_path NOT LIKE '%/node_modules/%' AND n.file_path NOT LIKE '%node_modules%' " +
+        "ORDER BY deg DESC LIMIT 12"
+      ).all();
+
+      // Staleness indicator: compare stored commit hash with current HEAD.
+      var staleIndicator = '';
+      try {
+        var lastCommitRow = null;
+        try { lastCommitRow = db.prepare("SELECT value FROM index_meta WHERE key='ua_last_commit'").get(); } catch (_) {}
+        if (lastCommitRow && lastCommitRow.value) {
+          var { execFileSync: execSync } = require('child_process');
+          var currentHead = '';
+          try { currentHead = execSync('git', ['rev-parse', 'HEAD'], { cwd: CWD, encoding: 'utf-8' }).trim(); } catch (_) {}
+          if (currentHead && currentHead !== lastCommitRow.value) {
+            var commitsBehind = 0;
+            try {
+              var revList = execSync('git', ['rev-list', '--count', lastCommitRow.value + '..' + currentHead], { cwd: CWD, encoding: 'utf-8' }).trim();
+              commitsBehind = parseInt(revList, 10) || 0;
+            } catch (_) {}
+            if (commitsBehind > 0) {
+              staleIndicator = ' [⚡ graph ' + commitsBehind + ' commit' + (commitsBehind === 1 ? '' : 's') + ' behind — run: npx monomind monograph build]';
+            }
+          }
+        }
+      } catch (_) {}
+
+      if (godNodes.length > 0) {
+        var godStr = godNodes.slice(0, 8).map(function(n) {
+          return n.name + ' (' + n.label + ', ' + n.deg + ' links)';
+        }).join(', ');
+        console.log('[MONOGRAPH_CONTEXT] ' + nodeCount + ' nodes · ' + edgeCount + ' edges. Key nodes: ' + godStr + staleIndicator);
+
+        // Write god nodes into knowledge/chunks.jsonl so semantic search finds them.
+        var knowledgeDir = path.join(CWD, '.monomind', 'knowledge');
+        var chunksFile = path.join(knowledgeDir, 'chunks.jsonl');
+        try {
+          fs.mkdirSync(knowledgeDir, { recursive: true });
+          var godChunk = JSON.stringify({
+            id: 'monograph-god-nodes',
+            text: 'Codebase architecture — high-centrality nodes (most depended-on): ' + godNodes.map(function(n) {
+              return n.name + ' [' + n.label + '] at ' + (n.file_path || '') + ' (' + n.deg + ' connections)';
+            }).join('; '),
+            namespace: 'knowledge:monograph',
+            metadata: { label: 'monograph-god-nodes', nodes: nodeCount, edges: edgeCount }
+          });
+          var existing = [];
+          try { existing = fs.readFileSync(chunksFile, 'utf-8').trim().split('\n').filter(Boolean); } catch(e) {}
+          existing = existing.filter(function(line) {
+            try { return JSON.parse(line).id !== 'monograph-god-nodes'; } catch(e) { return true; }
+          });
+          existing.push(godChunk);
+          fs.writeFileSync(chunksFile, existing.join('\n') + '\n');
+        } catch(e) {}
+      }
+    } catch(e) { /* non-fatal */ }
+  } catch(e) { /* non-fatal */ }
+}
+
+module.exports = {
+  _requireMonograph,
+  _openMonographDb,
+  getMonographSuggestions,
+  getMonographNeighbors,
+  _recordGraphTelemetry,
+  _injectCompactGraphMap,
+  _findAffectedTests,
+  _maybeRebuildMonograph,
+  injectGodNodesContext,
+};