@misterhuydo/cairn-mcp 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,263 @@
+# Cairn MCP
+
+> Persistent polyglot knowledge graph for Claude Code. Index once, query forever.
+
+Claude is stateless — every session starts at zero. On a multi-repo codebase with Java backends, TypeScript frontends, and Vue components, that means 50% of every session is archaeology: finding where things live before any real work can begin.
+
+**Cairn fixes this.** It indexes your project into a local SQLite knowledge graph (stored in `.cairn/`) and exposes 8 MCP tools that give Claude instant, persistent memory across sessions.
+
+---
+
+## Install
+
+```bash
+npm install -g @misterhuydo/cairn-mcp
+```
+
+**Requirements:** Node.js >= 22.15.0
+
+---
+
+## Setup
+
+Add to `~/.claude/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code. Done.
+
+---
+
+## How it works
+
+Cairn works like git — it looks for `.cairn/` in your current working directory. Run Claude Code from your project root and Cairn automatically stores the index at `.cairn/index.db` and bundles at `.cairn/bundles/`.
+
+No root paths needed. No global config. Just `cd` to your project and go.
+
+---
+
+## Tools
+
+### `cairn_maintain` — Index your project
+Run once at the start of each session. The index persists in `.cairn/index.db`.
+
+```
+cairn_maintain()
+cairn_maintain({ languages: ["typescript", "vue"] })  // limit to specific languages
+```
+
+```json
+{
+  "repos_indexed": 1,
+  "files_by_language": { "java": 412, "typescript": 287, "vue": 94 },
+  "symbols_total": 6841,
+  "security_findings": 47,
+  "duration_ms": 4200
+}
+```
+
+---
+
+### `cairn_search` — Find anything across all languages
+```
+cairn_search({ query: "user authentication", language: "typescript" })
+```
+
+```json
+[
+  { "lang": "typescript", "kind": "function",  "fqn": "src/composables/useAuth.ts::useAuth" },
+  { "lang": "vue",        "kind": "component", "fqn": "src/components/LoginForm.vue::LoginForm" },
+  { "lang": "java",       "kind": "class",     "fqn": "com.example.auth.UserAuthenticator" }
+]
+```
+
+---
+
+### `cairn_bundle` — Minified source snapshot for Claude to read
+Strips comments and empty lines, writes a compressed `### File:` bundle. Use after `cairn_search` to give Claude readable source without blowing the context window.
+
+```
+cairn_bundle({ filter_paths: ["src/components/checkout"], bundle_name: "checkout" })
+```
+
+```json
+{
+  "bundle_path": "/your/project/.cairn/bundles/checkout.txt",
+  "original_kb": 284,
+  "compressed_kb": 91,
+  "reduction_pct": 68
+}
+```
+
+---
+
+### `cairn_describe` — Summarize a module
+```
+cairn_describe({ path: "src/components/checkout" })
+```
+
+```json
+{
+  "languages": ["vue", "typescript"],
+  "symbols": {
+    "component": ["CheckoutForm", "OrderSummary", "PaymentStep"],
+    "function":  ["useCheckout", "usePayment"]
+  },
+  "imports_from":  ["src/store/cart.ts", "src/api/orders.ts"],
+  "imported_by":   ["src/views/CartView.vue"],
+  "external_deps": ["stripe", "@stripe/stripe-js"]
+}
+```
+
+---
+
+### `cairn_code_graph` — Dependency health
+```
+cairn_code_graph({ mode: "instability" })
+```
+
+```json
+{
+  "modules": [
+    { "name": "src/views",       "instability": 1.0, "status": "safe_to_refactor" },
+    { "name": "src/composables", "instability": 0.4, "status": "review_before_change" },
+    { "name": "src/utils",       "instability": 0.1, "status": "load_bearing" }
+  ]
+}
+```
+
+Modes: `instability` · `health` · `cycles`
+
+---
+
+### `cairn_security` — Vulnerability scan
+```
+cairn_security({ severity: "HIGH" })
+```
+
+```json
+{
+  "total_findings": 12,
+  "by_language": { "typescript": 7, "java": 5 },
+  "findings": [
+    { "severity": "HIGH", "cwe": "CWE-79",  "file": "src/components/UserProfile.vue", "line": 84, "rule": "XSS via innerHTML" },
+    { "severity": "HIGH", "cwe": "CWE-611", "file": "backend/src/.../XmlParser.java",  "line": 47, "rule": "XXE" }
+  ]
+}
+```
+
+Covers: XSS · XXE · SQL injection · command injection · weak crypto · hardcoded secrets · open redirect · unsafe deserialization
+
+---
+
+### `cairn_checkpoint` — Save session state
+Tell Cairn what you were working on so the next session can pick up where you left off.
+
+```
+cairn_checkpoint({
+  message: "Added multi-currency to CheckoutForm, still need PaymentStep",
+  active_files: ["src/components/checkout/CheckoutForm.vue"],
+  notes: ["CurrencyService expects ISO 4217 codes, not symbols"]
+})
+```
+
+```json
+{
+  "saved": true,
+  "checkpoint_at": "2026-02-25T14:30:00Z",
+  "active_files_tracked": 1,
+  "notes_saved": 1
+}
+```
+
+---
+
+### `cairn_resume` — Restore session + smart re-index
+Call instead of `cairn_maintain` when resuming work. Detects which files changed and only re-indexes those.
+
+```
+cairn_resume()
+```
+
+```json
+{
+  "last_checkpoint": "2026-02-25T14:30:00Z",
+  "message": "Added multi-currency to CheckoutForm, still need PaymentStep",
+  "index_status": "incremental",
+  "files_reindexed": 2,
+  "files_unchanged": 845,
+  "changed_since_checkpoint": [
+    { "file": "src/components/checkout/PaymentStep.vue", "change": "modified" }
+  ],
+  "active_files": ["src/components/checkout/CheckoutForm.vue"],
+  "notes": ["CurrencyService expects ISO 4217 codes, not symbols"],
+  "resume_summary": "Last session you were adding multi-currency support..."
+}
+```
+
+---
+
+## Supported Languages
+
+| Language | What Cairn extracts |
+|---|---|
+| Java | packages, classes, interfaces, enums, records, methods |
+| TypeScript / JavaScript | classes, interfaces, functions, types, enums |
+| Vue | components, composables, script block symbols |
+| Python | classes, functions, decorators |
+| SQL | tables, views, stored procedures |
+| XML / HTML | bean ids, component names |
+| Config (YAML, properties, .env) | top-level keys |
+| Markdown | headings |
+| Build files (pom.xml, package.json, build.gradle) | dependencies |
+
+---
+
+## Typical session
+
+**Fresh start:**
+```
+1. cairn_maintain     → index project (persists between sessions)
+2. cairn_search       → find the symbols you need
+3. cairn_bundle       → get a readable snapshot of relevant files
+4. cairn_describe     → understand a module before modifying it
+5. cairn_security     → check for issues before a PR
+6. cairn_checkpoint   → save what you were working on
+```
+
+**Resuming work:**
+```
+1. cairn_resume       → restore session + incremental re-index
+2. cairn_search       → continue where you left off
+```
+
+---
+
+## Custom DB path
+
+By default the index is stored at `.cairn/index.db` in your project directory. Override with an env variable:
+
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn-mcp",
+      "env": { "CAIRN_DB_PATH": "/your/custom/path/index.db" }
+    }
+  }
+}
+```
+
+---
+
+## License
+
+MIT

package/index.js

@@ -2,13 +2,15 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 
-import { openDB }    from './src/graph/db.js';
-import { maintain }  from './src/tools/maintain.js';
-import { search }    from './src/tools/search.js';
-import { describe }  from './src/tools/describe.js';
-import { codeGraph } from './src/tools/codeGraph.js';
-import { security }  from './src/tools/security.js';
-import { bundle }    from './src/tools/bundle.js';
+import { openDB }       from './src/graph/db.js';
+import { maintain }     from './src/tools/maintain.js';
+import { search }       from './src/tools/search.js';
+import { describe }     from './src/tools/describe.js';
+import { codeGraph }    from './src/tools/codeGraph.js';
+import { security }     from './src/tools/security.js';
+import { bundle }       from './src/tools/bundle.js';
+import { checkpoint }   from './src/tools/checkpoint.js';
+import { resume }       from './src/tools/resume.js';
 
 const db = openDB();
 
@@ -21,20 +23,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: 'cairn_maintain',
-      description: 'Index all repos into Cairn\'s polyglot knowledge graph. Supports Java, TypeScript, JavaScript, Vue, Python, SQL, config, and Markdown. Run at session start or after major changes.',
+      description: 'Index the current project into Cairn\'s polyglot knowledge graph. Supports Java, TypeScript, JavaScript, Vue, Python, SQL, config, and Markdown. Indexes from the current working directory. Run at session start or after major changes.',
       inputSchema: {
         type: 'object',
         properties: {
-          roots: {
-            type: 'array', items: { type: 'string' },
-            description: 'Absolute paths to repo roots to index',
-          },
           languages: {
             type: 'array', items: { type: 'string' },
             description: 'Optional: limit to specific languages e.g. ["java","typescript"]',
           },
         },
-        required: ['roots'],
       },
     },
     {
@@ -95,13 +92,9 @@ Typical workflow: cairn_search → find files → cairn_bundle those paths → C
       inputSchema: {
         type: 'object',
         properties: {
-          roots: {
-            type: 'array', items: { type: 'string' },
-            description: 'Repo roots to bundle',
-          },
           bundle_name: {
             type: 'string', default: 'default',
-            description: 'Name for the bundle file (saved to ~/.cairn/bundles/<name>.txt)',
+            description: 'Name for the bundle file (saved to .cairn/bundles/<name>.txt)',
           },
           filter_paths: {
             type: 'array', items: { type: 'string' },
@@ -118,7 +111,36 @@ Typical workflow: cairn_search → find files → cairn_bundle those paths → C
           only_changed:   { type: 'boolean', default: false, description: 'Incremental: only re-bundle files changed since last run' },
           max_size_kb:    { type: 'number',  default: 800,   description: 'Safety cap in KB to avoid context window overflow' },
         },
-        required: ['roots'],
+      },
+    },
+    {
+      name: 'cairn_checkpoint',
+      description: 'Save current session state to .cairn/session.json so it can be restored next session with cairn_resume.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          message: {
+            type: 'string',
+            description: 'What you were working on — will be shown on resume',
+          },
+          active_files: {
+            type: 'array', items: { type: 'string' },
+            description: 'Optional: absolute paths to files actively being worked on',
+          },
+          notes: {
+            type: 'array', items: { type: 'string' },
+            description: 'Optional: things Claude should remember next session',
+          },
+        },
+        required: ['message'],
+      },
+    },
+    {
+      name: 'cairn_resume',
+      description: 'Restore the last saved session state. Detects which files changed since the checkpoint and incrementally re-indexes only those files. Call at the start of a session instead of cairn_maintain when resuming work.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
       },
     },
   ],
@@ -127,12 +149,14 @@ Typical workflow: cairn_search → find files → cairn_bundle those paths → C
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   switch (name) {
-    case 'cairn_maintain':   return await maintain(db, args);
-    case 'cairn_search':     return search(db, args);
-    case 'cairn_describe':   return describe(db, args);
-    case 'cairn_code_graph': return codeGraph(db, args);
-    case 'cairn_security':   return security(db, args);
-    case 'cairn_bundle':     return await bundle(db, args);
+    case 'cairn_maintain':    return await maintain(db, args);
+    case 'cairn_search':      return search(db, args);
+    case 'cairn_describe':    return describe(db, args);
+    case 'cairn_code_graph':  return codeGraph(db, args);
+    case 'cairn_security':    return security(db, args);
+    case 'cairn_bundle':      return await bundle(db, args);
+    case 'cairn_checkpoint':  return checkpoint(db, args);
+    case 'cairn_resume':      return await resume(db);
     default: throw new Error(`Unknown tool: ${name}`);
   }
 });

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Persistent polyglot knowledge graph MCP server for Claude Code. Index once, query forever — across Java, TypeScript, Vue, Python, SQL and more.",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "cairn-mcp": "./bin/cairn-mcp.js"
+    "cairn-mcp": "bin/cairn-mcp.js"
   },
   "scripts": {
     "start": "node --experimental-sqlite index.js"

package/src/bundler/bundleWriter.js

@@ -1,13 +1,11 @@
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
 import { minifyContent } from './minifier.js';
 import { minifyVue }     from './vueMinifier.js';
 import { walkRepo, LANGUAGE_MAP } from '../indexer/fileWalker.js';
+import { getCairnDir } from '../graph/cwd.js';
 
-const BUNDLE_DIR = path.join(os.homedir(), '.cairn', 'bundles');
-
-export async function writeBundle(roots, options = {}) {
+export async function writeBundle(options = {}) {
   const {
     bundleName   = 'default',
     noComments   = true,
@@ -20,10 +18,11 @@ export async function writeBundle(roots, options = {}) {
     maxSizeKB    = 800,
   } = options;
 
-  fs.mkdirSync(BUNDLE_DIR, { recursive: true });
+  const bundleDir = path.join(getCairnDir(), 'bundles');
+  const root      = process.cwd();
 
-  const outPath    = path.join(BUNDLE_DIR, `${bundleName}.txt`);
-  const mtimePath  = path.join(BUNDLE_DIR, `${bundleName}.mtime.json`);
+  const outPath    = path.join(bundleDir, `${bundleName}.txt`);
+  const mtimePath  = path.join(bundleDir, `${bundleName}.mtime.json`);
   const mtimeCache = onlyChanged && fs.existsSync(mtimePath)
     ? JSON.parse(fs.readFileSync(mtimePath, 'utf8')) : {};
 
@@ -37,60 +36,58 @@ export async function writeBundle(roots, options = {}) {
   const langFilter = filterLang
     ? (Array.isArray(filterLang) ? filterLang : [filterLang]) : null;
 
-  for (const root of roots) {
-    const files = await walkRepo(root);
-
-    for (const filePath of files) {
-      const ext      = path.extname(filePath).toLowerCase();
-      const language = LANGUAGE_MAP[ext];
-      if (!language) continue;
-      if (langFilter && !langFilter.includes(language)) continue;
-
-      // Path filter — match against relative path from repo root
-      if (filterPaths) {
-        const rel = path.relative(root, filePath).replace(/\\/g, '/');
-        if (!filterPaths.some(p => rel.startsWith(p))) continue;
-      }
-
-      // Incremental: skip files unchanged since last bundle
-      const mtime = fs.statSync(filePath).mtimeMs;
-      newMtimes[filePath] = mtime;
-      if (onlyChanged && mtimeCache[filePath] === mtime) {
-        stats.skipped_unchanged++;
-        continue;
-      }
-
-      // Size cap — check current accumulated size before adding more
-      const currentKB = Buffer.byteLength(lines.join('\n'), 'utf8') / 1024;
-      if (currentKB > maxSizeKB) {
-        stats.skipped_size++;
-        continue;
-      }
-
-      let raw;
-      try {
-        raw = fs.readFileSync(filePath, 'utf8');
-      } catch {
-        continue;
-      }
-      stats.original_bytes += Buffer.byteLength(raw, 'utf8');
-
-      // Minify
-      const minified = language === 'vue'
-        ? minifyVue(raw, { noStyle, noComments, noEmptyLines, aggressive })
-        : minifyContent(raw, language, { noComments, noEmptyLines, aggressive });
-
-      if (!minified.trim()) continue;
-
-      const rel = path.relative(process.cwd(), filePath).replace(/\\/g, '/');
-      lines.push(`### File: ${rel}`);
-      lines.push(minified.trim());
-      lines.push('');
-
-      stats.compressed_bytes += Buffer.byteLength(minified, 'utf8');
-      stats.processed++;
-      stats.by_language[language] = (stats.by_language[language] || 0) + 1;
+  const files = await walkRepo(root);
+
+  for (const filePath of files) {
+    const ext      = path.extname(filePath).toLowerCase();
+    const language = LANGUAGE_MAP[ext];
+    if (!language) continue;
+    if (langFilter && !langFilter.includes(language)) continue;
+
+    // Path filter — match against relative path from cwd
+    if (filterPaths) {
+      const rel = path.relative(root, filePath).replace(/\\/g, '/');
+      if (!filterPaths.some(p => rel.startsWith(p))) continue;
+    }
+
+    // Incremental: skip files unchanged since last bundle
+    const mtime = fs.statSync(filePath).mtimeMs;
+    newMtimes[filePath] = mtime;
+    if (onlyChanged && mtimeCache[filePath] === mtime) {
+      stats.skipped_unchanged++;
+      continue;
+    }
+
+    // Size cap — check current accumulated size before adding more
+    const currentKB = Buffer.byteLength(lines.join('\n'), 'utf8') / 1024;
+    if (currentKB > maxSizeKB) {
+      stats.skipped_size++;
+      continue;
     }
+
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    stats.original_bytes += Buffer.byteLength(raw, 'utf8');
+
+    // Minify
+    const minified = language === 'vue'
+      ? minifyVue(raw, { noStyle, noComments, noEmptyLines, aggressive })
+      : minifyContent(raw, language, { noComments, noEmptyLines, aggressive });
+
+    if (!minified.trim()) continue;
+
+    const rel = path.relative(root, filePath).replace(/\\/g, '/');
+    lines.push(`### File: ${rel}`);
+    lines.push(minified.trim());
+    lines.push('');
+
+    stats.compressed_bytes += Buffer.byteLength(minified, 'utf8');
+    stats.processed++;
+    stats.by_language[language] = (stats.by_language[language] || 0) + 1;
   }
 
   const output = lines.join('\n');

