recallx 1.1.0 → 1.2.0

package/README.md

@@ -43,7 +43,7 @@ Use the public repo when you want the full source-run surface:
 
 - local API under `/api/v1`
 - source-run renderer workflow through `npm run dev`
-- stdio MCP bridge through `npm run mcp`
+- stdio MCP bridge through `npm run dev:mcp` during source development
 - runtime workspace create/open switching without restarting the service
 
 ```bash
@@ -56,6 +56,13 @@ npm run dev
 MCP from source:
 
 ```bash
+npm run dev:mcp
+```
+
+If you want to run the built MCP entrypoint instead, build the server first:
+
+```bash
+npm run build:server
 npm run mcp
 ```
 
@@ -88,6 +95,18 @@ When you are preparing a release, bump from the highest known version instead of
 npm run version:bump -- patch
 ```
 
+Workspace lifecycle and backup commands from the same source checkout:
+
+```bash
+recallx workspace current
+recallx workspace backups
+recallx workspace backup --label "before-upgrade"
+recallx workspace export --format markdown
+recallx workspace restore --backup <id> --root /path/to/restore
+```
+
+The renderer Workspace page exposes the same backup, export, restore, and single-writer safety warnings over the local API.
+
 If you want an installable runtime instead of source-run workflows, use one of the npm distribution paths below.
 
 ## 2. npm Full Runtime (`recallx`)
@@ -118,6 +137,15 @@ The full npm package includes:
 
 `recallx mcp install` writes a stable launcher to `~/.recallx/bin/recallx-mcp`, which is the recommended command path for Codex and other editor MCP configs.
 
+Workspace backup and recovery commands are available in the packaged CLI too:
+
+```bash
+recallx workspace backups
+recallx workspace backup --label "before-upgrade"
+recallx workspace export --format json
+recallx workspace restore --backup <id> --root /path/to/restore
+```
+
 If the API is running in bearer mode, set `RECALLX_API_TOKEN` in the MCP client environment. The launcher does not write tokens to disk.
 
 Start the packaged runtime with:
@@ -228,11 +256,14 @@ RecallX also ships a stdio MCP adapter for agent clients that prefer tool discov
 MCP tool results keep `structuredContent` as the authoritative machine-readable payload, while `content.text` is rendered as a compact deterministic summary instead of a pretty-printed JSON mirror when the payload shape is known.
 
 ```bash
+npm run dev:mcp
 npm run mcp
 node dist/server/app/mcp/index.js --api http://127.0.0.1:8787/api/v1
 recallx-mcp --api http://127.0.0.1:8787/api/v1
 ```
 
+Use `npm run dev:mcp` during source development. `npm run mcp` runs the built entrypoint, so it expects `npm run build:server` to have already created `dist/server/app/mcp/index.js`.
+
 For launcher paths, environment variables, and editor-specific setup, see `docs/mcp.md`.
 
 ## Docs
@@ -243,6 +274,7 @@ For launcher paths, environment variables, and editor-specific setup, see `docs/
 - `docs/api.md` for the local HTTP and CLI contract
 - `docs/mcp.md` for MCP bridge setup
 - `docs/workflows.md` for common usage flows
+- `docs/sync-backup.md` for backup, restore, and single-writer multi-device guidance
 - `docs/schema.md` for storage and data model details
 
 ## License

package/app/cli/src/cli.js

@@ -6,7 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { getApiBase, getAuthToken, requestJson } from "./http.js";
 import { RECALLX_VERSION } from "../../shared/version.js";
 import { applyCliUpdate, getCliUpdatePlan } from "./update.js";
-import { renderActivitySearchResults, renderBundleMarkdown, renderGovernanceIssues, renderJson, renderNode, renderRelated, renderSearchResults, renderTelemetryErrors, renderTelemetrySummary, renderText, renderUpdateResult, renderWorkspaceSearchResults, renderWorkspaces, } from "./format.js";
+import { renderActivitySearchResults, renderBundleMarkdown, renderGovernanceIssues, renderJson, renderNode, renderRelated, renderSearchResults, renderTelemetryErrors, renderTelemetrySummary, renderText, renderUpdateResult, renderWorkspaceBackups, renderWorkspaceSearchResults, renderWorkspaces, } from "./format.js";
 const DEFAULT_SOURCE = {
     actorType: "human",
     actorLabel: "recallx-cli",
@@ -465,6 +465,27 @@ async function runWorkspace(apiBase, token, format, args, positionals) {
                 action,
                 rootPath: args.root || args.path || positionals[1],
             });
+        case "backups": {
+            const data = await requestJson(apiBase, "/workspaces/backups", { token });
+            outputData(data, format, "workspace-backups");
+            return;
+        }
+        case "backup":
+            return runPostCommand(apiBase, token, format, "/workspaces/backups", "workspace-backup", {
+                label: args.label || args.name || positionals[1],
+            });
+        case "export":
+            return runPostCommand(apiBase, token, format, "/workspaces/export", "workspace-export", {
+                format: args.format || args.kind || "json",
+            });
+        case "restore":
+            validateRequired(args.backup || args.id || positionals[1], "workspace restore requires --backup");
+            validateRequired(args.root || args.path || positionals[2], "workspace restore requires --root");
+            return runPostCommand(apiBase, token, format, "/workspaces/restore", "workspace-restore", {
+                backupId: args.backup || args.id || positionals[1],
+                targetRootPath: args.root || args.path || positionals[2],
+                workspaceName: args.name || args.title,
+            });
     }
     throw new Error(`Unknown workspace action: ${action}`);
 }
@@ -547,6 +568,9 @@ function outputData(data, format, command) {
         case "workspace-list":
             writeStdout(renderWorkspaces(payload));
             return;
+        case "workspace-backups":
+            writeStdout(renderWorkspaceBackups(payload));
+            return;
         case "append":
         case "create":
         case "link":
@@ -557,6 +581,9 @@ function outputData(data, format, command) {
         case "workspace-current":
         case "workspace-create":
         case "workspace-open":
+        case "workspace-backup":
+        case "workspace-export":
+        case "workspace-restore":
             writeStdout(renderText(payload));
             return;
         case "observability-summary":
@@ -696,6 +723,10 @@ Usage:
   recallx workspace list
   recallx workspace create --root /path/to/workspace [--name "Personal"]
   recallx workspace open --root /path/to/workspace
+  recallx workspace backups
+  recallx workspace backup [--label "before-upgrade"]
+  recallx workspace export [--format json|markdown]
+  recallx workspace restore --backup <id> --root /path/to/restore [--name "Recovered"]
   recallx observability summary [--since 24h]
   recallx observability errors [--since 24h] [--surface mcp] [--limit 50]
 

package/app/cli/src/format.js

@@ -144,6 +144,20 @@ export function renderWorkspaces(data) {
     .join("\n\n")}\n`;
 }
 
+export function renderWorkspaceBackups(data) {
+  const items = data?.items || [];
+  if (!items.length) {
+    return "No backups.\n";
+  }
+
+  return `${items
+    .map(
+      (item, index) =>
+        `${index + 1}. ${item.label || item.id}\n  id: ${item.id}\n  created: ${item.createdAt}\n  path: ${item.backupPath}`,
+    )
+    .join("\n\n")}\n`;
+}
+
 export function renderUpdateResult(data) {
   const lines = [
     `package: ${data?.packageName || ""}`,