@alaarab/cortex 1.14.0 → 1.15.1

package/README.md

@@ -98,7 +98,7 @@ On a new machine: clone, run init, done.
 
 ## What's new
 
-- **Terminal shell**: open `cortex` and get tabs for Backlog, Findings, Memory Queue, and Health. No agent needed
+- **Terminal shell**: open `cortex` and get tabs for Backlog, Findings, Review Queue, Skills, Hooks, and Health. No agent needed
 - **Synonym search**: type "throttling" and find "rate limit" and "429". You don't need to remember what you called it
 - **Bulk operations**: `add_findings`, `add_backlog_items`, `complete_backlog_items`, `remove_findings` for batch work
 - **Memory quality**: confidence scoring, age decay, and a feedback loop. Stale or low-signal entries stop appearing
@@ -148,7 +148,7 @@ On a new machine: clone, run init, done.
 
 **Consolidation.** When findings accumulate past the threshold, cortex flags it once per session. The `/cortex-consolidate` skill archives old entries and promotes cross-project patterns to global findings.
 
-**Memory queue.** Findings that fail trust filtering land in `MEMORY_QUEUE.md` for review. Triage from the shell (press `m`) or with `:mq approve`, `:mq reject`, `:mq edit`.
+**Review queue.** Findings that fail trust filtering land in `MEMORY_QUEUE.md` for review. Triage from the shell (press `m`) or with `:mq approve`, `:mq reject`, `:mq edit`.
 
 ---
 
@@ -160,7 +160,8 @@ The server indexes your cortex into a local SQLite FTS5 database. Tools are grou
 
 | Tool | What it does |
 |------|-------------|
-| `search_cortex` | FTS5 search with synonym expansion. Filters by project, type, limit. |
+| `search_knowledge` | FTS5 search with synonym expansion. Filters by project, type, limit. |
+| `get_memory_detail` | Fetch full content of a memory by id (e.g. `mem:project/filename`). |
 | `get_project_summary` | Summary card and file list for a project. |
 | `list_projects` | Everything in your active profile. |
 | `get_findings` | Read recent findings for a project without a search query. |
@@ -225,14 +226,16 @@ Governance, policy, and maintenance tools are CLI-only (see `cortex config` and
 
 ## Interactive shell
 
-`cortex` in a terminal opens the shell. Five views, single-key navigation:
+`cortex` in a terminal opens the shell. Seven views, single-key navigation:
 
 | Key | View |
 |-----|------|
 | `p` | Projects |
 | `b` | Backlog |
 | `l` | Findings |
-| `m` | Memory Queue |
+| `m` | Review Queue |
+| `s` | Skills |
+| `k` | Hooks |
 | `h` | Health |
 | `/` | Filter current view |
 | `:` | Command palette |
@@ -263,16 +266,33 @@ The shell works the same on every machine, for every agent.
 For scripting, hooks, and quick lookups from the terminal:
 
 ```bash
-cortex                               # interactive shell (TTY default)
-cortex search "rate limiting"        # FTS5 search with synonym expansion
-cortex add-finding <project> "..."   # append a finding from the terminal
-cortex pin <project> "..."           # promote canonical memory
-cortex doctor [--fix]                # health checks + optional self-heal
-cortex review-ui [--port=3499]       # lightweight review UI in the browser
-cortex update                        # update to latest version
+cortex                                   # interactive shell (TTY default)
+cortex search "rate limiting"            # FTS5 search with synonym expansion
+cortex add-finding <project> "..."       # append a finding from the terminal
+cortex pin <project> "..."               # promote canonical memory
+cortex backlog [project]                 # cross-project backlog view
+cortex status                            # health, active project, stats
+cortex doctor [--fix]                    # health checks + optional self-heal
+cortex verify                            # check init completed correctly
+cortex review-ui [--port=3499]           # lightweight review UI in the browser
+cortex update                            # update to latest version
+cortex uninstall                         # remove cortex config and hooks
+
+cortex link [--machine <n>] [--profile <n>]  # sync profile, symlinks, hooks
+cortex mcp-mode [on|off|status]          # toggle MCP integration
+cortex hooks-mode [on|off|status]        # toggle hook execution
+
+cortex skills list                       # list all installed skills
+cortex skills add <project> <path>       # add a skill to a project
+cortex skills remove <project> <name>    # remove a skill from a project
+cortex skill-list                        # alias for skills list
+
+cortex hooks list                        # show hook status per tool
+cortex hooks enable <tool>              # enable hooks for tool (claude/copilot/cursor/codex)
+cortex hooks disable <tool>             # disable hooks for tool
 ```
 
-Use `cortex config` for policy tuning and `cortex maintain` for governance operations. Top-level aliases still work for backwards compatibility. Run `--dry-run` before destructive maintenance commands.
+Use `cortex config` for policy tuning and `cortex maintain` for governance operations. Run `--dry-run` before destructive maintenance commands.
 
 ### cortex doctor
 
@@ -365,6 +385,27 @@ Four skills for the things that can't be automatic:
 
 Put personal workflow skills in `~/.cortex/global/skills/`. `cortex link` symlinks them to `~/.claude/skills/` so they're available everywhere.
 
+### Per-project agent config
+
+Drop a `cortex.project.yaml` in `~/.cortex/<project>/` to control what gets injected for that project:
+
+```yaml
+# Opt out of global skill injection for this project
+skills: false
+
+# Register extra MCP servers when this project is linked
+mcpServers:
+  my-tool:
+    command: node
+    args: [/path/to/server.js]
+  my-api:
+    command: /usr/local/bin/api-server
+    env:
+      API_KEY: "from-your-env"
+```
+
+`cortex link` merges project MCP servers into your agent config under namespaced keys (`cortex__<project>__<name>`) and cleans them up automatically when the config changes.
+
 ---
 
 ## Adding projects

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

@@ -5,7 +5,7 @@ import * as readline from "readline";
 import * as yaml from "js-yaml";
 import { execFileSync } from "child_process";
 import { fileURLToPath } from "url";
-import { configureClaude, configureCodexMcp, configureCopilotMcp, configureCursorMcp, configureVSCode, ensureGovernanceFiles, getHooksEnabledPreference, getMcpEnabledPreference, isVersionNewer, logMcpTargetStatus, setMcpEnabledPreference, } from "./init.js";
+import { configureClaude, configureCodexMcp, configureCopilotMcp, configureCursorMcp, configureVSCode, ensureGovernanceFiles, getHooksEnabledPreference, getMcpEnabledPreference, isVersionNewer, logMcpTargetStatus, patchJsonFile, setMcpEnabledPreference, } from "./init.js";
 import { configureAllHooks, detectInstalledTools } from "./hooks.js";
 import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, isRecord, } from "./shared.js";
 import { linkSkillsDir, writeSkillMd } from "./link-skills.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,10 +330,49 @@ 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);
     }