package/src/graph/cwd.js

@@ -0,0 +1,8 @@
+import fs from 'fs';
+import path from 'path';
+
+export function getCairnDir() {
+  const cairnDir = path.join(process.cwd(), '.cairn');
+  fs.mkdirSync(path.join(cairnDir, 'bundles'), { recursive: true });
+  return cairnDir;
+}

package/src/graph/db.js

@@ -1,9 +1,12 @@
 import { DatabaseSync } from 'node:sqlite';
 import path from 'path';
-import os from 'os';
 import fs from 'fs';
+import { getCairnDir } from './cwd.js';
 
-const DB_PATH = process.env.CAIRN_DB_PATH || path.join(os.homedir(), '.cairn', 'index.db');
+function getDbPath() {
+  if (process.env.CAIRN_DB_PATH) return process.env.CAIRN_DB_PATH;
+  return path.join(getCairnDir(), 'index.db');
+}
 
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS files (
@@ -58,10 +61,11 @@ const SCHEMA = `
 `;
 
 export function openDB() {
-  const dir = path.dirname(DB_PATH);
+  const dbPath = getDbPath();
+  const dir = path.dirname(dbPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
-  const db = new DatabaseSync(DB_PATH);
+  const db = new DatabaseSync(dbPath);
   db.exec('PRAGMA journal_mode = WAL');
   db.exec('PRAGMA synchronous = NORMAL');
   db.exec(SCHEMA);

package/src/tools/bundle.js

@@ -2,7 +2,6 @@ import { writeBundle } from '../bundler/bundleWriter.js';
 
 export async function bundle(_db, args) {
   const {
-    roots,
     bundle_name      = 'default',
     filter_paths     = null,
     filter_language  = null,
@@ -14,7 +13,7 @@ export async function bundle(_db, args) {
     max_size_kb      = 800,
   } = args;
 
-  const result = await writeBundle(roots, {
+  const result = await writeBundle({
     bundleName:   bundle_name,
     noComments:   no_comments,
     noEmptyLines: no_empty_lines,

package/src/tools/checkpoint.js

@@ -0,0 +1,40 @@
+import fs from 'fs';
+import path from 'path';
+import { getCairnDir } from '../graph/cwd.js';
+
+export function checkpoint(_db, { message, active_files = [], 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,
+    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),
+    }],
+  };
+}

package/src/tools/maintain.js

@@ -18,86 +18,108 @@ function inferFileType(filePath) {
   return 'source';
 }
 
-export async function maintain(db, { roots, languages }) {
-  const startTime = Date.now();
-  const stats = {
-    repos_indexed: 0,
-    files_by_language: {},
-    symbols_total: 0,
-    dependencies_mapped: 0,
-    security_findings: 0,
-  };
+async function indexFile(db, filePath, repoName, languages, stats) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const result = await parseFile(filePath, content, repoName);
+    if (!result) return;
+
+    const { language } = result;
+    if (languages && !languages.includes(language)) return;
+
+    stats.files_by_language[language] = (stats.files_by_language[language] || 0) + 1;
+
+    const fileId = upsertFile(db, {
+      repo: repoName,
+      path: filePath,
+      language,
+      file_type: inferFileType(filePath),
+    });
 
-  for (const root of roots) {
-    const repoName = path.basename(root);
-    stats.repos_indexed++;
-
-    // Index source files
-    const files = await walkRepo(root);
-    for (const filePath of files) {
-      try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        const result = await parseFile(filePath, content, repoName);
-        if (!result) continue;
-
-        const { language } = result;
-        if (languages && !languages.includes(language)) continue;
-
-        stats.files_by_language[language] = (stats.files_by_language[language] || 0) + 1;
-
-        const fileId = upsertFile(db, {
-          repo: repoName,
-          path: filePath,
-          language,
-          file_type: inferFileType(filePath),
-        });
-
-        clearFileData(db, fileId);
-
-        for (const sym of (result.symbols || [])) {
-          upsertSymbol(db, { ...sym, file_id: fileId, language });
-          stats.symbols_total++;
-        }
-
-        for (const imp of (result.imports || [])) {
-          insertDependency(db, { from_file_id: fileId, to_fqn: imp, dep_type: 'imports' });
-          stats.dependencies_mapped++;
-        }
-
-        const findings = scanFile(filePath, content, language);
-        for (const f of findings) {
-          insertSecurityFinding(db, { file_id: fileId, ...f });
-          stats.security_findings++;
-        }
-      } catch {
-        // Skip unreadable/unparseable files
-      }
+    clearFileData(db, fileId);
+
+    for (const sym of (result.symbols || [])) {
+      upsertSymbol(db, { ...sym, file_id: fileId, language });
+      stats.symbols_total++;
+    }
+
+    for (const imp of (result.imports || [])) {
+      insertDependency(db, { from_file_id: fileId, to_fqn: imp, dep_type: 'imports' });
+      stats.dependencies_mapped++;
     }
 
-    // Index build files
-    for (const buildFile of BUILD_FILES) {
-      const buildPath = path.join(root, buildFile);
-      try {
-        const content = await fs.readFile(buildPath, 'utf-8');
-        let deps = [];
-        if (buildFile === 'pom.xml')       deps = parseMaven(buildPath, content, repoName);
-        else if (buildFile === 'package.json') deps = parseNpm(buildPath, content, repoName);
-        else if (buildFile === 'build.gradle') deps = parseGradle(buildPath, content, repoName);
-        for (const dep of deps) insertBuildDep(db, { repo: repoName, ...dep });
-      } catch {
-        // Build file not present or unreadable
-      }
+    const findings = scanFile(filePath, content, language);
+    for (const f of findings) {
+      insertSecurityFinding(db, { file_id: fileId, ...f });
+      stats.security_findings++;
     }
+  } catch {
+    // Skip unreadable/unparseable files
   }
+}
 
-  // Rebuild FTS5 index
+function rebuildFts(db) {
   db.exec(`
     DELETE FROM fts_index;
     INSERT INTO fts_index(fqn, name, description, path, repo, language, kind)
     SELECT s.fqn, s.name, COALESCE(s.description,''), f.path, f.repo, s.language, s.kind
     FROM symbols s JOIN files f ON s.file_id = f.id;
   `);
+}
+
+export async function maintain(db, { languages } = {}) {
+  const startTime = Date.now();
+  const root = process.cwd();
+  const repoName = path.basename(root);
+  const stats = {
+    repos_indexed: 1,
+    files_by_language: {},
+    symbols_total: 0,
+    dependencies_mapped: 0,
+    security_findings: 0,
+  };
+
+  const files = await walkRepo(root);
+  for (const filePath of files) {
+    await indexFile(db, filePath, repoName, languages, stats);
+  }
+
+  // Index build files
+  for (const buildFile of BUILD_FILES) {
+    const buildPath = path.join(root, buildFile);
+    try {
+      const content = await fs.readFile(buildPath, 'utf-8');
+      let deps = [];
+      if (buildFile === 'pom.xml')           deps = parseMaven(buildPath, content, repoName);
+      else if (buildFile === 'package.json') deps = parseNpm(buildPath, content, repoName);
+      else if (buildFile === 'build.gradle') deps = parseGradle(buildPath, content, repoName);
+      for (const dep of deps) insertBuildDep(db, { repo: repoName, ...dep });
+    } catch {
+      // Build file not present or unreadable
+    }
+  }
+
+  rebuildFts(db);
 
   stats.duration_ms = Date.now() - startTime;
   return { content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }] };
 }
+
+// Incremental re-index: only process a specific list of changed file paths
+export async function incrementalMaintain(db, changedFiles) {
+  const root = process.cwd();
+  const repoName = path.basename(root);
+  const stats = {
+    files_by_language: {},
+    symbols_total: 0,
+    dependencies_mapped: 0,
+    security_findings: 0,
+  };
+
+  for (const filePath of changedFiles) {
+    await indexFile(db, filePath, repoName, null, stats);
+  }
+
+  rebuildFts(db);
+  return stats;
+}

package/src/tools/resume.js

@@ -0,0 +1,91 @@
+import fs from 'fs';
+import path from 'path';
+import { getCairnDir } from '../graph/cwd.js';
+import { walkRepo } from '../indexer/fileWalker.js';
+import { incrementalMaintain } from './maintain.js';
+
+export async function resume(db) {
+  const cairnDir = getCairnDir();
+  const sessionPath = path.join(cairnDir, 'session.json');
+
+  if (!fs.existsSync(sessionPath)) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'No checkpoint found. Run cairn_maintain to index the project, then cairn_checkpoint to save session state.',
+        }, null, 2),
+      }],
+    };
+  }
+
+  const session = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+  const snapshot = session.mtime_snapshot || {};
+
+  // Detect changed files by comparing current mtimes to snapshot
+  const changed = [];
+  for (const [filePath, savedMtime] of Object.entries(snapshot)) {
+    try {
+      const currentMtime = fs.statSync(filePath).mtimeMs;
+      if (currentMtime !== savedMtime) {
+        changed.push({ file: filePath, change: 'modified' });
+      }
+    } catch {
+      changed.push({ file: filePath, change: 'deleted' });
+    }
+  }
+
+  // Detect new files: walk cwd and find files not in the snapshot
+  try {
+    const allFiles = await walkRepo(process.cwd());
+    for (const filePath of allFiles) {
+      if (!(filePath in snapshot)) {
+        changed.push({ file: filePath, change: 'new' });
+      }
+    }
+  } catch {
+    // Walk may fail on some systems; proceed without new-file detection
+  }
+
+  // Incremental re-index only changed/new files
+  const filesToReindex = changed
+    .filter(c => c.change !== 'deleted')
+    .map(c => c.file);
+
+  let reindexStats = { files_reindexed: 0, files_unchanged: 0 };
+  if (filesToReindex.length > 0) {
+    const stats = await incrementalMaintain(db, filesToReindex);
+    reindexStats.files_reindexed = filesToReindex.length;
+  }
+
+  // Count unchanged files from snapshot
+  reindexStats.files_unchanged = Object.keys(snapshot).length - changed.filter(c => c.change !== 'new').length;
+
+  // Build human-readable resume summary
+  const changedSummary = changed.length > 0
+    ? changed.slice(0, 10).map(c => `${c.change}: ${path.relative(process.cwd(), c.file).replace(/\\/g, '/')}`).join(', ')
+    : 'none';
+
+  const resumeSummary = [
+    `Last session: ${session.message}`,
+    changed.length > 0 ? `Files changed since checkpoint: ${changedSummary}` : 'No files changed since checkpoint.',
+    session.notes?.length > 0 ? `Notes: ${session.notes.join(' | ')}` : '',
+  ].filter(Boolean).join(' ');
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        last_checkpoint: session.checkpoint_at,
+        message: session.message,
+        index_status: filesToReindex.length > 0 ? 'incremental' : 'up_to_date',
+        files_reindexed: reindexStats.files_reindexed,
+        files_unchanged: Math.max(0, reindexStats.files_unchanged),
+        changed_since_checkpoint: changed.slice(0, 20),
+        active_files: session.active_files || [],
+        notes: session.notes || [],
+        resume_summary: resumeSummary,
+      }, null, 2),
+    }],
+  };
+}