@alaarab/cortex 1.13.5 → 1.14.0

package/mcp/dist/cli-hooks-session.js

@@ -11,7 +11,12 @@ import { runDoctor } from "./link.js";
 import { getHooksEnabledPreference } from "./init.js";
 import { buildIndex, queryRows, } from "./shared-index.js";
 import { filterBacklogByPriority } from "./cli-hooks-retrieval.js";
-const cortexPath = ensureCortexPath();
+let _cortexPath;
+function getCortexPath() {
+    if (!_cortexPath)
+        _cortexPath = ensureCortexPath();
+    return _cortexPath;
+}
 const profile = process.env.CORTEX_PROFILE || "";
 export function getGitContext(cwd) {
     if (!cwd)
@@ -239,21 +244,21 @@ async function runBestEffortGit(args, cwd) {
 // ── Hook handlers ────────────────────────────────────────────────────────────
 export async function handleHookSessionStart() {
     const startedAt = new Date().toISOString();
-    if (!getHooksEnabledPreference(cortexPath)) {
-        updateRuntimeHealth(cortexPath, { lastSessionStartAt: startedAt });
-        appendAuditLog(cortexPath, "hook_session_start", "status=disabled");
+    if (!getHooksEnabledPreference(getCortexPath())) {
+        updateRuntimeHealth(getCortexPath(), { lastSessionStartAt: startedAt });
+        appendAuditLog(getCortexPath(), "hook_session_start", "status=disabled");
         return;
     }
-    const pull = await runBestEffortGit(["pull", "--rebase", "--quiet"], cortexPath);
-    const doctor = await runDoctor(cortexPath, false);
-    const maintenanceScheduled = scheduleBackgroundMaintenance(cortexPath);
+    const pull = await runBestEffortGit(["pull", "--rebase", "--quiet"], getCortexPath());
+    const doctor = await runDoctor(getCortexPath(), false);
+    const maintenanceScheduled = scheduleBackgroundMaintenance(getCortexPath());
     try {
         const { trackSession } = await import("./telemetry.js");
-        trackSession(cortexPath);
+        trackSession(getCortexPath());
     }
     catch { /* best-effort */ }
-    updateRuntimeHealth(cortexPath, { lastSessionStartAt: startedAt });
-    appendAuditLog(cortexPath, "hook_session_start", `pull=${pull.ok ? "ok" : "fail"} doctor=${doctor.ok ? "ok" : "issues"} maintenance=${maintenanceScheduled ? "scheduled" : "skipped"}`);
+    updateRuntimeHealth(getCortexPath(), { lastSessionStartAt: startedAt });
+    appendAuditLog(getCortexPath(), "hook_session_start", `pull=${pull.ok ? "ok" : "fail"} doctor=${doctor.ok ? "ok" : "issues"} maintenance=${maintenanceScheduled ? "scheduled" : "skipped"}`);
 }
 // ── Q21: Conversation memory capture ─────────────────────────────────────────
 const INSIGHT_KEYWORDS = [
@@ -291,35 +296,35 @@ export function extractConversationInsights(text) {
 }
 export async function handleHookStop() {
     const now = new Date().toISOString();
-    if (!getHooksEnabledPreference(cortexPath)) {
-        updateRuntimeHealth(cortexPath, {
+    if (!getHooksEnabledPreference(getCortexPath())) {
+        updateRuntimeHealth(getCortexPath(), {
             lastStopAt: now,
             lastAutoSave: { at: now, status: "clean", detail: "hooks disabled by preference" },
         });
-        appendAuditLog(cortexPath, "hook_stop", "status=disabled");
+        appendAuditLog(getCortexPath(), "hook_stop", "status=disabled");
         return;
     }
-    const status = await runBestEffortGit(["status", "--porcelain"], cortexPath);
+    const status = await runBestEffortGit(["status", "--porcelain"], getCortexPath());
     if (!status.ok) {
-        updateRuntimeHealth(cortexPath, {
+        updateRuntimeHealth(getCortexPath(), {
             lastStopAt: now,
             lastAutoSave: { at: now, status: "error", detail: status.error || "git status failed" },
         });
-        appendAuditLog(cortexPath, "hook_stop", `status=error detail=${JSON.stringify(status.error || "git status failed")}`);
+        appendAuditLog(getCortexPath(), "hook_stop", `status=error detail=${JSON.stringify(status.error || "git status failed")}`);
         return;
     }
     if (!status.output) {
-        updateRuntimeHealth(cortexPath, {
+        updateRuntimeHealth(getCortexPath(), {
             lastStopAt: now,
             lastAutoSave: { at: now, status: "clean", detail: "no changes" },
         });
-        appendAuditLog(cortexPath, "hook_stop", "status=clean");
+        appendAuditLog(getCortexPath(), "hook_stop", "status=clean");
         return;
     }
-    const add = await runBestEffortGit(["add", "-A"], cortexPath);
-    const commit = add.ok ? await runBestEffortGit(["commit", "-m", "auto-save cortex"], cortexPath) : { ok: false, error: add.error };
+    const add = await runBestEffortGit(["add", "-A"], getCortexPath());
+    const commit = add.ok ? await runBestEffortGit(["commit", "-m", "auto-save cortex"], getCortexPath()) : { ok: false, error: add.error };
     if (!add.ok || !commit.ok) {
-        updateRuntimeHealth(cortexPath, {
+        updateRuntimeHealth(getCortexPath(), {
             lastStopAt: now,
             lastAutoSave: {
                 at: now,
@@ -327,36 +332,36 @@ export async function handleHookStop() {
                 detail: add.error || commit.error || "git add/commit failed",
             },
         });
-        appendAuditLog(cortexPath, "hook_stop", `status=error detail=${JSON.stringify(add.error || commit.error || "git add/commit failed")}`);
+        appendAuditLog(getCortexPath(), "hook_stop", `status=error detail=${JSON.stringify(add.error || commit.error || "git add/commit failed")}`);
         return;
     }
-    const remotes = await runBestEffortGit(["remote"], cortexPath);
+    const remotes = await runBestEffortGit(["remote"], getCortexPath());
     if (!remotes.ok || !remotes.output) {
-        updateRuntimeHealth(cortexPath, {
+        updateRuntimeHealth(getCortexPath(), {
             lastStopAt: now,
             lastAutoSave: { at: now, status: "saved-local", detail: "commit created; no remote configured" },
         });
-        appendAuditLog(cortexPath, "hook_stop", "status=saved-local");
+        appendAuditLog(getCortexPath(), "hook_stop", "status=saved-local");
         return;
     }
-    const push = await runBestEffortGit(["push"], cortexPath);
+    const push = await runBestEffortGit(["push"], getCortexPath());
     if (push.ok) {
-        updateRuntimeHealth(cortexPath, {
+        updateRuntimeHealth(getCortexPath(), {
             lastStopAt: now,
             lastAutoSave: { at: now, status: "saved-pushed", detail: "commit pushed" },
         });
-        appendAuditLog(cortexPath, "hook_stop", "status=saved-pushed");
+        appendAuditLog(getCortexPath(), "hook_stop", "status=saved-pushed");
         // Q21: Auto-capture conversation insights (gated behind CORTEX_FEATURE_AUTO_CAPTURE=1)
         if (isFeatureEnabled("CORTEX_FEATURE_AUTO_CAPTURE", false)) {
             try {
                 const captureInput = process.env.CORTEX_CONVERSATION_CONTEXT || "";
                 if (captureInput) {
                     const cwd = process.cwd();
-                    const activeProject = detectProject(cortexPath, cwd, profile);
+                    const activeProject = detectProject(getCortexPath(), cwd, profile);
                     if (activeProject) {
                         const insights = extractConversationInsights(captureInput);
                         for (const insight of insights) {
-                            addFindingToFile(cortexPath, activeProject, `[pattern] ${insight}`);
+                            addFindingToFile(getCortexPath(), activeProject, `[pattern] ${insight}`);
                             debugLog(`auto-capture: saved insight for ${activeProject}: ${insight.slice(0, 60)}`);
                         }
                     }
@@ -368,7 +373,7 @@ export async function handleHookStop() {
         }
         // Auto governance scheduling: run governance weekly if overdue
         try {
-            const lastGovPath = runtimeFile(cortexPath, "last-governance.txt");
+            const lastGovPath = runtimeFile(getCortexPath(), "last-governance.txt");
             const lastRun = fs.existsSync(lastGovPath) ? parseInt(fs.readFileSync(lastGovPath, "utf8"), 10) : 0;
             const daysSince = (Date.now() - lastRun) / 86_400_000;
             if (daysSince >= 7) {
@@ -386,14 +391,14 @@ export async function handleHookStop() {
         }
         return;
     }
-    updateRuntimeHealth(cortexPath, {
+    updateRuntimeHealth(getCortexPath(), {
         lastStopAt: now,
         lastAutoSave: { at: now, status: "saved-local", detail: push.error || "push failed" },
     });
-    appendAuditLog(cortexPath, "hook_stop", `status=saved-local detail=${JSON.stringify(push.error || "push failed")}`);
+    appendAuditLog(getCortexPath(), "hook_stop", `status=saved-local detail=${JSON.stringify(push.error || "push failed")}`);
 }
 export async function handleHookContext() {
-    if (!getHooksEnabledPreference(cortexPath)) {
+    if (!getHooksEnabledPreference(getCortexPath())) {
         process.exit(0);
     }
     let cwd = process.cwd();
@@ -406,8 +411,8 @@ export async function handleHookContext() {
     catch (err) {
         debugLog(`hook-context: no stdin or invalid JSON, using cwd: ${err instanceof Error ? err.message : String(err)}`);
     }
-    const project = detectProject(cortexPath, cwd, profile);
-    const db = await buildIndex(cortexPath, profile);
+    const project = detectProject(getCortexPath(), cwd, profile);
+    const db = await buildIndex(getCortexPath(), profile);
     const contextLabel = project ? `\u25c6 cortex \u00b7 ${project} \u00b7 context` : `\u25c6 cortex \u00b7 context`;
     const parts = [contextLabel, "<cortex-context>"];
     if (project) {
@@ -456,7 +461,7 @@ export async function handleHookContext() {
 // ── PostToolUse hook ─────────────────────────────────────────────────────────
 const INTERESTING_TOOLS = new Set(["Read", "Write", "Edit", "Bash", "Glob", "Grep"]);
 export async function handleHookTool() {
-    if (!getHooksEnabledPreference(cortexPath)) {
+    if (!getHooksEnabledPreference(getCortexPath())) {
         process.exit(0);
     }
     const start = Date.now();
@@ -513,7 +518,7 @@ export async function handleHookTool() {
         entry.error = responseStr.slice(0, 300);
     }
     try {
-        const logFile = runtimeFile(cortexPath, "tool-log.jsonl");
+        const logFile = runtimeFile(getCortexPath(), "tool-log.jsonl");
         fs.mkdirSync(path.dirname(logFile), { recursive: true });
         fs.appendFileSync(logFile, JSON.stringify(entry) + "\n");
     }
@@ -521,17 +526,17 @@ export async function handleHookTool() {
         // best effort
     }
     const cwd = (data.cwd ?? input.cwd ?? undefined);
-    const activeProject = cwd ? detectProject(cortexPath, cwd, profile) : null;
+    const activeProject = cwd ? detectProject(getCortexPath(), cwd, profile) : null;
     if (activeProject) {
         try {
             const candidates = extractToolFindings(toolName, input, responseStr);
             for (const { text, confidence } of candidates) {
                 if (confidence >= 0.85) {
-                    addFindingToFile(cortexPath, activeProject, text);
+                    addFindingToFile(getCortexPath(), activeProject, text);
                     debugLog(`hook-tool: auto-added learning (conf=${confidence}): ${text.slice(0, 60)}`);
                 }
                 else {
-                    appendReviewQueue(cortexPath, activeProject, "Review", [text]);
+                    appendReviewQueue(getCortexPath(), activeProject, "Review", [text]);
                     debugLog(`hook-tool: queued candidate (conf=${confidence}): ${text.slice(0, 60)}`);
                 }
             }

package/mcp/dist/cli-hooks.js

@@ -30,7 +30,12 @@ import { searchDocuments, applyTrustFilter, rankResults, selectSnippets, detectT
 import { buildHookOutput } from "./cli-hooks-output.js";
 import { getGitContext, trackSessionMetrics, scheduleBackgroundMaintenance, } from "./cli-hooks-session.js";
 import { approximateTokens } from "./cli-hooks-retrieval.js";
-const cortexPath = ensureCortexPath();
+let _cortexPath;
+function getCortexPath() {
+    if (!_cortexPath)
+        _cortexPath = ensureCortexPath();
+    return _cortexPath;
+}
 const profile = process.env.CORTEX_PROFILE || "";
 async function readStdin() {
     return new Promise((resolve, reject) => {
@@ -67,21 +72,21 @@ export async function handleHookPrompt() {
     if (!input)
         process.exit(0);
     const { prompt, cwd, sessionId } = input;
-    if (!getHooksEnabledPreference(cortexPath)) {
-        appendAuditLog(cortexPath, "hook_prompt", "status=disabled");
+    if (!getHooksEnabledPreference(getCortexPath())) {
+        appendAuditLog(getCortexPath(), "hook_prompt", "status=disabled");
         process.exit(0);
     }
-    updateRuntimeHealth(cortexPath, { lastPromptAt: new Date().toISOString() });
+    updateRuntimeHealth(getCortexPath(), { lastPromptAt: new Date().toISOString() });
     const keywords = extractKeywords(prompt);
     if (!keywords)
         process.exit(0);
     debugLog(`hook-prompt keywords: "${keywords}"`);
     const tIndex0 = Date.now();
-    const db = await buildIndex(cortexPath, profile);
+    const db = await buildIndex(getCortexPath(), profile);
     stage.indexMs = Date.now() - tIndex0;
     const gitCtx = getGitContext(cwd);
     const intent = detectTaskIntent(prompt);
-    const detectedProject = cwd ? detectProject(cortexPath, cwd, profile) : null;
+    const detectedProject = cwd ? detectProject(getCortexPath(), cwd, profile) : null;
     if (detectedProject)
         debugLog(`Detected project: ${detectedProject}`);
     const safeQuery = buildRobustFtsQuery(keywords);
@@ -94,14 +99,14 @@ export async function handleHookPrompt() {
         if (!rows || !rows.length)
             process.exit(0);
         const tTrust0 = Date.now();
-        const policy = getRetentionPolicy(cortexPath);
+        const policy = getRetentionPolicy(getCortexPath());
         const memoryTtlDays = Number.parseInt(process.env.CORTEX_MEMORY_TTL_DAYS || String(policy.ttlDays), 10);
-        rows = applyTrustFilter(rows, cortexPath, Number.isNaN(memoryTtlDays) ? policy.ttlDays : memoryTtlDays, policy.minInjectConfidence, policy.decay);
+        rows = applyTrustFilter(rows, getCortexPath(), Number.isNaN(memoryTtlDays) ? policy.ttlDays : memoryTtlDays, policy.minInjectConfidence, policy.decay);
         stage.trustMs = Date.now() - tTrust0;
         if (!rows.length)
             process.exit(0);
         if (isFeatureEnabled("CORTEX_FEATURE_AUTO_EXTRACT", true) && sessionId && detectedProject && cwd) {
-            const marker = sessionMarker(cortexPath, `extracted-${sessionId}-${detectedProject}`);
+            const marker = sessionMarker(getCortexPath(), `extracted-${sessionId}-${detectedProject}`);
             if (!fs.existsSync(marker)) {
                 try {
                     await handleExtractMemories(detectedProject, cwd, true);
@@ -113,7 +118,7 @@ export async function handleHookPrompt() {
             }
         }
         const tRank0 = Date.now();
-        rows = rankResults(rows, intent, gitCtx, detectedProject, cortexPath, db, cwd, keywords);
+        rows = rankResults(rows, intent, gitCtx, detectedProject, getCortexPath(), db, cwd, keywords);
         stage.rankMs = Date.now() - tRank0;
         if (!rows.length)
             process.exit(0);
@@ -155,7 +160,7 @@ export async function handleHookPrompt() {
             budgetUsedTokens = runningTokens;
             debugLog(`injection-budget: trimmed ${selected.length} -> ${kept.length} snippets to fit ${maxInjectTokens} token budget`);
         }
-        const parts = buildHookOutput(budgetSelected, budgetUsedTokens, intent, gitCtx, detectedProject, stage, safeTokenBudget, cortexPath, sessionId);
+        const parts = buildHookOutput(budgetSelected, budgetUsedTokens, intent, gitCtx, detectedProject, stage, safeTokenBudget, getCortexPath(), sessionId);
         // Add budget info to trace
         if (parts.length > 0) {
             const traceIdx = parts.findIndex(p => p.includes("trace:"));
@@ -165,17 +170,17 @@ export async function handleHookPrompt() {
         }
         const changedCount = gitCtx?.changedFiles.size ?? 0;
         if (sessionId) {
-            trackSessionMetrics(cortexPath, sessionId, selected, changedCount);
+            trackSessionMetrics(getCortexPath(), sessionId, selected, changedCount);
         }
-        flushEntryScores(cortexPath);
-        scheduleBackgroundMaintenance(cortexPath);
-        const noticeFile = sessionId ? sessionMarker(cortexPath, `noticed-${sessionId}`) : null;
+        flushEntryScores(getCortexPath());
+        scheduleBackgroundMaintenance(getCortexPath());
+        const noticeFile = sessionId ? sessionMarker(getCortexPath(), `noticed-${sessionId}`) : null;
         const alreadyNoticed = noticeFile ? fs.existsSync(noticeFile) : false;
         if (!alreadyNoticed) {
             // Clean up stale session markers (>24h old) from .sessions/ dir
             try {
                 const cutoff = Date.now() - 86400000;
-                const sessDir = sessionsDir(cortexPath);
+                const sessDir = sessionsDir(getCortexPath());
                 if (fs.existsSync(sessDir)) {
                     for (const f of fs.readdirSync(sessDir)) {
                         if (!f.startsWith("noticed-") && !f.startsWith("extracted-"))
@@ -186,10 +191,10 @@ export async function handleHookPrompt() {
                     }
                 }
                 // Also clean legacy markers from root
-                for (const f of fs.readdirSync(cortexPath)) {
+                for (const f of fs.readdirSync(getCortexPath())) {
                     if (!f.startsWith(".noticed-") && !f.startsWith(".extracted-"))
                         continue;
-                    const fp = `${cortexPath}/${f}`;
+                    const fp = `${getCortexPath()}/${f}`;
                     try {
                         fs.unlinkSync(fp);
                     }
@@ -199,7 +204,7 @@ export async function handleHookPrompt() {
             catch (err) {
                 debugLog(`stale notice cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
             }
-            const needed = checkConsolidationNeeded(cortexPath, profile);
+            const needed = checkConsolidationNeeded(getCortexPath(), profile);
             if (needed.length > 0) {
                 const notices = needed.map((n) => {
                     const since = n.lastConsolidated ? ` since ${n.lastConsolidated}` : "";

package/mcp/dist/cli.js

@@ -21,7 +21,12 @@ import { handleHookPrompt, handleHookSessionStart, handleHookStop, handleHookCon
 import { handleExtractMemories } from "./cli-extract.js";
 import { handleGovernMemories, handlePruneMemories, handleConsolidateMemories, handleMigrateFindings, handleMaintain, handleBackgroundMaintenance, } from "./cli-govern.js";
 import { handleConfig, handleIndexPolicy, handleRetentionPolicy, handleWorkflowPolicy, handleAccessControl, } from "./cli-config.js";
-const cortexPath = ensureCortexPath();
+let _cortexPath;
+function getCortexPath() {
+    if (!_cortexPath)
+        _cortexPath = ensureCortexPath();
+    return _cortexPath;
+}
 const profile = process.env.CORTEX_PROFILE || "";
 // ── Search types and parsing ─────────────────────────────────────────────────
 const SEARCH_TYPE_ALIASES = {
@@ -42,7 +47,7 @@ const SEARCH_TYPES = new Set([
 // ── Search history ───────────────────────────────────────────────────────────
 const MAX_HISTORY = 20;
 function historyFile() {
-    return runtimeFile(cortexPath, "search-history.jsonl");
+    return runtimeFile(getCortexPath(), "search-history.jsonl");
 }
 function readSearchHistory() {
     const file = historyFile();
@@ -294,7 +299,7 @@ async function handleSearch(opts) {
         return;
     }
     recordSearchQuery(opts);
-    const db = await buildIndex(cortexPath, profile);
+    const db = await buildIndex(getCortexPath(), profile);
     try {
         let sql = "SELECT project, filename, type, content, path FROM docs";
         const where = [];
@@ -334,7 +339,7 @@ async function handleSearch(opts) {
             if (opts.query) {
                 try {
                     const { logSearchMiss } = await import("./mcp-search.js");
-                    logSearchMiss(cortexPath, opts.query, opts.project);
+                    logSearchMiss(getCortexPath(), opts.query, opts.project);
                 }
                 catch { /* best-effort */ }
             }
@@ -371,7 +376,7 @@ async function handleAddFinding(project, learning) {
         process.exit(1);
     }
     try {
-        const result = addFindingCore(cortexPath, project, learning);
+        const result = addFindingCore(getCortexPath(), project, learning);
         if (!result.ok) {
             console.error(result.message);
             process.exit(1);
@@ -388,14 +393,14 @@ async function handlePinCanonical(project, memory) {
         console.error('Usage: cortex pin <project> "<memory>"');
         process.exit(1);
     }
-    const result = upsertCanonical(cortexPath, project, memory);
+    const result = upsertCanonical(getCortexPath(), project, memory);
     console.log(result.ok ? result.data : result.error);
 }
 async function handleDoctor(args) {
     const fix = args.includes("--fix");
     const checkData = args.includes("--check-data");
     const agentsOnly = args.includes("--agents");
-    const result = await runDoctor(cortexPath, fix, checkData);
+    const result = await runDoctor(getCortexPath(), fix, checkData);
     if (agentsOnly) {
         // Filter to only agent-related checks
         const agentChecks = result.checks.filter((c) => c.name.includes("cursor") || c.name.includes("copilot") || c.name.includes("codex") || c.name.includes("windsurf"));
@@ -418,7 +423,7 @@ async function handleDoctor(args) {
     }
     // Q30: Show top search miss patterns
     try {
-        const missFile = runtimeFile(cortexPath, "search-misses.jsonl");
+        const missFile = runtimeFile(getCortexPath(), "search-misses.jsonl");
         if (fs.existsSync(missFile)) {
             const lines = fs.readFileSync(missFile, "utf8").split("\n").filter(Boolean);
             if (lines.length > 0) {
@@ -455,15 +460,15 @@ async function handleQualityFeedback(args) {
         console.error("Usage: cortex quality-feedback --key=<entry-key> --type=helpful|reprompt|regression");
         process.exit(1);
     }
-    recordFeedback(cortexPath, key, feedback);
-    flushEntryScores(cortexPath);
+    recordFeedback(getCortexPath(), key, feedback);
+    flushEntryScores(getCortexPath());
     console.log(`Recorded feedback: ${feedback} for ${key}`);
 }
 async function handleMemoryUi(args) {
     const portArg = args.find((a) => a.startsWith("--port="));
     const port = portArg ? Number.parseInt(portArg.slice("--port=".length), 10) : 3499;
     const safePort = Number.isNaN(port) ? 3499 : port;
-    await startReviewUi(cortexPath, safePort);
+    await startReviewUi(getCortexPath(), safePort);
 }
 async function handleShell(args) {
     if (args.includes("--help") || args.includes("-h")) {
@@ -471,7 +476,7 @@ async function handleShell(args) {
         console.log("Interactive shell with views for Projects, Backlog, Learnings, Memory Queue, Machines/Profiles, and Health.");
         return;
     }
-    await startShell(cortexPath, profile);
+    await startShell(getCortexPath(), profile);
 }
 async function handleUpdate(args) {
     if (args.includes("--help") || args.includes("-h")) {
@@ -511,9 +516,9 @@ function handleSkillList() {
             }
         }
     }
-    const globalSkillsDir = path.join(cortexPath, "global", "skills");
+    const globalSkillsDir = path.join(getCortexPath(), "global", "skills");
     collectSkills(globalSkillsDir, "global");
-    const projectDirs = getProjectDirs(cortexPath, profile);
+    const projectDirs = getProjectDirs(getCortexPath(), profile);
     for (const dir of projectDirs) {
         const projectName = path.basename(dir);
         if (projectName === "global")
@@ -543,7 +548,7 @@ function handleDetectSkills(args) {
         return;
     }
     const trackedSkills = new Set();
-    const globalSkillsDir = path.join(cortexPath, "global", "skills");
+    const globalSkillsDir = path.join(getCortexPath(), "global", "skills");
     if (fs.existsSync(globalSkillsDir)) {
         for (const entry of fs.readdirSync(globalSkillsDir)) {
             trackedSkills.add(entry.replace(/\.md$/, ""));
@@ -552,7 +557,7 @@ function handleDetectSkills(args) {
             }
         }
     }
-    const projectDirs = getProjectDirs(cortexPath, profile);
+    const projectDirs = getProjectDirs(getCortexPath(), profile);
     for (const dir of projectDirs) {
         const projectSkillsDir = path.join(dir, ".claude", "skills");
         if (!fs.existsSync(projectSkillsDir))
@@ -620,7 +625,7 @@ function handleDetectSkills(args) {
     console.log(`\nImported ${imported} skill(s). Run \`cortex link\` to activate.`);
 }
 function handleBacklogView() {
-    const docs = readBacklogs(cortexPath, profile);
+    const docs = readBacklogs(getCortexPath(), profile);
     if (!docs.length) {
         console.log("No backlogs found.");
         return;
@@ -670,8 +675,8 @@ async function handleQuickstart() {
     });
     console.log(`\nInitializing cortex for "${projectName}"...\n`);
     await runInit({ yes: true });
-    await runLink(cortexPath, {});
-    const projectDir = path.join(cortexPath, projectName);
+    await runLink(getCortexPath(), {});
+    const projectDir = path.join(getCortexPath(), projectName);
     if (!fs.existsSync(projectDir)) {
         fs.mkdirSync(projectDir, { recursive: true });
         fs.writeFileSync(path.join(projectDir, "FINDINGS.md"), `# ${projectName} Findings\n`);
@@ -722,7 +727,7 @@ async function handleDebugInjection(args) {
             input: payload,
             env: {
                 ...process.env,
-                CORTEX_PATH: cortexPath,
+                CORTEX_PATH: getCortexPath(),
                 CORTEX_PROFILE: profile,
             },
             timeout: EXEC_TIMEOUT_MS,
@@ -766,7 +771,7 @@ async function handleInspectIndex(args) {
             return;
         }
     }
-    const db = await buildIndex(cortexPath, profile);
+    const db = await buildIndex(getCortexPath(), profile);
     const where = [];
     const params = [];
     if (project) {

package/mcp/dist/data-access.js

@@ -2,55 +2,19 @@ import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import { appendAuditLog, cortexErr, CortexError, cortexOk, forwardErr, getProjectDirs, } from "./shared.js";
-import { checkPermission, getWorkflowPolicy, getRuntimeHealth, } from "./shared-governance.js";
+import { checkPermission, getWorkflowPolicy, getRuntimeHealth, withFileLock as withFileLockRaw, } from "./shared-governance.js";
 import { addFindingToFile, validateBacklogFormat, } from "./shared-content.js";
 import { isValidProjectName, queueFilePath, safeProjectPath } from "./utils.js";
 function withFileLock(filePath, fn) {
-    const lockPath = filePath + ".lock";
-    const maxWait = Number.parseInt(process.env.CORTEX_FILE_LOCK_MAX_WAIT_MS || "5000", 10) || 5000;
-    const pollInterval = Number.parseInt(process.env.CORTEX_FILE_LOCK_POLL_MS || "100", 10) || 100;
-    const staleThreshold = Number.parseInt(process.env.CORTEX_FILE_LOCK_STALE_MS || "30000", 10) || 30000;
-    const waiter = new Int32Array(new SharedArrayBuffer(4));
-    const sleep = (ms) => Atomics.wait(waiter, 0, 0, ms);
-    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-    let waited = 0;
-    let hasLock = false;
-    while (waited < maxWait) {
-        try {
-            fs.writeFileSync(lockPath, `${process.pid}\n${Date.now()}`, { flag: "wx" });
-            hasLock = true;
-            break;
-        }
-        catch {
-            try {
-                const stat = fs.statSync(lockPath);
-                if (Date.now() - stat.mtimeMs > staleThreshold) {
-                    fs.unlinkSync(lockPath);
-                    continue;
-                }
-            }
-            catch {
-                sleep(pollInterval);
-                waited += pollInterval;
-                continue;
-            }
-            // Block this thread without spin-looping CPU while waiting to retry lock acquisition.
-            sleep(pollInterval);
-            waited += pollInterval;
-        }
-    }
-    if (!hasLock)
-        return cortexErr(`Could not acquire write lock for "${path.basename(filePath)}" within ${maxWait}ms. Another write may be in progress; please retry.`, CortexError.LOCK_TIMEOUT);
     try {
-        return fn();
+        return withFileLockRaw(filePath, fn);
     }
-    finally {
-        if (hasLock) {
-            try {
-                fs.unlinkSync(lockPath);
-            }
-            catch { /* lock may not exist */ }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("could not acquire lock")) {
+            return cortexErr(`Could not acquire write lock for "${path.basename(filePath)}". Another write may be in progress; please retry.`, CortexError.LOCK_TIMEOUT);
         }
+        throw err;
     }
 }
 const SHELL_STATE_VERSION = 1;

package/mcp/dist/index.js

@@ -1,6 +1,21 @@
 #!/usr/bin/env node
 import { parseMcpMode, runInit } from "./init.js";
 import * as os from "os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { findCortexPathWithArg, debugLog, runtimeDir, } from "./shared.js";
+import { buildIndex, updateFileInIndex as updateFileInIndexFn } from "./shared-index.js";
+import { runCustomHooks } from "./hooks.js";
+import { register as registerSearch } from "./mcp-search.js";
+import { register as registerBacklog } from "./mcp-backlog.js";
+import { register as registerFinding } from "./mcp-finding.js";
+import { register as registerMemory } from "./mcp-memory.js";
+import { register as registerData } from "./mcp-data.js";
+import { register as registerGraph } from "./mcp-graph.js";
+import { register as registerSession } from "./mcp-session.js";
 if (process.argv[2] === "--help" || process.argv[2] === "-h" || process.argv[2] === "help") {
     console.log(`cortex - Long-term memory for Claude Code
 
@@ -218,21 +233,6 @@ if (CLI_COMMANDS.includes(process.argv[2])) {
     await runCliCommand(cmd, process.argv.slice(3));
     process.exit(0);
 }
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import * as fs from "fs";
-import * as path from "path";
-import { fileURLToPath } from "url";
-import { findCortexPathWithArg, debugLog, runtimeDir, } from "./shared.js";
-import { buildIndex, updateFileInIndex as updateFileInIndexFn } from "./shared-index.js";
-import { runCustomHooks } from "./hooks.js";
-import { register as registerSearch } from "./mcp-search.js";
-import { register as registerBacklog } from "./mcp-backlog.js";
-import { register as registerFinding } from "./mcp-finding.js";
-import { register as registerMemory } from "./mcp-memory.js";
-import { register as registerData } from "./mcp-data.js";
-import { register as registerGraph } from "./mcp-graph.js";
-import { register as registerSession } from "./mcp-session.js";
 // MCP mode: first non-flag arg is the cortex path
 const cortexArg = process.argv.find((a, i) => i >= 2 && !a.startsWith("-"));
 const cortexPath = findCortexPathWithArg(cortexArg);

package/mcp/dist/link-skills.js

@@ -215,12 +215,6 @@ Cursor, Codex, and more.
 - \`import_project\`: import project from previously exported JSON
 - \`manage_project(project, action: "archive"|"unarchive")\`: archive or restore a project
 
-**Graph and session:**
-- \`get_learnings\`: alias for browsing findings/learnings
-- \`add_learning\`: alias for add_finding (backward compat)
-- \`add_learnings\`: alias for add_findings (backward compat)
-- \`remove_learning\`: alias for remove_finding (backward compat)
-- \`remove_learnings\`: alias for remove_findings (backward compat)
 `;
     const dest = path.join(cortexPath, "cortex.SKILL.md");
     fs.writeFileSync(dest, content);

package/mcp/dist/mcp-finding.js

@@ -4,7 +4,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { isValidProjectName, safeProjectPath } from "./utils.js";
 import { removeFinding as removeFindingCore, removeFindings as removeFindingsCore, } from "./core-finding.js";
-import { debugLog, EXEC_TIMEOUT_MS, } from "./shared.js";
+import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, } from "./shared.js";
 import { addFindingToFile, addFindingsToFile, checkSemanticDedup, checkSemanticConflicts, autoMergeConflicts, } from "./shared-content.js";
 import { runCustomHooks } from "./hooks.js";
 import { incrementSessionFindings } from "./mcp-session.js";
@@ -26,7 +26,7 @@ export function register(server, ctx) {
                 commit: z.string().optional().describe("Git commit SHA that supports this finding."),
                 supersedes: z.string().optional().describe("First 60 chars of the old finding this one replaces. The old entry will be marked as superseded."),
             }).optional().describe("Optional source citation for traceability."),
-            findingType: z.enum(["decision", "pitfall", "pattern"])
+            findingType: z.enum(FINDING_TYPES)
                 .optional()
                 .describe("Classify this finding: 'decision' (architectural choice with rationale), 'pitfall' (bug or gotcha to avoid), 'pattern' (reusable approach that works well)."),
         }),