@alaarab/cortex 1.15.4 → 1.15.5

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

@@ -47,7 +47,18 @@ export function buildHookOutput(selected, usedTokens, intent, gitCtx, detectedPr
         }
     }
     else {
-        for (const injected of selected) {
+        // Position-aware injection: place most relevant at START and END (LaRA benchmark).
+        // Input `selected` is already ranked by relevance (best first).
+        // Reorder so: [0] stays first, [1] goes last, middle positions get [2..N-1].
+        let ordered = selected;
+        if (selected.length >= 3) {
+            ordered = [
+                selected[0], // most relevant → start
+                ...selected.slice(2), // remaining → middle
+                selected[1], // second most → end
+            ];
+        }
+        for (const injected of ordered) {
             const { doc, snippet, key } = injected;
             recordInjection(cortexPathLocal, key, sessionId);
             try {

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

@@ -1,4 +1,4 @@
-import { debugLog, appendAuditLog, runtimeFile, EXEC_TIMEOUT_MS, ensureCortexPath, } from "./shared.js";
+import { debugLog, appendAuditLog, runtimeFile, sessionMarker, EXEC_TIMEOUT_MS, ensureCortexPath, } from "./shared.js";
 import { appendReviewQueue, recordFeedback, getQualityMultiplier, updateRuntimeHealth, withFileLock, } from "./shared-governance.js";
 import { detectProject, } from "./shared-index.js";
 import { addFindingToFile, } from "./shared-content.js";
@@ -526,7 +526,37 @@ export async function handleHookTool() {
         // best effort
     }
     const cwd = (data.cwd ?? input.cwd ?? undefined);
-    const activeProject = cwd ? detectProject(getCortexPath(), cwd, profile) : null;
+    let activeProject = cwd ? detectProject(getCortexPath(), cwd, profile) : null;
+    // Check cooldown
+    const cooldownMs = Number.parseInt(process.env.CORTEX_HOOK_TOOL_COOLDOWN_MS || "30000", 10) || 30000;
+    const cooldownFile = runtimeFile(getCortexPath(), "hook-tool-cooldown");
+    try {
+        if (fs.existsSync(cooldownFile)) {
+            const age = Date.now() - fs.statSync(cooldownFile).mtimeMs;
+            if (age < cooldownMs) {
+                debugLog(`hook-tool: cooldown active (${Math.round(age / 1000)}s < ${Math.round(cooldownMs / 1000)}s), skipping extraction`);
+                // Skip to the log-only path
+                activeProject = null; // prevent extraction below
+            }
+        }
+    }
+    catch { /* best effort */ }
+    // Check session cap
+    const sessionCap = Number.parseInt(process.env.CORTEX_HOOK_TOOL_SESSION_CAP || "10", 10) || 10;
+    if (activeProject && sessionId) {
+        try {
+            const capFile = sessionMarker(getCortexPath(), `tool-findings-${sessionId}`);
+            let count = 0;
+            if (fs.existsSync(capFile)) {
+                count = Number.parseInt(fs.readFileSync(capFile, "utf8").trim(), 10) || 0;
+            }
+            if (count >= sessionCap) {
+                debugLog(`hook-tool: session cap reached (${count}/${sessionCap}), skipping extraction`);
+                activeProject = null; // prevent extraction below
+            }
+        }
+        catch { /* best effort */ }
+    }
     if (activeProject) {
         try {
             const candidates = extractToolFindings(toolName, input, responseStr);
@@ -540,6 +570,26 @@ export async function handleHookTool() {
                     debugLog(`hook-tool: queued candidate (conf=${confidence}): ${text.slice(0, 60)}`);
                 }
             }
+            // Update cooldown and session counter
+            if (candidates.length > 0) {
+                try {
+                    fs.writeFileSync(cooldownFile, Date.now().toString());
+                }
+                catch { /* best effort */ }
+                if (sessionId) {
+                    try {
+                        const capFile = sessionMarker(getCortexPath(), `tool-findings-${sessionId}`);
+                        let count = 0;
+                        try {
+                            count = Number.parseInt(fs.readFileSync(capFile, "utf8").trim(), 10) || 0;
+                        }
+                        catch { /* new file */ }
+                        count += candidates.filter(c => c.confidence >= 0.85).length; // only count directly added ones
+                        fs.writeFileSync(capFile, count.toString());
+                    }
+                    catch { /* best effort */ }
+                }
+            }
         }
         catch (err) {
             debugLog(`hook-tool: learning extraction failed: ${err instanceof Error ? err.message : String(err)}`);

package/mcp/dist/data-access.js

@@ -805,25 +805,30 @@ export function removeProjectFromProfile(cortexPath, profile, project) {
         return cortexOk(`Removed ${project} from profile ${profile}.`);
     });
 }
+function buildProjectCard(dir) {
+    const name = path.basename(dir);
+    const summaryFile = path.join(dir, "summary.md");
+    const claudeFile = path.join(dir, "CLAUDE.md");
+    const summarySource = fs.existsSync(summaryFile)
+        ? fs.readFileSync(summaryFile, "utf8")
+        : fs.existsSync(claudeFile)
+            ? fs.readFileSync(claudeFile, "utf8")
+            : "";
+    const summary = summarySource
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line && !line.startsWith("#")) || "";
+    const docs = ["CLAUDE.md", "FINDINGS.md", "LEARNINGS.md", "summary.md", "backlog.md", "MEMORY_QUEUE.md"]
+        .filter((file) => fs.existsSync(path.join(dir, file)));
+    return { name, summary, docs };
+}
 export function listProjectCards(cortexPath, profile) {
     const dirs = getProjectDirs(cortexPath, profile).sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
-    const cards = [];
-    for (const dir of dirs) {
-        const name = path.basename(dir);
-        const summaryFile = path.join(dir, "summary.md");
-        const claudeFile = path.join(dir, "CLAUDE.md");
-        const summarySource = fs.existsSync(summaryFile)
-            ? fs.readFileSync(summaryFile, "utf8")
-            : fs.existsSync(claudeFile)
-                ? fs.readFileSync(claudeFile, "utf8")
-                : "";
-        const summary = summarySource
-            .split("\n")
-            .map((line) => line.trim())
-            .find((line) => line && !line.startsWith("#")) || "";
-        const docs = ["CLAUDE.md", "FINDINGS.md", "LEARNINGS.md", "summary.md", "backlog.md", "MEMORY_QUEUE.md"]
-            .filter((file) => fs.existsSync(path.join(dir, file)));
-        cards.push({ name, summary, docs });
+    const cards = dirs.map(buildProjectCard);
+    // Prepend global as a pinned entry so it's always accessible from the shell
+    const globalDir = path.join(cortexPath, "global");
+    if (fs.existsSync(globalDir)) {
+        cards.unshift(buildProjectCard(globalDir));
     }
     return cards;
 }

package/mcp/dist/mcp-backlog.js

@@ -5,7 +5,8 @@ import * as path from "path";
 import { isValidProjectName } from "./utils.js";
 import { addBacklogItem as addBacklogItemStore, addBacklogItems as addBacklogItemsBatch, backlogMarkdown, completeBacklogItem as completeBacklogItemStore, completeBacklogItems as completeBacklogItemsBatch, readBacklog, readBacklogs, updateBacklogItem as updateBacklogItemStore, } from "./data-access.js";
 const BACKLOG_SECTION_ORDER = ["Active", "Queue", "Done"];
-function buildBacklogView(doc, status) {
+const DEFAULT_BACKLOG_LIMIT = 20;
+function buildBacklogView(doc, status, limit) {
     let includedSections;
     if (status === "all") {
         includedSections = BACKLOG_SECTION_ORDER;
@@ -22,11 +23,23 @@ function buildBacklogView(doc, status) {
     else {
         includedSections = ["Active", "Queue"];
     }
+    const effectiveLimit = limit ?? DEFAULT_BACKLOG_LIMIT;
+    let truncated = false;
     const items = {
-        Active: includedSections.includes("Active") ? doc.items.Active : [],
-        Queue: includedSections.includes("Queue") ? doc.items.Queue : [],
-        Done: includedSections.includes("Done") ? doc.items.Done : [],
+        Active: [],
+        Queue: [],
+        Done: [],
     };
+    for (const section of includedSections) {
+        const sectionItems = doc.items[section];
+        if (sectionItems.length > effectiveLimit) {
+            items[section] = sectionItems.slice(0, effectiveLimit);
+            truncated = true;
+        }
+        else {
+            items[section] = sectionItems;
+        }
+    }
     const totalItems = BACKLOG_SECTION_ORDER.reduce((sum, section) => sum + items[section].length, 0);
     return {
         doc: {
@@ -35,8 +48,26 @@ function buildBacklogView(doc, status) {
         },
         includedSections,
         totalItems,
+        truncated,
     };
 }
+function buildBacklogSummary(doc, includedSections) {
+    const lines = [`## ${doc.project}`];
+    for (const section of includedSections) {
+        const items = doc.items[section];
+        const highCount = items.filter(i => i.priority === "high").length;
+        const medCount = items.filter(i => i.priority === "medium").length;
+        lines.push(`**${section}**: ${items.length} items${highCount ? ` (${highCount} high` + (medCount ? `, ${medCount} medium` : "") + ")" : ""}`);
+        // Show first 3 items as preview
+        for (const item of items.slice(0, 3)) {
+            const prio = item.priority ? ` [${item.priority}]` : "";
+            lines.push(`  - ${item.line.slice(0, 80)}${item.line.length > 80 ? "\u2026" : ""}${prio}`);
+        }
+        if (items.length > 3)
+            lines.push(`  ... and ${items.length - 3} more`);
+    }
+    return lines.join("\n");
+}
 export function register(server, ctx) {
     const { cortexPath, profile, withWriteQueue, updateFileInIndex } = ctx;
     server.registerTool("get_backlog", {
@@ -47,8 +78,10 @@ export function register(server, ctx) {
             id: z.string().optional().describe("Backlog item ID like A1, Q3, D2. Requires project."),
             item: z.string().optional().describe("Exact backlog item text. Requires project."),
             status: z.enum(["all", "active", "queue", "done", "active+queue"]).optional().describe("Which backlog sections to include. Defaults to 'active+queue'."),
+            limit: z.number().optional().describe("Max items per section to return. Default 20."),
+            summary: z.boolean().optional().describe("If true, return counts and titles only (no full content). Reduces token usage."),
         }),
-    }, async ({ project, id, item, status }) => {
+    }, async ({ project, id, item, status, limit, summary }) => {
         // Single item lookup
         if (id || item) {
             if (!project)
@@ -78,7 +111,7 @@ export function register(server, ctx) {
             if (!result.ok)
                 return mcpResponse({ ok: false, error: result.error });
             const doc = result.data;
-            const view = buildBacklogView(doc, status);
+            const view = buildBacklogView(doc, status, limit);
             if (!fs.existsSync(doc.path)) {
                 return mcpResponse({
                     ok: true,
@@ -86,26 +119,43 @@ export function register(server, ctx) {
                     data: { project, items: view.doc.items, includedSections: view.includedSections, totalItems: view.totalItems },
                 });
             }
+            if (summary) {
+                return mcpResponse({
+                    ok: true,
+                    message: buildBacklogSummary(doc, view.includedSections),
+                    data: { project, includedSections: view.includedSections, totalItems: view.totalItems, summary: true },
+                });
+            }
+            const truncationNote = view.truncated ? `\n\n_Showing first ${limit ?? DEFAULT_BACKLOG_LIMIT} items per section. Pass a higher limit to see more._` : "";
             return mcpResponse({
                 ok: true,
-                message: `## ${project}\n${backlogMarkdown(view.doc)}`,
-                data: { project, items: view.doc.items, issues: doc.issues, includedSections: view.includedSections, totalItems: view.totalItems },
+                message: `## ${project}\n${backlogMarkdown(view.doc)}${truncationNote}`,
+                data: { project, items: view.doc.items, issues: doc.issues, includedSections: view.includedSections, totalItems: view.totalItems, truncated: view.truncated },
             });
         }
         // All projects
         const docs = readBacklogs(cortexPath, profile);
         if (!docs.length)
             return mcpResponse({ ok: true, message: "No backlogs found.", data: { projects: [] } });
-        const views = docs.map((doc) => ({ project: doc.project, view: buildBacklogView(doc, status), issues: doc.issues }));
-        const parts = views.map(({ project, view }) => `## ${project}\n${backlogMarkdown(view.doc)}`);
+        const views = docs.map((doc) => ({ project: doc.project, doc, view: buildBacklogView(doc, status, limit), issues: doc.issues }));
+        const anyTruncated = views.some(({ view }) => view.truncated);
+        let parts;
+        if (summary) {
+            parts = views.map(({ doc, view }) => buildBacklogSummary(doc, view.includedSections));
+        }
+        else {
+            parts = views.map(({ project, view }) => `## ${project}\n${backlogMarkdown(view.doc)}`);
+        }
+        const truncationNote = anyTruncated && !summary ? `\n\n_Showing first ${limit ?? DEFAULT_BACKLOG_LIMIT} items per section. Pass a higher limit to see more._` : "";
         const projectData = views.map(({ project, view, issues }) => ({
             project,
             items: view.doc.items,
             issues,
             includedSections: view.includedSections,
             totalItems: view.totalItems,
+            truncated: view.truncated,
         }));
-        return mcpResponse({ ok: true, message: parts.join("\n\n"), data: { projects: projectData } });
+        return mcpResponse({ ok: true, message: parts.join("\n\n") + truncationNote, data: { projects: projectData, summary: summary || false } });
     });
     server.registerTool("add_backlog_item", {
         title: "◆ cortex · add task",

package/mcp/dist/shared-governance.js

@@ -835,6 +835,8 @@ export function getQualityMultiplier(cortexPath, key) {
     let helpful = entry ? entry.helpful : 0;
     let repromptPenalty = entry ? entry.repromptPenalty : 0;
     let regressionPenalty = entry ? entry.regressionPenalty : 0;
+    let impressions = entry ? entry.impressions : 0;
+    let lastUsedAt = entry ? entry.lastUsedAt : "";
     // Include unflushed journal deltas
     const journalEntries = readScoreJournal(cortexPath).filter(e => e.key === key);
     for (const je of journalEntries) {
@@ -844,11 +846,39 @@ export function getQualityMultiplier(cortexPath, key) {
             repromptPenalty += je.delta.repromptPenalty;
         if (je.delta.regressionPenalty)
             regressionPenalty += je.delta.regressionPenalty;
+        if (je.delta.impressions)
+            impressions += je.delta.impressions;
+        // Track most recent journal timestamp as lastUsedAt
+        if (je.at && (!lastUsedAt || je.at > lastUsedAt))
+            lastUsedAt = je.at;
     }
     if (!entry && journalEntries.length === 0)
         return 1;
+    // ACT-R activation scoring components:
+    // 1. Temporal decay: recency of last retrieval
+    let recencyBoost = 0;
+    if (lastUsedAt) {
+        const lastUsedMs = new Date(lastUsedAt).getTime();
+        if (!Number.isNaN(lastUsedMs)) {
+            const daysSinceUse = Math.max(0, (Date.now() - lastUsedMs) / 86_400_000);
+            if (daysSinceUse <= 7) {
+                recencyBoost = 0.15; // recently used: boost
+            }
+            else if (daysSinceUse <= 30) {
+                recencyBoost = 0; // neutral
+            }
+            else {
+                recencyBoost = -0.1 * Math.min(3, (daysSinceUse - 30) / 30); // decay up to -0.3
+            }
+        }
+    }
+    // 2. Usage frequency: log-scaled impressions (diminishing returns)
+    const frequencyBoost = impressions > 0 ? Math.min(0.2, Math.log2(impressions + 1) * 0.05) : 0;
+    // 3. Feedback signals (existing)
     const penalties = repromptPenalty + regressionPenalty * 2;
-    const raw = 1 + helpful * 0.15 - penalties * 0.2;
+    const feedbackScore = helpful * 0.15 - penalties * 0.2;
+    // Combine all components
+    const raw = 1 + feedbackScore + recencyBoost + frequencyBoost;
     return Math.max(0.2, Math.min(1.5, raw));
 }
 export function recordRetrieval(cortexPath, file, section) {

package/package.json

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