@misterhuydo/cairn-mcp 1.7.1 → 1.8.1

package/bin/cairn-cli.js

@@ -14,91 +14,148 @@ const MINIFY_LANGS = new Set(['java', 'typescript', 'javascript', 'vue', 'python
 
 // Memory sync scripts deployed to ~/.claude/scripts/ during global install.
 // Using forward slashes in hook commands — bash on Windows handles them fine.
-const SYNC_FORWARD_SCRIPT = `\
-"""
-Forward sync: Claude Code auto-memory -> .cairn/memory/auto-memory/
-Triggered as a PostToolUse hook on Write.
-Only fires when the written file is inside Claude's projects memory dir
-and the current project has a .cairn/ folder.
-"""
-import sys, json, os, shutil
-
-data = json.load(sys.stdin)
-fp = data.get('tool_input', {}).get('file_path', '')
-
-user_home = os.path.expanduser('~')
-claude_projects = os.path.normpath(os.path.join(user_home, '.claude', 'projects'))
-
-fp_norm = os.path.normpath(fp)
-if not fp_norm.startswith(claude_projects) or 'memory' not in fp_norm:
-    sys.exit(0)
-
-cwd = os.getcwd()
-if not os.path.exists(os.path.join(cwd, '.cairn')):
-    sys.exit(0)
-
-memory_dir = os.path.dirname(fp_norm)
-dest = os.path.join(cwd, '.cairn', 'memory', 'auto-memory')
-os.makedirs(dest, exist_ok=True)
-
-for f in os.listdir(memory_dir):
-    src = os.path.join(memory_dir, f)
-    if os.path.isfile(src):
-        shutil.copy2(src, dest)
+const SYNC_FORWARD_SCRIPT = `#!/usr/bin/env node
+// Forward sync: Claude Code auto-memory -> .cairn/memory/auto-memory/
+// Triggered as a PostToolUse hook on Write.
+// Only fires when the written file is inside Claude's projects memory dir
+// and the current project has a .cairn/ folder.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+let stdinData = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', c => { stdinData += c; });
+process.stdin.on('end', () => {
+  let fp;
+  try { fp = JSON.parse(stdinData)?.tool_input?.file_path || ''; } catch { process.exit(0); }
+  if (!fp) process.exit(0);
+
+  const claudeProjects = path.normalize(path.join(os.homedir(), '.claude', 'projects'));
+  const fpNorm = path.normalize(fp);
+  if (!fpNorm.startsWith(claudeProjects) || !fpNorm.includes('memory')) process.exit(0);
+
+  const cwd = process.cwd();
+  if (!fs.existsSync(path.join(cwd, '.cairn'))) process.exit(0);
+
+  const memoryDir = path.dirname(fpNorm);
+  const cairnMemory = path.join(cwd, '.cairn', 'memory');
+  const dest = path.join(cairnMemory, 'auto-memory');
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const f of fs.readdirSync(memoryDir)) {
+    // Skip files that exist in canonical top-level — those are mirrored from cairn_memo,
+    // not out-of-band auto-memory writes, so backing them up would duplicate canonical content.
+    if (fs.existsSync(path.join(cairnMemory, f))) continue;
+    const src = path.join(memoryDir, f);
+    let st;
+    try { st = fs.statSync(src); } catch { continue; }
+    if (!st.isFile()) continue;
+    const dst = path.join(dest, f);
+    fs.copyFileSync(src, dst);
+    try { fs.utimesSync(dst, st.atime, st.mtime); } catch {}
+  }
+});
 `;
 
-const SYNC_RESTORE_SCRIPT = `\
-"""
-Restore sync: .cairn/memory/ -> Claude Code memory dir for current location.
-Triggered as a UserPromptSubmit hook on each new session prompt.
-Two passes:
-  1. New-machine restore: copy .cairn/memory/auto-memory/ -> Claude memory dir
-     (only when target is empty/missing, preserves Claude-native memory on new drive)
-  2. Always: sync .cairn/memory/ (top-level files only) -> Claude memory dir
-     using mtime comparison so cairn_memo writes are always reflected.
-Path encoding: H:\\\\Projects\\\\Cairn -> H--Projects-Cairn
-  (both ':' and '\\\\' map to '-', so ':' + '\\\\' = '--')
-"""
-import sys, os, shutil
-
-cwd = os.getcwd()
-cairn_memory = os.path.join(cwd, '.cairn', 'memory')
-
-if not os.path.exists(cairn_memory):
-    sys.exit(0)
-
-encoded = cwd.replace(':', '-').replace('\\\\', '-').replace('/', '-').lstrip('-')
-user_home = os.path.expanduser('~')
-memory_dir = os.path.join(user_home, '.claude', 'projects', encoded, 'memory')
-os.makedirs(memory_dir, exist_ok=True)
-
-# Pass 1: new-machine restore from auto-memory backup
-cairn_auto_memory = os.path.join(cairn_memory, 'auto-memory')
-if os.path.exists(cairn_auto_memory):
-    target_empty = not any(f.endswith('.md') for f in os.listdir(memory_dir))
-    if target_empty:
-        restored = 0
-        for f in os.listdir(cairn_auto_memory):
-            src = os.path.join(cairn_auto_memory, f)
-            if os.path.isfile(src):
-                shutil.copy2(src, memory_dir)
-                restored += 1
-        if restored > 0:
-            print(f"[cairn] Restored {restored} memory files from .cairn/memory/auto-memory/ (new project location detected)")
-
-# Pass 2: always sync top-level .cairn/memory/ files (cairn_memo writes) -> Claude memory dir
-synced = 0
-for f in os.listdir(cairn_memory):
-    src = os.path.join(cairn_memory, f)
-    if not os.path.isfile(src):
-        continue  # skip subdirs like auto-memory/
-    dst = os.path.join(memory_dir, f)
-    if not os.path.exists(dst) or os.path.getmtime(src) > os.path.getmtime(dst):
-        shutil.copy2(src, dst)
-        synced += 1
-
-if synced > 0:
-    print(f"[cairn] Synced {synced} memory file(s) from .cairn/memory/ to Claude memory dir")
+const SYNC_RESTORE_SCRIPT = `#!/usr/bin/env node
+// Restore sync: .cairn/memory/ -> Claude Code memory dir for current location.
+// Triggered as a UserPromptSubmit hook on each new session prompt.
+// Three passes:
+//   0. Bootstrap: capture any auto-memory files newer/missing in .cairn/memory/auto-memory/
+//      (catches files pre-dating the forward-sync hook install).
+//   1. New-machine restore: copy .cairn/memory/auto-memory/ -> Claude memory dir
+//      (only when target is empty, preserves Claude-native memory on new drive)
+//   2. Always: mtime-mirror .cairn/memory/*.md -> Claude memory dir
+//      (so cairn_memo writes are reflected)
+// Path encoding: H:\\Projects\\Cairn -> H--Projects-Cairn
+//   (':', '\\', '/' all map to '-')
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const cwd = process.cwd();
+const cairnMemory = path.join(cwd, '.cairn', 'memory');
+if (!fs.existsSync(cairnMemory)) process.exit(0);
+
+const encoded = cwd.replace(/[:/\\\\]/g, '-').replace(/^-+/, '');
+const memoryDir = path.join(os.homedir(), '.claude', 'projects', encoded, 'memory');
+fs.mkdirSync(memoryDir, { recursive: true });
+
+const cairnAutoMemory = path.join(cairnMemory, 'auto-memory');
+
+function copyWithMtime(src, dst, srcStat) {
+  fs.copyFileSync(src, dst);
+  try { fs.utimesSync(dst, srcStat.atime, srcStat.mtime); } catch {}
+}
+
+// Pass 0: bootstrap — capture auto-memory files missing/newer in .cairn/memory/auto-memory/
+// (catches files that pre-date the forward-sync hook install)
+// Skip files present in canonical top-level: they are mirrored from cairn_memo, not auto-memory.
+const claudeFiles = fs.readdirSync(memoryDir);
+let bootstrapped = 0;
+if (claudeFiles.length > 0) {
+  fs.mkdirSync(cairnAutoMemory, { recursive: true });
+  for (const f of claudeFiles) {
+    if (fs.existsSync(path.join(cairnMemory, f))) continue;
+    const src = path.join(memoryDir, f);
+    let srcStat;
+    try { srcStat = fs.statSync(src); } catch { continue; }
+    if (!srcStat.isFile()) continue;
+    const dst = path.join(cairnAutoMemory, f);
+    let needCopy = !fs.existsSync(dst);
+    if (!needCopy) {
+      try { needCopy = srcStat.mtimeMs > fs.statSync(dst).mtimeMs; } catch { needCopy = true; }
+    }
+    if (needCopy) {
+      copyWithMtime(src, dst, srcStat);
+      bootstrapped++;
+    }
+  }
+}
+if (bootstrapped > 0) {
+  process.stdout.write(\`[cairn] Bootstrapped \${bootstrapped} auto-memory file(s) into .cairn/memory/auto-memory/\\n\`);
+}
+
+// Pass 1: new-machine restore from auto-memory backup (only when target empty)
+if (fs.existsSync(cairnAutoMemory)) {
+  const targetEmpty = !fs.readdirSync(memoryDir).some(f => f.endsWith('.md'));
+  if (targetEmpty) {
+    let restored = 0;
+    for (const f of fs.readdirSync(cairnAutoMemory)) {
+      const src = path.join(cairnAutoMemory, f);
+      let srcStat;
+      try { srcStat = fs.statSync(src); } catch { continue; }
+      if (!srcStat.isFile()) continue;
+      copyWithMtime(src, path.join(memoryDir, f), srcStat);
+      restored++;
+    }
+    if (restored > 0) {
+      process.stdout.write(\`[cairn] Restored \${restored} memory files from .cairn/memory/auto-memory/ (new project location detected)\\n\`);
+    }
+  }
+}
+
+// Pass 2: mtime-mirror top-level .cairn/memory/*.md -> Claude memory dir
+let synced = 0;
+for (const f of fs.readdirSync(cairnMemory)) {
+  const src = path.join(cairnMemory, f);
+  let srcStat;
+  try { srcStat = fs.statSync(src); } catch { continue; }
+  if (!srcStat.isFile()) continue;  // skip subdirs like auto-memory/
+  const dst = path.join(memoryDir, f);
+  let needCopy = !fs.existsSync(dst);
+  if (!needCopy) {
+    try { needCopy = srcStat.mtimeMs > fs.statSync(dst).mtimeMs; } catch { needCopy = true; }
+  }
+  if (needCopy) {
+    copyWithMtime(src, dst, srcStat);
+    synced++;
+  }
+}
+if (synced > 0) {
+  process.stdout.write(\`[cairn] Synced \${synced} memory file(s) from .cairn/memory/ to Claude memory dir\\n\`);
+}
 `;
 
 process.on('uncaughtException', (e) => {
@@ -343,21 +400,9 @@ if (subcommand === '--version' || subcommand === '-v') {
       .filter(([, e]) => (e.readCount ?? 0) > 0)
       .map(([p]) => p);
   } catch { }
-  // Snapshot git state as a note so next resume knows where the session left off
-  // even if no explicit cairn_checkpoint was called.
-  const gitNotes = [...existingNotes.filter(n => !n.startsWith('git-snapshot:'))];
-  try {
-    const stat = execSync('git diff --stat HEAD', {
-      cwd: process.cwd(), encoding: 'utf8', timeout: 5000,
-    }).trim();
-    const status = execSync('git status --short', {
-      cwd: process.cwd(), encoding: 'utf8', timeout: 5000,
-    }).trim();
-    if (stat || status) {
-      gitNotes.push(`git-snapshot: ${stat || '(clean)'} | status: ${status || '(clean)'}`);
-    }
-  } catch { }
-  checkpoint(null, { message, active_files: activeFiles, notes: gitNotes });
+  // git state is already returned live by cairn_resume (git_status + uncommitted_changes)
+  // so there is no value in baking a stale snapshot into the notes array.
+  checkpoint(null, { message, active_files: activeFiles, notes: existingNotes });
   process.exit(0);
 
 } else if (subcommand === 'resume-hint') {
@@ -521,10 +566,10 @@ if (subcommand === '--version' || subcommand === '-v') {
   console.log('  PreToolUse[Read]     -> cairn minify                   (compress source files for reading)');
   console.log('  PreToolUse[Edit]     -> cairn edit-guard               (block Edit until re-read with full content)')
   console.log('  PreToolUse[Write]    -> cairn edit-guard               (clear minify state before full file overwrite)');
-  console.log('  PostToolUse[Write]   -> sync-memory-forward.py         (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
+  console.log('  PostToolUse[Write]   -> sync-memory-forward.mjs        (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
   console.log('  Stop                 -> cairn checkpoint --auto         (auto-save session)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
-  console.log('  UserPromptSubmit     -> sync-memory-restore.py          (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
+  console.log('  UserPromptSubmit     -> sync-memory-restore.mjs         (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
   console.log('');
   console.log('Restart Claude Code to activate the MCP server, then open any project and start working.');
   console.log('Upgrade any time with: npm install -g @misterhuydo/cairn-mcp');
@@ -544,12 +589,12 @@ if (subcommand === '--version' || subcommand === '-v') {
   console.log('  PreToolUse[Edit]     -> cairn edit-guard               (block Edit until re-read with full content)')
   console.log('  PreToolUse[Write]    -> cairn edit-guard               (clear minify state before full file overwrite)');
   if (isGlobal) {
-    console.log('  PostToolUse[Write]   -> sync-memory-forward.py         (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
+    console.log('  PostToolUse[Write]   -> sync-memory-forward.mjs        (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
   }
   console.log('  Stop                 -> cairn checkpoint --auto         (auto-save session)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
   if (isGlobal) {
-    console.log('  UserPromptSubmit     -> sync-memory-restore.py          (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
+    console.log('  UserPromptSubmit     -> sync-memory-restore.mjs         (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
   }
   process.exit(0);
 
@@ -591,32 +636,50 @@ function applyHooks(settingsDir, isGlobal) {
   }
 
   // UserPromptSubmit: cairn resume-hint
-  const submitHooks = settings.hooks.UserPromptSubmit || [];
+  let submitHooks = settings.hooks.UserPromptSubmit || [];
   if (!submitHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn resume-hint'))) {
     submitHooks.push({ hooks: [{ type: 'command', command: 'cairn resume-hint' }] });
   }
 
   if (isGlobal) {
-    // Deploy memory sync scripts to ~/.claude/scripts/
+    // Deploy memory sync scripts to ~/.claude/scripts/ (Node — cross-platform, no python3 required)
     const scriptsDir = path.join(settingsDir, 'scripts');
     fs.mkdirSync(scriptsDir, { recursive: true });
-    const forwardScript = path.join(scriptsDir, 'sync-memory-forward.py');
-    const restoreScript = path.join(scriptsDir, 'sync-memory-restore.py');
+    const forwardScript = path.join(scriptsDir, 'sync-memory-forward.mjs');
+    const restoreScript = path.join(scriptsDir, 'sync-memory-restore.mjs');
     fs.writeFileSync(forwardScript, SYNC_FORWARD_SCRIPT, 'utf8');
     fs.writeFileSync(restoreScript, SYNC_RESTORE_SCRIPT, 'utf8');
 
+    // Clean up legacy Python scripts from prior installs
+    for (const legacy of ['sync-memory-forward.py', 'sync-memory-restore.py']) {
+      const p = path.join(scriptsDir, legacy);
+      if (fs.existsSync(p)) { try { fs.unlinkSync(p); } catch {} }
+    }
+
     // Use forward slashes in hook commands — works across bash on Windows and Unix
-    const fwdCmd = `python3 "${scriptsDir.replace(/\\/g, '/')}/sync-memory-forward.py"`;
-    const rstCmd = `python3 "${scriptsDir.replace(/\\/g, '/')}/sync-memory-restore.py"`;
+    const scriptsDirFwd = scriptsDir.replace(/\\/g, '/');
+    const fwdCmd = `node "${scriptsDirFwd}/sync-memory-forward.mjs"`;
+    const rstCmd = `node "${scriptsDirFwd}/sync-memory-restore.mjs"`;
+
+    // Strip stale python3 .py references from prior installs (avoids duplicate hooks firing)
+    const isLegacyPyCmd = (cmd) => typeof cmd === 'string' &&
+      /python3?\s+.*sync-memory-(forward|restore)\.py/.test(cmd);
+    const stripLegacy = (entries) => entries
+      .map(entry => ({
+        ...entry,
+        hooks: (entry.hooks || []).filter(h => !isLegacyPyCmd(h.command)),
+      }))
+      .filter(entry => entry.hooks.length > 0);
 
     // PostToolUse[Write]: forward sync Claude memory -> .cairn/memory/auto-memory/
-    const postHooks = settings.hooks.PostToolUse || [];
+    let postHooks = stripLegacy(settings.hooks.PostToolUse || []);
     if (!postHooks.some(h => h.matcher === 'Write' && h.hooks?.some(hh => hh.command === fwdCmd))) {
       postHooks.push({ matcher: 'Write', hooks: [{ type: 'command', command: fwdCmd }] });
     }
     settings.hooks.PostToolUse = postHooks;
 
     // UserPromptSubmit: sync .cairn/memory/ -> Claude memory dir (always, mtime-based)
+    submitHooks = stripLegacy(submitHooks);
     if (!submitHooks.some(h => h.hooks?.some(hh => hh.command === rstCmd))) {
       submitHooks.push({ hooks: [{ type: 'command', command: rstCmd }] });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "MCP server that gives Claude Code persistent memory across sessions. Index your codebase once, search symbols, bundle source, scan for vulnerabilities, and checkpoint/resume work — across Java, TypeScript, Vue, Python, SQL and more.",
   "type": "module",
   "main": "index.js",

package/src/tools/checkpoint.js

@@ -1,45 +1,101 @@
-import fs from 'fs';
-import path from 'path';
-import { getCairnDir } from '../graph/cwd.js';
-
-export function checkpoint(_db, { message, active_files = [], notes = [] }) {
-  // Coerce notes to array in case the caller passed a pre-serialized JSON string
-  if (typeof notes === 'string') {
-    try { notes = JSON.parse(notes); } catch { notes = notes ? [notes] : []; }
-  }
-  if (!Array.isArray(notes)) notes = [];
-  const cairnDir = getCairnDir();
-  const sessionPath = path.join(cairnDir, 'session.json');
-
-  // Snapshot mtimes of active files
-  const mtimeSnapshot = {};
-  for (const filePath of active_files) {
-    try {
-      mtimeSnapshot[filePath] = fs.statSync(filePath).mtimeMs;
-    } catch {
-      // File may not exist yet
-    }
-  }
-
-  const session = {
-    message,
-    checkpoint_at: new Date().toISOString(),
-    active_files,
-    notes: notes.map(n => (/^\[\d{4}-\d{2}-\d{2}\]/.test(n) ? n : '[' + new Date().toISOString().slice(0, 10) + '] ' + n)),
-    mtime_snapshot: mtimeSnapshot,
-  };
-
-  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf8');
-
-  return {
-    content: [{
-      type: 'text',
-      text: JSON.stringify({
-        saved: true,
-        checkpoint_at: session.checkpoint_at,
-        active_files_tracked: active_files.length,
-        notes_saved: notes.length,
-      }, null, 2),
-    }],
-  };
-}
+import fs from 'fs';
+import path from 'path';
+import { getCairnDir } from '../graph/cwd.js';
+
+const NOTE_CHAR_LIMIT = 1000;
+const SESSION_ROTATION_LIMIT = 100 * 1024; // 100KB
+
+// Process a single note for storage:
+// - ref objects pass through unchanged (already filed)
+// - strings within limit get a date prefix and stay inline
+// - strings over limit get filed to .cairn/notes/ and replaced with a ref object
+function processNote(note, cairnDir, dateStr, index) {
+  // Already a ref object — pass through
+  if (note && typeof note === 'object' && note.ref) return note;
+
+  const text = typeof note === 'string' ? note : String(note);
+
+  // Add date prefix if missing
+  const dated = /^\[\d{4}-\d{2}-\d{2}\]/.test(text)
+    ? text
+    : `[${dateStr}] ${text}`;
+
+  // Short enough to stay inline
+  if (dated.length <= NOTE_CHAR_LIMIT) return dated;
+
+  // Too long — save to .cairn/notes/ and return a ref
+  const notesDir = path.join(cairnDir, 'notes');
+  fs.mkdirSync(notesDir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const fileName = `note-${ts}-${index}.md`;
+  const filePath = path.join(notesDir, fileName);
+  fs.writeFileSync(filePath, dated, 'utf8');
+
+  // Description: first line of the note, capped at 120 chars
+  const description = dated.split('\n')[0].slice(0, 120);
+  return { description, ref: path.join('.cairn', 'notes', fileName) };
+}
+
+export function checkpoint(_db, { message, active_files = [], notes = [] }) {
+  // Coerce notes to array in case the caller passed a pre-serialized JSON string
+  if (typeof notes === 'string') {
+    try { notes = JSON.parse(notes); } catch { notes = notes ? [notes] : []; }
+  }
+  if (!Array.isArray(notes)) notes = [];
+
+  const cairnDir = getCairnDir();
+  const sessionPath = path.join(cairnDir, 'session.json');
+  const dateStr = new Date().toISOString().slice(0, 10);
+
+  // Snapshot mtimes of all indexed files so resume can detect changes accurately.
+  // Without a full snapshot, resume labels every non-active file as "new" and
+  // triggers a full reindex on every call.
+  const mtimeSnapshot = {};
+  try {
+    const rows = _db.prepare('SELECT path FROM main.files').all();
+    for (const { path: filePath } of rows) {
+      try { mtimeSnapshot[filePath] = fs.statSync(filePath).mtimeMs; } catch { }
+    }
+  } catch { /* DB may not exist on first run */ }
+  // Also include active_files in case they are not yet indexed
+  for (const filePath of active_files) {
+    try { mtimeSnapshot[filePath] = fs.statSync(filePath).mtimeMs; } catch { }
+  }
+
+  // Process all notes: long strings get filed, short ones stay inline, refs pass through
+  const processedNotes = notes.map((n, i) => processNote(n, cairnDir, dateStr, i));
+
+  // Rotate session.json when it has grown beyond the size limit
+  if (fs.existsSync(sessionPath)) {
+    try {
+      const size = fs.statSync(sessionPath).size;
+      if (size > SESSION_ROTATION_LIMIT) {
+        let n = 1;
+        while (fs.existsSync(path.join(cairnDir, `session.${n}.json`))) n++;
+        fs.renameSync(sessionPath, path.join(cairnDir, `session.${n}.json`));
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  const session = {
+    message,
+    checkpoint_at: new Date().toISOString(),
+    active_files,
+    notes: processedNotes,
+    mtime_snapshot: mtimeSnapshot,
+  };
+
+  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf8');
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        saved: true,
+        checkpoint_at: session.checkpoint_at,
+        active_files_tracked: active_files.length,
+        notes_saved: processedNotes.length,
+      }, null, 2),
+    }],
+  };
+}

package/src/tools/relocate.js

@@ -91,14 +91,23 @@ export function repairRelocation(db, cairnDir, session, map, oldRoot, newRoot) {
     'utf8'
   );
 
-  // 2. Repair index.db: rewrite absolute paths in the files table
+  // 2. Repair index.db: rewrite absolute paths in all tables that store them
+  const oldBack = oldRoot.replace(/\//g, '\\');
+  function replaceInCol(table, col) {
+    try {
+      db.prepare(`UPDATE ${table} SET ${col} = replace(${col}, ?, ?)`).run(oldRoot, newRoot);
+      db.prepare(`UPDATE ${table} SET ${col} = replace(${col}, ?, ?)`).run(oldBack, newRoot);
+    } catch { /* column or table missing in older schema — safe to ignore */ }
+  }
+  replaceInCol('files', 'path');
+  replaceInCol('symbols', 'fqn');
+  replaceInCol('todos', 'file');
+  // FTS virtual table — delete stale content rows; the next maintain/reindex will repopulate
   try {
-    db.prepare('UPDATE files SET path = replace(path, ?, ?)').run(oldRoot, newRoot);
-    // Also handle the backslash variant stored on Windows
-    db.prepare('UPDATE files SET path = replace(path, ?, ?)').run(
-      oldRoot.replace(/\//g, '\\'), newRoot
-    );
-  } catch { /* older schema without files table — safe to ignore */ }
+    db.prepare(`DELETE FROM fts_index_content WHERE c0 LIKE ? OR c0 LIKE ? OR c3 LIKE ? OR c3 LIKE ?`)
+      .run(oldRoot + '%', oldBack + '%', oldRoot + '%', oldBack + '%');
+    db.prepare("INSERT INTO fts_index(fts_index) VALUES('rebuild')").run();
+  } catch { /* FTS not present in older schema */ }
 
   // 3. Repair minify map
   const newMap = {};

package/src/tools/resume.js

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import path from 'path';
-import { execSync } from 'child_process';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
 import { getCairnDir, getProjectRoot, getMemoryDir } from '../graph/cwd.js';
 import { walkRepo } from '../indexer/fileWalker.js';
 import { getAttachedSchemas } from '../graph/db.js';
@@ -38,6 +40,19 @@ export async function resume(db) {
   }
   if (!Array.isArray(session.notes)) session.notes = [];
 
+  // Migration: strip legacy git-snapshot notes (accumulated by old auto-checkpoint logic).
+  // These are pure noise — resume already returns live git_status + uncommitted_changes.
+  // Run once: back up the original to session.bak.json before modifying.
+  const gitSnapshotNotes = session.notes.filter(n => typeof n === 'string' && n.includes('git-snapshot:'));
+  if (gitSnapshotNotes.length > 0) {
+    const bakPath = path.join(cairnDir, 'session.bak.json');
+    if (!fs.existsSync(bakPath)) {
+      fs.copyFileSync(sessionPath, bakPath);
+    }
+    session.notes = session.notes.filter(n => !(typeof n === 'string' && n.includes('git-snapshot:')));
+    fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf8');
+  }
+
   // Detect and auto-repair project relocation before any path comparisons
   let relocation = null;
   const snapshot = session.mtime_snapshot || {};
@@ -128,9 +143,18 @@ export async function resume(db) {
     changed.length > 0 ? `Files changed since checkpoint: ${changedSummary}` : 'No files changed since checkpoint.',
     subSchemas.length > 0 ? `Federated sub-indexes: ${subSchemas.length}` : '',
     openTodos > 0 ? `Open todos: ${openTodos}` : '',
-    session.notes?.length > 0 ? `Notes: ${session.notes.join(' | ')}` : '',
+    session.notes?.length > 0 ? `Notes: ${session.notes.map(n => (n && typeof n === 'object' && n.ref) ? `${n.description} (see: ${n.ref})` : String(n)).join(' | ')}` : '',
   ].filter(Boolean).join(' ');
 
+  let gitignoreHint = null;
+  try {
+    const giContent = fs.readFileSync(path.join(getProjectRoot(), '.gitignore'), 'utf8');
+    const lines = giContent.split('\n').map(l => l.trim());
+    if (!lines.some(l => l === '.cairn' || l === '.cairn/' || l === '/.cairn' || l === '/.cairn/')) {
+      gitignoreHint = 'Add .cairn/ to your .gitignore to avoid committing the index and session cache.';
+    }
+  } catch { /* no .gitignore yet */ }
+
   const result = {
     last_checkpoint: session.checkpoint_at,
     message: session.message,
@@ -145,29 +169,31 @@ export async function resume(db) {
     notes: session.notes || [],
     resume_summary: resumeSummary,
   };
+  if (gitignoreHint) result.gitignore_hint = gitignoreHint;
+  if (gitSnapshotNotes.length > 0) {
+    result.migrated = `Removed ${gitSnapshotNotes.length} legacy git-snapshot note(s). Original session backed up to session.bak.json.`;
+  }
 
-  // Git state — lets Claude determine what's resolved vs still in-flight,
-  // regardless of checkpoint staleness.
+  // Git state — run all three queries in parallel to avoid sequential git startup overhead.
   const gitRoot = getProjectRoot();
-  try {
-    const since = new Date(session.checkpoint_at).toISOString();
-    const raw = execSync(`git log --oneline --after="${since}"`, {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000,
-    }).trim();
+  const since = new Date(session.checkpoint_at).toISOString();
+  const [logResult, diffResult, statusResult] = await Promise.allSettled([
+    execAsync(`git log --oneline --after="${since}"`, { cwd: gitRoot, timeout: 5000 }),
+    execAsync('git diff --name-only HEAD', { cwd: gitRoot, timeout: 5000 }),
+    execAsync('git status --short', { cwd: gitRoot, timeout: 5000 }),
+  ]);
+  if (logResult.status === 'fulfilled') {
+    const raw = logResult.value.stdout.trim();
     if (raw) result.commits_since_checkpoint = raw.split('\n');
-  } catch { }
-  try {
-    const raw = execSync('git diff --name-only HEAD', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000,
-    }).trim();
+  }
+  if (diffResult.status === 'fulfilled') {
+    const raw = diffResult.value.stdout.trim();
     if (raw) result.uncommitted_changes = raw.split('\n');
-  } catch { }
-  try {
-    const raw = execSync('git status --short', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000,
-    }).trim();
+  }
+  if (statusResult.status === 'fulfilled') {
+    const raw = statusResult.value.stdout.trim();
     if (raw) result.git_status = raw;
-  } catch { }
+  }
 
   if (relocation) result.relocated = relocation;
   if (preferences.length > 0) {

package/test/checkpoint.test.js

@@ -0,0 +1,99 @@
+import { strict as assert } from 'node:assert';
+import { test, beforeEach, afterEach } from 'node:test';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { setActiveProjectRoot } from '../src/graph/cwd.js';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cairn-checkpoint-'));
+  const cairnDir = path.join(tmpDir, '.cairn');
+  fs.mkdirSync(cairnDir, { recursive: true });
+  fs.writeFileSync(path.join(cairnDir, '.cairn-project'), '', 'utf8');
+  setActiveProjectRoot(tmpDir);
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// Dynamically import so setActiveProjectRoot takes effect before module runs
+async function getCheckpoint() {
+  const { checkpoint } = await import(`../src/tools/checkpoint.js?t=${Date.now()}`);
+  return checkpoint;
+}
+
+test('short notes stay inline with date prefix', async () => {
+  const checkpoint = await getCheckpoint();
+  checkpoint(null, { message: 'test', notes: ['short note'] });
+
+  const session = JSON.parse(fs.readFileSync(path.join(tmpDir, '.cairn', 'session.json'), 'utf8'));
+  assert.equal(session.notes.length, 1);
+  assert.ok(typeof session.notes[0] === 'string', 'short note should remain a string');
+  assert.match(session.notes[0], /^\[\d{4}-\d{2}-\d{2}\]/);
+});
+
+test('long notes are filed to .cairn/notes/ and replaced with a ref object', async () => {
+  const checkpoint = await getCheckpoint();
+  const longNote = 'x'.repeat(1001);
+  checkpoint(null, { message: 'test', notes: [longNote] });
+
+  const session = JSON.parse(fs.readFileSync(path.join(tmpDir, '.cairn', 'session.json'), 'utf8'));
+  assert.equal(session.notes.length, 1);
+  const note = session.notes[0];
+  assert.ok(note && typeof note === 'object', 'long note should be a ref object');
+  assert.ok(typeof note.ref === 'string', 'ref should be a string path');
+  assert.ok(typeof note.description === 'string', 'description should be present');
+
+  // Ref file should exist and contain the original content
+  const refPath = path.join(tmpDir, note.ref);
+  assert.ok(fs.existsSync(refPath), `ref file should exist at ${refPath}`);
+  const content = fs.readFileSync(refPath, 'utf8');
+  assert.ok(content.includes(longNote), 'ref file should contain the original note text');
+});
+
+test('existing ref objects pass through unchanged', async () => {
+  const checkpoint = await getCheckpoint();
+  const ref = { description: '[2026-01-01] some decision', ref: '.cairn/notes/note-old.md' };
+  checkpoint(null, { message: 'test', notes: [ref] });
+
+  const session = JSON.parse(fs.readFileSync(path.join(tmpDir, '.cairn', 'session.json'), 'utf8'));
+  assert.deepEqual(session.notes[0], ref);
+});
+
+test('session.json is rotated when it exceeds 100KB', async () => {
+  const checkpoint = await getCheckpoint();
+  const cairnDir = path.join(tmpDir, '.cairn');
+  const sessionPath = path.join(cairnDir, 'session.json');
+
+  // Write a fake oversized session.json (> 100KB)
+  fs.writeFileSync(sessionPath, JSON.stringify({ message: 'old', notes: [], active_files: [], mtime_snapshot: {}, checkpoint_at: '' }) + ' '.repeat(102 * 1024), 'utf8');
+
+  checkpoint(null, { message: 'new', notes: [] });
+
+  assert.ok(fs.existsSync(path.join(cairnDir, 'session.1.json')), 'old session should be rotated to session.1.json');
+  const current = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+  assert.equal(current.message, 'new');
+});
+
+test('old-format plain string notes longer than limit are migrated to refs on next checkpoint', async () => {
+  const checkpoint = await getCheckpoint();
+  const cairnDir = path.join(tmpDir, '.cairn');
+
+  // Simulate an old session.json with a long plain-string note (e.g. git-snapshot)
+  const oldNote = '[2026-04-11] git-snapshot: ' + 'M src/foo.js\n'.repeat(80);
+  fs.writeFileSync(
+    path.join(cairnDir, 'session.json'),
+    JSON.stringify({ message: 'old', notes: [oldNote], active_files: [], mtime_snapshot: {}, checkpoint_at: '' }),
+    'utf8'
+  );
+
+  // Pass the old notes through checkpoint (as would happen on next explicit checkpoint)
+  checkpoint(null, { message: 'migrated', notes: [oldNote] });
+
+  const session = JSON.parse(fs.readFileSync(path.join(cairnDir, 'session.json'), 'utf8'));
+  const note = session.notes[0];
+  assert.ok(note && typeof note === 'object' && note.ref, 'old long note should be migrated to a ref');
+});

package/test/relocate.test.js

@@ -1,4 +1,5 @@
 import { strict as assert } from 'node:assert';
+import { DatabaseSync } from 'node:sqlite';
 import { test, beforeEach, afterEach } from 'node:test';
 import fs from 'fs';
 import path from 'path';
@@ -138,6 +139,38 @@ test('repairRelocation rewrites session.json paths', () => {
   assert.ok(Object.keys(saved.mtime_snapshot).every(k => k.startsWith(newRoot)));
 });
 
+test('repairRelocation rewrites symbols.fqn and todos.file in DB', () => {
+  const cairnDir = path.join(dstDir, '.cairn');
+  fs.mkdirSync(cairnDir, { recursive: true });
+
+  const db = new DatabaseSync(':memory:');
+  db.prepare(`CREATE TABLE files (id INTEGER PRIMARY KEY, path TEXT UNIQUE)`).run();
+  db.prepare(`CREATE TABLE symbols (id INTEGER PRIMARY KEY, file_id INTEGER, fqn TEXT)`).run();
+  db.prepare(`CREATE TABLE todos (id INTEGER PRIMARY KEY, file TEXT)`).run();
+
+  const oldRoot = srcDir.replace(/\\/g, '/');
+  const newRoot = dstDir.replace(/\\/g, '/');
+
+  db.prepare('INSERT INTO files (path) VALUES (?)').run(`${oldRoot}/src/a.js`);
+  const fileId = db.prepare('SELECT id FROM files WHERE path = ?').get(`${oldRoot}/src/a.js`).id;
+  db.prepare('INSERT INTO symbols (file_id, fqn) VALUES (?, ?)').run(fileId, `${oldRoot}/src/a.js:MyClass`);
+  db.prepare('INSERT INTO todos (file) VALUES (?)').run(`${oldRoot}/README.md`);
+
+  const session = { message: 'x', checkpoint_at: '', active_files: [], mtime_snapshot: {} };
+  fs.writeFileSync(path.join(cairnDir, 'session.json'), JSON.stringify(session), 'utf8');
+
+  repairRelocation(db, cairnDir, session, {}, oldRoot, newRoot);
+
+  const file = db.prepare('SELECT path FROM files').get();
+  assert.ok(file.path.startsWith(newRoot), `files.path not updated: ${file.path}`);
+
+  const sym = db.prepare('SELECT fqn FROM symbols').get();
+  assert.ok(sym.fqn.startsWith(newRoot), `symbols.fqn not updated: ${sym.fqn}`);
+
+  const todo = db.prepare('SELECT file FROM todos').get();
+  assert.ok(todo.file.startsWith(newRoot), `todos.file not updated: ${todo.file}`);
+});
+
 test('repairRelocation rewrites minify map keys and tempPaths', () => {
   const cairnDir = path.join(dstDir, '.cairn');
   fs.mkdirSync(cairnDir, { recursive: true });

package/test/resume-migration.test.js

@@ -0,0 +1,83 @@
+import { strict as assert } from 'node:assert';
+import { test, beforeEach, afterEach } from 'node:test';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Test the git-snapshot migration logic in isolation by replicating the exact
+// block from resume.js against a real session.json on disk.
+function runMigration(cairnDir) {
+  const sessionPath = path.join(cairnDir, 'session.json');
+  const session = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+  if (!Array.isArray(session.notes)) session.notes = [];
+
+  const gitSnapshotNotes = session.notes.filter(n => typeof n === 'string' && n.includes('git-snapshot:'));
+  if (gitSnapshotNotes.length > 0) {
+    const bakPath = path.join(cairnDir, 'session.bak.json');
+    if (!fs.existsSync(bakPath)) fs.copyFileSync(sessionPath, bakPath);
+    session.notes = session.notes.filter(n => !(typeof n === 'string' && n.includes('git-snapshot:')));
+    fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf8');
+  }
+  return gitSnapshotNotes.length;
+}
+
+let tmpDir;
+beforeEach(() => { tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cairn-resume-mig-')); });
+afterEach(() => { fs.rmSync(tmpDir, { recursive: true, force: true }); });
+
+test('migration strips git-snapshot notes and backs up session.json', () => {
+  const cairnDir = path.join(tmpDir, '.cairn');
+  fs.mkdirSync(cairnDir, { recursive: true });
+
+  const realNote = '[2026-04-11] billing: 1000 credits = $1';
+  const gitNote  = '[2026-04-11] git-snapshot: M src/foo.js | status: M src/foo.js';
+  fs.writeFileSync(path.join(cairnDir, 'session.json'), JSON.stringify({
+    message: 'old', checkpoint_at: '', active_files: [], mtime_snapshot: {},
+    notes: [realNote, gitNote, gitNote],
+  }), 'utf8');
+
+  const removed = runMigration(cairnDir);
+
+  assert.equal(removed, 2, 'should detect 2 git-snapshot notes');
+
+  const session = JSON.parse(fs.readFileSync(path.join(cairnDir, 'session.json'), 'utf8'));
+  assert.deepEqual(session.notes, [realNote], 'only the real note should remain');
+
+  assert.ok(fs.existsSync(path.join(cairnDir, 'session.bak.json')), 'session.bak.json should be created');
+  const bak = JSON.parse(fs.readFileSync(path.join(cairnDir, 'session.bak.json'), 'utf8'));
+  assert.equal(bak.notes.length, 3, 'backup should contain all original notes');
+});
+
+test('migration does not overwrite an existing session.bak.json', () => {
+  const cairnDir = path.join(tmpDir, '.cairn');
+  fs.mkdirSync(cairnDir, { recursive: true });
+
+  const original = { message: 'original-backup', notes: [], active_files: [], mtime_snapshot: {}, checkpoint_at: '' };
+  fs.writeFileSync(path.join(cairnDir, 'session.bak.json'), JSON.stringify(original), 'utf8');
+  fs.writeFileSync(path.join(cairnDir, 'session.json'), JSON.stringify({
+    message: 'second-run', checkpoint_at: '', active_files: [], mtime_snapshot: {},
+    notes: ['[2026-04-12] git-snapshot: M x.js'],
+  }), 'utf8');
+
+  runMigration(cairnDir);
+
+  const bak = JSON.parse(fs.readFileSync(path.join(cairnDir, 'session.bak.json'), 'utf8'));
+  assert.equal(bak.message, 'original-backup', 'existing backup should not be overwritten');
+});
+
+test('migration is a no-op when no git-snapshot notes are present', () => {
+  const cairnDir = path.join(tmpDir, '.cairn');
+  fs.mkdirSync(cairnDir, { recursive: true });
+
+  const notes = ['[2026-04-11] clean note'];
+  fs.writeFileSync(path.join(cairnDir, 'session.json'), JSON.stringify({
+    message: 'clean', checkpoint_at: '', active_files: [], mtime_snapshot: {}, notes,
+  }), 'utf8');
+
+  const removed = runMigration(cairnDir);
+
+  assert.equal(removed, 0);
+  assert.ok(!fs.existsSync(path.join(cairnDir, 'session.bak.json')), 'no backup should be created');
+  const session = JSON.parse(fs.readFileSync(path.join(cairnDir, 'session.json'), 'utf8'));
+  assert.deepEqual(session.notes, notes, 'notes should be unchanged');
+});