@hasna/mementos 0.14.29 → 0.14.30

package/README.md

@@ -47,3 +47,16 @@ integration snippets. OpenCode and Antigravity receive the same MCP registration
 plus host instruction files that tell the agent to use `memory.search`,
 `memory.save`, and `mementos inject` as the hosted fallback path when native
 hooks are unavailable.
+
+## Bridge
+
+```bash
+mementos bridge status
+mementos bridge start --agent <name>
+mementos bridge stop
+mementos bridge install
+```
+
+The bridge is remote-only. It keeps PID/log/service metadata under user config
+paths and heartbeats the hosted agent when `--agent` or `MEMENTOS_AGENT_NAME` is
+set; it does not own a local memory store.

package/dist/bridge.d.ts

@@ -0,0 +1,50 @@
+export interface BridgeOptions {
+    agentName?: string;
+    apiUrl?: string;
+    homeDir?: string;
+    intervalMs?: number;
+    platform?: NodeJS.Platform;
+}
+export interface BridgeStartOptions extends BridgeOptions {
+    command?: string[];
+}
+export interface BridgeServiceOptions extends BridgeOptions {
+    command?: string;
+}
+export interface BridgePaths {
+    baseDir: string;
+    logFile: string;
+    pidFile: string;
+    serviceFile: string;
+}
+export interface BridgeStatus {
+    agentName?: string;
+    apiUrl: string;
+    localDatabase: false;
+    logFile: string;
+    pid?: number;
+    pidFile: string;
+    remoteOnly: true;
+    running: boolean;
+    startedAt?: string;
+}
+export interface BridgeServiceResult {
+    path: string;
+    remoteOnly: true;
+    status: "installed" | "removed" | "absent";
+}
+export declare function buildBridgePaths(homeDir?: string, platform?: NodeJS.Platform): BridgePaths;
+export declare function getBridgeStatus(options?: BridgeOptions): BridgeStatus;
+export declare function startBridge(options?: BridgeStartOptions): BridgeStatus;
+export declare function stopBridge(options?: BridgeOptions): BridgeServiceResult;
+export declare function installBridgeService(options?: BridgeServiceOptions): BridgeServiceResult;
+export declare function uninstallBridgeService(options?: BridgeOptions): BridgeServiceResult;
+export declare function readBridgeLogs(options?: BridgeOptions & {
+    lines?: number;
+}): string[];
+export declare function writeBridgePid(options: BridgeOptions & {
+    pid: number;
+    startedAt: string;
+}): void;
+export declare function clearBridgePid(options?: BridgeOptions): void;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,KAAK,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,IAAI,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;CAC5C;AASD,wBAAgB,gBAAgB,CAAC,OAAO,SAAY,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,WAAW,CAU/G;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,aAAkB,GAAG,YAAY,CAYzE;AAED,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,YAAY,CA8B1E;AAED,wBAAgB,UAAU,CAAC,OAAO,GAAE,aAAkB,GAAG,mBAAmB,CAO3E;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAW5F;AAED,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,aAAkB,GAAG,mBAAmB,CAKvF;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,EAAE,CAOzF;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAShG;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,aAAkB,GAAG,IAAI,CAEhE"}

package/dist/cli.js

@@ -573,6 +573,185 @@ function findLocalDatabaseFiles(dir) {
   });
 }
 
