om-memory-system 4.17.0-next.124 → 4.19.1

package/dist/adapters/opencode/profile-learning.js

@@ -5,6 +5,7 @@ import { CONFIG, refreshConfigIfChanged } from "../../config.js";
 import { resolveOpencodeHostModel } from "../../services/ai/live-model-choice.js";
 import { userPromptManager } from "../../services/user-prompt/user-prompt-manager.js";
 import { userProfileManager } from "../../services/user-profile/user-profile-manager.js";
+import { saveProfile } from "../../services/user-profile/merge-and-save.js";
 import { sortProfileItems } from "../../utils/profile.js";
 import { truncateToMaxBytes } from "../../utils/context-limit.js";
 import { loadOpencodeProvider } from "./opencode-provider-loader.js";
@@ -29,7 +30,8 @@ async function runAutomaticProfileCleanup(userId) {
         const result = await aiCleanupProfile(profileData);
         if (result.diff.merged.length === 0 && result.diff.removed.length === 0)
             return;
-        const updated = await userProfileManager.updateProfile(profile.id, result.cleaned, 0, `Automatic AI cleanup: ${result.diff.merged.length} merged, ${result.diff.removed.length} removed`);
+        const summary = `Automatic AI cleanup: ${result.diff.merged.length} merged, ${result.diff.removed.length} removed`;
+        const updated = await saveProfile(profile, result.cleaned, summary);
         log("user-profile-learning: automatic cleanup complete", {
             userId,
             updated,
@@ -177,7 +179,7 @@ Rules:
                 if (validationSummary) {
                     changeSummary = changeSummary + "; " + validationSummary;
                 }
-                success = await userProfileManager.updateProfile(existingProfile.id, updatedProfileData, prompts.length, changeSummary);
+                success = await saveProfile(existingProfile, updatedProfileData, changeSummary, prompts.length);
                 if (!success) {
                     log("User profile update conflict, retrying", {
                         profileId: existingProfile.id,
@@ -188,13 +190,12 @@ Rules:
                 retries++;
             }
             if (!success) {
-                // Mark the batch anyway so the same prompts are not retried forever
-                // (token burn + repeated toasts on every subsequent idle).
+                // Keep the prompts for a later run; the backoff stops a retry on every idle.
                 log("User profile update conflict: exhausted retries", {
                     profileId: existingProfile?.id,
                     userId,
                 });
-                await userPromptManager.markMultipleAsUserLearningCaptured(prompts.map((p) => p.id));
+                recordProfileFailure("opencode", "user-profile-learning: conflict", new Error("conflict"));
                 return;
             }
             await userPromptManager.markMultipleAsUserLearningCaptured(prompts.map((p) => p.id));
@@ -664,5 +665,5 @@ If no clear chains, return { "paths": [] }.`;
         return;
     const data = JSON.parse(profile.profileData);
     data.learning_paths = result.paths;
-    await userProfileManager.updateProfile(profileId, data, 0, `Updated learning paths: ${result.paths.map((p) => p.topic).join(", ")}`);
+    await saveProfile(profile, data, `Updated learning paths: ${result.paths.map((p) => p.topic).join(", ")}`);
 }

package/dist/adapters/opencode/tui-status.js

@@ -1,6 +1,7 @@
+import { ommsStatusLabel } from "../../services/status-glyphs.js";
 import { availableUpdate, latestNpmVersion } from "../../services/update-check.js";
 export function tuiStatusText(state) {
-    const web = state.web === "offline" ? "omms:web app off" : `omms:${state.web}`;
+    const web = ommsStatusLabel(state.web === "offline" ? "web app off" : state.web);
     return state.update ? `${web} · ${state.update} available` : web;
 }
 /**

package/dist/adapters/pi/extension.js

@@ -13,6 +13,7 @@ import { registerPiHistoryImportCommand } from "./import-command.js";
 import { performPiProfileLearning } from "./profile.js";
 import { buildRetrievalSection, retrievalWrapperBytes, wrapRetrievalSection, } from "../../core/retrieval.js";
 import { DEFAULT_RETRIEVAL_MAX_TOKENS, tokensToByteCeiling } from "../../core/context-budget.js";
+import { ommsStatusLabel } from "../../services/status-glyphs.js";
 const GLOBAL_PLUGIN_WARMUP_KEY = Symbol.for("omms.plugin.warmedup");
 const GLOBAL_PI_BACKFILL_KEY = Symbol.for("omms.pi.backfill.scheduled");
 const OMMS_STATUS_KEY = "omms";
@@ -79,13 +80,13 @@ export default function ommsPiExtension(pi) {
     const startStatus = (ctx, status) => {
         const version = ++statusVersion;
         if (ctx.hasUI)
-            ctx.ui.setStatus(OMMS_STATUS_KEY, `omms:${status}`);
+            ctx.ui.setStatus(OMMS_STATUS_KEY, ommsStatusLabel(status));
         return version;
     };
     const finishStatus = (ctx, version, status) => {
         if (version !== statusVersion || !ctx.hasUI)
             return;
-        ctx.ui.setStatus(OMMS_STATUS_KEY, `omms:${status}`);
+        ctx.ui.setStatus(OMMS_STATUS_KEY, ommsStatusLabel(status));
     };
     const clearStatus = (ctx) => {
         statusVersion++;

package/dist/adapters/pi/profile.js

@@ -62,6 +62,7 @@ export async function performPiProfileLearning(input) {
         }
         const userId = tags.user.userEmail;
         const { userProfileManager } = await import("../../services/user-profile/user-profile-manager.js");
+        const { saveMergedProfile } = await import("../../services/user-profile/merge-and-save.js");
         const existing = await userProfileManager.getActiveProfile(userId);
         const resolveProfileModel = input.resolveProfileModel;
         const analyzer = resolveProfileModel
@@ -79,7 +80,7 @@ export async function performPiProfileLearning(input) {
             return;
         }
         if (existing && analysis.merged) {
-            const updated = await userProfileManager.updateProfile(existing.id, analysis.merged, input.prompts.length, `Pi analysis of ${input.prompts.length} prompts`);
+            const updated = await saveMergedProfile(userProfileManager, existing, analysis, input.prompts.length, `Pi analysis of ${input.prompts.length} prompts`);
             if (!updated) {
                 log("pi profile learning: update conflict", { profileId: existing.id });
                 return;

package/dist/cli/profile-cleanup-categories-command.js

@@ -71,14 +71,13 @@ export async function runProfileCleanupCategoriesCommand(argv, print = console.l
             return 0;
         }
         const result = await cleanup.applyCategoryCleanup(userId, {
-            version: preview.version,
             groups: preview.groups.map((group) => ({
                 labels: group.labels.map((entry) => entry.label),
                 name: group.name,
             })),
         }, deps);
         if (!result.ok)
-            throw new Error(`Cleanup not applied (${result.error}). Run the preview again.`);
+            throw new Error(`Cleanup not applied (${result.error}). Run the command again.`);
         print(`Renamed ${result.renamed} items.`);
         return 0;
     }

package/dist/cli/profile-normalise-categories-command.js

@@ -69,7 +69,7 @@ export async function runProfileNormaliseCategoriesCommand(argv, print = console
             print("Preview only. Run again with --yes to save.");
             return 0;
         }
-        const saved = await userProfileManager.updateProfile(profile.id, after, 0, `Normalised profile categories: ${changes} items renamed`);
+        const saved = await userProfileManager.updateProfile(profile.id, after, 0, `Normalised profile categories: ${changes} items renamed`, profile.version);
         if (!saved)
             throw new Error("Profile was modified by another session. Please retry.");
         print("Category renames saved. The previous snapshot remains in the profile changelog.");

package/dist/core/memory-operations.js

@@ -145,6 +145,7 @@ export async function executeMemoryOperation(args, context) {
                     };
                 }
                 const { userProfileManager } = await import("../services/user-profile/user-profile-manager.js");
+                const { saveMergedProfile } = await import("../services/user-profile/merge-and-save.js");
                 const userId = tags.user.userEmail || "unknown";
                 if (args.content !== undefined) {
                     const trimmed = args.content.trim();
@@ -172,8 +173,15 @@ export async function executeMemoryOperation(args, context) {
                     const existingProfile = await userProfileManager.getActiveProfile(userId);
                     if (existingProfile) {
                         const existingData = JSON.parse(existingProfile.profileData);
-                        const mergedData = await userProfileManager.mergeProfileData(existingData, { preferences: [newPreference] }, undefined, existingProfile.id);
-                        await userProfileManager.updateProfile(existingProfile.id, mergedData, 0, `Explicit preference added: ${sanitizedContent.slice(0, 80)}`);
+                        const raw = { preferences: [newPreference] };
+                        const mergedData = await userProfileManager.mergeProfileData(existingData, raw, undefined, existingProfile.id);
+                        const saved = await saveMergedProfile(userProfileManager, existingProfile, { raw, merged: mergedData }, 0, `Explicit preference added: ${sanitizedContent.slice(0, 80)}`);
+                        if (!saved) {
+                            return {
+                                success: false,
+                                error: "The profile changed while saving. Try again.",
+                            };
+                        }
                         return { success: true, message: "Preference saved to profile" };
                     }
                     await userProfileManager.createProfile(userId, tags.user.displayName || userId, tags.user.userName || userId, tags.user.userEmail || userId, { preferences: [newPreference], patterns: [], workflows: [] }, 0);

package/dist/importer/claude-hook-api.js

@@ -449,8 +449,8 @@ async function learnProfile(directory, deps) {
         const context = batch.map((prompt, index) => `${index + 1}. ${prompt.content}`).join("\n");
         const analysis = await analyzeProfile(model, context, existing ? { id: existing.id, profileData: existing.profileData } : null);
         if (existing) {
-            const updated = analysis.merged &&
-                (await userProfileManager.updateProfile(existing.id, analysis.merged, batch.length, `Claude Code analysis of ${batch.length} prompts`));
+            const { saveMergedProfile } = await import("../services/user-profile/merge-and-save.js");
+            const updated = await saveMergedProfile(userProfileManager, existing, analysis, batch.length, `Claude Code analysis of ${batch.length} prompts`);
             if (!updated)
                 throw new Error("Profile update conflict");
         }

package/dist/importer/profile-backlog.d.ts

@@ -3,7 +3,7 @@ import { type ProfileFailureCode } from "../core/profile-failure.js";
 import { userProfileManager } from "../services/user-profile/user-profile-manager.js";
 import { userPromptManager } from "../services/user-prompt/user-prompt-manager.js";
 export type BacklogPromptStore = Pick<typeof userPromptManager, "countUnanalyzedForUserLearning" | "getPromptsForUserLearning" | "markMultipleAsUserLearningCaptured"> & Partial<Pick<typeof userPromptManager, "skipTrivialPromptsForLearning">>;
-export type BacklogProfileStore = Pick<typeof userProfileManager, "getActiveProfile" | "createProfile" | "updateProfile">;
+export type BacklogProfileStore = Pick<typeof userProfileManager, "getActiveProfile" | "getProfileById" | "createProfile" | "mergeProfileData" | "updateProfile">;
 export interface DrainProfileBacklogOptions {
     user: {
         userEmail: string;

package/dist/importer/profile-backlog.js

@@ -1,5 +1,6 @@
 import { analyzeProfile } from "../core/profile-analysis.js";
 import { profileFailureCode } from "../core/profile-failure.js";
+import { saveMergedProfile } from "../services/user-profile/merge-and-save.js";
 import { userProfileManager } from "../services/user-profile/user-profile-manager.js";
 import { userPromptManager } from "../services/user-prompt/user-prompt-manager.js";
 /**
@@ -54,8 +55,8 @@ export async function drainProfileBacklog(options) {
                 const context = batch.map((item, index) => `${index + 1}. ${item.content}`).join("\n");
                 const analysis = await analyzeProfile(model, context, existing ? { id: existing.id, profileData: existing.profileData } : null);
                 if (existing) {
-                    if (!analysis.merged ||
-                        !(await profiles.updateProfile(existing.id, analysis.merged, batch.length, `${label} of ${batch.length} prompts`)))
+                    const summary = `${label} of ${batch.length} prompts`;
+                    if (!(await saveMergedProfile(profiles, existing, analysis, batch.length, summary)))
                         throw new Error("Profile update conflict");
                 }
                 else {

package/dist/importer/profile-import.d.ts

@@ -13,7 +13,7 @@ export interface ProfileImportReport {
     error?: string;
 }
 type PromptStore = Pick<typeof userPromptManager, "savePrompt" | "markAsCaptured" | "countUnanalyzedForUserLearning" | "getPromptsForUserLearning" | "markMultipleAsUserLearningCaptured" | "markForUserLearning">;
-type ProfileStore = Pick<typeof userProfileManager, "getActiveProfile" | "createProfile" | "updateProfile">;
+type ProfileStore = Pick<typeof userProfileManager, "getActiveProfile" | "getProfileById" | "createProfile" | "mergeProfileData" | "updateProfile">;
 type Ledger = Pick<ImportLedger, "get" | "begin" | "complete"> & Partial<Pick<ImportLedger, "peek">>;
 export interface ProfileImportOptions {
     host: MemoryHost;

package/dist/services/api-handlers.js

@@ -9,6 +9,7 @@ import { log } from "./logger.js";
 import { countKeywords } from "./keyword-counts.js";
 import { CONFIG } from "../config.js";
 import { userPromptManager } from "./user-prompt/user-prompt-manager.js";
+import { saveProfile } from "./user-profile/merge-and-save.js";
 import { sortProfileItems, stripProfileVectors } from "../utils/profile.js";
 import { resolveWebProfileUserId } from "./profile-identity.js";
 async function getAllMemoryShards() {
@@ -863,8 +864,7 @@ export async function handleRefreshProfile(userId) {
             const pData = JSON.parse(profile.profileData);
             const { data: decayed, hasChanges } = userProfileManager.decayInMemory(pData);
             if (hasChanges) {
-                await userProfileManager.updateProfile(profile.id, decayed, 0, "Applied confidence decay");
-                decayApplied = true;
+                decayApplied = await saveProfile(profile, decayed, "Applied confidence decay");
             }
         }
         const unanalyzedCount = await userPromptManager.countUnanalyzedForUserLearning();
@@ -1054,7 +1054,7 @@ export async function handleApplyCleanup(userId, body) {
             explicitAcceptance,
         });
         const partial = (pending.includeIds && pending.includeIds.length > 0) || explicitAcceptance;
-        const success = await userProfileManager.updateProfile(profile.id, result, 0, partial ? "AI cleanup applied (partial)" : "AI cleanup applied");
+        const success = await saveProfile(profile, result, partial ? "AI cleanup applied (partial)" : "AI cleanup applied");
         if (!success) {
             return { success: false, error: "Profile was modified by another session. Please retry." };
         }
@@ -1108,14 +1108,14 @@ export async function handleCategoryCleanupApply(userId, body, deps) {
         const { applyCategoryCleanup } = await import("./user-profile/category-cleanup.js");
         const { clearCategoryCleanupJob } = await import("./user-profile/category-cleanup-job.js");
         const user = await categoryCleanupUser(userId);
-        const result = await applyCategoryCleanup(user, { version: body?.version, groups: body?.groups }, deps);
+        const result = await applyCategoryCleanup(user, { groups: body?.groups }, deps);
         if (result.ok) {
             // The finished preview no longer matches the profile.
             clearCategoryCleanupJob(user);
             return { success: true, data: { renamed: result.renamed } };
         }
         const messages = {
-            stale: "Profile changed since the preview. Build a new preview.",
+            stale: "Profile saved at the same moment. Try Apply again.",
             no_profile: "No profile found to clean up",
             invalid: "Each group needs at least two labels and a name.",
         };
@@ -1243,7 +1243,7 @@ export async function handleUpdateProfileItem(body) {
         const changeSummary = action === "delete"
             ? `Deleted ${type.slice(0, -1)} at index ${index}`
             : `Edited ${type.slice(0, -1)} at index ${index}`;
-        const success = await userProfileManager.updateProfile(profile.id, profileData, 0, changeSummary);
+        const success = await saveProfile(profile, profileData, changeSummary);
         if (!success)
             return { success: false, error: "Profile was modified by another session. Please retry." };
         return {

package/dist/services/profile-admin.d.ts

@@ -4,7 +4,7 @@ export interface ProfileAdminStore {
     getAllActiveProfiles(): Promise<UserProfile[]>;
     getProfileById(id: string): Promise<UserProfile | null>;
     mergeProfileData(existing: UserProfileData, updates: Partial<UserProfileData>, embedService?: undefined, profileId?: string): Promise<UserProfileData>;
-    updateProfile(profileId: string, profileData: UserProfileData, additionalPromptsAnalyzed: number, changeSummary: string): Promise<boolean>;
+    updateProfile(profileId: string, profileData: UserProfileData, additionalPromptsAnalyzed: number, changeSummary: string, expectedVersion: number): Promise<boolean>;
     deactivateProfile(profileId: string): Promise<boolean>;
 }
 export interface ProfileSummary {

package/dist/services/profile-admin.js

@@ -44,7 +44,7 @@ export async function mergeProfiles(store, sourceId, targetId) {
         throw new ProfileAdminError("Both profiles must exist and be active", 404);
     }
     const merged = await store.mergeProfileData(parse(target), parse(source), undefined, target.id);
-    const saved = await store.updateProfile(target.id, merged, source.totalPromptsAnalyzed, `Merged profile ${source.userId}`);
+    const saved = await store.updateProfile(target.id, merged, source.totalPromptsAnalyzed, `Merged profile ${source.userId}`, target.version);
     if (!saved)
         throw new ProfileAdminError("Profile was changed by another session. Retry.", 409);
     await store.deactivateProfile(source.id);

package/dist/services/status-glyphs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Footer label for the Pi and OpenCode adapters. Claude Code cannot import
+ * from `src/`, so `hooks/omms-status-glyphs.js` holds a twin of this file and
+ * `tests/status-glyph-parity.test.ts` keeps the two equal.
+ *
+ * Each glyph is a one-column text symbol. Never append U+FE0F: it asks the
+ * terminal for a two-column colour emoji.
+ */
+export declare const STATUS_GLYPHS: {
+    readonly warming: "⧖";
+    readonly connected: "✔";
+    readonly recalling: "↻";
+    readonly capturing: "✎";
+    readonly error: "✘";
+};
+export type StatusGlyphState = keyof typeof STATUS_GLYPHS;
+/** States that need an action keep their words after the error glyph. */
+export type StatusWordState = "web app off" | "not installed";
+export declare function ommsStatusLabel(state: StatusGlyphState | StatusWordState): string;

package/dist/services/status-glyphs.js

@@ -0,0 +1,21 @@
+/**
+ * Footer label for the Pi and OpenCode adapters. Claude Code cannot import
+ * from `src/`, so `hooks/omms-status-glyphs.js` holds a twin of this file and
+ * `tests/status-glyph-parity.test.ts` keeps the two equal.
+ *
+ * Each glyph is a one-column text symbol. Never append U+FE0F: it asks the
+ * terminal for a two-column colour emoji.
+ */
+export const STATUS_GLYPHS = {
+    warming: "⧖",
+    connected: "✔",
+    recalling: "↻",
+    capturing: "✎",
+    error: "✘",
+};
+export function ommsStatusLabel(state) {
+    if (state === "web app off" || state === "not installed") {
+        return `omms: ${STATUS_GLYPHS.error} ${state}`;
+    }
+    return `omms: ${STATUS_GLYPHS[state]}`;
+}

package/dist/services/user-profile/category-cleanup-store.d.ts

@@ -6,3 +6,14 @@ export declare function latestOpenCleanup(profileId: string): Promise<{
     renames: CategoryRename[];
 } | null>;
 export declare function markCleanupUndone(id: number): Promise<void>;
+/** What the profile model answered for one group: the labels it kept and the name it proposed. */
+export interface SavedVerdict {
+    keep: string[];
+    name: string | null;
+}
+export declare const VERDICT_MAX_AGE_MS: number;
+/** Saves the answers by group id. Only category names are stored, never descriptions. */
+export declare function saveVerdicts(profileId: string, verdicts: Map<string, SavedVerdict>, now?: number): Promise<void>;
+export declare function loadVerdicts(profileId: string): Promise<Map<string, SavedVerdict>>;
+/** Deletes the profile's answers that are too old or belong to a group that no longer exists. */
+export declare function pruneVerdicts(profileId: string, currentGroupIds: Iterable<string>, maxAgeMs?: number, now?: number): Promise<void>;

package/dist/services/user-profile/category-cleanup-store.js

@@ -2,7 +2,10 @@ import { join } from "node:path";
 import { CONFIG } from "../../config.js";
 import { tursoConnectionManager } from "../turso/connection-manager.js";
 import { USER_PROFILES_DB_NAME } from "./user-profile-manager.js";
-/** Undo records for category cleanups. The profile changelog keeps too few entries for undo. */
+/**
+ * Undo records for category cleanups (the profile changelog keeps too few entries for undo)
+ * and the profile model's saved verdicts per group, so a new preview asks only about new groups.
+ */
 async function connection() {
     const db = await tursoConnectionManager.getConnection(join(CONFIG.storagePath || "", USER_PROFILES_DB_NAME));
     await db.execute(`CREATE TABLE IF NOT EXISTS profile_category_cleanups (
@@ -11,6 +14,14 @@ async function connection() {
     created_at INTEGER NOT NULL,
     renames TEXT NOT NULL,
     undone_at INTEGER
+  )`);
+    await db.execute(`CREATE TABLE IF NOT EXISTS profile_category_verdicts (
+    profile_id TEXT NOT NULL,
+    group_id TEXT NOT NULL,
+    keep TEXT NOT NULL,
+    name TEXT,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (profile_id, group_id)
   )`);
     return db;
 }
@@ -33,3 +44,48 @@ export async function markCleanupUndone(id) {
         id,
     ]);
 }
+export const VERDICT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const DELETE_CHUNK = 200;
+/** Saves the answers by group id. Only category names are stored, never descriptions. */
+export async function saveVerdicts(profileId, verdicts, now = Date.now()) {
+    const db = await connection();
+    for (const [groupId, verdict] of verdicts) {
+        await db.execute("INSERT OR REPLACE INTO profile_category_verdicts (profile_id, group_id, keep, name, created_at) VALUES (?, ?, ?, ?, ?)", [profileId, groupId, JSON.stringify(verdict.keep), verdict.name, now]);
+    }
+}
+export async function loadVerdicts(profileId) {
+    const db = await connection();
+    const rows = await db.all("SELECT group_id, keep, name FROM profile_category_verdicts WHERE profile_id = ?", [profileId]);
+    const verdicts = new Map();
+    for (const row of rows) {
+        let keep;
+        try {
+            keep = JSON.parse(String(row.keep));
+        }
+        catch {
+            continue;
+        }
+        // A row that is not a list of names is skipped, so its group is asked again.
+        if (!Array.isArray(keep))
+            continue;
+        verdicts.set(String(row.group_id), {
+            keep: keep.filter((label) => typeof label === "string"),
+            name: row.name == null ? null : String(row.name),
+        });
+    }
+    return verdicts;
+}
+/** Deletes the profile's answers that are too old or belong to a group that no longer exists. */
+export async function pruneVerdicts(profileId, currentGroupIds, maxAgeMs = VERDICT_MAX_AGE_MS, now = Date.now()) {
+    const db = await connection();
+    await db.execute("DELETE FROM profile_category_verdicts WHERE profile_id = ? AND created_at < ?", [profileId, now - maxAgeMs]);
+    const current = new Set(currentGroupIds);
+    const rows = await db.all("SELECT group_id FROM profile_category_verdicts WHERE profile_id = ?", [
+        profileId,
+    ]);
+    const gone = rows.map((row) => String(row.group_id)).filter((id) => !current.has(id));
+    for (let start = 0; start < gone.length; start += DELETE_CHUNK) {
+        const chunk = gone.slice(start, start + DELETE_CHUNK);
+        await db.execute(`DELETE FROM profile_category_verdicts WHERE profile_id = ? AND group_id IN (${chunk.map(() => "?").join(",")})`, [profileId, ...chunk]);
+    }
+}

package/dist/services/user-profile/category-cleanup.d.ts

@@ -1,4 +1,5 @@
 import { type CategoryGroup } from "./category-groups.js";
+import { type SavedVerdict } from "./category-cleanup-store.js";
 import type { UserProfileManager } from "./user-profile-manager.js";
 export declare const GROUPS_PER_MODEL_CALL = 20;
 export declare const MAX_EXAMPLES_PER_LABEL = 3;
@@ -16,14 +17,20 @@ export interface NamedGroup extends CategoryGroup {
     /** False when the model did not check this group and the most used label was chosen. */
     checked: boolean;
 }
+/** The model's saved answers by group id, and where to save new ones. */
+export interface VerdictCache {
+    saved: Map<string, SavedVerdict>;
+    save: (verdicts: Map<string, SavedVerdict>) => Promise<void>;
+}
 /**
  * The profile model checks each group in batches: it removes names that do not belong
- * and proposes one name. A failed batch, a missing reply, or no model falls back to the
- * most used label and marks the group unchecked. The log holds counts and codes only.
+ * and proposes one name. A group with a saved answer skips the model. A failed batch, a
+ * missing reply, or no model falls back to the most used label, marks the group unchecked
+ * and saves nothing, so a later preview retries it. The log holds counts and codes only.
  */
 export declare function checkAndNameGroups(groups: CategoryGroup[], examples: Map<string, string[]>, model: CleanupModel | null, 
-/** Called with batches done and the total, before the first batch and after each one. */
-onProgress?: (done: number, total: number) => void): Promise<NamedGroup[]>;
+/** Called with batches to run and the total, before the first batch and after each one. */
+onProgress?: (done: number, total: number) => void, cache?: VerdictCache): Promise<NamedGroup[]>;
 /** The host model when one is registered, else the external API, else none. */
 export declare function resolveCleanupModel(): Promise<CleanupModel | null>;
 export interface CleanupDeps {
@@ -38,7 +45,6 @@ export interface CleanupDeps {
 }
 export interface CategoryCleanupPreview {
     profileId: string;
-    version: number;
     /** Distinct categories now, and if every group were accepted. */
     before: number;
     after: number;
@@ -65,9 +71,12 @@ export type UndoResult = {
 };
 /** Builds the groups for review. Changes nothing in the stored profile. */
 export declare function previewCategoryCleanup(userId: string, deps?: CleanupDeps): Promise<CategoryCleanupPreview | null>;
-/** Renames the categories of the accepted groups; refuses when the profile changed since the preview. */
+/**
+ * Renames the categories of the accepted groups on the profile as stored now. Learning may
+ * have saved newer versions since the preview; the rename goes by label, so that is safe.
+ * It refuses only when a save lands between the read and the write below.
+ */
 export declare function applyCategoryCleanup(userId: string, input: {
-    version: number;
     groups: AcceptedGroup[];
 }, deps?: CleanupDeps): Promise<ApplyResult>;
 /** Restores the categories of the newest cleanup that is not undone yet. */