om-memory-system 5.5.0-next.212 → 5.6.0-next.216

package/README.md

@@ -117,6 +117,10 @@ cannot be saved.
 
 ![Memory page showing the Pi host view with synthetic import status](.github/screenshots/memory.png)
 
+### Memory spaces
+
+Keep separate stores for separate lines of work. The Spaces item in the web app sidebar opens a page with one card for each space. Switching a space applies to every host. Memories can be copied or moved between spaces, exported to a shareable file and imported into a new space, and a space can read the spaces it links. See [Memory spaces](docs/memory-spaces.md).
+
 ### Settings
 
 Choose models and manage access. Diagnostics show capture outcomes and component health.
@@ -125,19 +129,20 @@ Choose models and manage access. Diagnostics show capture outcomes and component
 
 ## Documentation
 
-| 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)        | One card per host, imports, shared settings and avatars     |
-| [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                                           |
-| [Skill learning](docs/skill-learning.md)    | Opt-in turn recording, skill ranking and draft review       |
-| [For developers](docs/developers.md)        | Building, testing and architecture                          |
-| [Contributing](CONTRIBUTING.md)             | Development workflow and pull requests                      |
+| 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)        | One card per host, imports, shared settings and avatars           |
+| [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                                                 |
+| [Memory spaces](docs/memory-spaces.md)      | Separate stores, the Spaces page, backups and the `space` command |
+| [Skill learning](docs/skill-learning.md)    | Opt-in turn recording, skill ranking and draft review             |
+| [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).

package/dist/adapters/pi/extension.js

@@ -30,6 +30,7 @@ const MEMORY_TOOL_MODES = [
     "list-shards",
     "export",
     "import",
+    "space",
 ];
 function toSessionEntries(branch) {
     return Array.isArray(branch) ? branch : [];
@@ -347,6 +348,13 @@ export default function ommsPiExtension(pi) {
             inputPath: Type.Optional(Type.String()),
             dryRun: Type.Optional(Type.Boolean()),
             allowLinkedSource: Type.Optional(Type.Boolean()),
+            spaceAction: Type.Optional(Type.String()),
+            spaceName: Type.Optional(Type.String()),
+            spaceTo: Type.Optional(Type.String()),
+            spaceSince: Type.Optional(Type.String()),
+            spaceUntil: Type.Optional(Type.String()),
+            spaceProject: Type.Optional(Type.String()),
+            spaceIn: Type.Optional(Type.String()),
         }),
         async execute(_toolCallId, args, _signal, _onUpdate, ctx) {
             const result = await executeMemoryOperation(args, {

package/dist/cli/index.js

@@ -17,6 +17,7 @@ Commands:
   web install|uninstall|status  Manage the web app login item
   web update                Update the global install and restart the web app
   memory <mode> [options]   Search, add, list, or forget memories (run with --help)
+  space <action> [name]     List, create, switch, or archive memory spaces (run with --help)
   skills <mode> [options]   List skills, review proposals, record or delete turns (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)
@@ -66,6 +67,10 @@ export async function runCli(argv) {
         const { runMemoryCommand } = await import("./memory-command.js");
         return await runMemoryCommand(argv.slice(1));
     }
+    if (argv[0] === "space") {
+        const { runSpaceCommand } = await import("./space-command.js");
+        return await runSpaceCommand(argv.slice(1));
+    }
     if (argv[0] === "skills") {
         const { runSkillsCommand } = await import("./skills-command.js");
         return await runSkillsCommand(argv.slice(1));

package/dist/cli/memory-command.js

@@ -10,6 +10,7 @@ const MODES = {
     migrate: "Reassociate orphaned shards after a directory move (--from-path or --from-hash)",
     export: "Export project memories to a portable JSON file (--output)",
     import: "Import memories from a portable JSON file (--input)",
+    space: "Manage memory spaces: list, status, create, archive, unarchive, use (--action, --name)",
 };
 const VALUE_FLAGS = {
     "--content": "content",
@@ -23,6 +24,8 @@ const VALUE_FLAGS = {
     "--from-hash": "fromHash",
     "--output": "outputPath",
     "--input": "inputPath",
+    "--action": "spaceAction",
+    "--name": "spaceName",
     "--directory": "directory",
 };
 const BOOLEAN_FLAGS = {
@@ -51,6 +54,8 @@ Options:
   --from-hash <hash>      Old project hash (migrate)
   --output <file>         Export file (export)
   --input <file>          Import file (import)
+  --action <action>       Space action: list, status, create, archive, unarchive, use (space)
+  --name <name>           Space name or id (space)
   --dry-run               Report without writing (migrate, import)
   --allow-linked-source   Allow a linked source directory (migrate)
   --directory <path>      Project directory (default: the working directory)
@@ -107,7 +112,23 @@ export function parseMemoryCommandArgs(argv) {
             throw new Error(`${flag} needs a value`);
         values[key] = value;
     }
-    if (positionals.length > 0) {
+    if (mode === "space") {
+        // `space <action> [name]`
+        const [action, name, ...extra] = positionals;
+        if (extra.length > 0)
+            throw new Error(`Unexpected argument "${extra[0]}"`);
+        if (action !== undefined) {
+            if (values.spaceAction !== undefined)
+                throw new Error(`Unexpected argument "${action}"`);
+            values.spaceAction = action;
+        }
+        if (name !== undefined) {
+            if (values.spaceName !== undefined)
+                throw new Error(`Unexpected argument "${name}"`);
+            values.spaceName = name;
+        }
+    }
+    else if (positionals.length > 0) {
         if (mode !== "search" || positionals.length > 1 || values.query !== undefined) {
             throw new Error(`Unexpected argument "${positionals[0]}"`);
         }

package/dist/cli/space-command.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `om-memory-system space <action> [name] [options]`: list, create, switch, archive,
+ * unarchive, preview, copy, link, unlink, export and import memory spaces from a
+ * terminal. Deleting, renaming, backing up, restoring and moving exist only in the
+ * web app, so those actions reach the shared operation and are refused there.
+ * Parsing stays free of engine imports so `--help` is fast.
+ */
+export interface SpaceCommandIO {
+    cwd?: string;
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+}
+export declare const spaceCommandUsage = "Usage: om-memory-system space <action> [name] [options]\n\nActions:\n  list                 List spaces and show the active one\n  status               Show the space this project uses now\n  create <name>        Add an empty space (it does not become active)\n  use <name>           Make a space the active one for every host, from the next turn\n  archive <name>       Hide a space from the switcher and keep its data\n  unarchive <name>     Show an archived space again\n  preview [--from <a>] --to <b> [--since <date>] [--until <date>] [--project <tag>]\n                       Count the memories a copy would carry; writes nothing\n  copy [--from <a>] --to <b> [--since <date>] [--until <date>] [--project <tag>]\n                       Copy memories into another space; the source stays unchanged\n  link <name> [--in <space>]\n                       Make <name> searchable from <space> (the active space by default)\n  unlink <name> [--in <space>]\n                       Remove that link\n  export <name> --out <file> [--since <date>] [--until <date>] [--include-profile]\n                       Write one space to a JSON file that is safe to share\n  import <file> --name <new> [--retag-to-project <folder>]\n                       Create a new space from an export file\n\n<name> is a space name or id. Dates are ISO 8601 and both bounds are inclusive;\n--project takes the project tag a preview's groups show. Moving memories between\nspaces, and deleting, renaming, backing up or restoring a space, are only possible\nin the web app.\n\nExamples:\n  om-memory-system space list\n  om-memory-system space create \"Client work\"\n  om-memory-system space use \"Client work\"\n  om-memory-system space copy --from Experiments --to \"Client work\" --since 2026-10-01\n  om-memory-system space link \"Client work\" --in Experiments\n  om-memory-system space export \"Client work\" --out client.json";
+/** Run `om-memory-system space ...` and return the process exit code. */
+export declare function runSpaceCommand(argv: string[], io?: SpaceCommandIO): Promise<number>;

package/dist/cli/space-command.js

@@ -0,0 +1,189 @@
+import { resolve } from "node:path";
+import { SPACE_ACTIONS, WEB_ONLY_SPACE_ACTIONS } from "../services/spaces/operations.js";
+import { runSpaceExport, runSpaceImport } from "./space-transfer-command.js";
+export const spaceCommandUsage = `Usage: om-memory-system space <action> [name] [options]
+
+Actions:
+  list                 List spaces and show the active one
+  status               Show the space this project uses now
+  create <name>        Add an empty space (it does not become active)
+  use <name>           Make a space the active one for every host, from the next turn
+  archive <name>       Hide a space from the switcher and keep its data
+  unarchive <name>     Show an archived space again
+  preview [--from <a>] --to <b> [--since <date>] [--until <date>] [--project <tag>]
+                       Count the memories a copy would carry; writes nothing
+  copy [--from <a>] --to <b> [--since <date>] [--until <date>] [--project <tag>]
+                       Copy memories into another space; the source stays unchanged
+  link <name> [--in <space>]
+                       Make <name> searchable from <space> (the active space by default)
+  unlink <name> [--in <space>]
+                       Remove that link
+  export <name> --out <file> [--since <date>] [--until <date>] [--include-profile]
+                       Write one space to a JSON file that is safe to share
+  import <file> --name <new> [--retag-to-project <folder>]
+                       Create a new space from an export file
+
+<name> is a space name or id. Dates are ISO 8601 and both bounds are inclusive;
+--project takes the project tag a preview's groups show. Moving memories between
+spaces, and deleting, renaming, backing up or restoring a space, are only possible
+in the web app.
+
+Examples:
+  om-memory-system space list
+  om-memory-system space create "Client work"
+  om-memory-system space use "Client work"
+  om-memory-system space copy --from Experiments --to "Client work" --since 2026-10-01
+  om-memory-system space link "Client work" --in Experiments
+  om-memory-system space export "Client work" --out client.json`;
+/** Every action the parser admits; the shared operation refuses the web-only ones. */
+const KNOWN_ACTIONS = new Set([
+    ...SPACE_ACTIONS,
+    ...WEB_ONLY_SPACE_ACTIONS,
+    "move",
+    "export",
+    "import",
+]);
+/** The value flags of the transfer forms. `--directory` is the runner's own flag. */
+const VALUE_FLAGS = new Set([
+    "--from",
+    "--to",
+    "--since",
+    "--until",
+    "--project",
+    "--in",
+    "--out",
+    "--name",
+    "--retag-to-project",
+    "--directory",
+]);
+/** How many positional arguments each action takes and which value flags it allows. */
+const ACTION_FORMS = {
+    list: { positionals: 0, flags: new Set() },
+    status: { positionals: 0, flags: new Set() },
+    create: { positionals: 1, flags: new Set() },
+    use: { positionals: 1, flags: new Set() },
+    archive: { positionals: 1, flags: new Set() },
+    unarchive: { positionals: 1, flags: new Set() },
+    delete: { positionals: 1, flags: new Set() },
+    rename: { positionals: 1, flags: new Set() },
+    backup: { positionals: 1, flags: new Set() },
+    restore: { positionals: 1, flags: new Set() },
+    move: { positionals: 1, flags: new Set(["--from", "--to"]) },
+    preview: {
+        positionals: 1,
+        flags: new Set(["--from", "--to", "--since", "--until", "--project"]),
+    },
+    copy: { positionals: 1, flags: new Set(["--from", "--to", "--since", "--until", "--project"]) },
+    link: { positionals: 1, flags: new Set(["--in"]) },
+    unlink: { positionals: 1, flags: new Set(["--in"]) },
+    export: { positionals: 1, flags: new Set(["--out", "--since", "--until"]) },
+    import: { positionals: 1, flags: new Set(["--name", "--retag-to-project"]) },
+};
+/** One pass over the argument list; every option is `--flag value` or a positional. */
+function parseSpaceArgs(argv) {
+    const parsed = {
+        values: new Map(),
+        includeProfile: false,
+        positionals: [],
+        directory: undefined,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--include-profile") {
+            parsed.includeProfile = true;
+            continue;
+        }
+        if (token.startsWith("--")) {
+            if (!VALUE_FLAGS.has(token))
+                return `Unknown option "${token}".`;
+            const value = argv[++i];
+            if (value === undefined)
+                return `Option "${token}" needs a value.`;
+            parsed.values.set(token.slice(2), value);
+            continue;
+        }
+        parsed.positionals.push(token);
+    }
+    parsed.directory = parsed.values.get("directory");
+    return parsed;
+}
+/** Run `om-memory-system space ...` and return the process exit code. */
+export async function runSpaceCommand(argv, io = {}) {
+    const stdout = io.stdout ?? ((text) => console.log(text));
+    const stderr = io.stderr ?? ((text) => console.error(text));
+    const [action, ...rest] = argv;
+    if (action === undefined || action === "--help" || action === "-h") {
+        stdout(spaceCommandUsage);
+        return 0;
+    }
+    const fail = (problem) => {
+        stderr(`${problem}\n\n${spaceCommandUsage}`);
+        return 1;
+    };
+    if (!KNOWN_ACTIONS.has(action))
+        return fail(`Unknown space action "${action}"`);
+    const parsed = parseSpaceArgs(rest);
+    if (typeof parsed === "string")
+        return fail(parsed);
+    const form = ACTION_FORMS[action];
+    const { values, positionals, includeProfile } = parsed;
+    if (positionals.length > form.positionals) {
+        return fail(`Unexpected argument "${positionals[form.positionals]}"`);
+    }
+    for (const flag of values.keys()) {
+        if (flag === "directory")
+            continue;
+        if (!form.flags.has(`--${flag}`))
+            return fail(`The ${action} action does not take --${flag}.`);
+    }
+    if (includeProfile && action !== "export") {
+        return fail(`The ${action} action does not take --include-profile.`);
+    }
+    const directory = resolve(parsed.directory ?? io.cwd ?? process.cwd());
+    let result;
+    try {
+        if (action === "export" || action === "import") {
+            // The portability runners own their config bridge; the memory tool has none.
+            result =
+                action === "export"
+                    ? await runSpaceExport({
+                        name: positionals[0] ?? "",
+                        outPath: values.get("out") ?? "",
+                        ...(values.has("since") ? { since: values.get("since") } : {}),
+                        ...(values.has("until") ? { until: values.get("until") } : {}),
+                        ...(includeProfile ? { includeProfile: true } : {}),
+                    }, directory)
+                    : await runSpaceImport({
+                        filePath: positionals[0] ?? "",
+                        name: values.get("name") ?? "",
+                        ...(values.has("retag-to-project")
+                            ? { retagToProject: values.get("retag-to-project") }
+                            : {}),
+                    }, directory);
+        }
+        else {
+            const { initConfig } = await import("../config.js");
+            initConfig(directory);
+            const { runSpaceMode } = await import("../core/space-tool.js");
+            result = await runSpaceMode({
+                mode: "space",
+                spaceAction: action,
+                // The transfer source may be positional or --from; the other actions take a name.
+                spaceName: positionals[0] ??
+                    (action === "preview" || action === "copy" || action === "move"
+                        ? values.get("from")
+                        : undefined),
+                ...(values.has("to") ? { spaceTo: values.get("to") } : {}),
+                ...(values.has("since") ? { spaceSince: values.get("since") } : {}),
+                ...(values.has("until") ? { spaceUntil: values.get("until") } : {}),
+                ...(values.has("project") ? { spaceProject: values.get("project") } : {}),
+                ...(values.has("in") ? { spaceIn: values.get("in") } : {}),
+            }, directory);
+        }
+    }
+    catch (error) {
+        result = { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    stdout(JSON.stringify(result, null, 2));
+    return result.success === false ? 1 : 0;
+}

package/dist/cli/space-transfer-command.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The `space export` and `space import` runners (design D8). Both are CLI-only: the
+ * `memory` tool `space` mode refuses them. This file is the one place that bridges
+ * CONFIG into `exportSpace` and `importSpace`, which themselves never read CONFIG;
+ * the shared space operation runs them only when the CLI hands it this bridge.
+ */
+export interface SpaceExportCliRequest {
+    /** The space to export: a name or id. */
+    name: string;
+    outPath: string;
+    since?: string;
+    until?: string;
+    includeProfile?: boolean;
+}
+export interface SpaceImportCliRequest {
+    /** Path of the export file to read. */
+    filePath: string;
+    /** The name of the new space the file becomes. */
+    name: string;
+    retagToProject?: string;
+}
+/** Runs `space export <name> --out <file>` through the shared space operation. */
+export declare function runSpaceExport(request: SpaceExportCliRequest, directory: string): Promise<Record<string, unknown>>;
+/** Runs `space import <file> --name <new>` through the shared space operation. */
+export declare function runSpaceImport(request: SpaceImportCliRequest, directory: string): Promise<Record<string, unknown>>;

package/dist/cli/space-transfer-command.js

@@ -0,0 +1,79 @@
+import { homedir } from "node:os";
+/** The bridge the CLI hands the shared operation: the export/import capability made real. */
+async function portabilityBridge(files, directory) {
+    const { CONFIG } = await import("../config.js");
+    return {
+        export: async (request) => {
+            const { exportSpace, getOmmsVersion } = await import("../services/spaces/export-space.js");
+            return exportSpace({
+                ...request,
+                embeddingModel: CONFIG.embeddingModel,
+                embeddingDimensions: CONFIG.embeddingDimensions,
+                ommsVersion: getOmmsVersion(),
+                homePath: homedir(),
+            });
+        },
+        import: async (request) => {
+            const { importSpace } = await import("../services/spaces/import-space.js");
+            const { embeddingService } = await import("../services/embedding.js");
+            const { getTags } = await import("../services/tags.js");
+            const user = getTags(directory).user;
+            return importSpace({
+                ...request,
+                files,
+                embedding: { model: CONFIG.embeddingModel, dimensions: CONFIG.embeddingDimensions },
+                embed: (text) => embeddingService.embedWithTimeout(text, { task: "document" }),
+                user: {
+                    userTag: user.tag,
+                    displayName: user.displayName,
+                    ...(user.userName ? { userName: user.userName } : {}),
+                    ...(user.userEmail ? { userEmail: user.userEmail } : {}),
+                },
+            });
+        },
+    };
+}
+/** Runs `space export <name> --out <file>` through the shared space operation. */
+export async function runSpaceExport(request, directory) {
+    const { CONFIG, getActiveSpace, initConfig } = await import("../config.js");
+    initConfig(directory);
+    const { executeSpaceOperation } = await import("../services/spaces/operations.js");
+    const { spaceFiles } = await import("../services/spaces/registry-store.js");
+    const { ommsHomeDir } = await import("../services/spaces/storage-resolution.js");
+    const { spaceOperationSettings } = await import("../core/space-tool.js");
+    const files = spaceFiles(ommsHomeDir());
+    return executeSpaceOperation({
+        action: "export",
+        name: request.name,
+        outPath: request.outPath,
+        ...(request.since === undefined ? {} : { since: request.since }),
+        ...(request.until === undefined ? {} : { until: request.until }),
+        ...(request.includeProfile ? { includeProfile: true } : {}),
+    }, {
+        files,
+        current: getActiveSpace(),
+        settings: spaceOperationSettings(CONFIG, files.spacesRoot),
+        portability: await portabilityBridge(files, directory),
+    });
+}
+/** Runs `space import <file> --name <new>` through the shared space operation. */
+export async function runSpaceImport(request, directory) {
+    const { CONFIG, getActiveSpace, initConfig } = await import("../config.js");
+    initConfig(directory);
+    const { executeSpaceOperation } = await import("../services/spaces/operations.js");
+    const { spaceFiles } = await import("../services/spaces/registry-store.js");
+    const { ommsHomeDir } = await import("../services/spaces/storage-resolution.js");
+    const { spaceOperationSettings } = await import("../core/space-tool.js");
+    const files = spaceFiles(ommsHomeDir());
+    return executeSpaceOperation({
+        action: "import",
+        name: request.name,
+        filePath: request.filePath,
+        ...(request.retagToProject === undefined ? {} : { retagToProject: request.retagToProject }),
+    }, {
+        files,
+        current: getActiveSpace(),
+        settings: spaceOperationSettings(CONFIG, files.spacesRoot),
+        portability: await portabilityBridge(files, directory),
+    });
+}

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import { isPlaceholderApiKey } from "./services/ai/api-key-placeholder.js";
 import { type KeywordMode } from "./utils/keyword-boost.js";
+import { type ActiveSpace } from "./services/spaces/active-space.js";
 interface OmmsConfig {
     storagePath?: string;
     userEmailOverride?: string;
@@ -359,6 +360,8 @@ type RuntimeConfig = ReturnType<typeof buildConfig>;
 export { getAutoCaptureProviderStatus, type AutoCaptureProviderStatus, } from "./services/ai/live-model-choice.js";
 export { isPlaceholderApiKey };
 export declare function hasAutoCaptureProviderConfig(config?: RuntimeConfig): boolean;
+/** The memory space in use, as of the last config load. */
+export declare const getActiveSpace: () => ActiveSpace;
 export declare function refreshConfigIfChanged(directory: string): void;
 export declare function initConfig(directory: string, options?: {
     strict?: boolean;

package/dist/config.js

@@ -17,7 +17,10 @@ import { defaultSimilarityThreshold } from "./utils/threshold-default.js";
 import { RERANKER_TIMEOUT_DEFAULT_MS } from "./services/request-timeouts.js";
 import { checkedRerankerSettings } from "./utils/reranker-settings.js";
 import { checkedKeywordBoost, checkedKeywordMode, } from "./utils/keyword-boost.js";
-import { resolveDefaultStoragePath, runLegacyStoreMigration, legacyMigrationPaths, } from "./services/legacy-migration.js";
+import { runLegacyStoreMigration, legacyMigrationPaths } from "./services/legacy-migration.js";
+import { expandPath, storagePathFrom, withSkillStorage, } from "./services/spaces/storage-resolution.js";
+import { resolveActiveSpace } from "./services/spaces/active-space.js";
+import { resetStoreHandles } from "./services/spaces/store-handles.js";
 const OMMS_CONFIG_DIR = join(homedir(), ".config", "omms");
 const DATA_DIR = join(homedir(), ".omms");
 const LEGACY_CONFIG_FILES = [
@@ -120,23 +123,6 @@ const DEFAULTS = {
         injectOn: "first",
     },
 };
-function expandPath(path) {
-    if (path.startsWith("~/")) {
-        return join(homedir(), path.slice(2));
-    }
-    if (path === "~") {
-        return homedir();
-    }
-    return path;
-}
-function storagePathFrom(fileConfig) {
-    return fileConfig.storagePath ? expandPath(fileConfig.storagePath) : resolveDefaultStoragePath();
-}
-/** Keeps skills.db in the global storage path when a project config moves storagePath (ADR-036). */
-function withSkillStorage(config, global) {
-    const path = storagePathFrom(global);
-    return { ...config, skillStoragePath: path === config.storagePath ? undefined : path };
-}
 /**
  * Load the first config file that exists, in priority order. A file that
  * exists but cannot be read or parsed is not skipped: falling through would let
@@ -472,7 +458,7 @@ function projectConfigPaths(directory) {
     ];
 }
 function configSignature(directory) {
-    return [...CONFIG_FILES, ...projectConfigPaths(directory)]
+    return [...CONFIG_FILES, ...projectConfigPaths(directory), join(DATA_DIR, "spaces.json")]
         .filter((path) => existsSync(path))
         .map((path) => {
         try {
@@ -491,6 +477,9 @@ let lastConfigDirectory;
 let lastConfigSignature;
 /** Directory and signature of the last reload that failed. */
 let lastFailedConfig;
+let activeSpace = { id: "default", name: "Default", customStoragePath: false };
+/** The memory space in use, as of the last config load. */
+export const getActiveSpace = () => activeSpace;
 export function refreshConfigIfChanged(directory) {
     // Both hosts initialise their config at startup. Direct callers that have
     // not initialised it keep their in-memory settings untouched.
@@ -565,10 +554,18 @@ export function initConfig(directory, options = {}) {
     delete projectOverrides.webServerAutoStart;
     delete projectOverrides.webServerEnabled;
     const merged = { ...globalConfig, ...projectOverrides };
+    // The active memory space picks the storage folder unless the project sets its own (ADR-041).
+    activeSpace = resolveActiveSpace(DATA_DIR, storagePathFrom(globalConfig), "storagePath" in projectConfig);
+    if (activeSpace.storagePath)
+        merged.storagePath = activeSpace.storagePath;
     const nextConfig = withSkillStorage(buildConfig(merged), globalConfig);
     lastFileConfig = merged;
     lastGlobalFileConfig = globalConfig;
+    const storageMoved = nextConfig.storagePath !== CONFIG.storagePath;
     CONFIG = nextConfig;
+    // A new storage folder (another memory space) needs fresh store handles (ADR-041).
+    if (storageMoved)
+        void resetStoreHandles();
     lastConfigDirectory = directory;
     lastConfigSignature = configSignature(directory);
 }

package/dist/core/memory-operations.d.ts

@@ -1,7 +1,7 @@
 import { type MemoryScope } from "../services/client.js";
 import { getTags } from "../services/tags.js";
 import type { MemoryHost, MemoryType } from "../types/index.js";
-export type MemoryOperationMode = "add" | "search" | "profile" | "list" | "forget" | "help" | "migrate" | "list-shards" | "export" | "import";
+export type MemoryOperationMode = "add" | "search" | "profile" | "list" | "forget" | "help" | "migrate" | "list-shards" | "export" | "import" | "space";
 export interface MemoryOperationArgs {
     mode?: MemoryOperationMode;
     content?: string;
@@ -17,6 +17,20 @@ export interface MemoryOperationArgs {
     inputPath?: string;
     dryRun?: boolean;
     allowLinkedSource?: boolean;
+    /** `space` mode: list, status, create, archive, unarchive, use, preview, copy, link or unlink. */
+    spaceAction?: string;
+    /** `space` mode: the space name or id; the transfer source or the link target. */
+    spaceName?: string;
+    /** `space` mode: the transfer target (preview, copy). */
+    spaceTo?: string;
+    /** `space` mode: inclusive ISO 8601 lower bound on the creation time (preview, copy). */
+    spaceSince?: string;
+    /** `space` mode: inclusive ISO 8601 upper bound on the creation time (preview, copy). */
+    spaceUntil?: string;
+    /** `space` mode: only memories with this project tag (preview, copy). */
+    spaceProject?: string;
+    /** `space` mode: the space that owns a link (link, unlink); the active space when omitted. */
+    spaceIn?: string;
 }
 export interface MemoryOperationContext {
     directory: string;

package/dist/core/memory-operations.js

@@ -14,6 +14,8 @@ function formatSearchResults(query, results, limit) {
             content: result.memory || result.chunk,
             type: result.type,
             similarity: Math.round(result.similarity * 100),
+            // A linked result carries its space so the caller can tell it is read-only.
+            ...(result.spaceName ? { space: result.spaceName } : {}),
         })),
     };
 }
@@ -28,6 +30,10 @@ export async function executeMemoryOperation(args, context) {
         };
     }
     const mode = args.mode || "help";
+    if (mode === "space") {
+        const { runSpaceMode } = await import("./space-tool.js");
+        return runSpaceMode(args, context.directory);
+    }
     const needsEmbedding = !["help", "list-shards", "migrate", "export"].includes(mode);
     if (needsEmbedding) {
         const embeddingInitError = memoryClient.getEmbeddingInitError?.();
@@ -75,6 +81,19 @@ export async function executeMemoryOperation(args, context) {
                             args: ["content?"],
                         },
                         { command: "list", description: "List recent memories", args: ["limit?"] },
+                        {
+                            command: "space",
+                            description: "Manage memory spaces: list, status, create, archive, unarchive, use, preview, copy, link, unlink. Moving, deleting, exporting and importing are not offered here",
+                            args: [
+                                "spaceAction?",
+                                "spaceName?",
+                                "spaceTo?",
+                                "spaceSince?",
+                                "spaceUntil?",
+                                "spaceProject?",
+                                "spaceIn?",
+                            ],
+                        },
                         { command: "forget", description: "Remove memory", args: ["memoryId"] },
                         {
                             command: "list-shards",
@@ -132,7 +151,7 @@ export async function executeMemoryOperation(args, context) {
             case "search": {
                 if (!args.query)
                     return { success: false, error: "query required" };
-                const result = await memoryClient.searchMemories(args.query, tags.project.tag, args.scope ?? CONFIG.memory.defaultScope);
+                const result = await memoryClient.searchMemories(args.query, tags.project.tag, args.scope ?? CONFIG.memory.defaultScope, { includeLinked: true });
                 if (!result.success)
                     return { success: false, error: result.error };
                 return formatSearchResults(args.query, result, args.limit);
@@ -201,7 +220,7 @@ export async function executeMemoryOperation(args, context) {
                 };
             }
             case "list": {
-                const result = await memoryClient.listMemories(tags.project.tag, args.limit || 20, args.scope ?? CONFIG.memory.defaultScope);
+                const result = await memoryClient.listMemories(tags.project.tag, args.limit || 20, args.scope ?? CONFIG.memory.defaultScope, { includeLinked: true });
                 if (!result.success)
                     return { success: false, error: result.error };
                 return {