om-memory-system 4.14.0-next.106 → 4.15.0-next.116

package/README.md

@@ -1,191 +1,148 @@
+<p align="center">
+  <img src=".github/screenshots/omms-logo.png" alt="OMMS logo" width="96" height="96" />
+</p>
+
 # OMMS: Opinionated Modular Memory System
 
 [![npm version](https://img.shields.io/npm/v/om-memory-system.svg)](https://www.npmjs.com/package/om-memory-system)
 [![npm downloads](https://img.shields.io/npm/dm/om-memory-system.svg)](https://www.npmjs.com/package/om-memory-system)
-[![license](https://img.shields.io/npm/l/om-memory-system.svg)](https://www.npmjs.com/package/om-memory-system)
+[![MIT licence](https://img.shields.io/npm/l/om-memory-system.svg)](LICENSE.md)
+
+OMMS gives AI coding agents long-term project memory. It captures technical
+work, recalls relevant notes in later sessions and learns your working
+preferences. One shared engine serves **OpenCode**, **Pi** and **Claude Code**,
+so each host can retrieve memories captured by the others in the same project.
 
-![OMMS banner](.github/banner.png)
+Memories are stored locally, by default in `~/.omms/data`. Embeddings run
+locally by default; the first use downloads a search model. Capture and profile
+learning make additional model calls that can send conversation content to your
+chosen provider and incur costs. Remote embeddings are optional. OMMS removes
+text inside `<private>` tags before storage. See [Configuration](docs/configuration.md)
+for model choices and privacy controls.
 
-OMMS gives your AI coding agent a long-term memory. As you work, it writes
-short notes about what was done and decided in each project: fixes, design
-choices, things that did not work. It brings the relevant notes back in later
-sessions, so the agent does not start from zero every time. It also learns how
-you like to work and keeps that as a user profile.
+## Set up
 
-It runs inside [OpenCode](https://opencode.ai) and the
+Use Node.js **22.14 or later** for the terminal command and Claude Code hooks.
+OpenCode v1 needs **1.18.29 or later**. OMMS also supports OpenCode v2 and the
 [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent).
-Both share one memory per project, so a note written in one is available in
-the other. Everything is stored locally on your machine.
 
-Claude Code is also supported, through a plugin of hooks. It needs Node.js and
-your own external API for capture. A global install is optional. See the
-[Claude Code adapter](docs/claude-code-adapter.md) guide.
+> Automatic history import is enabled by default and makes model calls.
+> To disable it before your first session, set `"autoBackfill": false` in
+> `~/.config/omms/omms.jsonc`. See [Automatic import](docs/web-ui-memory.md#automatic-import).
 
-## What it does
+### OpenCode
 
-- **Remembers automatically.** After each piece of work, a background model
-  call summarises it into a memory. You do not have to ask.
-- **Recalls when relevant.** Matching memories are added to the agent's
-  context: on every prompt in OpenCode v2 and Pi, at the start of a session in
-  OpenCode v1.
-- **Learns your preferences.** A user profile of your habits builds up over
-  time and follows you across projects.
-- **Imports your past sessions.** Pi and OpenCode import older history after
-  startup. A command gives you a preview and manual control.
-- **Lets you look and edit.** A local web page shows every memory and your
-  profile.
-- **Keeps private things private.** Text inside `<private>` tags is never
-  stored.
+Add the package to `~/.config/opencode/opencode.json`. Keep your existing settings.
+On Windows, use `%USERPROFILE%\.config\opencode\opencode.json`.
 
-![Project memory timeline](.github/screenshot-project-memory.png)
+**OpenCode v2:**
 
-![User profile viewer](.github/screenshot-user-profile.png)
+```json
+{ "plugins": ["om-memory-system"] }
+```
 
-## Before you start
+**OpenCode v1:**
 
-You need one of:
+```json
+{ "plugin": ["om-memory-system"] }
+```
 
-- **OpenCode** 1.18.29 or later (v1 plugin API) or OpenCode v2
-- **Pi coding agent**
-- **Claude Code**, through a plugin of hooks. Capture needs your own external API. See
-  the [Claude Code adapter](docs/claude-code-adapter.md) guide for setup.
+OpenCode v2 also supports:
 
-Nothing else is required. OMMS brings its own database. On first use it
-downloads a small embedding model (the part that makes memories searchable),
-so you need internet access once. The terminal import command also needs
-Node.js 22.14 or later.
+```bash
+opencode plugin add om-memory-system
+```
 
-## Set up
+Restart OpenCode. The [OpenCode guide](docs/opencode-adapter.md#installation)
+covers plugin management and its additional `cli.json` configuration.
 
-### 1. Install
+### Pi
+
+```bash
+pi install npm:om-memory-system
+```
 
-**OpenCode.** Add `om-memory-system` to `~/.config/opencode/opencode.json`
-(on Windows, `%USERPROFILE%\.config\opencode\opencode.json`):
+Restart Pi. See the [Pi guide](docs/pi-adapter.md).
 
-```jsonc
-// OpenCode v2
-{ "plugins": ["om-memory-system"] }
+### Claude Code
 
-// OpenCode v1
-{ "plugin": ["om-memory-system"] }
-```
+Install the OMMS plugin using the [Claude Code guide](docs/claude-code-adapter.md#installation).
+Capture and profile learning require a configured external API; retrieval and
+manual memory operations remain available without it. A global npm install is optional.
 
-On OpenCode v2 you can run `opencode plugin add om-memory-system` instead.
-Restart OpenCode.
+### Model and web app
 
-**Pi.** Run:
+With no model settings, OpenCode and Pi use the session model. You can choose a
+host model or configure an external API under **Settings**. Claude Code uses
+only the external API. See [Choosing the model](docs/configuration.md#choosing-the-model)
+for the selection order and credentials.
 
-```bash
-pi install npm:om-memory-system
-```
+Start a host session, then open [http://127.0.0.1:4747](http://127.0.0.1:4747).
+Each host starts the shared web app when needed, unless it is disabled. Browse
+captured notes on **Project memories**, or ask your agent to search memory for
+an earlier decision.
 
-Restart Pi. You can install OMMS in both agents; they share the same memory.
+### Terminal command (optional)
 
-**Terminal command (optional).** A global install puts the `om-memory-system`
-command on your `PATH`. You do not need it. OMMS runs the newest copy it finds on
-the machine, so updating one host is enough. A global install from 4.3 or earlier
-needs one update. See
-[Updating and upgrading](docs/upgrading.md#one-update-updates-every-host).
-To install it:
+A global install puts `om-memory-system` on your `PATH`:
 
 ```bash
-npm i -g om-memory-system      # or: bun add -g om-memory-system
+npm install -g om-memory-system
 om-memory-system --version
 ```
 
-### 2. Choose which model writes memories (optional)
-
-With no settings, OMMS uses the model of the session you are working in. To
-use a different one, add it to `~/.config/omms/omms.jsonc`. If you have no
-config file yet, OMMS creates this one with comments on first start.
-
-```jsonc
-{
-  // A model you are already signed in to in OpenCode or Pi.
-  // Use "inherit" to always follow the session's model.
-  "opencodeProvider": "openai",
-  "opencodeModel": "gpt-5.6-luna",
-  "piProvider": "openai-codex",
-  "piModel": "gpt-5.6-luna",
-}
-```
+See the [CLI reference](docs/cli.md) for manual memory operations and history imports.
 
-You can also use any OpenAI-compatible or Anthropic API with your own key, set
-up on the Settings page's **External API** card, and choose `"external"` as a
-host's model. See [Configuration](docs/configuration.md#choosing-the-model).
+## Inside OMMS
 
-### 3. Check it works
+These screenshots use synthetic examples and configuration. All visible prompts,
+code snippets and outcomes are made up for the demonstration.
 
-Work normally for a few turns, then open `http://127.0.0.1:4747` in your
-browser. OpenCode or the login web app serves this page. New memories appear
-on the timeline. You can also ask the agent: "search memory for what we changed today".
+### Project memories
 
-## Import your past history
+Browse captured notes alongside example user input and technical outcomes.
 
-Older sessions import automatically after a host starts. This makes model
-calls. To turn it off, set `"autoBackfill": false` in
-`~/.config/omms/omms.jsonc` before you start the agent. For a manual import or
-a custom source, preview it inside the agent:
+![Project memories with synthetic English prompts, code and outcomes](.github/screenshots/project-memories.png)
 
-```text
-/memory-import-opencode-history --dry-run
-/memory-import-pi-history --dry-run
-```
+### Memory
+
+Review history imports, manage profile learning and set memory limits. This page
+also helps resolve missing project folders.
+
+![Memory page with synthetic import and profile examples](.github/screenshots/memory.png)
+
+### Settings
+
+Choose models and manage access. Diagnostics show capture outcomes and component health.
 
-The preview shows how many model calls a real import needs. It uses the
-session's model; add `--model provider/id` for a cheaper one. There is also a
-terminal version, `npx om-memory-system`, that uses an API key. See the
-[OpenCode](docs/opencode-history-import.md) and [Pi](docs/pi-history-import.md)
-import guides, and the [CLI reference](docs/cli.md).
-
-## Keeping OMMS up to date
-
-Pi shows a notice when a new version is out; update with
-`pi update npm:om-memory-system`. On OpenCode v2, the footer shows when a new version is out;
-run `opencode plugin update om-memory-system`. Restart the agent afterwards.
-[UPDATES.md](UPDATES.md) explains how updates work on every host.
-To stay on one version, install it with the number, for example
-`pi install npm:om-memory-system@3.1.1` or
-`opencode plugin add om-memory-system@3.1.1`; a pinned install is never
-updated. Coming from `opencode-mem`? Your memories move over automatically, with a
-backup first. See [Updating and upgrading](docs/upgrading.md) and
-[CHANGELOG.md](CHANGELOG.md).
+![Settings page with synthetic model configuration](.github/screenshots/settings.png)
 
 ## Documentation
 
-| Read this                                                        | To learn about                                                   |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
-| [Using memory day to day](docs/using-memory.md)                  | How capture and recall work, the `memory` tool, the user profile |
-| [Configuration](docs/configuration.md)                           | Settings, choosing the model, embeddings, troubleshooting        |
-| [Web UI](docs/web-ui.md)                                         | The memory explorer, opening it on a network safely              |
-| [Settings page](docs/web-ui-settings.md)                         | Every card and control on the web Settings page                  |
-| [Moving projects](docs/moving-projects.md)                       | Nested repositories, moved folders, backup and restore           |
-| [Updating and upgrading](docs/upgrading.md)                      | Updates, pinning a version, older stores                         |
-| [OpenCode adapter](docs/opencode-adapter.md)                     | How the OpenCode plugin hooks in                                 |
-| [Pi adapter](docs/pi-adapter.md)                                 | How the Pi extension hooks in                                    |
-| [Claude Code adapter](docs/claude-code-adapter.md)               | Installing the Claude Code plugin, hooks, the `memory` command   |
-| [OpenCode history import](docs/opencode-history-import.md)       | Importing past OpenCode sessions                                 |
-| [Pi history import](docs/pi-history-import.md)                   | Importing past Pi sessions, moving machines                      |
-| [Claude Code history import](docs/claude-code-history-import.md) | Importing past Claude Code transcripts                           |
-| [CLI reference](docs/cli.md)                                     | The `om-memory-system` terminal command                          |
-| [Migrating from opencode-mem](docs/omms-migration.md)            | What changes when upgrading from the original plugin             |
-| [For developers](docs/developers.md)                             | Building, testing, the public `tags` export, architecture        |
-| [Contributing](CONTRIBUTING.md)                                  | How to set up, test, and send a pull request                     |
-
-## About this fork
-
-OMMS is [`cmdaltctr/omms`](https://github.com/cmdaltctr/omms), a fork of
-[`tickernelz/opencode-mem`](https://github.com/tickernelz/opencode-mem),
-published on npm as `om-memory-system`. The fork runs the memory engine as a
-shared core for both OpenCode and Pi (see [shared core](docs/shared-core.md)).
-Existing OpenCode memories and settings keep working.
-
-## License and links
-
-MIT License. See [LICENSE.md](LICENSE.md).
-
-- Repository: https://github.com/cmdaltctr/omms
-- Upstream: https://github.com/tickernelz/opencode-mem
-- Issues: https://github.com/cmdaltctr/omms/issues
-
-Inspired by [opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory).
+| Guide                                       | Covers                                                       |
+| ------------------------------------------- | ------------------------------------------------------------ |
+| [Using memory](docs/using-memory.md)        | Daily use, capture, recall and the user profile              |
+| [Web UI](docs/web-ui.md)                    | Starting the app, browsing memories and safe network access  |
+| [Memory page](docs/web-ui-memory.md)        | History imports, profile actions, limits and missing folders |
+| [Settings page](docs/web-ui-settings.md)    | Models, credentials, diagnostics and profile identities      |
+| [Configuration](docs/configuration.md)      | Config files, model selection, privacy and embeddings        |
+| [Moving projects](docs/moving-projects.md)  | Folder moves, backup and restore                             |
+| [Updating and upgrading](docs/upgrading.md) | Updates, version pinning and older stores                    |
+| [CLI reference](docs/cli.md)                | Terminal commands                                            |
+| [For developers](docs/developers.md)        | Building, testing and architecture                           |
+| [Contributing](CONTRIBUTING.md)             | Development workflow and pull requests                       |
+
+History import guides: [OpenCode](docs/opencode-history-import.md),
+[Pi](docs/pi-history-import.md) and [Claude Code](docs/claude-code-history-import.md).
+See [UPDATES.md](UPDATES.md) for host update commands and
+[CHANGELOG.md](CHANGELOG.md) for release changes. Existing `opencode-mem` users
+can follow the [migration guide](docs/omms-migration.md).
+
+## Licence
+
+MIT. See [LICENSE.md](LICENSE.md) for copyright and attribution, and
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for bundled dependencies.
+
+[Repository](https://github.com/cmdaltctr/omms) ·
+[Issues](https://github.com/cmdaltctr/omms/issues) ·
+[Documentation index](docs/README.md)

package/dist/adapters/claude-code/hook-command.d.ts

@@ -4,4 +4,6 @@ import { type ClaudeStatusOptions } from "./status.js";
  * `om-memory-system claude-hook <event>`. Always returns 0: a hook must never
  * block or break a Claude Code session, whatever goes wrong.
  */
-export declare function runClaudeHookCommand(argv: string[], io?: ClaudeHookOptions & ClaudeStatusOptions): Promise<number>;
+export declare function runClaudeHookCommand(argv: string[], io?: ClaudeHookOptions & ClaudeStatusOptions & {
+    skipSelfUpdate?: boolean;
+}): Promise<number>;

package/dist/adapters/claude-code/hook-command.js

@@ -9,6 +9,18 @@ async function printStatus(io) {
     const status = await buildClaudeStatus({ ...inputs, fetch: io.fetch ?? globalThis.fetch });
     (io.writeStdout ?? ((text) => process.stdout.write(text)))(`${JSON.stringify(status)}\n`);
 }
+/** Update the Claude plugin in the background when npm has a newer release. Never throws. */
+async function selfUpdate(io) {
+    try {
+        const { startPluginSelfUpdate, pluginSelfUpdateDeps } = await import("./plugin-self-update.js");
+        const log = io.log ??
+            (async (message, data) => (await import("../../services/logger.js")).log(message, data));
+        await startPluginSelfUpdate(pluginSelfUpdateDeps(log));
+    }
+    catch {
+        /* The memory hook already ran; a failed update check changes nothing. */
+    }
+}
 /**
  * `om-memory-system claude-hook <event>`. Always returns 0: a hook must never
  * block or break a Claude Code session, whatever goes wrong.
@@ -22,6 +34,8 @@ export async function runClaudeHookCommand(argv, io = {}) {
         }
         if (isHookEvent(event)) {
             await runClaudeHook(event, io);
+            if (event === "session-start" && !io.skipSelfUpdate)
+                await selfUpdate(io);
             return 0;
         }
         // Only a known name reaches the log; argv is not trusted text.

package/dist/adapters/claude-code/plugin-self-update.d.ts

@@ -0,0 +1,27 @@
+/** A second session does not start another update for the same release within this time. */
+export declare const SELF_UPDATE_RETRY_MS: number;
+export type PluginSelfUpdateCode = "started" | "current" | "recent" | "disabled" | "no-plugin" | "unreadable-plugin" | "unreachable" | "spawn-failed";
+export interface PluginSelfUpdateDeps {
+    /** False when `OMMS_DISABLE_UPDATE_CHECK` is `1`. */
+    enabled: boolean;
+    /** `CLAUDE_PLUGIN_ROOT`; undefined outside a Claude plugin. */
+    pluginRoot: string | undefined;
+    readPluginVersion: (root: string) => string;
+    fetch: typeof fetch;
+    now: () => number;
+    readMarker: () => {
+        version: string;
+        startedAt: number;
+    } | null;
+    writeMarker: (value: {
+        version: string;
+        startedAt: number;
+    }) => void;
+    /** Start a process that outlives this hook. */
+    spawnDetached: (command: string, args: string[]) => void;
+    log: (message: string, data: Record<string, unknown>) => void | Promise<void>;
+}
+/** Start a background plugin update when npm has a newer release. Never throws. */
+export declare function startPluginSelfUpdate(deps: PluginSelfUpdateDeps): Promise<PluginSelfUpdateCode>;
+/** Production inputs: the real plugin manifest, npm, and a marker file in ~/.omms. */
+export declare function pluginSelfUpdateDeps(log: PluginSelfUpdateDeps["log"], env?: NodeJS.ProcessEnv): PluginSelfUpdateDeps;

package/dist/adapters/claude-code/plugin-self-update.js

@@ -0,0 +1,103 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { availableUpdate, latestNpmVersion } from "../../services/update-check.js";
+// Claude Code installs the OMMS plugin from the `stable` branch, but its own
+// update pass runs at its own time and can leave a new session on the old
+// plugin. At session start OMMS compares the plugin with npm `latest` and, when
+// it is older, runs Claude Code's own update commands in the background. The
+// new copy loads in the next session or after /reload-plugins.
+/** A second session does not start another update for the same release within this time. */
+export const SELF_UPDATE_RETRY_MS = 30 * 60 * 1000;
+/** Node script that refreshes the marketplace, then updates the plugin. Run detached. */
+const UPDATE_SCRIPT = `
+const { spawnSync } = require("node:child_process");
+const shell = process.platform === "win32";
+for (const args of [["plugin", "marketplace", "update", "omms"], ["plugin", "update", "omms@omms"]]) {
+  const run = spawnSync("claude", args, { stdio: "ignore", shell, timeout: 120000 });
+  if (run.status !== 0) process.exit(1);
+}
+`;
+/** Start a background plugin update when npm has a newer release. Never throws. */
+export async function startPluginSelfUpdate(deps) {
+    const code = await decide(deps);
+    if (code.code === "started" || code.code === "spawn-failed") {
+        await deps.log("Claude plugin self-update", {
+            code: code.code,
+            plugin: code.plugin,
+            latest: code.latest,
+        });
+    }
+    return code.code;
+}
+async function decide(deps) {
+    if (!deps.enabled)
+        return { code: "disabled" };
+    if (!deps.pluginRoot)
+        return { code: "no-plugin" };
+    let plugin;
+    try {
+        plugin = deps.readPluginVersion(deps.pluginRoot);
+    }
+    catch {
+        return { code: "unreadable-plugin" };
+    }
+    const latest = await latestNpmVersion(deps.fetch);
+    if (latest === null)
+        return { code: "unreachable" };
+    const newer = availableUpdate(plugin, latest);
+    if (!newer)
+        return { code: "current" };
+    const marker = deps.readMarker();
+    const now = deps.now();
+    if (marker?.version === newer && now - marker.startedAt <= SELF_UPDATE_RETRY_MS) {
+        return { code: "recent" };
+    }
+    // Write first, so a session that starts during the update does not start another.
+    deps.writeMarker({ version: newer, startedAt: now });
+    try {
+        deps.spawnDetached(process.execPath, ["-e", UPDATE_SCRIPT]);
+    }
+    catch {
+        return { code: "spawn-failed", plugin, latest: newer };
+    }
+    return { code: "started", plugin, latest: newer };
+}
+/** Production inputs: the real plugin manifest, npm, and a marker file in ~/.omms. */
+export function pluginSelfUpdateDeps(log, env = process.env) {
+    const markerPath = join(homedir(), ".omms", "claude-plugin-update.json");
+    return {
+        enabled: env.OMMS_DISABLE_UPDATE_CHECK !== "1",
+        pluginRoot: env.CLAUDE_PLUGIN_ROOT || undefined,
+        readPluginVersion: (root) => {
+            const manifest = JSON.parse(readFileSync(join(root, ".claude-plugin", "plugin.json"), "utf8"));
+            if (typeof manifest.version !== "string")
+                throw new Error("no version");
+            return manifest.version;
+        },
+        fetch: globalThis.fetch,
+        now: Date.now,
+        readMarker: () => {
+            try {
+                const value = JSON.parse(readFileSync(markerPath, "utf8"));
+                return typeof value.version === "string" && typeof value.startedAt === "number"
+                    ? { version: value.version, startedAt: value.startedAt }
+                    : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        writeMarker: (value) => {
+            mkdirSync(dirname(markerPath), { recursive: true });
+            writeFileSync(markerPath, JSON.stringify(value));
+        },
+        spawnDetached: (command, args) => {
+            const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+            child.on("error", () => { });
+            child.unref();
+        },
+        log,
+    };
+}

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

@@ -246,30 +246,7 @@ function generateChangeSummary(oldProfile, newProfile) {
     return changes.length > 0 ? changes.join(", ") : "Profile refinement";
 }
 function buildCategorySummary(profileData) {
-    const prefCats = [...new Set(profileData.preferences.map((p) => p.category))];
-    const patCats = [...new Set(profileData.patterns.map((p) => p.category))];
-    const catParts = [];
-    if (prefCats.length > 0) {
-        const catCounts = prefCats
-            .map((cat) => {
-            const cnt = profileData.preferences.filter((p) => p.category === cat).length;
-            return `${cat} (${cnt})`;
-        })
-            .join(", ");
-        catParts.push(`Preference categories: ${catCounts}`);
-    }
-    if (patCats.length > 0) {
-        const catCounts = patCats
-            .map((cat) => {
-            const cnt = profileData.patterns.filter((p) => p.category === cat).length;
-            return `${cat} (${cnt})`;
-        })
-            .join(", ");
-        catParts.push(`Pattern categories: ${catCounts}`);
-    }
-    const catSection = catParts.length > 0
-        ? `## Existing Categories\nUse these exact category names when your observation fits:\n\n${catParts.join("\n")}\n`
-        : "";
+    const catSection = buildCategoryList(profileData);
     const prefCount = profileData.preferences.length;
     const patCount = profileData.patterns.length;
     const wfCount = profileData.workflows.length;
@@ -350,7 +327,7 @@ CRITICAL: Only output observations grounded in the RECENT PROMPTS above. Write d
     }
     return truncate(base);
 }
-import { createUserProfileAnalysisSchema, USER_PROFILE_LLM_CONFIDENCE_MAX, } from "../../core/extraction.js";
+import { buildCategoryList, createUserProfileAnalysisSchema, USER_PROFILE_LLM_CONFIDENCE_MAX, WORKFLOW_PROMPT_RULES, } from "../../core/extraction.js";
 export { createUserProfileAnalysisSchema, USER_PROFILE_LLM_CONFIDENCE_MAX };
 export function createUserProfileToolSchema(existingProfile) {
     return {
@@ -523,6 +500,8 @@ CRITICAL: Detect the language used by the user in their prompts. You MUST output
 
 CRITICAL: All JSON string values MUST escape double quotes with backslash. Do NOT use unescaped quotation marks inside string values.
 
+${WORKFLOW_PROMPT_RULES}
+
 Use the update_user_profile tool to save the ${existingProfile ? "updated" : "new"} profile.`;
             const { z } = await import("zod");
             const schema = createUserProfileAnalysisSchema(z);
@@ -580,6 +559,8 @@ CRITICAL: Detect the language used by the user in their prompts. You MUST output
 
 CRITICAL: All JSON string values MUST escape double quotes with backslash. Do NOT use unescaped quotation marks inside string values.
 
+${WORKFLOW_PROMPT_RULES}
+
 Use the update_user_profile tool to save the ${existingProfile ? "updated" : "new"} profile.`;
     const toolSchema = createUserProfileToolSchema(Boolean(existingProfile));
     const result = await provider.executeToolCall(systemPrompt, context, toolSchema, `user-profile-${Date.now()}`);

package/dist/cli/index.js

@@ -18,6 +18,8 @@ Commands:
   web update                Update the global install and restart the web app
   memory <mode> [options]   Search, add, list, or forget memories (run with --help)
   profile-catch-up          Analyse every prompt waiting for profile learning (run with --help)
+  profile-normalise-categories  Preview or confirm profile category renames (run with --help)
+  profile-cleanup-categories    Group category names by meaning; preview, apply or undo (run with --help)
   claude-hook <event>       Run a Claude Code hook (used by the Claude Code plugin)
 
 Options:
@@ -67,6 +69,14 @@ export async function runCli(argv) {
         const { runProfileCatchUpCommand } = await import("./profile-catch-up-command.js");
         return await runProfileCatchUpCommand(argv.slice(1));
     }
+    if (argv[0] === "profile-normalise-categories") {
+        const { runProfileNormaliseCategoriesCommand } = await import("./profile-normalise-categories-command.js");
+        return await runProfileNormaliseCategoriesCommand(argv.slice(1));
+    }
+    if (argv[0] === "profile-cleanup-categories") {
+        const { runProfileCleanupCategoriesCommand } = await import("./profile-cleanup-categories-command.js");
+        return await runProfileCleanupCategoriesCommand(argv.slice(1));
+    }
     if (argv[0] === "web") {
         try {
             const { runWebCommand } = await import("./web-command.js");
@@ -107,6 +117,18 @@ export async function runCli(argv) {
             model = `${selected.provider}/${selected.modelId}`;
             console.log(`Import model: ${model}`);
         }
+        // Profile merging buffers findings (capped at 50 per type) while the embedding service is
+        // cold, and a profile-only import never embeds through the memory store. Warm it first.
+        if (!args.dryRun && !args.skipProfile) {
+            try {
+                const { memoryClient } = await import("../services/client.js");
+                await memoryClient.warmup();
+            }
+            catch (error) {
+                console.warn(`Embedding warm-up failed: ${error instanceof Error ? error.message : String(error)}. ` +
+                    "Profile findings may be held back until it works.");
+            }
+        }
         const { formatHistoryImportReport, historyImportFailed, runHistoryImport } = await import("../importer/run-import.js");
         const report = await runHistoryImport(host, args, {
             cwd: process.cwd(),

package/dist/cli/profile-catch-up-command.js

@@ -75,6 +75,18 @@ export async function runProfileCatchUpCommand(argv, print = console.log) {
         const { selectImportModel } = await import("../importer/model-selection.js");
         const selected = selectImportModel(flags.model);
         print(`Profile model: ${selected.provider}/${selected.modelId}`);
+        // A cold embedding service makes profile merging buffer findings (capped at 50 per type).
+        // A backlog that needs no model call never merges, so it does not start the service.
+        if (preview.calls > 0) {
+            try {
+                const { memoryClient } = await import("../services/client.js");
+                await memoryClient.warmup();
+            }
+            catch (error) {
+                print(`Embedding warm-up failed: ${error instanceof Error ? error.message : String(error)}. ` +
+                    "Profile findings may be held back until it works.");
+            }
+        }
         const { drainProfileBacklog } = await import("../importer/profile-backlog.js");
         const { catchUpLeaseHooks } = await import("../importer/profile-catch-up.js");
         const hooks = await catchUpLeaseHooks();

package/dist/cli/profile-cleanup-categories-command.d.ts

@@ -0,0 +1,3 @@
+import type { CleanupDeps } from "../services/user-profile/category-cleanup.js";
+/** Preview, apply or undo a meaning-based cleanup of the current user's profile categories. */
+export declare function runProfileCleanupCategoriesCommand(argv: string[], print?: (line: string) => void, deps?: CleanupDeps): Promise<number>;