@alaarab/cortex 1.14.0 → 1.15.0

package/mcp/dist/cli-config.js

@@ -8,7 +8,6 @@ function getCortexPath() {
         _cortexPath = ensureCortexPath();
     return _cortexPath;
 }
-const profile = process.env.CORTEX_PROFILE || "";
 // ── Config router ────────────────────────────────────────────────────────────
 export async function handleConfig(args) {
     const sub = args[0];

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

@@ -20,7 +20,7 @@ export function clearCitationValidCache() {
     citationValidCache.clear();
 }
 /** @deprecated Legacy citation formats. Use `<!-- cortex:cite {...} -->` instead. */
-const CITATION_PATTERN = /<!-- source: ([^:]+):(\d+) -->|\[file:([^:]+):(\d+)\]/g;
+const CITATION_PATTERN = /<!-- source: ((?:[a-zA-Z]:[\\\/])?[^:]+):(\d+) -->|\[file:((?:[a-zA-Z]:[\\\/])?[^:]+):(\d+)\]/g;
 export function parseCitations(text) {
     const results = [];
     let m;

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

@@ -122,7 +122,7 @@ function semanticFallbackDocs(db, prompt, project) {
     const queryTokens = tokenizeForOverlap(prompt);
     if (!queryTokens.length)
         return [];
-    const sampleLimit = project ? 180 : 260;
+    const sampleLimit = 100;
     const docs = project
         ? queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ? LIMIT ?", [project, sampleLimit]) || []
         : queryDocRows(db, "SELECT project, filename, type, content, path FROM docs LIMIT ?", [sampleLimit]) || [];
@@ -132,7 +132,7 @@ function semanticFallbackDocs(db, prompt, project) {
         const score = overlapScore(queryTokens, corpus);
         return { doc, score };
     })
-        .filter((x) => x.score >= 0.15)
+        .filter((x) => x.score >= 0.25)
         .sort((a, b) => b.score - a.score)
         .slice(0, 8)
         .map((x) => x.doc);
@@ -219,6 +219,22 @@ function mostRecentDate(content) {
         return "0000-00-00";
     return matches.map((m) => m.slice(3)).sort().reverse()[0];
 }
+function crossProjectAgeMultiplier(doc, detectedProject) {
+    if (doc.type !== "findings" || !detectedProject || doc.project === detectedProject)
+        return 1;
+    const decayDaysRaw = Number.parseInt(process.env.CORTEX_CROSS_PROJECT_DECAY_DAYS ?? "30", 10);
+    const decayDays = Number.isFinite(decayDaysRaw) && decayDaysRaw > 0 ? decayDaysRaw : 30;
+    const latest = mostRecentDate(doc.content);
+    const todayUtc = Date.UTC(new Date().getUTCFullYear(), new Date().getUTCMonth(), new Date().getUTCDate());
+    let ageInDays = 90;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(latest) && latest !== "0000-00-00") {
+        const entryUtc = Date.parse(`${latest}T00:00:00Z`);
+        if (!Number.isNaN(entryUtc)) {
+            ageInDays = Math.max(0, Math.floor((todayUtc - entryUtc) / 86_400_000));
+        }
+    }
+    return Math.max(0.1, 1 - (ageInDays / decayDays));
+}
 export function rankResults(rows, intent, gitCtx, detectedProject, cortexPathLocal, db, cwd, query) {
     let ranked = [...rows];
     if (detectedProject) {
@@ -260,31 +276,48 @@ export function rankResults(rows, intent, gitCtx, detectedProject, cortexPathLoc
             if (byDate !== 0)
                 return byDate;
         }
+        const changedFiles = gitCtx?.changedFiles || new Set();
+        const globBoostA = getProjectGlobBoost(cortexPathLocal, a.project, cwd, gitCtx?.changedFiles);
+        const globBoostB = getProjectGlobBoost(cortexPathLocal, b.project, cwd, gitCtx?.changedFiles);
+        const keyA = entryScoreKey(a.project, a.filename, a.content);
+        const keyB = entryScoreKey(b.project, b.filename, b.content);
+        const entityA = entityBoostPaths.has(a.path) ? 1.3 : 1;
+        const entityB = entityBoostPaths.has(b.path) ? 1.3 : 1;
+        const scoreA = (intentBoost(intent, a.type) +
+            fileRelevanceBoost(a.path, changedFiles) +
+            branchMatchBoost(a.content, gitCtx?.branch) +
+            globBoostA +
+            getQualityMultiplier(cortexPathLocal, keyA) +
+            entityA -
+            lowValuePenalty(a.content, a.type)) * crossProjectAgeMultiplier(a, detectedProject);
+        const scoreB = (intentBoost(intent, b.type) +
+            fileRelevanceBoost(b.path, changedFiles) +
+            branchMatchBoost(b.content, gitCtx?.branch) +
+            globBoostB +
+            getQualityMultiplier(cortexPathLocal, keyB) +
+            entityB -
+            lowValuePenalty(b.content, b.type)) * crossProjectAgeMultiplier(b, detectedProject);
+        const scoreDelta = scoreB - scoreA;
+        if (Math.abs(scoreDelta) > 0.01)
+            return scoreDelta;
         const intentDelta = intentBoost(intent, b.type) - intentBoost(intent, a.type);
         if (intentDelta !== 0)
             return intentDelta;
-        const changedFiles = gitCtx?.changedFiles || new Set();
         const fileDelta = fileRelevanceBoost(b.path, changedFiles) - fileRelevanceBoost(a.path, changedFiles);
         if (fileDelta !== 0)
             return fileDelta;
         const branchDelta = branchMatchBoost(b.content, gitCtx?.branch) - branchMatchBoost(a.content, gitCtx?.branch);
         if (branchDelta !== 0)
             return branchDelta;
-        const globBoostA = getProjectGlobBoost(cortexPathLocal, a.project, cwd, gitCtx?.changedFiles);
-        const globBoostB = getProjectGlobBoost(cortexPathLocal, b.project, cwd, gitCtx?.changedFiles);
         const globDelta = globBoostB - globBoostA;
         if (Math.abs(globDelta) > 0.01)
             return globDelta;
-        const keyA = entryScoreKey(a.project, a.filename, a.content);
-        const keyB = entryScoreKey(b.project, b.filename, b.content);
         const qualityDelta = getQualityMultiplier(cortexPathLocal, keyB) - getQualityMultiplier(cortexPathLocal, keyA);
         if (qualityDelta !== 0)
             return qualityDelta;
         const penaltyDelta = lowValuePenalty(a.content, a.type) - lowValuePenalty(b.content, b.type);
         if (penaltyDelta !== 0)
             return penaltyDelta;
-        const entityA = entityBoostPaths.has(a.path) ? 1.3 : 1;
-        const entityB = entityBoostPaths.has(b.path) ? 1.3 : 1;
         if (entityB !== entityA)
             return entityB - entityA;
         return 0;

package/mcp/dist/cli-hooks.js

@@ -40,7 +40,7 @@ const profile = process.env.CORTEX_PROFILE || "";
 async function readStdin() {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("data", (chunk) => chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk));
         process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
         process.stdin.on("error", reject);
     });
@@ -89,7 +89,7 @@ export async function handleHookPrompt() {
     const detectedProject = cwd ? detectProject(getCortexPath(), cwd, profile) : null;
     if (detectedProject)
         debugLog(`Detected project: ${detectedProject}`);
-    const safeQuery = buildRobustFtsQuery(keywords);
+    const safeQuery = buildRobustFtsQuery(keywords, detectedProject);
     if (!safeQuery)
         process.exit(0);
     try {

package/mcp/dist/cli.js

@@ -21,6 +21,7 @@ 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";
+import { readInstallPreferences, writeInstallPreferences } from "./init-preferences.js";
 let _cortexPath;
 function getCortexPath() {
     if (!_cortexPath)
@@ -275,6 +276,10 @@ export async function runCliCommand(command, args) {
             return handleMaintain(args);
         case "skill-list":
             return handleSkillList();
+        case "skills":
+            return handleSkillsNamespace(args);
+        case "hooks":
+            return handleHooksNamespace(args);
         case "backlog":
             return handleBacklogView();
         case "quickstart":
@@ -305,7 +310,7 @@ async function handleSearch(opts) {
         const where = [];
         const params = [];
         if (opts.query) {
-            const safeQuery = buildRobustFtsQuery(opts.query);
+            const safeQuery = buildRobustFtsQuery(opts.query, opts.project);
             if (!safeQuery) {
                 console.error("Query empty after sanitization.");
                 process.exit(1);
@@ -487,14 +492,149 @@ async function handleUpdate(args) {
     const result = await runCortexUpdate();
     console.log(result);
 }
+const HOOK_TOOLS = ["claude", "copilot", "cursor", "codex"];
+function printSkillsUsage() {
+    console.log("Usage:");
+    console.log("  cortex skills list");
+    console.log("  cortex skills add <project> <path>");
+    console.log("  cortex skills remove <project> <name>");
+}
+function printHooksUsage() {
+    console.log("Usage:");
+    console.log("  cortex hooks list");
+    console.log("  cortex hooks enable <tool>");
+    console.log("  cortex hooks disable <tool>");
+    console.log("  tools: claude|copilot|cursor|codex");
+}
+function normalizeHookTool(raw) {
+    if (!raw)
+        return null;
+    const tool = raw.toLowerCase();
+    return HOOK_TOOLS.includes(tool) ? tool : null;
+}
+function handleSkillsNamespace(args) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        printSkillsUsage();
+        return;
+    }
+    if (subcommand === "list") {
+        handleSkillList();
+        return;
+    }
+    if (subcommand === "add") {
+        const project = args[1];
+        const skillPath = args[2];
+        if (!project || !skillPath) {
+            printSkillsUsage();
+            process.exit(1);
+        }
+        if (!isValidProjectName(project)) {
+            console.error(`Invalid project name: "${project}"`);
+            process.exit(1);
+        }
+        const source = path.resolve(skillPath.replace(/^~/, os.homedir()));
+        if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+            console.error(`Skill file not found: ${source}`);
+            process.exit(1);
+        }
+        const baseName = path.basename(source);
+        const fileName = baseName.toLowerCase().endsWith(".md") ? baseName : `${baseName}.md`;
+        const destDir = path.join(getCortexPath(), project, ".claude", "skills");
+        const dest = path.join(destDir, fileName);
+        fs.mkdirSync(destDir, { recursive: true });
+        if (fs.existsSync(dest)) {
+            console.error(`Skill already exists: ${dest}`);
+            process.exit(1);
+        }
+        try {
+            fs.symlinkSync(source, dest);
+            console.log(`Linked skill ${fileName} into ${project}.`);
+        }
+        catch {
+            fs.copyFileSync(source, dest);
+            console.log(`Copied skill ${fileName} into ${project}.`);
+        }
+        return;
+    }
+    if (subcommand === "remove") {
+        const project = args[1];
+        const name = args[2];
+        if (!project || !name) {
+            printSkillsUsage();
+            process.exit(1);
+        }
+        if (!isValidProjectName(project)) {
+            console.error(`Invalid project name: "${project}"`);
+            process.exit(1);
+        }
+        const dest = path.join(getCortexPath(), project, ".claude", "skills", `${name.replace(/\.md$/i, "")}.md`);
+        if (!fs.existsSync(dest)) {
+            console.error(`Skill not found: ${dest}`);
+            process.exit(1);
+        }
+        fs.unlinkSync(dest);
+        console.log(`Removed skill ${name.replace(/\.md$/i, "")}.md from ${project}.`);
+        return;
+    }
+    console.error(`Unknown skills subcommand: ${subcommand}`);
+    printSkillsUsage();
+    process.exit(1);
+}
+function handleHooksNamespace(args) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        printHooksUsage();
+        return;
+    }
+    if (subcommand === "list") {
+        const prefs = readInstallPreferences(getCortexPath());
+        const hooksEnabled = prefs.hooksEnabled !== false;
+        const toolPrefs = prefs.hookTools && typeof prefs.hookTools === "object" ? prefs.hookTools : {};
+        const rows = HOOK_TOOLS.map((tool) => ({
+            tool,
+            hookType: "lifecycle",
+            status: hooksEnabled && toolPrefs[tool] !== false ? "enabled" : "disabled",
+        }));
+        console.log(`Tool      Hook Type  Status`);
+        console.log(`--------  ---------  --------`);
+        for (const row of rows) {
+            console.log(`${row.tool.padEnd(8)}  ${row.hookType.padEnd(9)}  ${row.status}`);
+        }
+        return;
+    }
+    if (subcommand === "enable" || subcommand === "disable") {
+        const tool = normalizeHookTool(args[1]);
+        if (!tool) {
+            printHooksUsage();
+            process.exit(1);
+        }
+        const prefs = readInstallPreferences(getCortexPath());
+        writeInstallPreferences(getCortexPath(), {
+            hookTools: {
+                ...(prefs.hookTools && typeof prefs.hookTools === "object" ? prefs.hookTools : {}),
+                [tool]: subcommand === "enable",
+            },
+        });
+        console.log(`${subcommand === "enable" ? "Enabled" : "Disabled"} hooks for ${tool}.`);
+        return;
+    }
+    console.error(`Unknown hooks subcommand: ${subcommand}`);
+    printHooksUsage();
+    process.exit(1);
+}
 function handleSkillList() {
     const sources = [];
+    const seenPaths = new Set();
     function collectSkills(root, sourceLabel) {
         if (!fs.existsSync(root))
             return;
         for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
             const entryPath = path.join(root, entry.name);
             if (entry.isFile() && entry.name.endsWith(".md")) {
+                if (seenPaths.has(entryPath))
+                    continue;
+                seenPaths.add(entryPath);
                 sources.push({
                     name: entry.name.replace(/\.md$/, ""),
                     source: sourceLabel,
@@ -507,6 +647,9 @@ function handleSkillList() {
                 const skillFile = path.join(entryPath, "SKILL.md");
                 if (!fs.existsSync(skillFile))
                     continue;
+                if (seenPaths.has(skillFile))
+                    continue;
+                seenPaths.add(skillFile);
                 sources.push({
                     name: entry.name,
                     source: sourceLabel,
@@ -523,8 +666,8 @@ function handleSkillList() {
         const projectName = path.basename(dir);
         if (projectName === "global")
             continue;
-        const projectSkillsDir = path.join(dir, "skills");
-        collectSkills(projectSkillsDir, projectName);
+        collectSkills(path.join(dir, "skills"), projectName);
+        collectSkills(path.join(dir, ".claude", "skills"), projectName);
     }
     if (!sources.length) {
         console.log("No skills found.");

package/mcp/dist/index.js

@@ -25,6 +25,12 @@ Usage:
   cortex init [--machine <n>] [--profile <n>] [--mcp on|off] [--template <t>] [--from-existing <path>] [--dry-run] [-y]
                                          Set up cortex (templates: python-project, monorepo, library, frontend)
   cortex detect-skills [--import]        Find untracked skills in ~/.claude/skills/
+  cortex skills list                     List installed skills
+  cortex skills add <project> <path>    Link or copy a skill file into one project
+  cortex skills remove <project> <name> Remove a project skill by name
+  cortex hooks list                      Show hook tool preferences
+  cortex hooks enable <tool>             Enable hooks for one tool
+  cortex hooks disable <tool>            Disable hooks for one tool
   cortex status                          Health, active project, stats
   cortex search <query> [--project <n>] [--type <t>] [--limit <n>]
                                          Search your cortex
@@ -206,6 +212,8 @@ const CLI_COMMANDS = [
     "review-ui",
     "quality-feedback",
     "skill-list",
+    "skills",
+    "hooks",
     "detect-skills",
     "backlog",
     "quickstart",

package/mcp/dist/link.js

@@ -124,6 +124,18 @@ function currentPackageVersion() {
         return null;
     }
 }
+function readProjectConfig(cortexPath, project) {
+    const configPath = path.join(cortexPath, project, "cortex.project.yaml");
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        const parsed = yaml.load(fs.readFileSync(configPath, "utf8"), { schema: yaml.CORE_SCHEMA });
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
 function maybeOfferStarterTemplateUpdate(cortexPath) {
     const current = currentPackageVersion();
     if (!current)
@@ -318,7 +330,8 @@ function linkProject(cortexPath, project, tools) {
     }
     // Project-level skills
     const projectSkills = path.join(cortexPath, project, ".claude", "skills");
-    if (fs.existsSync(projectSkills)) {
+    const config = readProjectConfig(cortexPath, project);
+    if (config.skills !== false && fs.existsSync(projectSkills)) {
         const targetSkills = path.join(target, ".claude", "skills");
         linkSkillsDir(projectSkills, targetSkills, cortexPath, symlinkFile);
     }

package/mcp/dist/utils.js

@@ -1,5 +1,8 @@
+import * as fs from "fs";
 import * as path from "path";
 import { execFileSync } from "child_process";
+import * as yaml from "js-yaml";
+import { findCortexPath } from "./shared.js";
 // ── Shared Git helper ────────────────────────────────────────────────────────
 export function runGit(cwd, args, timeoutMs, debugLogFn) {
     try {
@@ -266,17 +269,59 @@ export function sanitizeFts5Query(raw) {
     q = q.replace(/\s+/g, " ");
     return q.trim();
 }
+function parseSynonymsYaml(filePath) {
+    if (!fs.existsSync(filePath))
+        return {};
+    try {
+        const parsed = yaml.load(fs.readFileSync(filePath, "utf8"), { schema: yaml.CORE_SCHEMA });
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const loaded = {};
+        for (const [rawKey, value] of Object.entries(parsed)) {
+            const key = String(rawKey).trim().toLowerCase();
+            if (!key || !Array.isArray(value))
+                continue;
+            const synonyms = value
+                .filter((item) => typeof item === "string")
+                .map((item) => item.replace(/"/g, "").trim())
+                .filter((item) => item.length > 1);
+            if (synonyms.length > 0)
+                loaded[key] = synonyms;
+        }
+        return loaded;
+    }
+    catch {
+        return {};
+    }
+}
+function loadUserSynonyms(project) {
+    const cortexPath = findCortexPath();
+    if (!cortexPath)
+        return {};
+    const globalSynonyms = parseSynonymsYaml(path.join(cortexPath, "global", "synonyms.yaml"));
+    if (!project || !isValidProjectName(project))
+        return globalSynonyms;
+    const projectSynonyms = parseSynonymsYaml(path.join(cortexPath, project, "synonyms.yaml"));
+    return {
+        ...globalSynonyms,
+        ...projectSynonyms,
+    };
+}
 // Build a defensive FTS5 MATCH query:
 // - sanitizes user input
 // - extracts bigrams and treats them as quoted phrases
 // - expands known synonyms (capped at 10 total terms)
 // - applies AND between core terms, with synonyms as OR alternatives
-export function buildRobustFtsQuery(raw) {
+export function buildRobustFtsQuery(raw, project) {
     const MAX_TOTAL_TERMS = 10;
     const MAX_SYNONYM_GROUPS = 3;
     const safe = sanitizeFts5Query(raw);
     if (!safe)
         return "";
+    const synonymsMap = {
+        ...SYNONYMS,
+        ...loadUserSynonyms(project),
+    };
     const baseWords = safe.split(/\s+/).filter((t) => t.length > 1);
     if (baseWords.length === 0)
         return "";
@@ -286,12 +331,11 @@ export function buildRobustFtsQuery(raw) {
         bigrams.push(`${baseWords[i]} ${baseWords[i + 1]}`);
     }
     // Determine which words are consumed by bigrams that match synonym keys
-    const lowered = safe.toLowerCase();
     const consumedIndices = new Set();
     const matchedBigrams = [];
     for (let i = 0; i < bigrams.length; i++) {
         const bg = bigrams[i].toLowerCase();
-        if (SYNONYMS[bg]) {
+        if (synonymsMap[bg]) {
             consumedIndices.add(i);
             consumedIndices.add(i + 1);
             matchedBigrams.push(bigrams[i]);
@@ -326,8 +370,8 @@ export function buildRobustFtsQuery(raw) {
     for (const coreTerm of coreTerms) {
         const termText = coreTerm.slice(1, -1).toLowerCase(); // strip quotes
         const synonyms = [];
-        if (groupsExpanded < MAX_SYNONYM_GROUPS && SYNONYMS[termText]) {
-            for (const syn of SYNONYMS[termText]) {
+        if (groupsExpanded < MAX_SYNONYM_GROUPS && synonymsMap[termText]) {
+            for (const syn of synonymsMap[termText]) {
                 if (totalTermCount >= MAX_TOTAL_TERMS)
                     break;
                 const cleanSyn = syn.replace(/"/g, "").trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/cortex",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Long-term memory for AI agents. Stored as markdown in a git repo you own.",
   "type": "module",
   "bin": {
@@ -12,21 +12,21 @@
     "skills"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@xenova/transformers": "^2.17.2",
-    "glob": "^12.0.0",
-    "js-yaml": "^4.1.0",
+    "glob": "^13.0.6",
+    "js-yaml": "^4.1.1",
     "sql.js-fts5": "^1.4.0",
-    "zod": "^4.0.0"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/js-yaml": "^4.0.0",
-    "@types/node": "^22.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.3.5",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",
-    "eslint": "^10.0.2",
-    "tsx": "^4.0.0",
-    "typescript": "^5.7.0",
+    "eslint": "^10.0.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "scripts": {