+    // Per-project MCP servers
+    if (config.mcpServers && typeof config.mcpServers === "object") {
+        linkProjectMcpServers(project, config.mcpServers);
+    }
+}
+/**
+ * Merge per-project MCP servers into Claude's settings.json.
+ * Keys are namespaced as "cortex__<project>__<name>" so we can identify
+ * and clean them up without touching user-managed servers.
+ */
+function linkProjectMcpServers(project, servers) {
+    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    if (!fs.existsSync(settingsPath) && Object.keys(servers).length === 0)
+        return;
+    try {
+        patchJsonFile(settingsPath, (data) => {
+            if (!data.mcpServers || typeof data.mcpServers !== "object")
+                data.mcpServers = {};
+            // Remove stale entries for this project (keys we previously wrote)
+            for (const key of Object.keys(data.mcpServers)) {
+                if (key.startsWith(`cortex__${project}__`))
+                    delete data.mcpServers[key];
+            }
+            // Add current entries
+            for (const [name, entry] of Object.entries(servers)) {
+                const key = `cortex__${project}__${name}`;
+                const server = { command: entry.command };
+                if (Array.isArray(entry.args))
+                    server.args = entry.args;
+                if (entry.env && typeof entry.env === "object")
+                    server.env = entry.env;
+                data.mcpServers[key] = server;
+            }
+        });
+    }
+    catch (err) {
+        debugLog(`linkProjectMcpServers: failed for ${project}: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 // ── Main orchestrator ───────────────────────────────────────────────────────
 export async function runLink(cortexPath, opts = {}) {

package/mcp/dist/shell-input.js

@@ -8,6 +8,7 @@ import * as path from "path";
 import { addBacklogItem, addFinding, addProjectToProfile, approveQueueItem, completeBacklogItem, editQueueItem, listProjectCards, pinBacklogItem, readBacklog, readFindings, readReviewQueue, rejectQueueItem, removeFinding, removeProjectFromProfile, resetShellState, saveShellState, setMachineProfile, tidyBacklogDone, unpinBacklogItem, updateBacklogItem, workNextBacklogItem, loadShellState, } from "./data-access.js";
 import { style } from "./shell-render.js";
 import { SUB_VIEWS, TAB_ICONS } from "./shell-types.js";
+import { getProjectSkills, getHookEntries, writeInstallPreferences } from "./shell-view.js";
 import { resultMsg, editDistance, tokenize, expandIds, normalizeSection, resolveEntryScript, backlogsByFilter, queueByFilter, } from "./shell-palette.js";
 export async function executePalette(host, input) {
     const trimmed = input.trim();
@@ -600,6 +601,14 @@ export function getListItems(cortexPath, profile, state, healthLineCount) {
                 return [];
             return state.filter ? queueByFilter(result.data, state.filter) : result.data;
         }
+        case "Skills": {
+            if (!state.project)
+                return [];
+            return getProjectSkills(cortexPath, state.project).map((s) => ({ name: s.name, text: s.path }));
+        }
+        case "Hooks": {
+            return getHookEntries(cortexPath).map((e) => ({ name: e.tool, text: e.enabled ? "enabled" : "disabled" }));
+        }
         case "Health":
             return Array.from({ length: Math.max(1, healthLineCount) }, (_, i) => ({ id: String(i) }));
         default:
@@ -644,7 +653,17 @@ export async function activateSelected(host) {
             break;
         case "Review Queue":
             if (item.text) {
-                host.setMessage(`  ${style.dim(item.id ?? "")}  ${item.text}  ${style.dim("[ a approve · r reject ]")}`);
+                host.setMessage(`  ${style.dim(item.id ?? "")}  ${item.text}  ${style.dim("[ a approve · d reject ]")}`);
+            }
+            break;
+        case "Skills":
+            if (item.name) {
+                host.setMessage(`  ${style.bold(item.name)}  ${style.dim(item.text ?? "")}`);
+            }
+            break;
+        case "Hooks":
+            if (item.name) {
+                host.setMessage(`  ${item.text === "enabled" ? style.boldGreen("enabled") : style.dim("disabled")}  ${style.bold(item.name)}`);
             }
             break;
     }
@@ -705,7 +724,7 @@ export async function doViewAction(host, key) {
                     host.setCursor(Math.max(0, cursor - 1));
                 });
             }
-            else if (key === "r" && item?.id) {
+            else if (key === "d" && item?.id) {
                 if (!project) {
                     host.setMessage("Select a project first.");
                     return;
@@ -720,6 +739,36 @@ export async function doViewAction(host, key) {
                 host.startInput("mq-edit", item.text || "");
             }
             break;
+        case "Skills":
+            if ((key === "d" || key === "\x7f") && item?.name) {
+                if (!project) {
+                    host.setMessage("Select a project first.");
+                    return;
+                }
+                const skillPath = item.text;
+                host.confirmThen(`Remove skill "${item.name}"?`, () => {
+                    try {
+                        fs.unlinkSync(skillPath);
+                        host.setMessage(`  Removed ${item.name}`);
+                        host.setCursor(Math.max(0, cursor - 1));
+                    }
+                    catch (err) {
+                        host.setMessage(`  Failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                });
+            }
+            else if (key === "a") {
+                host.setMessage(`  Use "cortex skills add ${project ?? "<project>"} <path>" to add a skill`);
+            }
+            break;
+        case "Hooks":
+            if ((key === "a" || key === "d") && item?.name) {
+                const enable = key === "a";
+                const prefs = { hookTools: { ...((getHookEntries(host.cortexPath).reduce((acc, e) => ({ ...acc, [e.tool]: e.enabled }), {}))), [item.name]: enable } };
+                writeInstallPreferences(host.cortexPath, prefs);
+                host.setMessage(`  ${enable ? style.boldGreen("Enabled") : style.dim("Disabled")} hooks for ${item.name}`);
+            }
+            break;
     }
 }
 // ── Cursor position display ───────────────────────────────────────────────────
