Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,44 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### Fixed

- **Two files given the same new name no longer stop the whole Move.** Two exports from the same
day, for example, could both be renamed to the same name in the same folder, and Organize refused
the run with "Cannot organize: 2 files have destination conflicts". The second file now gets a
number (`_1`), as it does when a file of that name is already in the folder, and Preview marks it
"Name taken — number added". If files still clash, the message lists their own names, not the
shared new name.
- **Correcting a file whose AI label already named the right folder now teaches StratoSort.** When
the label was right but the ranking put another folder first, the correction was saved without the
label, so two such corrections never changed later suggestions.
- **A short, accurate summary that uses a Smart Folder description's words is no longer erased.** It
was taken for a copy of the description: the summary or reason was removed, the confidence was cut
to 50% and the file could be held for review. Words that also appear in the file no longer count
as copied, and the reason may cite the folder's description, as the analysis asks it to. Real
copies of a description or of the instructions are still caught.
- **A label that paraphrases a folder name no longer goes to whichever folder was added first.**
With folders such as "GSC exports" and "Bing exports", a label like "Google Search Console
exports" matched every folder on the shared word "exports", and the first folder in the list won.
Words that several folder names share are now ignored, and a tie is decided by the folder
descriptions.
- **On a Mac, models are no longer unloaded and loaded again between files when the GPU check gives
no answer.** The model memory budget was based on free memory pages only, which macOS keeps low,
so a busy Mac could get a budget of a few hundred MB. It now uses the memory macOS reports as
available, and an Apple Silicon Mac is always treated as having its Metal GPU.
- **A Move the app refuses as a whole now says why.** When another run was still in progress, or the
batch was too large, the app said only "Check the logs for details" and listed every file as if
the run had ended before it. The reason is now shown in the run summary and on each file.
- **A card whose folder you changed no longer shows a confidence score.** The score was for
StratoSort's own choice, so beside your choice it looked like the app agreed with it.
- **On a Mac, messages name Finder instead of Explorer,** and a warning that the Uncategorized
folder could not be created points to System Settings > Privacy & Security instead of Windows
Security. The MCP copy buttons confirm with the app's name (Claude Desktop, Cursor, Zed) instead
of an internal id, and the Advanced settings text no longer says "Save to apply", since settings
save automatically.
- **Memory & Rules no longer says a typed rule applies to every file of that type.** A rule moves
its folder up when StratoSort already considers that folder for a file; two corrections teach a
firm change. The User Guide says the same.
- **The Zed MCP config matches the format in Zed's documentation.** It no longer includes a
`"source": "http"` entry.
- **Two identical files in one folder are no longer both sent to the trash when one run renames or
moves them.** Each was taken for a copy of the other that was already in place, so both were
removed instead of moved, and the run could then fail and be undone with the two files missing
Expand Down
12 changes: 8 additions & 4 deletions docs/USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,10 @@ folder for the next such file. Its card then gives the reason _You moved 2 simil
Undoing those moves takes it back, and so does moving as many such files away from your folder when
StratoSort suggests it.

