@alaarab/cortex 1.15.0 → 1.15.2

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/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";
@@ -335,6 +335,44 @@ function linkProject(cortexPath, project, tools) {
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/cortex",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "description": "Long-term memory for AI agents. Stored as markdown in a git repo you own.",
   "type": "module",
   "bin": {