@@ -862,6 +911,20 @@ export async function handleNavigateKey(host, key) {
         host.setMessage(`  ${TAB_ICONS["Review Queue"]} Review Queue`);
         return true;
     }
+    if (key === "s") {
+        if (!host.state.project) {
+            host.setMessage(style.dim("  Select a project first (↵)"));
+            return true;
+        }
+        host.setView("Skills");
+        host.setMessage(`  ${TAB_ICONS.Skills} Skills`);
+        return true;
+    }
+    if (key === "k") {
+        host.setView("Hooks");
+        host.setMessage(`  ${TAB_ICONS.Hooks} Hooks`);
+        return true;
+    }
     if (key === "h") {
         host.prevHealthView = host.state.view === "Health" ? host.prevHealthView : host.state.view;
         host.healthCache = undefined;
@@ -869,7 +932,7 @@ export async function handleNavigateKey(host, key) {
         host.setMessage(`  ${TAB_ICONS.Health} Health  ${style.dim("(esc to return)")}`);
         return true;
     }
-    if (["a", "d", "r", "e", "\x7f"].includes(key)) {
+    if (["a", "d", "e", "\x7f"].includes(key)) {
         await doViewAction(host, key);
         return true;
     }

package/mcp/dist/shell-types.js

@@ -1,11 +1,13 @@
 // Projects is level 0 (the home screen); these sub-views are level 1 (drill-down into a project)
 // Health is NOT a sub-view — it's a global overlay accessible from anywhere via [h]
-export const SUB_VIEWS = ["Backlog", "Findings", "Review Queue"];
+export const SUB_VIEWS = ["Backlog", "Findings", "Review Queue", "Skills", "Hooks"];
 export const TAB_ICONS = {
     Projects: "◉",
     Backlog: "▤",
     Findings: "✦",
     "Review Queue": "◈",
+    Skills: "◆",
+    Hooks: "⚡",
     Health: "♡",
 };
 export const MAX_UNDO_STACK = 10;

package/mcp/dist/shell-view.js

@@ -9,6 +9,7 @@ import { RESET, style, badge, separator, stripAnsi, padToWidth, truncateLine, li
 import { SUB_VIEWS, TAB_ICONS, } from "./shell-types.js";
 import { backlogsByFilter, queueByFilter, } from "./shell-palette.js";
 import { listMachines, listProfiles, } from "./data-access.js";
+import { readInstallPreferences } from "./init-preferences.js";
 // ── Tab bar ────────────────────────────────────────────────────────────────
 export function renderTabBar(state) {
     const cols = process.stdout.columns || 80;
@@ -56,7 +57,9 @@ export function renderBottomBar(state, navMode, inputCtx, inputBuf) {
         Projects: [`${k("↵")} ${d("open project")}`],
         Backlog: [`${k("a")} ${d("add")}`, `${k("↵")} ${d("mark done")}`, `${k("d")} ${d("toggle active")}`],
         Findings: [`${k("a")} ${d("add")}`, `${k("d")} ${d("remove")}`],
-        "Review Queue": [`${k("a")} ${d("keep")}`, `${k("r")} ${d("discard")}`, `${k("e")} ${d("edit")}`],
+        "Review Queue": [`${k("a")} ${d("keep")}`, `${k("d")} ${d("discard")}`, `${k("e")} ${d("edit")}`],
+        Skills: [`${k("d")} ${d("remove")}`],
+        Hooks: [`${k("a")} ${d("enable")}`, `${k("d")} ${d("disable")}`],
         Health: [`${k("↑↓")} ${d("scroll")}`, `${k("esc")} ${d("back")}`],
     };
     const extra = viewHints[state.view] ?? [];
@@ -356,6 +359,118 @@ export function renderMemoryQueueView(ctx, cursor, height) {
     }
     return vp.lines;
 }
+export function getProjectSkills(cortexPath, project) {
+    const dirs = [
+        path.join(cortexPath, project, "skills"),
+        path.join(cortexPath, project, ".claude", "skills"),
+    ];
+    const seen = new Set();
+    const skills = [];
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith(".md")) {
+                const name = entry.name.replace(/\.md$/, "");
+                if (!seen.has(name)) {
+                    seen.add(name);
+                    skills.push({ name, path: path.join(dir, entry.name) });
+                }
+            }
+            else if (entry.isDirectory()) {
+                const skillFile = path.join(dir, entry.name, "SKILL.md");
+                if (fs.existsSync(skillFile) && !seen.has(entry.name)) {
+                    seen.add(entry.name);
+                    skills.push({ name: entry.name, path: skillFile });
+                }
+            }
+        }
+    }
+    return skills;
+}
+export function renderSkillsView(ctx, cursor, height) {
+    const cols = process.stdout.columns || 80;
+    const project = ctx.state.project;
+    if (!project)
+        return [style.dim("  No project selected.")];
+    const skills = getProjectSkills(ctx.cortexPath, project);
+    const filtered = ctx.state.filter
+        ? skills.filter((s) => s.name.toLowerCase().includes(ctx.state.filter.toLowerCase()))
+        : skills;
+    if (!filtered.length) {
+        return [style.dim(`  No skills for ${project}. Use "cortex skills add ${project} <path>" to add one.`)];
+    }
+    const allLines = [];
+    let cursorFirstLine = 0;
+    let cursorLastLine = 0;
+    for (let i = 0; i < filtered.length; i++) {
+        const s = filtered[i];
+        const isSelected = i === cursor;
+        if (isSelected)
+            cursorFirstLine = allLines.length;
+        const isSymlink = (() => { try {
+            return fs.lstatSync(s.path).isSymbolicLink();
+        }
+        catch {
+            return false;
+        } })();
+        const linkTag = isSymlink ? style.dim(" →") : "";
+        let row = `  ${style.dim((i + 1).toString().padEnd(3))} ${style.bold(s.name)}${linkTag}`;
+        if (isSelected)
+            row = `\x1b[7m${padToWidth(row, cols)}${RESET}`;
+        else
+            row = truncateLine(row, cols);
+        allLines.push(row);
+        if (isSelected)
+            cursorLastLine = allLines.length - 1;
+    }
+    const usableHeight = Math.max(1, height - (allLines.length > height ? 1 : 0));
+    const vp = lineViewport(allLines, cursorFirstLine, cursorLastLine, usableHeight, ctx.currentScroll());
+    ctx.setScroll(vp.scrollStart);
+    if (allLines.length > usableHeight) {
+        const pct = filtered.length <= 1 ? 100 : Math.round((cursor / (filtered.length - 1)) * 100);
+        vp.lines.push(style.dim(`  ─── ${cursor + 1}/${filtered.length}  ${pct}%`));
+    }
+    return vp.lines;
+}
+// ── Hooks view ─────────────────────────────────────────────────────────────
+const HOOK_TOOLS = ["claude", "copilot", "cursor", "codex"];
+export function getHookEntries(cortexPath) {
+    const prefs = readInstallPreferences(cortexPath);
+    const hooksEnabled = prefs.hooksEnabled !== false;
+    const toolPrefs = (prefs.hookTools && typeof prefs.hookTools === "object") ? prefs.hookTools : {};
+    return HOOK_TOOLS.map((tool) => ({
+        tool,
+        enabled: hooksEnabled && toolPrefs[tool] !== false,
+    }));
+}
+export function renderHooksView(ctx, cursor, height) {
+    const cols = process.stdout.columns || 80;
+    const entries = getHookEntries(ctx.cortexPath);
+    const allLines = [];
+    let cursorFirstLine = 0;
+    let cursorLastLine = 0;
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        const isSelected = i === cursor;
+        if (isSelected)
+            cursorFirstLine = allLines.length;
+        const statusBadge = e.enabled ? style.boldGreen("enabled ") : style.dim("disabled");
+        let row = `  ${style.dim((i + 1).toString().padEnd(3))} ${statusBadge}  ${style.bold(e.tool)}`;
+        if (isSelected)
+            row = `\x1b[7m${padToWidth(row, cols)}${RESET}`;
+        else
+            row = truncateLine(row, cols);
+        allLines.push(row);
+        if (isSelected)
+            cursorLastLine = allLines.length - 1;
+    }
+    const usableHeight = Math.max(1, height - (allLines.length > height ? 1 : 0));
+    const vp = lineViewport(allLines, cursorFirstLine, cursorLastLine, usableHeight, ctx.currentScroll());
+    ctx.setScroll(vp.scrollStart);
+    return vp.lines;
+}
+export { writeInstallPreferences } from "./init-preferences.js";
 // ── Machines/Profiles view ─────────────────────────────────────────────────
 export function renderMachinesView(cortexPath) {
     const machines = listMachines(cortexPath);
@@ -455,6 +570,12 @@ export async function renderShell(ctx, navMode, inputCtx, inputBuf, showHelp, me
             case "Review Queue":
                 contentLines = renderMemoryQueueView(ctx, cursor, height);
                 break;
+            case "Skills":
+                contentLines = renderSkillsView(ctx, cursor, height);
+                break;
+            case "Hooks":
+                contentLines = renderHooksView(ctx, cursor, height);
+                break;
             case "Machines/Profiles":
                 contentLines = renderMachinesView(ctx.cortexPath);
                 break;

package/mcp/dist/shell.js

@@ -298,6 +298,20 @@ export class CortexShell {
             this.setMessage(`  ${TAB_ICONS["Review Queue"]} Review Queue`);
             return true;
         }
+        if (input === "s") {
+            if (!this.state.project) {
+                this.setMessage(style.dim("  Select a project first (↵)"));
+                return true;
+            }
+            this.setView("Skills");
+            this.setMessage(`  ${TAB_ICONS.Skills} Skills`);
+            return true;
+        }
+        if (input === "k") {
+            this.setView("Hooks");
+            this.setMessage(`  ${TAB_ICONS.Hooks} Hooks`);
+            return true;
+        }
         if (input === "h") {
             if (!this.state.project) {
                 this.setMessage(style.dim("  Select a project first (↵)"));

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.1",
   "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": {