@tekmidian/pai 0.8.5 → 0.9.0

package/dist/{tools-BXSwlzeH.mjs → tools-C4SBZHga.mjs}

@@ -1,8 +1,10 @@
 import { t as __exportAll } from "./rolldown-runtime-95iHPtFO.mjs";
+import { t as STOP_WORDS } from "./stop-words-BaMEGVeY.mjs";
 import { i as searchMemoryHybrid, n as populateSlugs } from "./search-DC1qhkKn.mjs";
 import { r as formatDetectionJson, t as detectProject } from "./detect-CdaA48EI.mjs";
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, resolve } from "node:path";
 
 //#region src/mcp/tools/types.ts
 /**
@@ -906,6 +908,790 @@ async function toolZettelCommunities(backend, params) {
 	}
 }
 
+//#endregion
+//#region src/memory/kg.ts
+function rowToTriple(row) {
+	return {
+		id: row.id,
+		subject: row.subject,
+		predicate: row.predicate,
+		object: row.object,
+		project_id: row.project_id,
+		source_session: row.source_session,
+		valid_from: new Date(row.valid_from),
+		valid_to: row.valid_to ? new Date(row.valid_to) : void 0,
+		confidence: row.confidence,
+		created_at: new Date(row.created_at)
+	};
+}
+/**
+* Add a new triple to the knowledge graph.
+* Returns the inserted triple.
+*/
+async function kgAdd(pool, params) {
+	const confidence = params.confidence ?? "EXTRACTED";
+	return rowToTriple((await pool.query(`INSERT INTO kg_triples
+       (subject, predicate, object, project_id, source_session, confidence)
+     VALUES ($1, $2, $3, $4, $5, $6)
+     RETURNING *`, [
+		params.subject,
+		params.predicate,
+		params.object,
+		params.project_id ?? null,
+		params.source_session ?? null,
+		confidence
+	])).rows[0]);
+}
+/**
+* Query triples by subject, predicate, object, and/or project.
+* Supports point-in-time queries via as_of.
+* By default only returns currently-valid triples (valid_to IS NULL).
+*/
+async function kgQuery(pool, params) {
+	const conditions = [];
+	const values = [];
+	let idx = 1;
+	if (params.subject !== void 0) {
+		conditions.push(`subject = $${idx++}`);
+		values.push(params.subject);
+	}
+	if (params.predicate !== void 0) {
+		conditions.push(`predicate = $${idx++}`);
+		values.push(params.predicate);
+	}
+	if (params.object !== void 0) {
+		conditions.push(`object = $${idx++}`);
+		values.push(params.object);
+	}
+	if (params.project_id !== void 0) {
+		conditions.push(`project_id = $${idx++}`);
+		values.push(params.project_id);
+	}
+	if (params.as_of !== void 0) {
+		conditions.push(`valid_from <= $${idx++}`);
+		values.push(params.as_of);
+		conditions.push(`(valid_to IS NULL OR valid_to > $${idx++})`);
+		values.push(params.as_of);
+	} else if (!params.include_invalidated) conditions.push(`valid_to IS NULL`);
+	const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+	return (await pool.query(`SELECT * FROM kg_triples ${where} ORDER BY valid_from DESC`, values)).rows.map(rowToTriple);
+}
+/**
+* Invalidate a triple by setting valid_to = NOW().
+* Does not delete the row — preserves history.
+*/
+async function kgInvalidate(pool, tripleId) {
+	await pool.query(`UPDATE kg_triples SET valid_to = NOW() WHERE id = $1 AND valid_to IS NULL`, [tripleId]);
+}
+/**
+* Find contradictions: cases where the same (subject, predicate) pair has
+* multiple currently-valid objects.
+*/
+async function kgContradictions(pool, subject) {
+	return (await pool.query(`SELECT subject, predicate, array_agg(object ORDER BY object) AS objects
+     FROM kg_triples
+     WHERE subject = $1
+       AND valid_to IS NULL
+     GROUP BY subject, predicate
+     HAVING COUNT(*) > 1`, [subject])).rows.map((row) => ({
+		subject: row.subject,
+		predicate: row.predicate,
+		objects: row.objects
+	}));
+}
+
+//#endregion
+//#region src/mcp/tools/kg.ts
+async function toolKgAdd(pool, params) {
+	try {
+		if (!params.subject || !params.predicate || !params.object) return {
+			content: [{
+				type: "text",
+				text: "kg_add error: subject, predicate, and object are required"
+			}],
+			isError: true
+		};
+		const triple = await kgAdd(pool, params);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(triple, null, 2)
+		}] };
+	} catch (e) {
+		return {
+			content: [{
+				type: "text",
+				text: `kg_add error: ${String(e)}`
+			}],
+			isError: true
+		};
+	}
+}
+async function toolKgQuery(pool, params) {
+	try {
+		const asOf = params.as_of ? new Date(params.as_of) : void 0;
+		if (asOf && isNaN(asOf.getTime())) return {
+			content: [{
+				type: "text",
+				text: `kg_query error: invalid as_of date: ${params.as_of}`
+			}],
+			isError: true
+		};
+		const triples = await kgQuery(pool, {
+			subject: params.subject,
+			predicate: params.predicate,
+			object: params.object,
+			project_id: params.project_id,
+			as_of: asOf,
+			include_invalidated: params.include_invalidated
+		});
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(triples, null, 2)
+		}] };
+	} catch (e) {
+		return {
+			content: [{
+				type: "text",
+				text: `kg_query error: ${String(e)}`
+			}],
+			isError: true
+		};
+	}
+}
+async function toolKgInvalidate(pool, params) {
+	try {
+		if (params.triple_id === void 0 || params.triple_id === null) return {
+			content: [{
+				type: "text",
+				text: "kg_invalidate error: triple_id is required"
+			}],
+			isError: true
+		};
+		await kgInvalidate(pool, params.triple_id);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				invalidated: true,
+				triple_id: params.triple_id
+			})
+		}] };
+	} catch (e) {
+		return {
+			content: [{
+				type: "text",
+				text: `kg_invalidate error: ${String(e)}`
+			}],
+			isError: true
+		};
+	}
+}
+async function toolKgContradictions(pool, params) {
+	try {
+		if (!params.subject) return {
+			content: [{
+				type: "text",
+				text: "kg_contradictions error: subject is required"
+			}],
+			isError: true
+		};
+		const contradictions = await kgContradictions(pool, params.subject);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(contradictions, null, 2)
+		}] };
+	} catch (e) {
+		return {
+			content: [{
+				type: "text",
+				text: `kg_contradictions error: ${String(e)}`
+			}],
+			isError: true
+		};
+	}
+}
+
+//#endregion
+//#region src/memory/wakeup.ts
+/**
+* Wake-up context system — progressive context loading inspired by mempalace.
+*
+* Layers:
+*   L0 Identity     (~100 tokens)   — user identity from ~/.pai/identity.txt. Always loaded.
+*   L1 Essential Story (~500-800t)  — top session notes for the project, key lines extracted.
+*   L2 On-Demand                    — triggered by topic queries (handled by memory_search).
+*   L3 Deep Search                  — unlimited federated memory search (memory_search tool).
+*/
+/** Maximum tokens for the L1 essential story block. Approx 4 chars/token. */
+const L1_TOKEN_BUDGET = 800;
+L1_TOKEN_BUDGET * 4;
+/** Maximum session notes to scan when building L1. */
+const L1_MAX_NOTES = 10;
+/** Sections to extract from session notes (in priority order). */
+const EXTRACT_SECTIONS = [
+	"Work Done",
+	"Key Decisions",
+	"Next Steps",
+	"Checkpoint"
+];
+/** Identity file location. */
+const IDENTITY_FILE = join(homedir(), ".pai", "identity.txt");
+/**
+* Load L0 identity from ~/.pai/identity.txt.
+* Returns the file content, or an empty string if the file does not exist.
+* Never throws.
+*/
+function loadL0Identity() {
+	if (!existsSync(IDENTITY_FILE)) return "";
+	try {
+		return readFileSync(IDENTITY_FILE, "utf-8").trim();
+	} catch {
+		return "";
+	}
+}
+/**
+* Find the Notes directory for a project given its root_path from the registry.
+* Checks local Notes/ first, then central ~/.claude/projects/... path.
+*/
+function findNotesDirForProject(rootPath) {
+	const localCandidates = [
+		join(rootPath, "Notes"),
+		join(rootPath, "notes"),
+		join(rootPath, ".claude", "Notes")
+	];
+	for (const p of localCandidates) if (existsSync(p)) return p;
+	const encoded = rootPath.replace(/\//g, "-").replace(/\./g, "-").replace(/ /g, "-");
+	const centralNotes = join(homedir(), ".claude", "projects", encoded, "Notes");
+	if (existsSync(centralNotes)) return centralNotes;
+	return null;
+}
+/**
+* Recursively find all .md session note files in a Notes directory.
+* Handles both flat layout (Notes/*.md) and month-subdirectory layout
+* (Notes/YYYY/MM/*.md). Returns files sorted newest-first by filename
+* (note numbers are monotonically increasing, so lexicographic = newest-last,
+* so we reverse).
+*/
+function findSessionNotes(notesDir) {
+	const result = [];
+	const scanDir = (dir) => {
+		if (!existsSync(dir)) return;
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true }).map((e) => ({
+				name: e.name,
+				isDir: e.isDirectory()
+			}));
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const fullPath = join(dir, entry.name);
+			if (entry.isDir) scanDir(fullPath);
+			else if (entry.name.match(/^\d{3,4}[\s_-].*\.md$/)) result.push(fullPath);
+		}
+	};
+	scanDir(notesDir);
+	result.sort((a, b) => {
+		const numA = parseInt(basename(a).match(/^(\d+)/)?.[1] ?? "0", 10);
+		return parseInt(basename(b).match(/^(\d+)/)?.[1] ?? "0", 10) - numA;
+	});
+	return result;
+}
+/**
+* Extract the most important lines from a session note.
+* Prioritises: Work Done items, Key Decisions, Next Steps, Checkpoint headings.
+* Returns a condensed string under maxChars.
+*/
+function extractKeyLines(content, maxChars) {
+	const lines = content.split("\n");
+	const selected = [];
+	let inTargetSection = false;
+	let currentSection = "";
+	let charCount = 0;
+	for (const line of lines) {
+		const h2Match = line.match(/^## (.+)$/);
+		const h3Match = line.match(/^### (.+)$/);
+		if (h2Match) {
+			currentSection = h2Match[1];
+			inTargetSection = EXTRACT_SECTIONS.some((s) => currentSection.toLowerCase().includes(s.toLowerCase()));
+			continue;
+		}
+		if (h3Match) {
+			if (inTargetSection) {
+				const label = `[${h3Match[1]}]`;
+				if (charCount + label.length < maxChars) {
+					selected.push(label);
+					charCount += label.length + 1;
+				}
+			}
+			continue;
+		}
+		if (!inTargetSection) continue;
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("<!--") || trimmed === "---") continue;
+		if (trimmed.startsWith("- ") || trimmed.startsWith("* ") || trimmed.match(/^\d+\./) || trimmed.startsWith("**")) {
+			if (charCount + trimmed.length + 1 > maxChars) break;
+			selected.push(trimmed);
+			charCount += trimmed.length + 1;
+		}
+	}
+	return selected.join("\n");
+}
+/**
+* Build the L1 essential story block.
+*
+* Reads the most recent session notes for the project and extracts the key
+* lines (Work Done, Key Decisions, Next Steps) within the token budget.
+*
+* @param rootPath   The project root path (from the registry).
+* @param tokenBudget  Max tokens to consume. Default 800 (~3200 chars).
+* @returns Formatted L1 block, or empty string if no notes found.
+*/
+function buildL1EssentialStory(rootPath, tokenBudget = L1_TOKEN_BUDGET) {
+	const charBudget = tokenBudget * 4;
+	const notesDir = findNotesDirForProject(rootPath);
+	if (!notesDir) return "";
+	const noteFiles = findSessionNotes(notesDir).slice(0, L1_MAX_NOTES);
+	if (noteFiles.length === 0) return "";
+	const sections = [];
+	let remaining = charBudget;
+	for (const noteFile of noteFiles) {
+		if (remaining <= 50) break;
+		let content;
+		try {
+			content = readFileSync(noteFile, "utf-8");
+		} catch {
+			continue;
+		}
+		const name = basename(noteFile);
+		const titleMatch = name.match(/^\d+ - (\d{4}-\d{2}-\d{2}) - (.+)\.md$/);
+		const dateLabel = titleMatch ? titleMatch[1] : "";
+		const titleLabel = titleMatch ? titleMatch[2] : name.replace(/^\d+ - /, "").replace(/\.md$/, "");
+		const perNoteChars = Math.min(remaining, Math.floor(charBudget / noteFiles.length) + 200);
+		const extracted = extractKeyLines(content, perNoteChars);
+		if (!extracted) continue;
+		const noteBlock = `[${dateLabel} - ${titleLabel}]\n${extracted}`;
+		sections.push(noteBlock);
+		remaining -= noteBlock.length + 1;
+	}
+	if (sections.length === 0) return "";
+	return sections.join("\n\n");
+}
+/**
+* Build the combined wake-up context block (L0 + L1).
+*
+* Returns a formatted string suitable for injection as a system-reminder,
+* or an empty string if both layers are empty.
+*
+* @param rootPath   Project root path for L1 note lookup. Optional.
+* @param tokenBudget  L1 token budget. Default 800.
+*/
+function buildWakeupContext(rootPath, tokenBudget = L1_TOKEN_BUDGET) {
+	const identity = loadL0Identity();
+	const essentialStory = rootPath ? buildL1EssentialStory(rootPath, tokenBudget) : "";
+	if (!identity && !essentialStory) return "";
+	const parts = [];
+	if (identity) parts.push(`## L0 Identity\n\n${identity}`);
+	if (essentialStory) parts.push(`## L1 Essential Story\n\n${essentialStory}`);
+	return parts.join("\n\n");
+}
+
+//#endregion
+//#region src/mcp/tools/wakeup.ts
+const DEFAULT_TOKEN_BUDGET = 800;
+function toolMemoryWakeup(registryDb, params) {
+	try {
+		const tokenBudget = params.token_budget ?? DEFAULT_TOKEN_BUDGET;
+		let rootPath;
+		if (params.project) {
+			const bySlug = registryDb.prepare("SELECT root_path FROM projects WHERE slug = ?").get(params.project);
+			if (bySlug) rootPath = bySlug.root_path;
+			else {
+				const detected = detectProjectFromPath(registryDb, params.project);
+				if (detected) rootPath = detected.root_path;
+			}
+		} else {
+			const detected = detectProjectFromPath(registryDb, process.cwd());
+			if (detected) rootPath = detected.root_path;
+		}
+		const wakeupBlock = buildWakeupContext(rootPath, tokenBudget);
+		if (!wakeupBlock) return { content: [{
+			type: "text",
+			text: "No wake-up context available. Create ~/.pai/identity.txt for L0 identity, or ensure session notes exist for L1 story."
+		}] };
+		return { content: [{
+			type: "text",
+			text: `WAKEUP CONTEXT\n\n${wakeupBlock}`
+		}] };
+	} catch (e) {
+		return {
+			content: [{
+				type: "text",
+				text: `Wakeup context error: ${String(e)}`
+			}],
+			isError: true
+		};
+	}
+}
+
+//#endregion
+//#region src/memory/taxonomy.ts
+/**
+* Build a taxonomy of stored memory — what projects exist, how much is stored,
+* and what has been active recently.
+*
+* Registry queries (projects, sessions) are synchronous (better-sqlite3).
+* Storage backend queries (files, chunks) are async.
+*/
+async function getTaxonomy(registryDb, storage, options = {}) {
+	const includeArchived = options.include_archived ?? false;
+	const limit = options.limit ?? 50;
+	const statusFilter = includeArchived ? "status IN ('active', 'archived', 'migrating')" : "status = 'active'";
+	const projectRows = registryDb.prepare(`SELECT id, slug, display_name, status, created_at, updated_at
+       FROM projects
+       WHERE ${statusFilter}
+       ORDER BY updated_at DESC
+       LIMIT ?`).all(limit);
+	if (projectRows.length === 0) return {
+		projects: [],
+		totals: {
+			projects: 0,
+			sessions: 0,
+			notes: 0,
+			chunks: 0
+		},
+		recent_activity: []
+	};
+	const projectIds = projectRows.map((p) => p.id);
+	const sessionCountsByProject = /* @__PURE__ */ new Map();
+	const lastSessionDateByProject = /* @__PURE__ */ new Map();
+	for (const projectId of projectIds) {
+		const countRow = registryDb.prepare("SELECT COUNT(*) AS n FROM sessions WHERE project_id = ?").get(projectId);
+		sessionCountsByProject.set(projectId, countRow.n);
+		const lastRow = registryDb.prepare("SELECT date FROM sessions WHERE project_id = ? ORDER BY number DESC LIMIT 1").get(projectId);
+		lastSessionDateByProject.set(projectId, lastRow?.date ?? null);
+	}
+	const tagsByProject = /* @__PURE__ */ new Map();
+	for (const projectId of projectIds) {
+		const tags = registryDb.prepare(`SELECT t.name
+         FROM tags t
+         JOIN project_tags pt ON pt.tag_id = t.id
+         WHERE pt.project_id = ?
+         ORDER BY t.name`).all(projectId);
+		tagsByProject.set(projectId, tags.map((t) => t.name));
+	}
+	const noteCountsByProject = /* @__PURE__ */ new Map();
+	const chunkCountsByProject = /* @__PURE__ */ new Map();
+	const isBackend = (x) => x.backendType === "sqlite";
+	if (isBackend(storage)) {
+		const rawDb = storage.getRawDb?.();
+		if (rawDb) for (const projectId of projectIds) {
+			const noteRow = rawDb.prepare("SELECT COUNT(*) AS n FROM memory_files WHERE project_id = ?").get(projectId);
+			noteCountsByProject.set(projectId, noteRow.n);
+			const chunkRow = rawDb.prepare("SELECT COUNT(*) AS n FROM memory_chunks WHERE project_id = ?").get(projectId);
+			chunkCountsByProject.set(projectId, chunkRow.n);
+		}
+	} else for (const projectId of projectIds) {
+		noteCountsByProject.set(projectId, 0);
+		chunkCountsByProject.set(projectId, 0);
+	}
+	const stats = await storage.getStats();
+	const totalProjects = registryDb.prepare(`SELECT COUNT(*) AS n FROM projects WHERE ${statusFilter}`).get().n;
+	const totalSessions = registryDb.prepare("SELECT COUNT(*) AS n FROM sessions").get().n;
+	const recentActivity = registryDb.prepare(`SELECT s.date, s.title, p.slug
+       FROM sessions s
+       JOIN projects p ON p.id = s.project_id
+       WHERE p.${statusFilter.replace("status", "p.status")}
+       ORDER BY s.created_at DESC
+       LIMIT 10`).all().map((row) => ({
+		project_slug: row.slug,
+		action: `session: ${row.title || "(untitled)"}`,
+		timestamp: row.date
+	}));
+	return {
+		projects: projectRows.map((row) => ({
+			slug: row.slug,
+			display_name: row.display_name,
+			session_count: sessionCountsByProject.get(row.id) ?? 0,
+			note_count: noteCountsByProject.get(row.id) ?? 0,
+			last_activity: lastSessionDateByProject.get(row.id) ?? null,
+			top_tags: tagsByProject.get(row.id) ?? []
+		})),
+		totals: {
+			projects: totalProjects,
+			sessions: totalSessions,
+			notes: stats.files,
+			chunks: stats.chunks
+		},
+		recent_activity: recentActivity
+	};
+}
+
+//#endregion
+//#region src/mcp/tools/taxonomy.ts
+async function toolMemoryTaxonomy(registryDb, storage, params = {}) {
+	try {
+		const result = await getTaxonomy(registryDb, storage, {
+			include_archived: params.include_archived,
+			limit: params.limit
+		});
+		const lines = [];
+		lines.push(`PAI Memory Taxonomy — ${result.totals.projects} project(s), ${result.totals.sessions} session(s), ${result.totals.notes} indexed file(s), ${result.totals.chunks} chunk(s)`);
+		lines.push("");
+		if (result.projects.length === 0) lines.push("No active projects found.");
+		else {
+			lines.push("Projects:");
+			for (const p of result.projects) {
+				const tagStr = p.top_tags.length > 0 ? ` [${p.top_tags.join(", ")}]` : "";
+				const activityStr = p.last_activity ? ` last: ${p.last_activity}` : "";
+				lines.push(`  ${p.slug} — ${p.display_name}  sessions=${p.session_count}` + (p.note_count > 0 ? ` files=${p.note_count}` : "") + activityStr + tagStr);
+			}
+		}
+		if (result.recent_activity.length > 0) {
+			lines.push("");
+			lines.push("Recent activity (last 10 sessions across all projects):");
+			for (const a of result.recent_activity) lines.push(`  ${a.timestamp}  ${a.project_slug}  ${a.action}`);
+		}
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (e) {
+		return {
+			content: [{
+				type: "text",
+				text: `memory_taxonomy error: ${String(e)}`
+			}],
+			isError: true
+		};
+	}
+}
+
+//#endregion
+//#region src/memory/tunnels.ts
+/**
+* tunnels.ts — cross-project concept detection ("palace graph / tunnel detection")
+*
+* A "tunnel" is a concept (word or short phrase) that appears in chunks from
+* at least two distinct projects.  These serendipitous cross-project connections
+* are surfaced so the user can discover unexpected relationships between their
+* work streams.
+*
+* Algorithm:
+*  1. Pull the top-N most frequent significant terms from memory_chunks via BM25 FTS.
+*     We use the FTS5 vocab table (if available) or fall back to term frequency
+*     aggregation over the raw text via a trigram approach.
+*  2. For each candidate term, count how many distinct projects have at least one
+*     chunk containing it and aggregate occurrence stats.
+*  3. Filter by min_projects and min_occurrences, sort by project breadth then
+*     frequency, return top limit results.
+*
+* Backend support:
+*  - SQLite  — uses `memory_fts` MATCH to count per-project occurrences.
+*  - Postgres — uses `memory_chunks` tsvector + ts_stat for term extraction and
+*               per-project term frequency counting via plainto_tsquery.
+*/
+/**
+* Extract candidate terms from the SQLite FTS5 index using the vocabulary
+* approach: iterate the fts5vocab table (if it exists) for the most common
+* terms, then per-term count distinct projects.
+*/
+async function findTunnelsSqlite(db, slugMap, opts) {
+	const projectIds = Object.keys(slugMap).map(Number);
+	if (projectIds.length < 2) return {
+		tunnels: [],
+		projects_analyzed: projectIds.length,
+		total_concepts_evaluated: 0
+	};
+	let candidateTerms = [];
+	try {
+		candidateTerms = db.prepare(`SELECT term, SUM(doc) AS doc_count, SUM(cnt) AS total_cnt
+         FROM memory_fts_v
+         GROUP BY term
+         HAVING SUM(cnt) >= ?
+         ORDER BY SUM(doc) DESC
+         LIMIT 500`).all(opts.min_occurrences).map((r) => r.term).filter((t) => t.length >= 3 && !STOP_WORDS.has(t));
+	} catch {
+		const sampleRows = db.prepare(`SELECT LOWER(text) AS text FROM memory_chunks
+         WHERE LENGTH(text) > 20
+         ORDER BY RANDOM()
+         LIMIT 2000`).all();
+		const freq = /* @__PURE__ */ new Map();
+		for (const { text } of sampleRows) {
+			const tokens = text.split(/[\s\p{P}]+/u).filter(Boolean).filter((t) => t.length >= 3 && !STOP_WORDS.has(t));
+			for (const t of tokens) freq.set(t, (freq.get(t) ?? 0) + 1);
+		}
+		candidateTerms = [...freq.entries()].filter(([, n]) => n >= opts.min_occurrences).sort((a, b) => b[1] - a[1]).slice(0, 200).map(([t]) => t);
+	}
+	if (candidateTerms.length === 0) return {
+		tunnels: [],
+		projects_analyzed: projectIds.length,
+		total_concepts_evaluated: 0
+	};
+	const tunnels = [];
+	for (const term of candidateTerms) try {
+		const rows = db.prepare(`SELECT c.project_id, COUNT(*) AS cnt,
+                  MIN(c.updated_at) AS first_seen,
+                  MAX(c.updated_at) AS last_seen
+           FROM memory_fts f
+           JOIN memory_chunks c ON c.id = f.id
+           WHERE memory_fts MATCH ?
+             AND c.project_id IN (${projectIds.map(() => "?").join(", ")})
+           GROUP BY c.project_id`).all(`"${term.replace(/"/g, "\"\"")}"`, ...projectIds);
+		if (rows.length < opts.min_projects) continue;
+		const totalOccurrences = rows.reduce((s, r) => s + Number(r.cnt), 0);
+		if (totalOccurrences < opts.min_occurrences) continue;
+		const projects = rows.map((r) => slugMap[r.project_id] ?? String(r.project_id)).filter(Boolean);
+		const firstSeen = Math.min(...rows.map((r) => r.first_seen));
+		const lastSeen = Math.max(...rows.map((r) => r.last_seen));
+		tunnels.push({
+			concept: term,
+			projects,
+			occurrences: totalOccurrences,
+			first_seen: firstSeen,
+			last_seen: lastSeen
+		});
+	} catch {
+		continue;
+	}
+	tunnels.sort((a, b) => {
+		const byProjects = b.projects.length - a.projects.length;
+		if (byProjects !== 0) return byProjects;
+		return b.occurrences - a.occurrences;
+	});
+	return {
+		tunnels: tunnels.slice(0, opts.limit),
+		projects_analyzed: projectIds.length,
+		total_concepts_evaluated: candidateTerms.length
+	};
+}
+/**
+* Use Postgres ts_stat() + plainto_tsquery to efficiently find terms that
+* appear across multiple projects.
+*/
+async function findTunnelsPostgres(pool, slugMap, opts) {
+	const projectIds = Object.keys(slugMap).map(Number);
+	if (projectIds.length < 2) return {
+		tunnels: [],
+		projects_analyzed: projectIds.length,
+		total_concepts_evaluated: 0
+	};
+	let candidateTerms = (await pool.query(`SELECT word, ndoc, nentry
+     FROM ts_stat(
+       'SELECT to_tsvector(''simple'', text) FROM memory_chunks WHERE project_id = ANY($1)'
+     )
+     WHERE length(word) >= 3
+       AND nentry >= $2
+     ORDER BY ndoc DESC
+     LIMIT 500`, [projectIds, opts.min_occurrences])).rows.map((r) => r.word).filter((t) => !STOP_WORDS.has(t));
+	if (candidateTerms.length === 0) return {
+		tunnels: [],
+		projects_analyzed: projectIds.length,
+		total_concepts_evaluated: 0
+	};
+	candidateTerms = candidateTerms.slice(0, 200);
+	const valuesClause = candidateTerms.map((t, i) => `($${i + 2}::text)`).join(", ");
+	const batchResult = await pool.query(`SELECT v.concept, c.project_id::text, COUNT(*) AS cnt,
+            MIN(c.updated_at) AS first_seen,
+            MAX(c.updated_at) AS last_seen
+     FROM (VALUES ${valuesClause}) AS v(concept)
+     JOIN memory_chunks c
+       ON to_tsvector('simple', c.text) @@ plainto_tsquery('simple', v.concept)
+      AND c.project_id = ANY($1)
+     GROUP BY v.concept, c.project_id`, [projectIds, ...candidateTerms]);
+	const byConceptMap = /* @__PURE__ */ new Map();
+	for (const row of batchResult.rows) {
+		const existing = byConceptMap.get(row.concept) ?? {
+			projects: /* @__PURE__ */ new Set(),
+			occurrences: 0,
+			firstSeen: Infinity,
+			lastSeen: -Infinity
+		};
+		existing.projects.add(parseInt(row.project_id, 10));
+		existing.occurrences += parseInt(row.cnt, 10);
+		const fs = parseInt(row.first_seen, 10);
+		const ls = parseInt(row.last_seen, 10);
+		if (fs < existing.firstSeen) existing.firstSeen = fs;
+		if (ls > existing.lastSeen) existing.lastSeen = ls;
+		byConceptMap.set(row.concept, existing);
+	}
+	const tunnels = [];
+	for (const [concept, data] of byConceptMap) {
+		if (data.projects.size < opts.min_projects) continue;
+		if (data.occurrences < opts.min_occurrences) continue;
+		const projects = [...data.projects].map((id) => slugMap[id] ?? String(id)).filter(Boolean);
+		tunnels.push({
+			concept,
+			projects,
+			occurrences: data.occurrences,
+			first_seen: data.firstSeen === Infinity ? 0 : data.firstSeen,
+			last_seen: data.lastSeen === -Infinity ? 0 : data.lastSeen
+		});
+	}
+	tunnels.sort((a, b) => {
+		const byProjects = b.projects.length - a.projects.length;
+		if (byProjects !== 0) return byProjects;
+		return b.occurrences - a.occurrences;
+	});
+	return {
+		tunnels: tunnels.slice(0, opts.limit),
+		projects_analyzed: projectIds.length,
+		total_concepts_evaluated: candidateTerms.length
+	};
+}
+/**
+* Find cross-project concept tunnels.
+*
+* Works with both SQLite and Postgres storage backends.
+* Requires the `registryDb` (better-sqlite3) for project slug resolution.
+*
+* @param backend        Active PAI storage backend.
+* @param registryDb     Registry database for project slug resolution.
+* @param options        Filter and limit options.
+*/
+async function findTunnels(backend, registryDb, options) {
+	const opts = {
+		min_projects: options?.min_projects ?? 2,
+		min_occurrences: options?.min_occurrences ?? 3,
+		limit: options?.limit ?? 20
+	};
+	const projectRows = registryDb.prepare("SELECT id, slug FROM projects WHERE status != 'archived'").all();
+	const slugMap = {};
+	for (const { id, slug } of projectRows) slugMap[id] = slug;
+	if (backend.backendType === "postgres") {
+		const pool = backend.getPool?.();
+		if (!pool) throw new Error("findTunnels: Postgres backend does not expose getPool()");
+		return findTunnelsPostgres(pool, slugMap, opts);
+	}
+	const rawDb = backend.getRawDb?.();
+	if (!rawDb) throw new Error("findTunnels: SQLite backend does not expose getRawDb()");
+	return findTunnelsSqlite(rawDb, slugMap, opts);
+}
+
+//#endregion
+//#region src/mcp/tools/tunnels.ts
+async function toolMemoryTunnels(registryDb, backend, params) {
+	try {
+		const result = await findTunnels(backend, registryDb, {
+			min_projects: params.min_projects,
+			min_occurrences: params.min_occurrences,
+			limit: params.limit
+		});
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	} catch (e) {
+		return {
+			content: [{
+				type: "text",
+				text: `memory_tunnels error: ${String(e)}`
+			}],
+			isError: true
+		};
+	}
+}
+
 //#endregion
 //#region src/mcp/tools.ts
 var tools_exports = /* @__PURE__ */ __exportAll({
@@ -913,8 +1699,15 @@ var tools_exports = /* @__PURE__ */ __exportAll({
 	detectProjectFromPath: () => detectProjectFromPath,
 	formatProject: () => formatProject,
 	lookupProjectId: () => lookupProjectId,
+	toolKgAdd: () => toolKgAdd,
+	toolKgContradictions: () => toolKgContradictions,
+	toolKgInvalidate: () => toolKgInvalidate,
+	toolKgQuery: () => toolKgQuery,
 	toolMemoryGet: () => toolMemoryGet,
 	toolMemorySearch: () => toolMemorySearch,
+	toolMemoryTaxonomy: () => toolMemoryTaxonomy,
+	toolMemoryTunnels: () => toolMemoryTunnels,
+	toolMemoryWakeup: () => toolMemoryWakeup,
 	toolProjectDetect: () => toolProjectDetect,
 	toolProjectHealth: () => toolProjectHealth,
 	toolProjectInfo: () => toolProjectInfo,
@@ -934,5 +1727,5 @@ var tools_exports = /* @__PURE__ */ __exportAll({
 });
 
 //#endregion
-export { toolProjectDetect as a, toolProjectList as c, toolMemorySearch as d, toolSessionRoute as i, toolProjectTodo as l, toolRegistrySearch as n, toolProjectHealth as o, toolSessionList as r, toolProjectInfo as s, tools_exports as t, toolMemoryGet as u };
-//# sourceMappingURL=tools-BXSwlzeH.mjs.map
+export { toolSessionList as a, toolProjectHealth as c, toolProjectTodo as d, toolMemoryGet as f, toolRegistrySearch as i, toolProjectInfo as l, toolMemoryTaxonomy as n, toolSessionRoute as o, toolMemorySearch as p, toolMemoryWakeup as r, toolProjectDetect as s, tools_exports as t, toolProjectList as u };
+//# sourceMappingURL=tools-C4SBZHga.mjs.map