@alaarab/cortex 1.13.6 → 1.15.0

package/README.md

@@ -19,9 +19,9 @@ Supports Claude Code, Copilot CLI, Cursor, and Codex.
 
 <br>
 
-Project knowledge, field findings, task queues — stored as markdown in a git repo you own. No vendor lock-in, no cloud dependency. One command to set up. Zero commands to use after that.
+Project knowledge, field findings, task queues. Stored as markdown in a git repo you own. No vendor lock-in, no cloud dependency. One command to set up. Zero commands to use after that.
 
-> **Quick start:** `npx @alaarab/cortex init` -- takes 30 seconds, no account needed.
+> **Quick start:** `npx @alaarab/cortex init` takes 30 seconds, no account needed.
 
 <br>
 </div>
@@ -98,24 +98,24 @@ On a new machine: clone, run init, done.
 
 ## What's new
 
-- **Bulk MCP tools** -- `add_findings`, `add_backlog_items`, `complete_backlog_items`, `remove_findings` for batch operations
-- **TUI shell** -- interactive terminal UI with Backlog, Findings, Memory Queue, and Health tabs (`cortex shell`)
-- **Tiered reference** -- `reference/` subdirectories for deep reference docs, indexed separately from findings
-- **FTS5 full-text search** with synonym expansion and keyword extraction
-- **Multi-agent governance** -- role-based access control for teams (admins, maintainers, contributors, viewers)
-- **Starter templates** -- `cortex init --template python-project|monorepo|library|frontend`
-- **Memory quality** -- confidence scoring, age decay, trust filtering, and a feedback loop
-- **Data portability** -- export/import projects as JSON, archive/unarchive projects
+- **Terminal shell**: open `cortex` and get tabs for Backlog, Findings, Memory Queue, 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
+- **Starter templates**: `cortex init --template python-project|monorepo|library|frontend`
+- **Multi-agent access control**: four roles (admin, maintainer, contributor, viewer) for shared cortex repos
+- **Deep reference**: `reference/` subdirectories indexed separately so API docs don't drown out your findings
+- **Data portability**: export/import projects as JSON, archive/unarchive anytime
 
 ---
 
 ## What makes this different
 
-**It runs itself.** Hooks inject context before every prompt and auto-save after every response. No manual calls needed. Trust filtering gates what gets injected based on confidence, age decay, and citation validity.
+**It runs itself.** Hooks inject context before every prompt and auto-save after every response. Trust filtering checks confidence, age decay, and citation validity before anything lands in your context.
 
 **It's just files.** Markdown in a git repo you own. No database, no vector store, no account. `git log` shows how it grew.
 
-**Search that works.** Type "throttling" and it finds "rate limit" and "429". Synonym expansion means you don't need exact phrases.
+**Search that works.** Type "throttling" and it finds "rate limit" and "429". You don't need to remember what you called it.
 
 **Every machine, same brain.** Push to a private repo, clone on a new machine, run init. Profiles control which projects each machine sees.
 
@@ -123,15 +123,15 @@ On a new machine: clone, run init, done.
 
 ## What lives in your cortex
 
-`cortex init` creates your project store with starter templates. Each project gets its own directory — add files as the project grows.
+`cortex init` creates your project store with starter templates. Each project gets its own directory. Add files as the project grows.
 
 | File | What it's for |
 |------|--------------|
-| `summary.md` | Five-line card: what, stack, status, how to run, the finding |
+| `summary.md` | Five-line card: what, stack, status, how to run, key insight |
 | `CLAUDE.md` | Full context: architecture, commands, conventions |
 | `REFERENCE.md` | Deep reference: API details, data models, things too long for CLAUDE.md |
 | `FINDINGS.md` | Bugs hit, patterns discovered, things to avoid next time |