+// src/bridge.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+function buildBridgePaths(homeDir = homedir2(), platform = process.platform) {
+  const baseDir = join2(homeDir, ".config", "mementos", "bridge");
+  return {
+    baseDir,
+    logFile: join2(baseDir, "bridge.log"),
+    pidFile: join2(baseDir, "bridge.pid.json"),
+    serviceFile: platform === "darwin" ? join2(homeDir, "Library", "LaunchAgents", "md.mementos.bridge.plist") : join2(homeDir, ".config", "systemd", "user", "mementos-bridge.service")
+  };
+}
+function getBridgeStatus(options = {}) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  const pidFile = readBridgePid(paths.pidFile);
+  if (pidFile && !isRunning(pidFile.pid)) {
+    rmSync2(paths.pidFile, { force: true });
+    return baseStatus(paths, options, false);
+  }
+  return {
+    ...baseStatus(paths, options, Boolean(pidFile)),
+    ...pidFile?.agentName ? { agentName: pidFile.agentName } : {},
+    ...pidFile ? { pid: pidFile.pid, startedAt: pidFile.startedAt } : {}
+  };
+}
+function startBridge(options = {}) {
+  const current = getBridgeStatus(options);
+  if (current.running)
+    return current;
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  mkdirSync2(paths.baseDir, { recursive: true });
+  const out = openSync(paths.logFile, "a");
+  const err = openSync(paths.logFile, "a");
+  const command = options.command ?? [process.execPath, process.argv[1] ?? "mementos", "bridge", "run"];
+  const child = spawn(command[0] ?? "mementos", command.slice(1), {
+    detached: true,
+    env: {
+      ...process.env,
+      ...options.agentName ? { MEMENTOS_AGENT_NAME: options.agentName } : {},
+      ...options.apiUrl ? { MEMENTOS_API_URL: options.apiUrl } : {},
+      ...options.homeDir ? { MEMENTOS_BRIDGE_HOME: options.homeDir } : {},
+      ...options.intervalMs ? { MEMENTOS_BRIDGE_INTERVAL_MS: String(options.intervalMs) } : {}
+    },
+    stdio: ["ignore", out, err]
+  });
+  child.unref();
+  writeBridgePid({
+    agentName: options.agentName,
+    apiUrl: options.apiUrl,
+    homeDir: options.homeDir,
+    pid: child.pid ?? 0,
+    startedAt: new Date().toISOString()
+  });
+  return getBridgeStatus(options);
+}
+function stopBridge(options = {}) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  const pidFile = readBridgePid(paths.pidFile);
+  if (!pidFile)
+    return { path: paths.pidFile, remoteOnly: true, status: "absent" };
+  if (isRunning(pidFile.pid))
+    process.kill(pidFile.pid, "SIGTERM");
+  clearBridgePid(options);
+  return { path: paths.pidFile, remoteOnly: true, status: "removed" };
+}
+function installBridgeService(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const paths = buildBridgePaths(options.homeDir, platform);
+  mkdirSync2(dirname2(paths.serviceFile), { recursive: true });
+  const command = options.command ?? "mementos bridge run";
+  const apiUrl = options.apiUrl ?? "https://mementos.md/api/v1";
+  const content = platform === "darwin" ? renderLaunchdService(command, apiUrl, options.agentName) : renderSystemdService(command, apiUrl, options.agentName);
+  writeFileSync2(paths.serviceFile, content, { mode: 420 });
+  return { path: paths.serviceFile, remoteOnly: true, status: "installed" };
+}
+function uninstallBridgeService(options = {}) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  if (!existsSync2(paths.serviceFile))
+    return { path: paths.serviceFile, remoteOnly: true, status: "absent" };
+  rmSync2(paths.serviceFile, { force: true });
+  return { path: paths.serviceFile, remoteOnly: true, status: "removed" };
+}
+function readBridgeLogs(options = {}) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  if (!existsSync2(paths.logFile))
+    return [];
+  return readFileSync2(paths.logFile, "utf8").split(`
+`).filter(Boolean).slice(-(options.lines ?? 40));
+}
+function writeBridgePid(options) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  mkdirSync2(paths.baseDir, { recursive: true });
+  writeFileSync2(paths.pidFile, `${JSON.stringify({
+    ...options.agentName ? { agentName: options.agentName } : {},
+    ...options.apiUrl ? { apiUrl: options.apiUrl } : {},
+    pid: options.pid,
+    startedAt: options.startedAt
+  }, null, 2)}
+`, { mode: 420 });
+}
+function clearBridgePid(options = {}) {
+  rmSync2(buildBridgePaths(options.homeDir, options.platform).pidFile, { force: true });
+}
+function baseStatus(paths, options, running) {
+  return {
+    ...options.agentName ? { agentName: options.agentName } : {},
+    apiUrl: options.apiUrl ?? "https://mementos.md/api/v1",
+    localDatabase: false,
+    logFile: paths.logFile,
+    pidFile: paths.pidFile,
+    remoteOnly: true,
+    running
+  };
+}
+function readBridgePid(path) {
+  if (!existsSync2(path))
+    return;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return Number.isInteger(parsed.pid) && parsed.pid > 0 ? parsed : undefined;
+  } catch {
+    return;
+  }
+}
+function isRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function renderSystemdService(command, apiUrl, agentName) {
+  return `[Unit]
+Description=mementos.md remote bridge
+
+[Service]
+Type=simple
+Environment=MEMENTOS_API_URL=${apiUrl}
+${agentName ? `Environment=MEMENTOS_AGENT_NAME=${agentName}
+` : ""}ExecStart=${command}
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+`;
+}
+function renderLaunchdService(command, apiUrl, agentName) {
+  const args = command.split(/\s+/).map((part) => `    <string>${escapeXml(part)}</string>`).join(`
+`);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>md.mementos.bridge</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>MEMENTOS_API_URL</key>
+    <string>${escapeXml(apiUrl)}</string>
+${agentName ? `    <key>MEMENTOS_AGENT_NAME</key>
+    <string>${escapeXml(agentName)}</string>
+` : ""}  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
 // src/remote-client.ts
 var DEFAULT_API_URL = "https://mementos.md/api/v1";
 
@@ -753,6 +932,8 @@ async function run(name, args) {
       return injectMemory(args);
     case "hook":
       return runHook(args);
+    case "bridge":
+      return runBridge(args);
     case "billing":
       return runBilling(args);
     case "inbox":
@@ -778,6 +959,37 @@ async function run(name, args) {
 ${helpText()}`);
   }
 }
+async function runBridge(args) {
+  const subcommand = args[0] ?? "status";
+  const options = parseBridgeOptions(args.slice(1));
+  const bridgeOptions = {
+    agentName: options.agentName ?? process.env.MEMENTOS_AGENT_NAME,
+    apiUrl: baseApiUrl().endsWith("/api/v1") ? baseApiUrl() : `${baseApiUrl()}/api/v1`,
+    homeDir: options.homeDir ?? process.env.MEMENTOS_BRIDGE_HOME,
+    intervalMs: options.intervalMs ?? readPositiveInteger(process.env.MEMENTOS_BRIDGE_INTERVAL_MS)
+  };
+  switch (subcommand) {
+    case "start":
+      return startBridge(bridgeOptions);
+    case "status":
+      return getBridgeStatus(bridgeOptions);
+    case "stop":
+      return stopBridge(bridgeOptions);
+    case "install":
+      return installBridgeService({
+        ...bridgeOptions,
+        command: "mementos bridge run"
+      });
+    case "uninstall":
+      return uninstallBridgeService(bridgeOptions);
+    case "logs":
+      return { lines: readBridgeLogs({ ...bridgeOptions, lines: options.lines }) };
+    case "run":
+      return runBridgeDaemon(bridgeOptions, Boolean(options.once));
+    default:
+      throw new Error("usage: mementos bridge <start|status|stop|install|uninstall|logs|run>");
+  }
+}
 async function runInbox(args) {
   const subcommand = args[0] ?? "list";
   switch (subcommand) {
@@ -803,6 +1015,44 @@ async function runInbox(args) {
       throw new Error("usage: mementos inbox <send|list|claim>");
   }
 }
+async function runBridgeDaemon(options, once) {
+  writeBridgePid({
+    agentName: options.agentName,
+    apiUrl: options.apiUrl,
+    homeDir: options.homeDir,
+    pid: process.pid,
+    startedAt: new Date().toISOString()
+  });
+  const cleanup = () => clearBridgePid(options);
+  process.once("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.once("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+  try {
+    const intervalMs = options.intervalMs ?? 30000;
+    do {
+      if (options.agentName) {
+        await client.heartbeatAgent({
+          name: options.agentName,
+          source: "mementos-bridge"
+        });
+      }
+      if (once)
+        break;
+      await sleep(intervalMs);
+    } while (true);
+    if (once)
+      cleanup();
+    return getBridgeStatus(options);
+  } finally {
+    if (once)
+      cleanup();
+  }
+}
 async function runBilling(args) {
   const subcommand = args[0] ?? "status";
   switch (subcommand) {
@@ -1017,6 +1267,26 @@ function parseSetupOptions(args) {
   }
   return options;
 }
+function parseBridgeOptions(args) {
+  const options = {};
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--agent" || arg === "--agent-name") {
+      options.agentName = args[++index];
+    } else if (arg === "--home") {
+      options.homeDir = args[++index];
+    } else if (arg === "--interval-ms") {
+      options.intervalMs = readPositiveInteger(args[++index]);
+    } else if (arg === "--lines") {
+      options.lines = readPositiveInteger(args[++index]);
+    } else if (arg === "--once") {
+      options.once = true;
+    } else {
+      throw new Error(`Unknown bridge option: ${arg}`);
+    }
+  }
+  return options;
+}
 function parseInboxOptions(args) {
   const options = {};
   for (let index = 0;index < args.length; index += 1) {
@@ -1049,6 +1319,18 @@ function parseHosts(input) {
 function baseProductUrl() {
   return (process.env.MEMENTOS_API_URL ?? DEFAULT_API_URL).replace(/\/api\/v1\/?$/, "").replace(/\/+$/, "");
 }
+function baseApiUrl() {
+  return (process.env.MEMENTOS_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
+}
+function readPositiveInteger(input) {
+  if (!input)
+    return;
+  const value = Number(input);
+  return Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function readTextPayload(payload) {
   if (typeof payload !== "object" || payload === null)
     return;
@@ -1063,6 +1345,7 @@ Usage:
   mementos setup agents [--dry-run|--verify|--uninstall]
   mementos inject <query>
   mementos hook <stop|user-prompt-submit|session-start|subagent-start|subagent-stop|pre-tool-use|post-tool-use|notification|setup|doctor>
+  mementos bridge <start|status|stop|install|uninstall|logs|run>
   mementos inbox <send|list|claim>
   mementos billing <status|credits|buy>
   mementos capabilities

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { DEFAULT_API_URL, MementosRemoteClient, MementosRemoteError, createRemoteClientFromEnv, normalizeApiUrl, type RemoteClientConfig, type RemoteRequestOptions, } from "./remote-client";
 export { REMOTE_MCP_TOOLS, callRemoteMcpTool, handleMcpMessage, startMcpStdio, type RemoteMcpTool, } from "./mcp-runtime";
 export { SUPPORTED_AGENT_HOSTS, buildAgentSetupPlan, diagnoseAgentSetup, formatMemoryInjection, installAgentSetup, renderSignupInstructions, type AgentSetupFile, type AgentSetupOptions, type AgentSetupPlan, type AgentSetupDiagnostic, type AgentSetupDiagnosticOptions, type SupportedAgentHost, } from "./agent-setup";
+export { buildBridgePaths, clearBridgePid, getBridgeStatus, installBridgeService, readBridgeLogs, startBridge, stopBridge, uninstallBridgeService, writeBridgePid, type BridgeOptions, type BridgePaths, type BridgeServiceOptions, type BridgeServiceResult, type BridgeStartOptions, type BridgeStatus, } from "./bridge";
 //# 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,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,YAAY,GAClB,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -146,7 +146,7 @@ function readErrorMessage(payload, status) {
 }
 // src/mcp-runtime.ts
 import { createInterface } from "readline";
-var MEMENTOS_MCP_VERSION = "0.14.29";
+var MEMENTOS_MCP_VERSION = "0.14.30";
 var AUTHLESS_SCHEMA = {
   type: "object",
   properties: {},
@@ -915,16 +915,203 @@ function findLocalDatabaseFiles(dir) {
     return localDbPattern.test(entry) ? [path] : [];
   });
 }
+// src/bridge.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+function buildBridgePaths(homeDir = homedir2(), platform = process.platform) {
+  const baseDir = join2(homeDir, ".config", "mementos", "bridge");
+  return {
+    baseDir,
+    logFile: join2(baseDir, "bridge.log"),
+    pidFile: join2(baseDir, "bridge.pid.json"),
+    serviceFile: platform === "darwin" ? join2(homeDir, "Library", "LaunchAgents", "md.mementos.bridge.plist") : join2(homeDir, ".config", "systemd", "user", "mementos-bridge.service")
+  };
+}
+function getBridgeStatus(options = {}) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  const pidFile = readBridgePid(paths.pidFile);
+  if (pidFile && !isRunning(pidFile.pid)) {
+    rmSync2(paths.pidFile, { force: true });
+    return baseStatus(paths, options, false);
+  }
+  return {
+    ...baseStatus(paths, options, Boolean(pidFile)),
+    ...pidFile?.agentName ? { agentName: pidFile.agentName } : {},
+    ...pidFile ? { pid: pidFile.pid, startedAt: pidFile.startedAt } : {}
+  };
+}
+function startBridge(options = {}) {
+  const current = getBridgeStatus(options);
+  if (current.running)
+    return current;
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  mkdirSync2(paths.baseDir, { recursive: true });
+  const out = openSync(paths.logFile, "a");
+  const err = openSync(paths.logFile, "a");
+  const command = options.command ?? [process.execPath, process.argv[1] ?? "mementos", "bridge", "run"];
+  const child = spawn(command[0] ?? "mementos", command.slice(1), {
+    detached: true,
+    env: {
+      ...process.env,
+      ...options.agentName ? { MEMENTOS_AGENT_NAME: options.agentName } : {},
+      ...options.apiUrl ? { MEMENTOS_API_URL: options.apiUrl } : {},
+      ...options.homeDir ? { MEMENTOS_BRIDGE_HOME: options.homeDir } : {},
+      ...options.intervalMs ? { MEMENTOS_BRIDGE_INTERVAL_MS: String(options.intervalMs) } : {}
+    },
+    stdio: ["ignore", out, err]
+  });
+  child.unref();
+  writeBridgePid({
+    agentName: options.agentName,
+    apiUrl: options.apiUrl,
+    homeDir: options.homeDir,
+    pid: child.pid ?? 0,
+    startedAt: new Date().toISOString()
+  });
+  return getBridgeStatus(options);
+}
+function stopBridge(options = {}) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  const pidFile = readBridgePid(paths.pidFile);
+  if (!pidFile)
+    return { path: paths.pidFile, remoteOnly: true, status: "absent" };
+  if (isRunning(pidFile.pid))
+    process.kill(pidFile.pid, "SIGTERM");
+  clearBridgePid(options);
+  return { path: paths.pidFile, remoteOnly: true, status: "removed" };
+}
+function installBridgeService(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const paths = buildBridgePaths(options.homeDir, platform);
+  mkdirSync2(dirname2(paths.serviceFile), { recursive: true });
+  const command = options.command ?? "mementos bridge run";
+  const apiUrl = options.apiUrl ?? "https://mementos.md/api/v1";
+  const content = platform === "darwin" ? renderLaunchdService(command, apiUrl, options.agentName) : renderSystemdService(command, apiUrl, options.agentName);
+  writeFileSync2(paths.serviceFile, content, { mode: 420 });
+  return { path: paths.serviceFile, remoteOnly: true, status: "installed" };
+}
+function uninstallBridgeService(options = {}) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  if (!existsSync2(paths.serviceFile))
+    return { path: paths.serviceFile, remoteOnly: true, status: "absent" };
+  rmSync2(paths.serviceFile, { force: true });
+  return { path: paths.serviceFile, remoteOnly: true, status: "removed" };
+}
+function readBridgeLogs(options = {}) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  if (!existsSync2(paths.logFile))
+    return [];
+  return readFileSync2(paths.logFile, "utf8").split(`
+`).filter(Boolean).slice(-(options.lines ?? 40));
+}
+function writeBridgePid(options) {
+  const paths = buildBridgePaths(options.homeDir, options.platform);
+  mkdirSync2(paths.baseDir, { recursive: true });
+  writeFileSync2(paths.pidFile, `${JSON.stringify({
+    ...options.agentName ? { agentName: options.agentName } : {},
+    ...options.apiUrl ? { apiUrl: options.apiUrl } : {},
+    pid: options.pid,
+    startedAt: options.startedAt
+  }, null, 2)}
+`, { mode: 420 });
+}
+function clearBridgePid(options = {}) {
+  rmSync2(buildBridgePaths(options.homeDir, options.platform).pidFile, { force: true });
+}
+function baseStatus(paths, options, running) {
+  return {
+    ...options.agentName ? { agentName: options.agentName } : {},
+    apiUrl: options.apiUrl ?? "https://mementos.md/api/v1",
+    localDatabase: false,
+    logFile: paths.logFile,
+    pidFile: paths.pidFile,
+    remoteOnly: true,
+    running
+  };
+}
+function readBridgePid(path) {
+  if (!existsSync2(path))
+    return;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return Number.isInteger(parsed.pid) && parsed.pid > 0 ? parsed : undefined;
+  } catch {
+    return;
+  }
+}
+function isRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function renderSystemdService(command, apiUrl, agentName) {
+  return `[Unit]
+Description=mementos.md remote bridge
+
+[Service]
+Type=simple
+Environment=MEMENTOS_API_URL=${apiUrl}
+${agentName ? `Environment=MEMENTOS_AGENT_NAME=${agentName}
+` : ""}ExecStart=${command}
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+`;
+}
+function renderLaunchdService(command, apiUrl, agentName) {
+  const args = command.split(/\s+/).map((part) => `    <string>${escapeXml(part)}</string>`).join(`
+`);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>md.mementos.bridge</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>MEMENTOS_API_URL</key>
+    <string>${escapeXml(apiUrl)}</string>
+${agentName ? `    <key>MEMENTOS_AGENT_NAME</key>
+    <string>${escapeXml(agentName)}</string>
+` : ""}  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
 export {
+  writeBridgePid,
+  uninstallBridgeService,
+  stopBridge,
   startMcpStdio,
+  startBridge,
   renderSignupInstructions,
+  readBridgeLogs,
   normalizeApiUrl,
+  installBridgeService,
   installAgentSetup,
   handleMcpMessage,
+  getBridgeStatus,
   formatMemoryInjection,
   diagnoseAgentSetup,
   createRemoteClientFromEnv,
+  clearBridgePid,
   callRemoteMcpTool,
+  buildBridgePaths,
   buildAgentSetupPlan,
   SUPPORTED_AGENT_HOSTS,
   REMOTE_MCP_TOOLS,

package/dist/mcp-runtime.d.ts

@@ -1,5 +1,5 @@
 import { MementosRemoteClient } from "./remote-client";
-export declare const MEMENTOS_MCP_VERSION = "0.14.29";
+export declare const MEMENTOS_MCP_VERSION = "0.14.30";
 export interface RemoteMcpTool {
     name: string;
     description: string;

package/dist/mcp.js

@@ -151,7 +151,7 @@ function readErrorMessage(payload, status) {
 }
 
 // src/mcp-runtime.ts
-var MEMENTOS_MCP_VERSION = "0.14.29";
+var MEMENTOS_MCP_VERSION = "0.14.30";
 var AUTHLESS_SCHEMA = {
   type: "object",
   properties: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/mementos",
-  "version": "0.14.29",
+  "version": "0.14.30",
   "description": "Remote-only mementos.md SaaS CLI and MCP client",
   "type": "module",
   "main": "dist/index.js",