@seanhogg/builderforce-memory-mcp 2026.6.19 → 2026.6.27

package/README.md

@@ -75,6 +75,26 @@ const backend = await createLocalMemoryStoreBackend({ runtime: ssmMemoryService.
 
 Recall quality then improves automatically as that model is adapted/distilled.
 
+## One-shot install into any MCP host (not just Claude)
+
+```bash
+# Auto-detect installed agents and register the memory server into each:
+npx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install
+
+npx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install --host=all
+npx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install --host=cursor,windsurf
+```
+
+Writes the stdio server entry into each host's own config, idempotently and with
+`.bak` backups. Supported hosts: **Claude Code, Claude Desktop, Cursor, Windsurf,
+VS Code, Cline, Gemini CLI, Codex CLI**. Every agent points at one shared store
+(`~/.builderforce-memory/memory.json` by default, override with `--memory-file`),
+so a fact remembered in one agent is recalled in another. `--readonly` drops the
+write tools; `--local=<dist/bin/stdio.js>` runs a checkout for development.
+
+The same launch spec is exported for programmatic use:
+`buildServerSpec()` / `installMemoryServer()` (see `src/install/`).
+
 ## Quick start — stdio (any process / language)
 
 ```bash

package/dist/bin/install.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * builderforce-memory-install — wire the memory MCP server into any MCP-capable
+ * agent (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, Gemini
+ * CLI, Codex CLI), not just Claude Code.
+ *
+ *   npx -y @seanhogg/builderforce-memory-mcp                 # via the package's other bin
+ *   builderforce-memory-install                              # auto-detect installed hosts
+ *   builderforce-memory-install --host=cursor,windsurf       # explicit hosts
+ *   builderforce-memory-install --host=all                   # every known host
+ *   builderforce-memory-install --memory-file=/path/mem.json # shared store path
+ *   builderforce-memory-install --readonly                   # recall-only
+ *   builderforce-memory-install --local=/abs/dist/bin/stdio.js  # dev: local bin
+ *
+ * The store defaults to ~/.builderforce-memory/memory.json so every agent on
+ * the machine shares one memory. Re-running is safe (idempotent + .bak backups).
+ */
+export {};
+//# sourceMappingURL=install.d.ts.map

package/dist/bin/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/bin/install.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG"}

package/dist/bin/install.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * builderforce-memory-install — wire the memory MCP server into any MCP-capable
+ * agent (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, Gemini
+ * CLI, Codex CLI), not just Claude Code.
+ *
+ *   npx -y @seanhogg/builderforce-memory-mcp                 # via the package's other bin
+ *   builderforce-memory-install                              # auto-detect installed hosts
+ *   builderforce-memory-install --host=cursor,windsurf       # explicit hosts
+ *   builderforce-memory-install --host=all                   # every known host
+ *   builderforce-memory-install --memory-file=/path/mem.json # shared store path
+ *   builderforce-memory-install --readonly                   # recall-only
+ *   builderforce-memory-install --local=/abs/dist/bin/stdio.js  # dev: local bin
+ *
+ * The store defaults to ~/.builderforce-memory/memory.json so every agent on
+ * the machine shares one memory. Re-running is safe (idempotent + .bak backups).
+ */
+import os from "node:os";
+import path from "node:path";
+import { HOSTS } from "../install/hosts.js";
+import { installMemoryServer } from "../install/install.js";
+function argValue(name) {
+    const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
+    return hit ? hit.slice(name.length + 3) : undefined;
+}
+const hasFlag = (name) => process.argv.includes(`--${name}`);
+if (hasFlag("help") || hasFlag("h")) {
+    process.stdout.write([
+        "builderforce-memory-install — register the memory MCP server into MCP hosts.",
+        "",
+        "  --host=<a,b|all>     hosts to target (default: auto-detect installed)",
+        "  --memory-file=<path> JSON snapshot path (default: ~/.builderforce-memory/memory.json)",
+        "  --readonly           recall-only (no remember/forget)",
+        "  --local=<path>       run a locally-built stdio bin via node (dev)",
+        "",
+        `Known hosts: ${HOSTS.map((h) => h.id).join(", ")}`,
+        "",
+    ].join("\n"));
+    process.exit(0);
+}
+const hostArg = argValue("host");
+const hosts = hostArg === undefined || hostArg === "auto"
+    ? "auto"
+    : hostArg === "all"
+        ? "all"
+        : hostArg.split(",").map((s) => s.trim()).filter(Boolean);
+const memoryFile = argValue("memory-file") ?? path.join(os.homedir(), ".builderforce-memory", "memory.json");
+let results;
+try {
+    results = installMemoryServer({
+        hosts,
+        memoryFile,
+        readonly: hasFlag("readonly"),
+        localBin: argValue("local"),
+    });
+}
+catch (err) {
+    process.stderr.write(`✗ ${String(err.message ?? err)}\n`);
+    process.exit(1);
+}
+const icon = {
+    installed: "✓",
+    updated: "✓",
+    skipped: "•",
+    unsupported: "–",
+    error: "✗",
+};
+let wrote = 0;
+for (const r of results) {
+    const where = r.path ? `  ${r.path}` : "";
+    const why = r.detail ? `  (${r.detail})` : "";
+    process.stdout.write(`${icon[r.status] ?? "?"} ${r.label}: ${r.status}${why}${where}\n`);
+    if (r.status === "installed" || r.status === "updated")
+        wrote += 1;
+}
+if (results.length === 0) {
+    process.stdout.write("No MCP hosts detected. Pass --host=all to write configs anyway, or --host=cursor (etc.).\n");
+}
+else {
+    process.stdout.write(`\nDone — ${wrote} config(s) written. Store: ${memoryFile}\nRestart the agent(s) to connect. Tools: memory_recall · memory_remember · memory_get · memory_recall_by_tag · memory_forget\n`);
+}
+//# sourceMappingURL=install.js.map

package/dist/bin/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/bin/install.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -18,4 +18,10 @@ export type { McpServerOptions } from "./transports/mcp-server.js";
 export { runStdio } from "./transports/stdio.js";
 export { createMemoryHttpHandler } from "./transports/http.js";
 export type { HttpHandlerOptions } from "./transports/http.js";
+export { buildServerSpec, MCP_PACKAGE, MCP_BIN, RUNTIME_PEERS } from "./install/server-spec.js";
+export type { StdioServerSpec, ServerSpecOptions } from "./install/server-spec.js";
+export { installMemoryServer } from "./install/install.js";
+export type { InstallOptions, InstallResult, InstallStatus, HostSelector, FsLike } from "./install/install.js";
+export { HOSTS, SERVER_KEY, findHost } from "./install/hosts.js";
+export type { HostAdapter, HostEnv, ConfigFormat } from "./install/hosts.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAC/F,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAC/F,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAChG,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -15,4 +15,8 @@ export { createMemoryMcpServer } from "./transports/sdk.js";
 export { buildMcpServer } from "./transports/mcp-server.js";
 export { runStdio } from "./transports/stdio.js";
 export { createMemoryHttpHandler } from "./transports/http.js";
+// ── Multi-host installer (wire the stdio server into any MCP-capable agent) ───
+export { buildServerSpec, MCP_PACKAGE, MCP_BIN, RUNTIME_PEERS } from "./install/server-spec.js";
+export { installMemoryServer } from "./install/install.js";
+export { HOSTS, SERVER_KEY, findHost } from "./install/hosts.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,0FAA0F;AAC1F,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAG/F,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,+EAA+E;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,0FAA0F;AAC1F,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAG/F,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,+EAA+E;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,iFAAiF;AACjF,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEhG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/install/hosts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Host registry — every MCP-capable agent we know how to wire memory into.
+ *
+ * The differences between hosts collapse to three things: WHERE the config
+ * file lives, which top-level key holds the server map (`mcpServers` vs VS
+ * Code's `servers`), and whether the entry carries an explicit `type:"stdio"`.
+ * Codex CLI is the one odd-one-out (TOML, not JSON). Everything else is one
+ * shared JSON merge — see install.ts.
+ */
+export type ConfigFormat = "json-mcpServers" | "json-servers" | "toml";
+export interface HostEnv {
+    homedir: string;
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+}
+export interface HostAdapter {
+    id: string;
+    label: string;
+    format: ConfigFormat;
+    /** Include `type:"stdio"` in the written entry (Claude Code + VS Code want it). */
+    includeType: boolean;
+    /** Absolute config-file path for this host, or null if N/A on this OS. */
+    configPath(e: HostEnv): string | null;
+}
+/** The server key written into every host's config. */
+export declare const SERVER_KEY = "builderforce-memory";
+export declare const HOSTS: HostAdapter[];
+export declare function findHost(id: string): HostAdapter | undefined;
+//# sourceMappingURL=hosts.d.ts.map

package/dist/install/hosts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.d.ts","sourceRoot":"","sources":["../../src/install/hosts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,cAAc,GAAG,MAAM,CAAC;AAEvE,MAAM,WAAW,OAAO;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,mFAAmF;IACnF,WAAW,EAAE,OAAO,CAAC;IACrB,0EAA0E;IAC1E,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,uDAAuD;AACvD,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAqBhD,eAAO,MAAM,KAAK,EAAE,WAAW,EAoE9B,CAAC;AAEF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAE5D"}

package/dist/install/hosts.js

@@ -0,0 +1,102 @@
+/**
+ * Host registry — every MCP-capable agent we know how to wire memory into.
+ *
+ * The differences between hosts collapse to three things: WHERE the config
+ * file lives, which top-level key holds the server map (`mcpServers` vs VS
+ * Code's `servers`), and whether the entry carries an explicit `type:"stdio"`.
+ * Codex CLI is the one odd-one-out (TOML, not JSON). Everything else is one
+ * shared JSON merge — see install.ts.
+ */
+import path from "node:path";
+/** The server key written into every host's config. */
+export const SERVER_KEY = "builderforce-memory";
+/** Per-OS application-support directory for a desktop vendor (Claude, Code). */
+function appSupport(e, vendor) {
+    if (e.platform === "win32") {
+        const roaming = e.env["APPDATA"] ?? path.join(e.homedir, "AppData", "Roaming");
+        return path.join(roaming, vendor);
+    }
+    if (e.platform === "darwin") {
+        return path.join(e.homedir, "Library", "Application Support", vendor);
+    }
+    const xdg = e.env["XDG_CONFIG_HOME"] ?? path.join(e.homedir, ".config");
+    return path.join(xdg, vendor);
+}
+/** VS Code stores its per-user files under `<appSupport(Code)>/User`. */
+function vscodeUserDir(e) {
+    const base = appSupport(e, "Code");
+    return base ? path.join(base, "User") : null;
+}
+export const HOSTS = [
+    {
+        id: "claude-code",
+        label: "Claude Code",
+        format: "json-mcpServers",
+        includeType: true,
+        configPath: (e) => path.join(e.homedir, ".claude.json"),
+    },
+    {
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => {
+            const dir = appSupport(e, "Claude");
+            return dir ? path.join(dir, "claude_desktop_config.json") : null;
+        },
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => path.join(e.homedir, ".cursor", "mcp.json"),
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => path.join(e.homedir, ".codeium", "windsurf", "mcp_config.json"),
+    },
+    {
+        id: "vscode",
+        label: "VS Code",
+        format: "json-servers",
+        includeType: true,
+        configPath: (e) => {
+            const dir = vscodeUserDir(e);
+            return dir ? path.join(dir, "mcp.json") : null;
+        },
+    },
+    {
+        id: "cline",
+        label: "Cline (VS Code)",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => {
+            const dir = vscodeUserDir(e);
+            return dir
+                ? path.join(dir, "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json")
+                : null;
+        },
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => path.join(e.homedir, ".gemini", "settings.json"),
+    },
+    {
+        id: "codex",
+        label: "Codex CLI",
+        format: "toml",
+        includeType: false,
+        configPath: (e) => path.join(e.homedir, ".codex", "config.toml"),
+    },
+];
+export function findHost(id) {
+    return HOSTS.find((h) => h.id === id);
+}
+//# sourceMappingURL=hosts.js.map

package/dist/install/hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.js","sourceRoot":"","sources":["../../src/install/hosts.ts"],"names":[],"mappings":"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"}

package/dist/install/install.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Host-agnostic installer: register the builderforce-memory MCP server into any
+ * combination of MCP-capable agents. One shared launch spec (server-spec.ts),
+ * one entry per host config, idempotent and backup-safe.
+ *
+ * Pure-ish: all filesystem + environment access goes through injectable seams
+ * so the merge logic is unit-testable without touching a real machine.
+ */
+import { type HostEnv } from "./hosts.js";
+import { type ServerSpecOptions } from "./server-spec.js";
+export interface FsLike {
+    existsSync(p: string): boolean;
+    readFileSync(p: string, enc: "utf8"): string;
+    writeFileSync(p: string, data: string): void;
+    mkdirSync(p: string, opts: {
+        recursive: boolean;
+    }): void;
+    copyFileSync(src: string, dest: string): void;
+}
+export type HostSelector = string[] | "auto" | "all";
+export interface InstallOptions extends ServerSpecOptions {
+    /**
+     * Which hosts to target:
+     *   - "auto" (default) — only hosts whose config file or parent dir exists.
+     *   - "all"            — every known host (creates configs as needed).
+     *   - string[]         — explicit host ids (see HOSTS).
+     */
+    hosts?: HostSelector;
+    fs?: FsLike;
+    hostEnv?: HostEnv;
+}
+export type InstallStatus = "installed" | "updated" | "skipped" | "unsupported" | "error";
+export interface InstallResult {
+    host: string;
+    label: string;
+    path: string | null;
+    status: InstallStatus;
+    detail?: string;
+}
+/**
+ * Register (or refresh) the memory MCP server across the selected hosts.
+ * Never throws for a single host — per-host failures are captured as
+ * `status:"error"` so one bad config can't abort the rest.
+ */
+export declare function installMemoryServer(opts?: InstallOptions): InstallResult[];
+//# sourceMappingURL=install.d.ts.map

package/dist/install/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/install/install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAuC,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAmB,KAAK,iBAAiB,EAAwB,MAAM,kBAAkB,CAAC;AAEjG,MAAM,WAAW,MAAM;IACnB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7C,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,KAAK,CAAC;AAErD,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACrD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAsGD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,cAAmB,GAAG,aAAa,EAAE,CAwB9E"}

package/dist/install/install.js

@@ -0,0 +1,135 @@
+/**
+ * Host-agnostic installer: register the builderforce-memory MCP server into any
+ * combination of MCP-capable agents. One shared launch spec (server-spec.ts),
+ * one entry per host config, idempotent and backup-safe.
+ *
+ * Pure-ish: all filesystem + environment access goes through injectable seams
+ * so the merge logic is unit-testable without touching a real machine.
+ */
+import nodeFs from "node:fs";
+import nodeOs from "node:os";
+import nodePath from "node:path";
+import { HOSTS, SERVER_KEY } from "./hosts.js";
+import { buildServerSpec } from "./server-spec.js";
+function defaultHostEnv() {
+    return { homedir: nodeOs.homedir(), platform: process.platform, env: process.env };
+}
+function readJson(fs, file) {
+    if (!fs.existsSync(file))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        // Corrupt/partial config — surface as error rather than clobbering it.
+        throw new Error("existing config is not valid JSON");
+    }
+}
+function entryFor(spec, includeType) {
+    return {
+        ...(includeType ? { type: "stdio" } : {}),
+        command: spec.command,
+        args: spec.args,
+        ...(spec.env ? { env: spec.env } : {}),
+    };
+}
+function ensureParent(fs, file) {
+    const dir = nodePath.dirname(file);
+    if (dir && !fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+/** A host is "present" if its config file or its parent directory already exists. */
+function isPresent(fs, file) {
+    return fs.existsSync(file) || fs.existsSync(nodePath.dirname(file));
+}
+function installJson(fs, host, file, spec) {
+    const mapKey = host.format === "json-servers" ? "servers" : "mcpServers";
+    const config = readJson(fs, file);
+    const map = (config[mapKey] && typeof config[mapKey] === "object" ? config[mapKey] : {});
+    const next = entryFor(spec, host.includeType);
+    const prev = map[SERVER_KEY];
+    const existed = prev !== undefined;
+    if (existed && JSON.stringify(prev) === JSON.stringify(next))
+        return "skipped";
+    if (fs.existsSync(file))
+        fs.copyFileSync(file, `${file}.bak`);
+    map[SERVER_KEY] = next;
+    config[mapKey] = map;
+    ensureParent(fs, file);
+    fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+    return existed ? "updated" : "installed";
+}
+/** TOML emit is append-only and idempotent: skip if the table already exists. */
+function installToml(fs, file, spec) {
+    const header = `[mcp_servers.${SERVER_KEY}]`;
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    if (existing.includes(header))
+        return "skipped";
+    const q = (s) => JSON.stringify(s); // TOML basic strings are JSON-compatible here
+    const lines = [
+        header,
+        `command = ${q(spec.command)}`,
+        `args = [${spec.args.map(q).join(", ")}]`,
+    ];
+    if (spec.env) {
+        lines.push(`[mcp_servers.${SERVER_KEY}.env]`);
+        for (const [k, v] of Object.entries(spec.env))
+            lines.push(`${k} = ${q(v)}`);
+    }
+    const block = `${lines.join("\n")}\n`;
+    if (fs.existsSync(file))
+        fs.copyFileSync(file, `${file}.bak`);
+    ensureParent(fs, file);
+    const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : "";
+    fs.writeFileSync(file, `${existing}${sep}${block}`);
+    return "installed";
+}
+function resolveHosts(selector, fs, hostEnv) {
+    if (Array.isArray(selector)) {
+        return selector.map((id) => {
+            const h = HOSTS.find((x) => x.id === id);
+            if (!h)
+                throw new Error(`unknown host "${id}" (known: ${HOSTS.map((x) => x.id).join(", ")})`);
+            return h;
+        });
+    }
+    if (selector === "all")
+        return HOSTS;
+    // "auto": only hosts that look installed on this machine.
+    return HOSTS.filter((h) => {
+        const p = h.configPath(hostEnv);
+        return p !== null && isPresent(fs, p);
+    });
+}
+/**
+ * Register (or refresh) the memory MCP server across the selected hosts.
+ * Never throws for a single host — per-host failures are captured as
+ * `status:"error"` so one bad config can't abort the rest.
+ */
+export function installMemoryServer(opts = {}) {
+    const fs = opts.fs ?? nodeFs;
+    const hostEnv = opts.hostEnv ?? defaultHostEnv();
+    const selector = opts.hosts ?? "auto";
+    const spec = buildServerSpec({
+        memoryFile: opts.memoryFile,
+        readonly: opts.readonly,
+        platform: opts.platform ?? hostEnv.platform,
+        localBin: opts.localBin,
+    });
+    const hosts = resolveHosts(selector, fs, hostEnv);
+    return hosts.map((host) => {
+        const file = host.configPath(hostEnv);
+        if (file === null) {
+            return { host: host.id, label: host.label, path: null, status: "unsupported", detail: "not available on this OS" };
+        }
+        try {
+            const status = host.format === "toml" ? installToml(fs, file, spec) : installJson(fs, host, file, spec);
+            return { host: host.id, label: host.label, path: file, status };
+        }
+        catch (err) {
+            return { host: host.id, label: host.label, path: file, status: "error", detail: String(err.message ?? err) };
+        }
+    });
+}
+//# sourceMappingURL=install.js.map

package/dist/install/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/install/install.ts"],"names":[],"mappings":"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"}

package/dist/install/server-spec.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The canonical stdio launch spec for the builderforce-memory MCP server.
+ *
+ * Every host (Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini/Codex CLI,
+ * Claude Desktop) registers the SAME server — only the surrounding config
+ * file/shape differs. This module is the single source of truth for HOW the
+ * server is launched, so the per-host adapters never re-derive the command.
+ */
+export interface StdioServerSpec {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface ServerSpecOptions {
+    /** Absolute path to the JSON snapshot that makes memory survive restarts. */
+    memoryFile?: string;
+    /** Register read-only (disables the remember/forget tools). */
+    readonly?: boolean;
+    /** Platform to target (command wrapping). Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /**
+     * Run a locally-built stdio bin via `node <path>` instead of the published
+     * package via `npx` — for development against a checkout.
+     */
+    localBin?: string;
+}
+/** Published package + bin. The bin name matches the unscoped package name. */
+export declare const MCP_PACKAGE = "@seanhogg/builderforce-memory-mcp";
+export declare const MCP_BIN = "builderforce-memory-mcp";
+/**
+ * Runtime peers the stdio bin loads on demand. They are OPTIONAL peers of the
+ * MCP package (so a custom-backend / HTTP-thin-client consumer needn't install
+ * them), which means `npx` will NOT auto-pull them — the stdio launch lists
+ * them explicitly. `-engine` arrives as `-memory`'s required peer; listed too
+ * for determinism.
+ */
+export declare const RUNTIME_PEERS: string[];
+/**
+ * Build the stdio launch spec. On Windows `npx` is a `.cmd` shim that an MCP
+ * launcher must invoke through `cmd`; `node` + a local path needs no shell.
+ */
+export declare function buildServerSpec(opts?: ServerSpecOptions): StdioServerSpec;
+//# sourceMappingURL=server-spec.d.ts.map

package/dist/install/server-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-spec.d.ts","sourceRoot":"","sources":["../../src/install/server-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAC9B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+EAA+E;AAC/E,eAAO,MAAM,WAAW,sCAAsC,CAAC;AAC/D,eAAO,MAAM,OAAO,4BAA4B,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,UAIzB,CAAC;AASF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,iBAAsB,GAAG,eAAe,CAc7E"}

package/dist/install/server-spec.js

@@ -0,0 +1,48 @@
+/**
+ * The canonical stdio launch spec for the builderforce-memory MCP server.
+ *
+ * Every host (Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini/Codex CLI,
+ * Claude Desktop) registers the SAME server — only the surrounding config
+ * file/shape differs. This module is the single source of truth for HOW the
+ * server is launched, so the per-host adapters never re-derive the command.
+ */
+/** Published package + bin. The bin name matches the unscoped package name. */
+export const MCP_PACKAGE = "@seanhogg/builderforce-memory-mcp";
+export const MCP_BIN = "builderforce-memory-mcp";
+/**
+ * Runtime peers the stdio bin loads on demand. They are OPTIONAL peers of the
+ * MCP package (so a custom-backend / HTTP-thin-client consumer needn't install
+ * them), which means `npx` will NOT auto-pull them — the stdio launch lists
+ * them explicitly. `-engine` arrives as `-memory`'s required peer; listed too
+ * for determinism.
+ */
+export const RUNTIME_PEERS = [
+    "@seanhogg/builderforce-memory",
+    "@seanhogg/builderforce-memory-engine",
+    "fake-indexeddb",
+];
+function specEnv(opts) {
+    const env = {};
+    if (opts.memoryFile)
+        env["BUILDERFORCE_MEMORY_FILE"] = opts.memoryFile;
+    if (opts.readonly)
+        env["BUILDERFORCE_MEMORY_READONLY"] = "1";
+    return Object.keys(env).length > 0 ? env : undefined;
+}
+/**
+ * Build the stdio launch spec. On Windows `npx` is a `.cmd` shim that an MCP
+ * launcher must invoke through `cmd`; `node` + a local path needs no shell.
+ */
+export function buildServerSpec(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = specEnv(opts);
+    if (opts.localBin) {
+        return { command: "node", args: [opts.localBin], ...(env ? { env } : {}) };
+    }
+    const npxArgs = ["-y", "-p", MCP_PACKAGE, ...RUNTIME_PEERS.flatMap((p) => ["-p", p]), MCP_BIN];
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/c", "npx", ...npxArgs], ...(env ? { env } : {}) };
+    }
+    return { command: "npx", args: npxArgs, ...(env ? { env } : {}) };
+}
+//# sourceMappingURL=server-spec.js.map

package/dist/install/server-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-spec.js","sourceRoot":"","sources":["../../src/install/server-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAsBH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,WAAW,GAAG,mCAAmC,CAAC;AAC/D,MAAM,CAAC,MAAM,OAAO,GAAG,yBAAyB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,+BAA+B;IAC/B,sCAAsC;IACtC,gBAAgB;CACnB,CAAC;AAEF,SAAS,OAAO,CAAC,IAAuB;IACpC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,IAAI,IAAI,CAAC,UAAU;QAAE,GAAG,CAAC,0BAA0B,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;IACvE,IAAI,IAAI,CAAC,QAAQ;QAAE,GAAG,CAAC,8BAA8B,CAAC,GAAG,GAAG,CAAC;IAC7D,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAA0B,EAAE;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACnD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC/E,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAE/F,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACxF,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACtE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-mcp",
-  "version": "2026.6.19",
+  "version": "2026.6.27",
   "description": "BuilderForce Agent Memory — MCP transport. Exposes @seanhogg/builderforce-memory to any MCP client (Claude Agent SDK in-process, stdio, or HTTP) over a pluggable MemoryBackend, with token-saving fetch-on-demand recall.",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
   },
   "bin": {
     "builderforce-memory-mcp": "dist/bin/stdio.js",
-    "builderforce-memory-mcp-http": "dist/bin/http.js"
+    "builderforce-memory-mcp-http": "dist/bin/http.js",
+    "builderforce-memory-install": "dist/bin/install.js"
   },
   "files": [
     "dist",
@@ -49,7 +50,7 @@
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": ">=0.1.0",
-    "@seanhogg/builderforce-memory": "^2026.6.19",
+    "@seanhogg/builderforce-memory": "^2026.6.27",
     "fake-indexeddb": "^6.0.0"
   },
   "peerDependenciesMeta": {
@@ -71,7 +72,7 @@
     "eslint": "^8.57.0",
     "fake-indexeddb": "^6.0.0",
     "typescript": "^5.0.0",
-    "@seanhogg/builderforce-memory": "2026.6.19"
+    "@seanhogg/builderforce-memory": "2026.6.27"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -81,6 +82,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "tsc && node --test tests/install.test.mjs",
     "lint": "eslint src/"
   }
 }

package/src/bin/install.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * builderforce-memory-install — wire the memory MCP server into any MCP-capable
+ * agent (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, Gemini
+ * CLI, Codex CLI), not just Claude Code.
+ *
+ *   npx -y @seanhogg/builderforce-memory-mcp                 # via the package's other bin
+ *   builderforce-memory-install                              # auto-detect installed hosts
+ *   builderforce-memory-install --host=cursor,windsurf       # explicit hosts
+ *   builderforce-memory-install --host=all                   # every known host
+ *   builderforce-memory-install --memory-file=/path/mem.json # shared store path
+ *   builderforce-memory-install --readonly                   # recall-only
+ *   builderforce-memory-install --local=/abs/dist/bin/stdio.js  # dev: local bin
+ *
+ * The store defaults to ~/.builderforce-memory/memory.json so every agent on
+ * the machine shares one memory. Re-running is safe (idempotent + .bak backups).
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { HOSTS } from "../install/hosts.js";
+import { installMemoryServer, type HostSelector } from "../install/install.js";
+
+function argValue(name: string): string | undefined {
+    const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
+    return hit ? hit.slice(name.length + 3) : undefined;
+}
+const hasFlag = (name: string): boolean => process.argv.includes(`--${name}`);
+
+if (hasFlag("help") || hasFlag("h")) {
+    process.stdout.write(
+        [
+            "builderforce-memory-install — register the memory MCP server into MCP hosts.",
+            "",
+            "  --host=<a,b|all>     hosts to target (default: auto-detect installed)",
+            "  --memory-file=<path> JSON snapshot path (default: ~/.builderforce-memory/memory.json)",
+            "  --readonly           recall-only (no remember/forget)",
+            "  --local=<path>       run a locally-built stdio bin via node (dev)",
+            "",
+            `Known hosts: ${HOSTS.map((h) => h.id).join(", ")}`,
+            "",
+        ].join("\n"),
+    );
+    process.exit(0);
+}
+
+const hostArg = argValue("host");
+const hosts: HostSelector =
+    hostArg === undefined || hostArg === "auto"
+        ? "auto"
+        : hostArg === "all"
+          ? "all"
+          : hostArg.split(",").map((s) => s.trim()).filter(Boolean);
+
+const memoryFile = argValue("memory-file") ?? path.join(os.homedir(), ".builderforce-memory", "memory.json");
+
+let results;
+try {
+    results = installMemoryServer({
+        hosts,
+        memoryFile,
+        readonly: hasFlag("readonly"),
+        localBin: argValue("local"),
+    });
+} catch (err) {
+    process.stderr.write(`✗ ${String((err as Error).message ?? err)}\n`);
+    process.exit(1);
+}
+
+const icon: Record<string, string> = {
+    installed: "✓",
+    updated: "✓",
+    skipped: "•",
+    unsupported: "–",
+    error: "✗",
+};
+
+let wrote = 0;
+for (const r of results) {
+    const where = r.path ? `  ${r.path}` : "";
+    const why = r.detail ? `  (${r.detail})` : "";
+    process.stdout.write(`${icon[r.status] ?? "?"} ${r.label}: ${r.status}${why}${where}\n`);
+    if (r.status === "installed" || r.status === "updated") wrote += 1;
+}
+
+if (results.length === 0) {
+    process.stdout.write(
+        "No MCP hosts detected. Pass --host=all to write configs anyway, or --host=cursor (etc.).\n",
+    );
+} else {
+    process.stdout.write(
+        `\nDone — ${wrote} config(s) written. Store: ${memoryFile}\nRestart the agent(s) to connect. Tools: memory_recall · memory_remember · memory_get · memory_recall_by_tag · memory_forget\n`,
+    );
+}

package/src/index.ts

@@ -29,3 +29,11 @@ export { runStdio } from "./transports/stdio.js";
 
 export { createMemoryHttpHandler } from "./transports/http.js";
 export type { HttpHandlerOptions } from "./transports/http.js";
+
+// ── Multi-host installer (wire the stdio server into any MCP-capable agent) ───
+export { buildServerSpec, MCP_PACKAGE, MCP_BIN, RUNTIME_PEERS } from "./install/server-spec.js";
+export type { StdioServerSpec, ServerSpecOptions } from "./install/server-spec.js";
+export { installMemoryServer } from "./install/install.js";
+export type { InstallOptions, InstallResult, InstallStatus, HostSelector, FsLike } from "./install/install.js";
+export { HOSTS, SERVER_KEY, findHost } from "./install/hosts.js";
+export type { HostAdapter, HostEnv, ConfigFormat } from "./install/hosts.js";

package/src/install/hosts.ts

@@ -0,0 +1,125 @@
+/**
+ * Host registry — every MCP-capable agent we know how to wire memory into.
+ *
+ * The differences between hosts collapse to three things: WHERE the config
+ * file lives, which top-level key holds the server map (`mcpServers` vs VS
+ * Code's `servers`), and whether the entry carries an explicit `type:"stdio"`.
+ * Codex CLI is the one odd-one-out (TOML, not JSON). Everything else is one
+ * shared JSON merge — see install.ts.
+ */
+
+import path from "node:path";
+
+export type ConfigFormat = "json-mcpServers" | "json-servers" | "toml";
+
+export interface HostEnv {
+    homedir: string;
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+}
+
+export interface HostAdapter {
+    id: string;
+    label: string;
+    format: ConfigFormat;
+    /** Include `type:"stdio"` in the written entry (Claude Code + VS Code want it). */
+    includeType: boolean;
+    /** Absolute config-file path for this host, or null if N/A on this OS. */
+    configPath(e: HostEnv): string | null;
+}
+
+/** The server key written into every host's config. */
+export const SERVER_KEY = "builderforce-memory";
+
+/** Per-OS application-support directory for a desktop vendor (Claude, Code). */
+function appSupport(e: HostEnv, vendor: string): string | null {
+    if (e.platform === "win32") {
+        const roaming = e.env["APPDATA"] ?? path.join(e.homedir, "AppData", "Roaming");
+        return path.join(roaming, vendor);
+    }
+    if (e.platform === "darwin") {
+        return path.join(e.homedir, "Library", "Application Support", vendor);
+    }
+    const xdg = e.env["XDG_CONFIG_HOME"] ?? path.join(e.homedir, ".config");
+    return path.join(xdg, vendor);
+}
+
+/** VS Code stores its per-user files under `<appSupport(Code)>/User`. */
+function vscodeUserDir(e: HostEnv): string | null {
+    const base = appSupport(e, "Code");
+    return base ? path.join(base, "User") : null;
+}
+
+export const HOSTS: HostAdapter[] = [
+    {
+        id: "claude-code",
+        label: "Claude Code",
+        format: "json-mcpServers",
+        includeType: true,
+        configPath: (e) => path.join(e.homedir, ".claude.json"),
+    },
+    {
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => {
+            const dir = appSupport(e, "Claude");
+            return dir ? path.join(dir, "claude_desktop_config.json") : null;
+        },
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => path.join(e.homedir, ".cursor", "mcp.json"),
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => path.join(e.homedir, ".codeium", "windsurf", "mcp_config.json"),
+    },
+    {
+        id: "vscode",
+        label: "VS Code",
+        format: "json-servers",
+        includeType: true,
+        configPath: (e) => {
+            const dir = vscodeUserDir(e);
+            return dir ? path.join(dir, "mcp.json") : null;
+        },
+    },
+    {
+        id: "cline",
+        label: "Cline (VS Code)",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => {
+            const dir = vscodeUserDir(e);
+            return dir
+                ? path.join(dir, "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json")
+                : null;
+        },
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        format: "json-mcpServers",
+        includeType: false,
+        configPath: (e) => path.join(e.homedir, ".gemini", "settings.json"),
+    },
+    {
+        id: "codex",
+        label: "Codex CLI",
+        format: "toml",
+        includeType: false,
+        configPath: (e) => path.join(e.homedir, ".codex", "config.toml"),
+    },
+];
+
+export function findHost(id: string): HostAdapter | undefined {
+    return HOSTS.find((h) => h.id === id);
+}

package/src/install/install.ts

@@ -0,0 +1,177 @@
+/**
+ * Host-agnostic installer: register the builderforce-memory MCP server into any
+ * combination of MCP-capable agents. One shared launch spec (server-spec.ts),
+ * one entry per host config, idempotent and backup-safe.
+ *
+ * Pure-ish: all filesystem + environment access goes through injectable seams
+ * so the merge logic is unit-testable without touching a real machine.
+ */
+
+import nodeFs from "node:fs";
+import nodeOs from "node:os";
+import nodePath from "node:path";
+import { HOSTS, SERVER_KEY, type HostAdapter, type HostEnv } from "./hosts.js";
+import { buildServerSpec, type ServerSpecOptions, type StdioServerSpec } from "./server-spec.js";
+
+export interface FsLike {
+    existsSync(p: string): boolean;
+    readFileSync(p: string, enc: "utf8"): string;
+    writeFileSync(p: string, data: string): void;
+    mkdirSync(p: string, opts: { recursive: boolean }): void;
+    copyFileSync(src: string, dest: string): void;
+}
+
+export type HostSelector = string[] | "auto" | "all";
+
+export interface InstallOptions extends ServerSpecOptions {
+    /**
+     * Which hosts to target:
+     *   - "auto" (default) — only hosts whose config file or parent dir exists.
+     *   - "all"            — every known host (creates configs as needed).
+     *   - string[]         — explicit host ids (see HOSTS).
+     */
+    hosts?: HostSelector;
+    fs?: FsLike;
+    hostEnv?: HostEnv;
+}
+
+export type InstallStatus = "installed" | "updated" | "skipped" | "unsupported" | "error";
+
+export interface InstallResult {
+    host: string;
+    label: string;
+    path: string | null;
+    status: InstallStatus;
+    detail?: string;
+}
+
+function defaultHostEnv(): HostEnv {
+    return { homedir: nodeOs.homedir(), platform: process.platform, env: process.env };
+}
+
+function readJson(fs: FsLike, file: string): Record<string, unknown> {
+    if (!fs.existsSync(file)) return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+    } catch {
+        // Corrupt/partial config — surface as error rather than clobbering it.
+        throw new Error("existing config is not valid JSON");
+    }
+}
+
+function entryFor(spec: StdioServerSpec, includeType: boolean): Record<string, unknown> {
+    return {
+        ...(includeType ? { type: "stdio" } : {}),
+        command: spec.command,
+        args: spec.args,
+        ...(spec.env ? { env: spec.env } : {}),
+    };
+}
+
+function ensureParent(fs: FsLike, file: string): void {
+    const dir = nodePath.dirname(file);
+    if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+/** A host is "present" if its config file or its parent directory already exists. */
+function isPresent(fs: FsLike, file: string): boolean {
+    return fs.existsSync(file) || fs.existsSync(nodePath.dirname(file));
+}
+
+function installJson(
+    fs: FsLike,
+    host: HostAdapter,
+    file: string,
+    spec: StdioServerSpec,
+): InstallStatus {
+    const mapKey = host.format === "json-servers" ? "servers" : "mcpServers";
+    const config = readJson(fs, file);
+    const map = (config[mapKey] && typeof config[mapKey] === "object" ? config[mapKey] : {}) as Record<
+        string,
+        unknown
+    >;
+    const next = entryFor(spec, host.includeType);
+    const prev = map[SERVER_KEY];
+    const existed = prev !== undefined;
+    if (existed && JSON.stringify(prev) === JSON.stringify(next)) return "skipped";
+
+    if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`);
+    map[SERVER_KEY] = next;
+    config[mapKey] = map;
+    ensureParent(fs, file);
+    fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+    return existed ? "updated" : "installed";
+}
+
+/** TOML emit is append-only and idempotent: skip if the table already exists. */
+function installToml(fs: FsLike, file: string, spec: StdioServerSpec): InstallStatus {
+    const header = `[mcp_servers.${SERVER_KEY}]`;
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    if (existing.includes(header)) return "skipped";
+
+    const q = (s: string) => JSON.stringify(s); // TOML basic strings are JSON-compatible here
+    const lines = [
+        header,
+        `command = ${q(spec.command)}`,
+        `args = [${spec.args.map(q).join(", ")}]`,
+    ];
+    if (spec.env) {
+        lines.push(`[mcp_servers.${SERVER_KEY}.env]`);
+        for (const [k, v] of Object.entries(spec.env)) lines.push(`${k} = ${q(v)}`);
+    }
+    const block = `${lines.join("\n")}\n`;
+
+    if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`);
+    ensureParent(fs, file);
+    const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : "";
+    fs.writeFileSync(file, `${existing}${sep}${block}`);
+    return "installed";
+}
+
+function resolveHosts(selector: HostSelector, fs: FsLike, hostEnv: HostEnv): HostAdapter[] {
+    if (Array.isArray(selector)) {
+        return selector.map((id) => {
+            const h = HOSTS.find((x) => x.id === id);
+            if (!h) throw new Error(`unknown host "${id}" (known: ${HOSTS.map((x) => x.id).join(", ")})`);
+            return h;
+        });
+    }
+    if (selector === "all") return HOSTS;
+    // "auto": only hosts that look installed on this machine.
+    return HOSTS.filter((h) => {
+        const p = h.configPath(hostEnv);
+        return p !== null && isPresent(fs, p);
+    });
+}
+
+/**
+ * Register (or refresh) the memory MCP server across the selected hosts.
+ * Never throws for a single host — per-host failures are captured as
+ * `status:"error"` so one bad config can't abort the rest.
+ */
+export function installMemoryServer(opts: InstallOptions = {}): InstallResult[] {
+    const fs: FsLike = opts.fs ?? nodeFs;
+    const hostEnv = opts.hostEnv ?? defaultHostEnv();
+    const selector: HostSelector = opts.hosts ?? "auto";
+    const spec = buildServerSpec({
+        memoryFile: opts.memoryFile,
+        readonly: opts.readonly,
+        platform: opts.platform ?? hostEnv.platform,
+        localBin: opts.localBin,
+    });
+
+    const hosts = resolveHosts(selector, fs, hostEnv);
+    return hosts.map((host): InstallResult => {
+        const file = host.configPath(hostEnv);
+        if (file === null) {
+            return { host: host.id, label: host.label, path: null, status: "unsupported", detail: "not available on this OS" };
+        }
+        try {
+            const status = host.format === "toml" ? installToml(fs, file, spec) : installJson(fs, host, file, spec);
+            return { host: host.id, label: host.label, path: file, status };
+        } catch (err) {
+            return { host: host.id, label: host.label, path: file, status: "error", detail: String((err as Error).message ?? err) };
+        }
+    });
+}

package/src/install/server-spec.ts

@@ -0,0 +1,72 @@
+/**
+ * The canonical stdio launch spec for the builderforce-memory MCP server.
+ *
+ * Every host (Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini/Codex CLI,
+ * Claude Desktop) registers the SAME server — only the surrounding config
+ * file/shape differs. This module is the single source of truth for HOW the
+ * server is launched, so the per-host adapters never re-derive the command.
+ */
+
+export interface StdioServerSpec {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+
+export interface ServerSpecOptions {
+    /** Absolute path to the JSON snapshot that makes memory survive restarts. */
+    memoryFile?: string;
+    /** Register read-only (disables the remember/forget tools). */
+    readonly?: boolean;
+    /** Platform to target (command wrapping). Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /**
+     * Run a locally-built stdio bin via `node <path>` instead of the published
+     * package via `npx` — for development against a checkout.
+     */
+    localBin?: string;
+}
+
+/** Published package + bin. The bin name matches the unscoped package name. */
+export const MCP_PACKAGE = "@seanhogg/builderforce-memory-mcp";
+export const MCP_BIN = "builderforce-memory-mcp";
+
+/**
+ * Runtime peers the stdio bin loads on demand. They are OPTIONAL peers of the
+ * MCP package (so a custom-backend / HTTP-thin-client consumer needn't install
+ * them), which means `npx` will NOT auto-pull them — the stdio launch lists
+ * them explicitly. `-engine` arrives as `-memory`'s required peer; listed too
+ * for determinism.
+ */
+export const RUNTIME_PEERS = [
+    "@seanhogg/builderforce-memory",
+    "@seanhogg/builderforce-memory-engine",
+    "fake-indexeddb",
+];
+
+function specEnv(opts: ServerSpecOptions): Record<string, string> | undefined {
+    const env: Record<string, string> = {};
+    if (opts.memoryFile) env["BUILDERFORCE_MEMORY_FILE"] = opts.memoryFile;
+    if (opts.readonly) env["BUILDERFORCE_MEMORY_READONLY"] = "1";
+    return Object.keys(env).length > 0 ? env : undefined;
+}
+
+/**
+ * Build the stdio launch spec. On Windows `npx` is a `.cmd` shim that an MCP
+ * launcher must invoke through `cmd`; `node` + a local path needs no shell.
+ */
+export function buildServerSpec(opts: ServerSpecOptions = {}): StdioServerSpec {
+    const platform = opts.platform ?? process.platform;
+    const env = specEnv(opts);
+
+    if (opts.localBin) {
+        return { command: "node", args: [opts.localBin], ...(env ? { env } : {}) };
+    }
+
+    const npxArgs = ["-y", "-p", MCP_PACKAGE, ...RUNTIME_PEERS.flatMap((p) => ["-p", p]), MCP_BIN];
+
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/c", "npx", ...npxArgs], ...(env ? { env } : {}) };
+    }
+    return { command: "npx", args: npxArgs, ...(env ? { env } : {}) };
+}