-| `CANONICAL_MEMORIES.md` | Pinned high-signal memories that bypass decay |
+| `CANONICAL_MEMORIES.md` | Pinned memories that never expire and always inject |
 | `backlog.md` | Task queue that persists across sessions |
 | `MEMORY_QUEUE.md` | Items waiting for your review (see [Memory queue](#memory-queue) below) |
 | `.claude/skills/` | Project-specific slash commands |
@@ -209,6 +209,7 @@ The server indexes your cortex into a local SQLite FTS5 database. Tools are grou
 | `get_related_docs` | Get docs linked to a named entity. |
 | `read_graph` | Read the entity graph for a project or all projects. |
 | `link_findings` | Manually link a finding to an entity. Persists to manual-links.json and survives rebuilds. |
+| `cross_project_entities` | Find entities shared across multiple projects. |
 
 ### Session management
 

package/mcp/dist/cli-config.js

@@ -2,8 +2,12 @@ import { ensureCortexPath } from "./shared.js";
 import { getIndexPolicy, updateIndexPolicy, getRetentionPolicy, updateRetentionPolicy, getWorkflowPolicy, updateWorkflowPolicy, getAccessControl, updateAccessControl, } from "./shared-governance.js";
 import { listMachines as listMachinesStore, listProfiles as listProfilesStore } from "./data-access.js";
 import { setTelemetryEnabled, getTelemetrySummary, resetTelemetry } from "./telemetry.js";
-const cortexPath = ensureCortexPath();
-const profile = process.env.CORTEX_PROFILE || "";
+let _cortexPath;
+function getCortexPath() {
+    if (!_cortexPath)
+        _cortexPath = ensureCortexPath();
+    return _cortexPath;
+}
 // ── Config router ────────────────────────────────────────────────────────────
 export async function handleConfig(args) {
     const sub = args[0];
@@ -43,7 +47,7 @@ Subcommands:
 // ── Index policy ─────────────────────────────────────────────────────────────
 export async function handleIndexPolicy(args) {
     if (!args.length || args[0] === "get") {
-        console.log(JSON.stringify(getIndexPolicy(cortexPath), null, 2));
+        console.log(JSON.stringify(getIndexPolicy(getCortexPath()), null, 2));
         return;
     }
     if (args[0] === "set") {
@@ -64,7 +68,7 @@ export async function handleIndexPolicy(args) {
                 patch.includeHidden = /^(1|true|yes|on)$/i.test(v);
             }
         }
-        const result = updateIndexPolicy(cortexPath, patch);
+        const result = updateIndexPolicy(getCortexPath(), patch);
         if (!result.ok) {
             console.log(result.error);
             if (result.code === "PERMISSION_DENIED")
@@ -80,7 +84,7 @@ export async function handleIndexPolicy(args) {
 // ── Memory policy ────────────────────────────────────────────────────────────
 export async function handleRetentionPolicy(args) {
     if (!args.length || args[0] === "get") {
-        console.log(JSON.stringify(getRetentionPolicy(cortexPath), null, 2));
+        console.log(JSON.stringify(getRetentionPolicy(getCortexPath()), null, 2));
         return;
     }
     if (args[0] === "set") {
@@ -101,7 +105,7 @@ export async function handleRetentionPolicy(args) {
                 patch[k] = value;
             }
         }
-        const result = updateRetentionPolicy(cortexPath, patch);
+        const result = updateRetentionPolicy(getCortexPath(), patch);
         if (!result.ok) {
             console.log(result.error);
             if (result.code === "PERMISSION_DENIED")
@@ -117,7 +121,7 @@ export async function handleRetentionPolicy(args) {
 // ── Memory workflow ──────────────────────────────────────────────────────────
 export async function handleWorkflowPolicy(args) {
     if (!args.length || args[0] === "get") {
-        console.log(JSON.stringify(getWorkflowPolicy(cortexPath), null, 2));
+        console.log(JSON.stringify(getWorkflowPolicy(getCortexPath()), null, 2));
         return;
     }
     if (args[0] === "set") {
@@ -139,7 +143,7 @@ export async function handleWorkflowPolicy(args) {
                 patch[k] = Number.isNaN(num) ? v : num;
             }
         }
-        const result = updateWorkflowPolicy(cortexPath, patch);
+        const result = updateWorkflowPolicy(getCortexPath(), patch);
         if (!result.ok) {
             console.log(result.error);
             if (result.code === "PERMISSION_DENIED")
@@ -155,7 +159,7 @@ export async function handleWorkflowPolicy(args) {
 // ── Memory access ────────────────────────────────────────────────────────────
 export async function handleAccessControl(args) {
     if (!args.length || args[0] === "get") {
-        console.log(JSON.stringify(getAccessControl(cortexPath), null, 2));
+        console.log(JSON.stringify(getAccessControl(getCortexPath()), null, 2));
         return;
     }
     if (args[0] === "set") {
@@ -168,7 +172,7 @@ export async function handleAccessControl(args) {
                 continue;
             patch[k] = v.split(",").map((s) => s.trim()).filter(Boolean);
         }
-        const result = updateAccessControl(cortexPath, patch);
+        const result = updateAccessControl(getCortexPath(), patch);
         if (!result.ok) {
             console.log(result.error);
             if (result.code === "PERMISSION_DENIED")
@@ -183,7 +187,7 @@ export async function handleAccessControl(args) {
 }
 // ── Machines and profiles ────────────────────────────────────────────────────
 export function handleConfigMachines() {
-    const result = listMachinesStore(cortexPath);
+    const result = listMachinesStore(getCortexPath());
     if (!result.ok) {
         console.log(result.error);
         return;
@@ -192,7 +196,7 @@ export function handleConfigMachines() {
     console.log(`Registered Machines\n${lines.join("\n")}`);
 }
 export function handleConfigProfiles() {
-    const result = listProfilesStore(cortexPath);
+    const result = listProfilesStore(getCortexPath());
     if (!result.ok) {
         console.log(result.error);
         return;
@@ -209,19 +213,19 @@ function handleConfigTelemetry(args) {
     const action = args[0];
     switch (action) {
         case "on":
-            setTelemetryEnabled(cortexPath, true);
+            setTelemetryEnabled(getCortexPath(), true);
             console.log("Telemetry enabled. Local usage stats will be collected.");
             console.log("No data is sent externally. Stats are stored in .runtime/telemetry.json.");
             return;
         case "off":
-            setTelemetryEnabled(cortexPath, false);
+            setTelemetryEnabled(getCortexPath(), false);
             console.log("Telemetry disabled.");
             return;
         case "reset":
-            resetTelemetry(cortexPath);
+            resetTelemetry(getCortexPath());
             console.log("Telemetry stats reset.");
             return;
         default:
-            console.log(getTelemetrySummary(cortexPath));
+            console.log(getTelemetrySummary(getCortexPath()));
     }
 }

package/mcp/dist/cli-extract.js

@@ -8,7 +8,12 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { execFileSync } from "child_process";
-const cortexPath = ensureCortexPath();
+let _cortexPath;
+function getCortexPath() {
+    if (!_cortexPath)
+        _cortexPath = ensureCortexPath();
+    return _cortexPath;
+}
 const profile = process.env.CORTEX_PROFILE || "";
 function runGit(cwd, args) {
     return runGitShared(cwd, args, EXEC_TIMEOUT_MS, debugLog);
@@ -20,7 +25,7 @@ function shouldRetryGh(err) {
 function inferProject(arg) {
     if (arg)
         return arg;
-    return detectProject(cortexPath, process.cwd(), profile);
+    return detectProject(getCortexPath(), process.cwd(), profile);
 }
 // ── Git log parsing ──────────────────────────────────────────────────────────
 export function parseGitLogRecords(cwd, days) {
@@ -219,7 +224,7 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false)
         return;
     }
     const days = Number.parseInt(process.env.CORTEX_MEMORY_EXTRACT_WINDOW_DAYS || "30", 10);
-    const threshold = Number.parseFloat(process.env.CORTEX_MEMORY_AUTO_ACCEPT || String(getRetentionPolicy(cortexPath).autoAcceptThreshold));
+    const threshold = Number.parseFloat(process.env.CORTEX_MEMORY_AUTO_ACCEPT || String(getRetentionPolicy(getCortexPath()).autoAcceptThreshold));
     const records = parseGitLogRecords(repoRoot, Number.isNaN(days) ? 30 : days);
     const ghCandidates = isFeatureEnabled("CORTEX_FEATURE_GH_MINING", false)
         ? await mineGithubCandidates(repoRoot)
@@ -232,14 +237,14 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false)
             continue;
         const line = `${candidate.text} (source commit ${rec.hash.slice(0, 8)})`;
         if (candidate.score >= threshold) {
-            addFindingToFile(cortexPath, project, line, {
+            addFindingToFile(getCortexPath(), project, line, {
                 repo: repoRoot,
                 commit: rec.hash,
             });
             accepted++;
         }
         else {
-            const qr1 = appendReviewQueue(cortexPath, project, "Review", [`[confidence ${candidate.score.toFixed(2)}] ${line}`]);
+            const qr1 = appendReviewQueue(getCortexPath(), project, "Review", [`[confidence ${candidate.score.toFixed(2)}] ${line}`]);
             if (qr1.ok)
                 queued += qr1.data;
         }
@@ -248,10 +253,10 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false)
         const line = `${c.text}${c.commit ? ` (source commit ${c.commit.slice(0, 8)})` : ""}`;
         if (c.text.startsWith("CI failure pattern:")) {
             const key = entryScoreKey(project, "FINDINGS.md", line);
-            recordFeedback(cortexPath, key, "regression");
+            recordFeedback(getCortexPath(), key, "regression");
         }
         if (c.score >= threshold) {
-            addFindingToFile(cortexPath, project, line, {
+            addFindingToFile(getCortexPath(), project, line, {
                 repo: repoRoot,
                 commit: c.commit,
                 file: c.file,
@@ -259,13 +264,13 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false)
             accepted++;
         }
         else {
-            const qr2 = appendReviewQueue(cortexPath, project, "Review", [`[confidence ${c.score.toFixed(2)}] ${line}`]);
+            const qr2 = appendReviewQueue(getCortexPath(), project, "Review", [`[confidence ${c.score.toFixed(2)}] ${line}`]);
             if (qr2.ok)
                 queued += qr2.data;
         }
     }
-    flushEntryScores(cortexPath);
-    appendAuditLog(cortexPath, "extract_memories", `project=${project} accepted=${accepted} queued=${queued} window_days=${days}`);
+    flushEntryScores(getCortexPath());
+    appendAuditLog(getCortexPath(), "extract_memories", `project=${project} accepted=${accepted} queued=${queued} window_days=${days}`);
     if (!silent)
         console.log(`Extracted memory candidates for ${project}: accepted=${accepted}, queued=${queued}, window=${days}d`);
 }

package/mcp/dist/cli-govern.js

@@ -4,13 +4,18 @@ import { filterTrustedFindingsDetailed, migrateLegacyFindings, } from "./shared-
 import * as fs from "fs";
 import * as path from "path";
 import { handleExtractMemories } from "./cli-extract.js";
-const cortexPath = ensureCortexPath();
+let _cortexPath;
+function getCortexPath() {
+    if (!_cortexPath)
+        _cortexPath = ensureCortexPath();
+    return _cortexPath;
+}
 const profile = process.env.CORTEX_PROFILE || "";
 // ── Shared helpers ───────────────────────────────────────────────────────────
 function targetProjects(projectArg) {
     return projectArg
         ? [projectArg]
-        : getProjectDirs(cortexPath, profile).map((p) => path.basename(p)).filter((p) => p !== "global");
+        : getProjectDirs(getCortexPath(), profile).map((p) => path.basename(p)).filter((p) => p !== "global");
 }
 function parseProjectDryRunArgs(args, command, usage) {
     let projectArg;
@@ -36,7 +41,7 @@ function parseProjectDryRunArgs(args, command, usage) {
 function captureFindingBackups(projects) {
     const snapshots = new Map();
     for (const project of projects) {
-        const backup = path.join(cortexPath, project, "FINDINGS.md.bak");
+        const backup = path.join(getCortexPath(), project, "FINDINGS.md.bak");
         if (!fs.existsSync(backup))
             continue;
         snapshots.set(backup, fs.statSync(backup).mtimeMs);
@@ -46,14 +51,14 @@ function captureFindingBackups(projects) {
 function summarizeBackupChanges(before, projects) {
     const changed = [];
     for (const project of projects) {
-        const backup = path.join(cortexPath, project, "FINDINGS.md.bak");
+        const backup = path.join(getCortexPath(), project, "FINDINGS.md.bak");
         if (!fs.existsSync(backup))
             continue;
         const current = fs.statSync(backup).mtimeMs;
         const previous = before.get(backup);
         if (previous === undefined || current !== previous) {
             // Normalize to forward slashes for consistent output across platforms
-            changed.push(path.relative(cortexPath, backup).replace(/\\/g, "/"));
+            changed.push(path.relative(getCortexPath(), backup).replace(/\\/g, "/"));
         }
     }
     return changed.sort();
@@ -66,16 +71,16 @@ function qualityMarkers(cortexPathLocal) {
     };
 }
 export async function handleGovernMemories(projectArg, silent = false, dryRun = false) {
-    const policy = getRetentionPolicy(cortexPath);
+    const policy = getRetentionPolicy(getCortexPath());
     const ttlDays = Number.parseInt(process.env.CORTEX_MEMORY_TTL_DAYS || String(policy.ttlDays), 10);
     const projects = projectArg
         ? [projectArg]
-        : getProjectDirs(cortexPath, profile).map((p) => path.basename(p)).filter((p) => p !== "global");
+        : getProjectDirs(getCortexPath(), profile).map((p) => path.basename(p)).filter((p) => p !== "global");
     let staleCount = 0;
     let conflictCount = 0;
     let reviewCount = 0;
     for (const project of projects) {
-        const learningsPath = path.join(cortexPath, project, "FINDINGS.md");
+        const learningsPath = path.join(getCortexPath(), project, "FINDINGS.md");
         if (!fs.existsSync(learningsPath))
             continue;
         const content = fs.readFileSync(learningsPath, "utf8");
@@ -93,18 +98,18 @@ export async function handleGovernMemories(projectArg, silent = false, dryRun =
             .filter((l) => /(fixed stuff|updated things|misc|temp|wip|quick note)/i.test(l) || l.length < 16);
         reviewCount += lowValue.length;
         if (!dryRun) {
-            appendReviewQueue(cortexPath, project, "Stale", stale);
-            appendReviewQueue(cortexPath, project, "Conflicts", conflicts);
-            appendReviewQueue(cortexPath, project, "Review", lowValue);
+            appendReviewQueue(getCortexPath(), project, "Stale", stale);
+            appendReviewQueue(getCortexPath(), project, "Conflicts", conflicts);
+            appendReviewQueue(getCortexPath(), project, "Review", lowValue);
         }
     }
     if (!dryRun) {
-        appendAuditLog(cortexPath, "govern_memories", `projects=${projects.length} stale=${staleCount} conflicts=${conflictCount} review=${reviewCount}`);
+        appendAuditLog(getCortexPath(), "govern_memories", `projects=${projects.length} stale=${staleCount} conflicts=${conflictCount} review=${reviewCount}`);
         for (const project of projects) {
-            consolidateProjectFindings(cortexPath, project);
+            consolidateProjectFindings(getCortexPath(), project);
         }
     }
-    const lockSummary = dryRun ? "" : enforceCanonicalLocks(cortexPath, projectArg);
+    const lockSummary = dryRun ? "" : enforceCanonicalLocks(getCortexPath(), projectArg);
     if (!silent) {
         const prefix = dryRun ? "[dry-run] Would govern" : "Governed";
         console.log(`${prefix} memories: stale=${staleCount}, conflicts=${conflictCount}, review=${reviewCount}`);
@@ -123,19 +128,19 @@ export async function handlePruneMemories(args = []) {
     const { projectArg, dryRun } = parseProjectDryRunArgs(args, "prune-memories", usage);
     const projects = targetProjects(projectArg);
     const beforeBackups = dryRun ? new Map() : captureFindingBackups(projects);
-    const result = pruneDeadMemories(cortexPath, projectArg, dryRun);
+    const result = pruneDeadMemories(getCortexPath(), projectArg, dryRun);
     if (!result.ok) {
         console.log(result.error);
         return;
     }
     console.log(result.data);
     // TTL enforcement: move entries older than ttlDays that haven't been retrieved recently
-    const policy = getRetentionPolicy(cortexPath);
+    const policy = getRetentionPolicy(getCortexPath());
     const ttlDays = policy.ttlDays;
     const retrievalGraceDays = Math.floor(ttlDays / 2);
     const now = Date.now();
     // Load retrieval log once for all projects
-    const retrievalLogPath = path.join(cortexPath, ".runtime", "retrieval-log.jsonl");
+    const retrievalLogPath = path.join(getCortexPath(), ".runtime", "retrieval-log.jsonl");
     let retrievalEntries = [];
     if (fs.existsSync(retrievalLogPath)) {
         try {
@@ -165,7 +170,7 @@ export async function handlePruneMemories(args = []) {
     }
     let ttlExpired = 0;
     for (const project of projects) {
-        const learningsPath = path.join(cortexPath, project, "FINDINGS.md");
+        const learningsPath = path.join(getCortexPath(), project, "FINDINGS.md");
         if (!fs.existsSync(learningsPath))
             continue;
         const content = fs.readFileSync(learningsPath, "utf8");
@@ -197,7 +202,7 @@ export async function handlePruneMemories(args = []) {
             ttlExpired++;
         }
         if (expiredEntries.length > 0 && !dryRun) {
-            appendReviewQueue(cortexPath, project, "Stale", expiredEntries);
+            appendReviewQueue(getCortexPath(), project, "Stale", expiredEntries);
         }
         if (expiredEntries.length > 0 && dryRun) {
             for (const entry of expiredEntries) {
@@ -221,7 +226,7 @@ export async function handleConsolidateMemories(args = []) {
     const { projectArg, dryRun } = parseProjectDryRunArgs(args, "consolidate-memories", usage);
     const projects = targetProjects(projectArg);
     const beforeBackups = dryRun ? new Map() : captureFindingBackups(projects);
-    const results = projects.map((p) => consolidateProjectFindings(cortexPath, p, dryRun));
+    const results = projects.map((p) => consolidateProjectFindings(getCortexPath(), p, dryRun));
     console.log(results.map((r) => r.ok ? r.data : r.error).join("\n"));
     if (dryRun)
         return;
@@ -238,7 +243,7 @@ export async function handleMigrateFindings(args) {
     }
     const pinCanonical = args.includes("--pin");
     const dryRun = args.includes("--dry-run");
-    const result = migrateLegacyFindings(cortexPath, project, { pinCanonical, dryRun });
+    const result = migrateLegacyFindings(getCortexPath(), project, { pinCanonical, dryRun });
     console.log(result.ok ? result.data : result.error);
 }
 function printMaintainMigrationUsage() {
@@ -299,7 +304,7 @@ function parseMaintainMigrationArgs(args) {
     return { kind: "data", project: positional[0], pinCanonical, dryRun };
 }
 function describeGovernanceMigrationPlan() {
-    const govDir = path.join(cortexPath, ".governance");
+    const govDir = path.join(getCortexPath(), ".governance");
     if (!fs.existsSync(govDir))
         return [];
     const files = [
@@ -335,7 +340,7 @@ function runGovernanceMigration(dryRun) {
         const details = pending.map((entry) => `${entry.file} (${entry.from} -> ${entry.to})`).join(", ");
         return `[dry-run] Would migrate ${pending.length} governance file(s): ${details}`;
     }
-    const migrated = migrateGovernanceFiles(cortexPath);
+    const migrated = migrateGovernanceFiles(getCortexPath());
     if (!migrated.length)
         return "Governance files are already up to date.";
     return `Migrated ${migrated.length} governance file(s): ${migrated.join(", ")}`;
@@ -347,7 +352,7 @@ export async function handleMaintainMigrate(args) {
         lines.push(`Governance migration: ${runGovernanceMigration(parsed.dryRun)}`);
     }
     if (parsed.kind === "data" || parsed.kind === "all") {
-        const result = migrateLegacyFindings(cortexPath, parsed.project, {
+        const result = migrateLegacyFindings(getCortexPath(), parsed.project, {
             pinCanonical: parsed.pinCanonical,
             dryRun: parsed.dryRun,
         });
@@ -404,7 +409,7 @@ function findBackups(projects) {
     const results = [];
     const now = Date.now();
     for (const project of projects) {
-        const dir = path.join(cortexPath, project);
+        const dir = path.join(getCortexPath(), project);
         if (!fs.existsSync(dir))
             continue;
         for (const f of fs.readdirSync(dir)) {
@@ -450,35 +455,35 @@ async function handleRestoreBackup(args) {
         fs.copyFileSync(b.fullPath, target);
         console.log(`Restored ${b.project}/${b.file.replace(/\.bak$/, "")} from backup`);
     }
-    appendAuditLog(cortexPath, "restore_backup", `project=${projectArg} files=${projectBackups.length}`);
+    appendAuditLog(getCortexPath(), "restore_backup", `project=${projectArg} files=${projectBackups.length}`);
 }
 // ── Background maintenance ───────────────────────────────────────────────────
 export async function handleBackgroundMaintenance(projectArg) {
-    const markers = qualityMarkers(cortexPath);
+    const markers = qualityMarkers(getCortexPath());
     const startedAt = new Date().toISOString();
     try {
         const governance = await handleGovernMemories(projectArg, true);
-        const pruneResult = pruneDeadMemories(cortexPath, projectArg);
+        const pruneResult = pruneDeadMemories(getCortexPath(), projectArg);
         const pruneMsg = pruneResult.ok ? pruneResult.data : pruneResult.error;
         fs.writeFileSync(markers.done, new Date().toISOString() + "\n");
-        updateRuntimeHealth(cortexPath, {
+        updateRuntimeHealth(getCortexPath(), {
             lastGovernance: {
                 at: startedAt,
                 status: "ok",
                 detail: `projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}; ${pruneMsg}`,
             },
         });
-        appendAuditLog(cortexPath, "background_maintenance", `status=ok projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}`);
+        appendAuditLog(getCortexPath(), "background_maintenance", `status=ok projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}`);
     }
     catch (err) {
-        updateRuntimeHealth(cortexPath, {
+        updateRuntimeHealth(getCortexPath(), {
             lastGovernance: {
                 at: startedAt,
                 status: "error",
                 detail: err?.message || String(err),
             },
         });
-        appendAuditLog(cortexPath, "background_maintenance_failed", `error=${err?.message || String(err)}`);
+        appendAuditLog(getCortexPath(), "background_maintenance_failed", `error=${err?.message || String(err)}`);
     }
     finally {
         try {

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;