recallx 1.0.8 → 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:
@@ -204,16 +232,38 @@ Use the returned endpoint list and request examples to search nodes and activiti
 Reuse the existing local service instead of starting a new one.
 ```
 
+Recommended instruction for MCP-connected coding agents:
+
+```text
+Use my RecallX MCP server as an active local memory layer during this task, not just for final write-back.
+Treat the current workspace as the default scope and do not switch workspaces unless I explicitly ask.
+Before making assumptions or starting meaningful work, read context first: confirm the current workspace, use recallx_search_workspace when the target is still unclear, search for an existing project node when the task is clearly project-shaped, and build a compact recallx_context_bundle once the relevant node or project is known.
+Prefer compact context over repeated broad browsing.
+Once a project is known, append routine work logs to that project instead of writing untargeted workspace captures.
+At the end of meaningful work, write back a concise summary of what changed, what was verified, and any follow-up.
+```
+
+MCP result rendering note:
+
+- RecallX MCP keeps `structuredContent` as the authoritative machine-readable payload.
+- The mirrored text content may be a compact deterministic summary rather than a pretty-printed JSON dump.
+- For the current rendering policy and compatibility guidance, see `docs/mcp.md`.
+
 ## MCP Bridge
 
 RecallX also ships a stdio MCP adapter for agent clients that prefer tool discovery over raw HTTP calls.
 
+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
@@ -224,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 || ""}`,
@@ -206,8 +220,18 @@ export function renderTelemetrySummary(data) {
     `since: ${data?.since || ""}`,
     `logs: ${data?.logsPath || ""}`,
     `events: ${data?.totalEvents ?? 0}`,
+    `slow threshold: ${data?.slowRequestThresholdMs ?? ""}ms`,
   ];
 
+  const hot = Array.isArray(data?.hotOperations) ? data.hotOperations : [];
+  if (hot.length > 0) {
+    lines.push("");
+    lines.push("Hot operations:");
+    for (const item of hot.slice(0, 5)) {
+      lines.push(`- [${item.surface}] ${item.operation} p95=${item.p95DurationMs ?? ""}ms errors=${item.errorCount}/${item.count}`);
+    }
+  }
+
   const slow = Array.isArray(data?.slowOperations) ? data.slowOperations : [];
   if (slow.length > 0) {
     lines.push("");

package/app/mcp/index.js

@@ -45,7 +45,7 @@ async function resolveObservabilityState() {
             workspaceRoot: typeof workspace.rootPath === "string" ? workspace.rootPath : process.cwd(),
             workspaceName: typeof workspace.workspaceName === "string" ? workspace.workspaceName : "RecallX MCP",
             retentionDays: typeof values["observability.retentionDays"] === "number" ? values["observability.retentionDays"] : 14,
-            slowRequestMs: typeof values["observability.slowRequestMs"] === "number" ? values["observability.slowRequestMs"] : 250,
+            slowRequestMs: typeof values["observability.slowRequestMs"] === "number" ? values["observability.slowRequestMs"] : 50,
             capturePayloadShape: values["observability.capturePayloadShape"] !== false
         };
     }
@@ -55,7 +55,7 @@ async function resolveObservabilityState() {
             workspaceRoot: process.cwd(),
             workspaceName: "RecallX MCP",
             retentionDays: 14,
-            slowRequestMs: 250,
+            slowRequestMs: 50,
             capturePayloadShape: true
         };
     }