To give a rule straight away, type it in **Settings > Performance > Memory & Rules** (see
[Performance](#performance)).
You can also type a rule in **Settings > Performance > Memory & Rules** (see
[Performance](#performance)). A rule moves its folder up for files of that type when that folder is
already one of the folders StratoSort considers for the file. It does not add a folder StratoSort
did not consider. For a firm change, make the two corrections described above.

---

Expand Down Expand Up @@ -227,8 +229,10 @@ See [MCP_SERVER.md](MCP_SERVER.md).
### Performance

- **Auto-organize**: Watch Downloads (and related routing).
- **Memory & Rules**: Type a rule such as "CSV files go to Reports" and it applies to every file of
that type. Your corrections are listed here too; edit or delete any that are wrong.
- **Memory & Rules**: Type a rule such as "CSV files go to Reports". It moves Reports up for CSV
files when Reports is already one of the folders StratoSort considers for them. Two corrections
teach a firm change (see [Teaching StratoSort](#teaching-stratosort)). Your corrections are listed
here too; edit or delete any that are wrong.
- **Background Mode**: Keep running in the tray.
- **Exclusion rules**: Skip paths or patterns from watchers and triage.
- **Processing limits** and **Search enrichment** (relationship expansion and the relationship index
Expand Down
8 changes: 7 additions & 1 deletion src/main/analysis/documentAnalysis.js
Original file line number Diff line number Diff line change
Expand Up @@ -1113,7 +1113,13 @@ async function analyzeDocumentStages(filePath, smartFolders = [], options = {},
});
const normalized = normalizeAnalysisResult(
{
...dropPromptEchoes(analysis, smartFolders),
// The file's own words are not echoes of a folder description
// that happens to use them too.
...dropPromptEchoes(
analysis,
smartFolders,
`${fileName || ''}\n${extractedTextForStorage || ''}`
),
llmSuggestedName: analysis.suggestedName || null,
contentLength: extractedTextLength,
extractionMethod: 'content',
Expand Down
72 changes: 52 additions & 20 deletions src/main/analysis/utils.js
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,9 @@ const ECHO_STOPWORDS = new Set(
)
);
const ECHO_FIELDS = ['summary', 'purpose', 'project', 'reasoning', 'type', 'entity'];
// The prompt asks for the reasoning to cite the chosen folder's description,
// so it is only checked against the schema instructions.
const ECHO_SCHEMA_ONLY_FIELDS = new Set(['reasoning']);
// A value is an echo when nearly all of its words come from one source text
// AND it reproduces a good part of that text. The second test keeps a real
// answer that merely shares vocabulary ("A logo for a company or
Expand Down Expand Up @@ -127,42 +130,71 @@ function echoWords(text) {
* guess so the file is flagged for review. Same idea as
* normalizeImageContentType, applied to the free-text fields.
*
* A well-described folder shares its vocabulary with the files that belong
* in it: a GSC export's summary names the same queries, clicks and
* impressions the folder's description lists. When the caller has the
* document's text, a word the document itself contains is the model reading
* the file, not the folder description, so it is not counted as copied from
* one. Callers without text (images, media) keep the stricter check. The
* schema instructions are generic words any long document contains, so
* they are always checked in full.
*
* @param {Record<string, any>} result - Model output (mutated copy returned)
* @param {Array<{ description?: string }>} [smartFolders]
* @param {string | null} [documentText] - The file's extracted text and name
* @returns {Record<string, any>}
*/
function dropPromptEchoes(result, smartFolders = []) {
function dropPromptEchoes(result, smartFolders = [], documentText = null) {
if (!result || typeof result !== 'object') return result;
const sources = [
// The instructions without their "(e.g., ...)" examples: an example like
// 'sunset_beach' is a legitimate thing for a picture to show.
...Object.values(ANALYSIS_SCHEMA_PROMPT)
/** @param {string[]} texts */
const toSources = (texts) =>
texts.map((text) => new Set(echoWords(text))).filter((source) => source.size > 0);
// The instructions without their "(e.g., ...)" examples: an example like
// 'sunset_beach' is a legitimate thing for a picture to show.
const schemaSources = toSources(
Object.values(ANALYSIS_SCHEMA_PROMPT)
.filter((v) => typeof v === 'string')
.map((v) => v.replace(/\(e\.g\.[^)]*\)/gi, ' ')),
...(Array.isArray(smartFolders) ? smartFolders : [])
.map((v) => v.replace(/\(e\.g\.[^)]*\)/gi, ' '))
);
const folderSources = toSources(
(Array.isArray(smartFolders) ? smartFolders : [])
.map((f) => f?.description)
.filter((d) => typeof d === 'string' && d.trim())
]
.map((text) => new Set(echoWords(text)))
.filter((source) => source.size > 0);
);
/** @type {Set<string>} */
const documentWords = new Set(
typeof documentText === 'string' && documentText ? echoWords(documentText) : []
);

/** @param {unknown} value */
const isEcho = (value) => {
if (typeof value !== 'string') return false;
// Compared without "(e.g., ...)" on both sides: a copied instruction
// carries its examples along.
const words = new Set(echoWords(value.replace(/\(e\.g\.[^)]*\)/gi, ' ')));
if (words.size < ECHO_MIN_WORDS) return false;
return sources.some((source) => {
/**
* @param {Set<string>} words
* @param {Set<string>[]} sources
* @param {Set<string>} [grounded] - Words not counted as shared
*/
const copiesAny = (words, sources, grounded) =>
sources.some((source) => {
let shared = 0;
for (const word of words) if (source.has(word)) shared += 1;
for (const word of words) if (source.has(word) && !grounded?.has(word)) shared += 1;
return (
shared / words.size >= ECHO_CONTAINMENT && shared / source.size >= ECHO_SOURCE_COVERAGE
);
});

/** @param {string} field */
const isEcho = (field) => {
const value = result[field];
if (typeof value !== 'string') return false;
// Compared without "(e.g., ...)" on both sides: a copied instruction
// carries its examples along.
const words = new Set(echoWords(value.replace(/\(e\.g\.[^)]*\)/gi, ' ')));
if (words.size < ECHO_MIN_WORDS) return false;
return (
copiesAny(words, schemaSources) ||
(!ECHO_SCHEMA_ONLY_FIELDS.has(field) && copiesAny(words, folderSources, documentWords))
);
};

const echoed = ECHO_FIELDS.filter((field) => isEcho(result[field]));
const echoed = ECHO_FIELDS.filter(isEcho);
if (echoed.length === 0) return result;

const cleaned = { ...result };
Expand Down
18 changes: 17 additions & 1 deletion src/main/core/customFolders.js
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,22 @@ async function probeFolder(op, label) {
}
}

/**
* What to tell the user when the Uncategorized folder cannot be created: the
* setting that most often blocks it on this OS.
* @param {NodeJS.Platform} [platform]
* @returns {string}
*/
function uncategorizedAccessHint(platform = process.platform) {
if (platform === 'win32') {
return "If Windows Security's Controlled folder access is on, allow StratoSort Stack through it.";
}
if (platform === 'darwin') {
return 'Check that StratoSort Stack is allowed in System Settings > Privacy & Security > Files and Folders.';
}
return 'Check that you can write to that folder.';
}

/**
* Create the directory for a new or healed Uncategorized entry. Never throws,
* and the entry always keeps `preferredPath`.
Expand Down Expand Up @@ -157,7 +173,7 @@ async function createUncategorizedDirectory(preferredPath) {
code: 'storage.uncategorized-unavailable',
subsystem: 'storage',
severity: 'warning',
message: `StratoSort could not create the Uncategorized folder at ${preferredPath}, so files that match no smart folder cannot be moved there. If Windows Security's Controlled folder access is on, allow StratoSort Stack through it.`,
message: `StratoSort could not create the Uncategorized folder at ${preferredPath}, so files that match no smart folder cannot be moved there. ${uncategorizedAccessHint()}`,
detail: { path: preferredPath, code: created.error?.code }
});
} catch {
Expand Down
26 changes: 20 additions & 6 deletions src/main/ipc/files/batchOrganizeHandler.js
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ const {
* @property {{ similarFile: string, similarity: number }} [_semanticDuplicate]
* @property {{ folder: string, path?: string, source?: string }} [suggestion] - What the
* app suggested before the user confirmed; a different landing folder is a correction
* @property {string} [analysisLabel] - The label the analysis gave the file, which a
* correction is recorded under when the history holds no different one
*/

/**
Expand Down Expand Up @@ -2322,14 +2324,21 @@ async function recordUndoAndUpdateDatabase(
const divergencesByPath = new Map(
(coordinatorResult?.divergences || []).map((d) => [d.filePath, d])
);
// What the app suggested for each file (Organize sends it per op).
// Keyed by where the file landed, like the divergences above.
// What the app suggested for each file, and the label the analysis
// gave it (Organize sends both per op). Keyed by where the file
// landed, like the divergences above.
/** @type {Map<string, { folder: string }>} */
const suggestionsByNewPath = new Map();
/** @type {Map<string, string>} */
const labelsByNewPath = new Map();
for (const c of Array.isArray(completedOperations) ? completedOperations : []) {
const suggested = batch?.operations?.[c?.index]?.suggestion;
if (typeof c?.destination === 'string' && typeof suggested?.folder === 'string') {
suggestionsByNewPath.set(c.destination, suggested);
if (typeof c?.destination !== 'string') continue;
const op = batch?.operations?.[c?.index];
if (typeof op?.suggestion?.folder === 'string') {
suggestionsByNewPath.set(c.destination, op.suggestion);
}
if (typeof op?.analysisLabel === 'string' && op.analysisLabel.trim()) {
labelsByNewPath.set(c.destination, op.analysisLabel);
}
}
let learned = 0;
Expand Down Expand Up @@ -2386,11 +2395,16 @@ async function recordUndoAndUpdateDatabase(
!isDefaultCategoryName(wrongFolder) &&
wrongFolder.toLowerCase() !== String(change.newSmartFolder).toLowerCase()
) {
// The correction is counted under the analysis label
// (findLearnedCorrection). With no divergence the history
// label already named this folder, while the engine ranked
// another first, so the label the op carries is used.
const didCorrect = await learningService.recordCorrection({
filePath: change.newPath,
wrongFolder,
correctFolder: change.newSmartFolder,
oldCategory: divergence?.oldCategory || null
oldCategory:
divergence?.oldCategory || labelsByNewPath.get(change.newPath) || null
});
if (didCorrect) corrected++;
}
Expand Down
6 changes: 5 additions & 1 deletion src/main/ipc/validationSchemas.js
Original file line number Diff line number Diff line change
Expand Up @@ -799,7 +799,11 @@ if (!z) {
source: fileOpPathSchema,
destination: fileOpPathSchema,
type: z.string().optional(),
suggestion: organizeSuggestionSchema
suggestion: organizeSuggestionSchema,
// The label the analysis gave the file; a correction is recorded under
// it. Listed for the same reason as `suggestion`. Organize leaves off a
// label longer than this rather than have the whole batch refused.
analysisLabel: z.string().max(255).optional()
});

const fileOperationSchema = z
Expand Down
41 changes: 30 additions & 11 deletions src/main/services/FolderMatchingService.js
Original file line number Diff line number Diff line change
Expand Up @@ -1971,29 +1971,48 @@ class FolderMatchingService {

// Token overlap scoring (simple, deterministic). Filler words and plain
// numbers do not count, so a shared "for", "data" or "2026" alone is not
// a match.
// a match. Nor does a word two or more folder names share: with "GSC
// exports", "Bing exports" and "Clarity exports", "exports" does not tell
// them apart, and counting it filed "Search Console exports" in whichever
// of them came first.
const nameTokensByFolder = folders.map((f) =>
overlapTokens(canon(String(f?.name || '').trim()))
);
/** @type {Map<string, number>} */
const foldersPerToken = new Map();
for (const nameTokens of nameTokensByFolder) {
for (const t of new Set(nameTokens)) {
foldersPerToken.set(t, (foldersPerToken.get(t) || 0) + 1);
}
}
const tokens = new Set(overlapTokens(rawCanon));
let best = null;
let bestScore = 0;
for (const f of folders) {
let bestShared = 0;
let tiedShared = false;
folders.forEach((f, index) => {
const name = String(f?.name || '').trim();
if (!name) continue;
const nameCanon = canon(name);
const nameTokens = overlapTokens(nameCanon);
if (nameTokens.length === 0) continue;
let score = 0;
const nameTokens = nameTokensByFolder[index];
if (!name || nameTokens.length === 0) return;
let shared = 0;
nameTokens.forEach((t) => {
if (tokens.has(t)) score += 1;
if (tokens.has(t) && (foldersPerToken.get(t) || 0) < 2) shared += 1;
});
if (shared === 0) return;
// Small bias for shorter names to avoid always matching long "Financial Documents" when raw is "Financial"
score -= Math.min(0.25, nameTokens.length * 0.01);
const score = shared - Math.min(0.25, nameTokens.length * 0.01);
if (shared === bestShared) tiedShared = true;
if (score > bestScore) {
if (shared > bestShared) tiedShared = false;
bestScore = score;
bestShared = shared;
best = name;
}
}
});

if (bestScore > 0.5 && best) {
// Two folders matching as many words each is a guess, not a match: the
// description step below can tell them apart, or nothing does.
if (bestScore > 0.5 && best && !tiedShared) {
logger.debug('[FolderMatching] Token overlap match', {
rawCategory: raw,
matchedFolder: best,
Expand Down
Loading
Loading