recallx 1.0.4 → 1.0.7

package/README.md

@@ -69,11 +69,25 @@ npm start
 Checks:
 
 ```bash
+npm run branch:check
+npm run version:check
 npm run check
 npm test
 npm run build
 ```
 
+Start unrelated work in a separate branch/worktree instead of stacking it on the current checkout:
+
+```bash
+npm run branch:new -- fix-short-name
+```
+
+When you are preparing a release, bump from the highest known version instead of whatever the current branch happens to say:
+
+```bash
+npm run version:bump -- patch
+```
+
 If you want an installable runtime instead of source-run workflows, use one of the npm distribution paths below.
 
 ## 2. npm Full Runtime (`recallx`)

package/app/cli/src/format.js

@@ -304,7 +304,7 @@ export function renderTelemetryErrors(data) {
   return `${items
     .map(
       (item, index) =>
-        `${index + 1}. [${item.surface}] ${item.operation}\n  ts: ${item.ts}\n  trace: ${item.traceId}\n  error: ${item.errorKind || ""}/${item.errorCode || ""}\n  status: ${item.statusCode ?? ""}\n  durationMs: ${item.durationMs ?? ""}`
+        `${index + 1}. [${item.surface}] ${item.operation}\n  ts: ${item.ts}\n  trace: ${item.traceId}\n  span: ${item.spanId ?? ""}\n  parent: ${item.parentSpanId ?? ""}\n  error: ${item.errorKind || ""}/${item.errorCode || ""}\n  status: ${item.statusCode ?? ""}\n  durationMs: ${item.durationMs ?? ""}`
     )
     .join("\n\n")}\n`;
 }

package/app/mcp/api-client.js

@@ -1,5 +1,5 @@
 import { buildApiRequestInit, buildApiUrl, parseApiJsonBody } from "../shared/request-runtime.js";
-import { currentTelemetryContext } from "../server/observability.js";
+import { currentTelemetryContext, currentTelemetrySpanId } from "../server/observability.js";
 export class RecallXApiError extends Error {
     status;
     code;
@@ -43,6 +43,10 @@ export class RecallXApiClient {
         if (telemetryContext?.traceId) {
             headers.set("x-recallx-trace-id", telemetryContext.traceId);
         }
+        const telemetrySpanId = currentTelemetrySpanId();
+        if (telemetrySpanId) {
+            headers.set("x-recallx-parent-span-id", telemetrySpanId);
+        }
         if (telemetryContext?.toolName) {
             headers.set("x-recallx-mcp-tool", telemetryContext.toolName);
         }

package/app/mcp/index.js

@@ -10,7 +10,7 @@ function createObservabilityStateReader() {
     let cachedState = null;
     let cachedAt = 0;
     let inFlight = null;
-    const cacheTtlMs = 5_000;
+    const cacheTtlMs = 60_000;
     return async function readObservabilityState() {
         const now = Date.now();
         if (cachedState && now - cachedAt < cacheTtlMs) {

package/app/mcp/server.js

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod/v4";
-import { activityTypes, bundleModes, bundlePresets, canonicalities, captureModes, governanceStates, inferredRelationStatuses, nodeStatuses, nodeTypes, relationSources, relationStatuses, relationTypes, relationUsageEventTypes, searchFeedbackResultTypes, searchFeedbackVerdicts, sourceTypes } from "../shared/contracts.js";
+import { activityTypes, bundleModes, bundlePresets, canonicalities, captureModes, governanceStates, inferredRelationStatuses, normalizeBundleMode, normalizeBundlePreset, nodeStatuses, nodeTypes, relationSources, relationStatuses, relationTypes, relationUsageEventTypes, searchFeedbackResultTypes, searchFeedbackVerdicts, sourceTypes } from "../shared/contracts.js";
 import { RECALLX_VERSION } from "../shared/version.js";
 import { createObservabilityWriter, summarizePayloadShape } from "../server/observability.js";
 import { RecallXApiClient, RecallXApiError } from "./api-client.js";
@@ -67,6 +67,24 @@ function coerceBooleanSchema(defaultValue) {
 function formatStructuredContent(content) {
     return JSON.stringify(content, null, 2);
 }
+function formatInvalidBundleModeMessage(input) {
+    const quotedInput = typeof input === "string" && input.trim() ? `'${input}'` : "that value";
+    return `Unsupported mode ${quotedInput}. Use one of ${bundleModes.join(", ")}. Common aliases also work: small -> micro, concise -> compact, normal -> standard, full -> deep.`;
+}
+function formatInvalidBundlePresetMessage(input) {
+    const quotedInput = typeof input === "string" && input.trim() ? `'${input}'` : "that value";
+    return `Unsupported preset ${quotedInput}. Use one of ${bundlePresets.join(", ")}. Common aliases also work: coding -> for-coding, assistant/default -> for-assistant.`;
+}
+function bundleModeSchema(defaultValue) {
+    return z.preprocess(normalizeBundleMode, z.enum(bundleModes, {
+        error: (issue) => formatInvalidBundleModeMessage(issue.input)
+    })).default(defaultValue);
+}
+function bundlePresetSchema(defaultValue) {
+    return z.preprocess(normalizeBundlePreset, z.enum(bundlePresets, {
+        error: (issue) => formatInvalidBundlePresetMessage(issue.input)
+    })).default(defaultValue);
+}
 function toolResult(structuredContent) {
     return {
         content: [
@@ -317,7 +335,7 @@ export function createRecallXMcpServer(params) {
         name: "recallx-mcp",
         version: params?.serverVersion ?? RECALLX_VERSION
     }, {
-        instructions: "Use RecallX as a local knowledge backend. Treat the current workspace as the default scope, and do not create or open another workspace unless the user explicitly asks. When the work is clearly project-shaped, search for an existing project inside the current workspace first: prefer recallx_search_nodes with type=project, broaden with recallx_search_workspace when needed, create a project node only if no suitable one exists, and then anchor follow-up context with recallx_context_bundle targetId. If the conversation is not project-specific, keep memory at workspace scope. Prefer read tools first, and include source details on durable writes when you want caller-specific provenance.",
+        instructions: "Use RecallX as a local knowledge backend. Treat the current workspace as the default scope, and do not create or open another workspace unless the user explicitly asks. When the work is clearly project-shaped, search for an existing project inside the current workspace first: prefer recallx_search_nodes with type=project, broaden with recallx_search_workspace when needed, create a project node only if no suitable one exists, and then anchor follow-up context with recallx_context_bundle targetId. Once a project is known, do not keep writing untargeted workspace captures for routine work logs: append activity to that project or pass targetNodeId on capture writes. Reserve workspace-scope inbox activity for genuinely untargeted, cross-project, or not-yet-classified short logs. If the conversation is not project-specific, keep memory at workspace scope. Prefer read tools first, and include source details on durable writes when you want caller-specific provenance.",
         capabilities: {
             logging: {}
         }
@@ -617,7 +635,7 @@ export function createRecallXMcpServer(params) {
     }, createPostToolHandler(apiClient, "/activities"));
     registerTool(server, "recallx_capture_memory", {
         title: "Capture Memory",
-        description: "Safely capture a memory item without choosing low-level storage first. Prefer this as the default write when the conversation is not yet tied to a specific project or node. General short logs can stay at workspace scope and be auto-routed into activities, while reusable content can still land as durable memory.",
+        description: "Safely capture a memory item without choosing low-level storage first. Prefer this as the default write only when the conversation is not yet tied to a specific project or node. Once a project or target node is known, include targetNodeId or switch to recallx_append_activity for routine work logs. General short logs can stay at workspace scope and be auto-routed into activities, while reusable content can still land as durable memory.",
         inputSchema: {
             mode: z.enum(captureModes).default("auto"),
             body: z.string().min(1),
@@ -726,8 +744,8 @@ export function createRecallXMcpServer(params) {
         description: "Build a compact RecallX context bundle for coding, research, writing, or decision support. Omit targetId to get a workspace-entry bundle when the work is not yet tied to a specific project or node, and add targetId only after you know which project or node should anchor the context.",
         inputSchema: {
             targetId: z.string().min(1).optional(),
-            mode: z.enum(bundleModes).default("compact"),
-            preset: z.enum(bundlePresets).default("for-assistant"),
+            mode: bundleModeSchema("compact"),
+            preset: bundlePresetSchema("for-assistant"),
             options: z
                 .object({
                 includeRelated: coerceBooleanSchema(true),
@@ -778,7 +796,7 @@ export function createRecallXMcpServer(params) {
         inputSchema: {
             query: z.string().default(""),
             candidateNodeIds: z.array(z.string().min(1)).min(1).max(100),
-            preset: z.enum(bundlePresets).default("for-assistant"),
+            preset: bundlePresetSchema("for-assistant"),
             targetNodeId: z.string().optional()
         }
     }, createPostToolHandler(apiClient, "/retrieval/rank-candidates"));

package/app/server/app.js

@@ -1160,6 +1160,25 @@ export function createRecallXApp(params) {
             reason: input.reason
         };
     }
+    function resolveCaptureActivityTarget(repository, input) {
+        if (input.targetNodeId) {
+            return {
+                targetNode: repository.getNode(input.targetNodeId),
+                route: "explicit"
+            };
+        }
+        const activeProjects = repository.listActiveNodesByType("project", 2);
+        if (activeProjects.length === 1) {
+            return {
+                targetNode: activeProjects[0],
+                route: "sole_active_project"
+            };
+        }
+        return {
+            targetNode: repository.ensureWorkspaceInboxNode(),
+            route: "workspace_inbox"
+        };
+    }
     function createDurableNodeResponse(repository, input) {
         const governance = resolveNodeGovernance(input, resolveGovernancePolicy(repository.getSettings(["review.autoApproveLowRisk", "review.trustedSourceToolNames"])));
         const node = repository.createNode({
@@ -1204,6 +1223,7 @@ export function createRecallXApp(params) {
     app.use((request, response, next) => {
         const requestId = createId("req");
         const traceId = request.header("x-recallx-trace-id")?.trim() || createId("trace");
+        const parentSpanId = request.header("x-recallx-parent-span-id")?.trim() || null;
         const operation = `${request.method.toUpperCase()} ${normalizeApiRequestPath(request.path)}`;
         const observabilityState = currentObservabilityConfig();
         const requestSpan = observability.startSpan({
@@ -1211,6 +1231,7 @@ export function createRecallXApp(params) {
             operation,
             requestId,
             traceId,
+            parentSpanId,
             details: {
                 ...(observabilityState.capturePayloadShape ? summarizePayloadShape(request.body) : {}),
                 mcpTool: request.header("x-recallx-mcp-tool") ?? null
@@ -1221,6 +1242,7 @@ export function createRecallXApp(params) {
         response.locals.telemetryRequestSpan = requestSpan;
         response.setHeader("x-recallx-request-id", requestId);
         response.setHeader("x-recallx-trace-id", traceId);
+        response.setHeader("x-recallx-span-id", requestSpan.spanId);
         response.on("finish", () => {
             void requestSpan.finish({
                 outcome: response.statusCode >= 400 ? "error" : "success",
@@ -1229,14 +1251,14 @@ export function createRecallXApp(params) {
                 errorKind: response.locals.telemetryErrorKind ?? null
             });
         });
-        observability.withContext({
+        requestSpan.run(() => observability.withContext({
             traceId,
             requestId,
             workspaceRoot: currentWorkspaceRoot(),
             workspaceName: currentWorkspaceInfo().workspaceName,
             toolName: request.header("x-recallx-mcp-tool") ?? null,
             surface: "api"
-        }, next);
+        }, next));
     });
     app.use(express.json({ limit: "2mb" }));
     app.use("/api/v1", (request, response, next) => {
@@ -1597,7 +1619,8 @@ export function createRecallXApp(params) {
             })()));
             return;
         }
-        const targetNode = input.targetNodeId ? repository.getNode(input.targetNodeId) : repository.ensureWorkspaceInboxNode();
+        const captureTarget = resolveCaptureActivityTarget(repository, input);
+        const targetNode = captureTarget.targetNode;
         const activity = repository.appendActivity({
             targetNodeId: targetNode.id,
             activityType: "agent_run_summary",
@@ -1605,6 +1628,7 @@ export function createRecallXApp(params) {
             source,
             metadata: {
                 ...input.metadata,
+                autoTargetRoute: captureTarget.route,
                 captureMode: input.mode,
                 capturedTitle: title
             }
@@ -1635,9 +1659,13 @@ export function createRecallXApp(params) {
                 storedAs: "activity",
                 status: "recorded",
                 governanceState: null,
-                reason: input.mode === "activity"
-                    ? "Capture was explicitly routed to the activity timeline."
-                    : "Short log-like capture was routed to the activity timeline."
+                reason: captureTarget.route === "sole_active_project"
+                    ? input.mode === "activity"
+                        ? "Capture was routed to the sole active project timeline."
+                        : "Short log-like capture was routed to the sole active project timeline."
+                    : input.mode === "activity"
+                        ? "Capture was explicitly routed to the activity timeline."
+                        : "Short log-like capture was routed to the activity timeline."
             })
         }));
     });

package/app/server/governance.js

@@ -1,6 +1,6 @@
 import { AppError } from "./errors.js";
 import { countTokensApprox, nowIso } from "./utils.js";
-const relaxedShortFormNodeTypes = new Set(["reference", "question", "conversation"]);
+const relaxedShortFormNodeTypes = new Set(["project", "reference", "question", "conversation"]);
 function clampConfidence(value) {
     return Math.min(Math.max(value, 0), 1);
 }

package/app/server/observability.js

@@ -1,16 +1,39 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { appendFile, mkdir, readFile, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
+import { createId } from "./utils.js";
 const telemetryStorage = new AsyncLocalStorage();
 function nowIso() {
     return new Date().toISOString();
 }
+function createSpanId() {
+    return createId("span");
+}
 function parseJsonLine(line) {
     if (!line.trim()) {
         return null;
     }
     try {
-        return JSON.parse(line);
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== "object" || typeof parsed.ts !== "string" || typeof parsed.operation !== "string") {
+            return null;
+        }
+        return {
+            ts: parsed.ts,
+            traceId: typeof parsed.traceId === "string" ? parsed.traceId : "trace_unknown",
+            spanId: typeof parsed.spanId === "string" ? parsed.spanId : null,
+            parentSpanId: typeof parsed.parentSpanId === "string" ? parsed.parentSpanId : null,
+            requestId: typeof parsed.requestId === "string" ? parsed.requestId : null,
+            surface: parsed.surface === "mcp" ? "mcp" : "api",
+            operation: parsed.operation,
+            outcome: parsed.outcome === "error" ? "error" : "success",
+            durationMs: typeof parsed.durationMs === "number" ? parsed.durationMs : null,
+            statusCode: typeof parsed.statusCode === "number" ? parsed.statusCode : null,
+            errorCode: typeof parsed.errorCode === "string" ? parsed.errorCode : null,
+            errorKind: typeof parsed.errorKind === "string" ? parsed.errorKind : null,
+            workspaceName: typeof parsed.workspaceName === "string" ? parsed.workspaceName : null,
+            details: parsed.details && typeof parsed.details === "object" && !Array.isArray(parsed.details) ? parsed.details : {}
+        };
     }
     catch {
         return null;
@@ -142,14 +165,18 @@ export class TelemetrySpan {
     writer;
     state;
     context;
+    spanId;
+    parentSpanId;
     operation;
     startedAt = process.hrtime.bigint();
     details;
     finished = false;
-    constructor(writer, state, context, operation, details) {
+    constructor(writer, state, context, spanId, parentSpanId, operation, details) {
         this.writer = writer;
         this.state = state;
         this.context = context;
+        this.spanId = spanId;
+        this.parentSpanId = parentSpanId;
         this.operation = operation;
         this.details = sanitizeDetails(details);
     }
@@ -165,6 +192,8 @@ export class TelemetrySpan {
         await this.writer.enqueue({
             ts: nowIso(),
             traceId: this.context.traceId,
+            spanId: this.spanId,
+            parentSpanId: this.parentSpanId,
             requestId: input.requestId ?? this.context.requestId,
             surface: this.context.surface,
             operation: this.operation,
@@ -198,14 +227,16 @@ export class ObservabilityWriter {
         return telemetryStorage.getStore() ?? null;
     }
     withContext(input, callback) {
+        const current = telemetryStorage.getStore();
         return telemetryStorage.run({
             ...input,
-            spans: []
+            spans: current?.spans ?? []
         }, callback);
     }
     startSpan(input) {
         const state = this.options.getState();
         const current = telemetryStorage.getStore();
+        const parentSpan = current?.spans[current.spans.length - 1] ?? null;
         const context = {
             traceId: input.traceId ?? current?.traceId ?? "trace_unknown",
             requestId: input.requestId ?? current?.requestId ?? null,
@@ -215,7 +246,7 @@ export class ObservabilityWriter {
             toolName: current?.toolName ?? null,
             spans: current?.spans ?? []
         };
-        return new TelemetrySpan(this, state, context, input.operation, input.details);
+        return new TelemetrySpan(this, state, context, createSpanId(), input.parentSpanId ?? parentSpan?.spanId ?? null, input.operation, input.details);
     }
     addCurrentSpanDetails(details) {
         const current = telemetryStorage.getStore();
@@ -230,6 +261,8 @@ export class ObservabilityWriter {
         await this.enqueue({
             ts: nowIso(),
             traceId: input.traceId ?? current?.traceId ?? "trace_unknown",
+            spanId: createSpanId(),
+            parentSpanId: current?.spans[current.spans.length - 1]?.spanId ?? null,
             requestId: input.requestId ?? current?.requestId ?? null,
             surface: input.surface ?? current?.surface ?? "api",
             operation: input.operation,
@@ -497,9 +530,10 @@ export class ObservabilityWriter {
                 }
                 workspaceFallbackModeBuckets.set(bucketKey, current);
             }
-            if (event.details.feedbackVerdict === "useful" ||
-                event.details.feedbackVerdict === "not_useful" ||
-                event.details.feedbackVerdict === "uncertain") {
+            if (event.operation === "search.feedback" &&
+                (event.details.feedbackVerdict === "useful" ||
+                    event.details.feedbackVerdict === "not_useful" ||
+                    event.details.feedbackVerdict === "uncertain")) {
                 feedbackSampleCount += 1;
                 if (event.details.feedbackVerdict === "useful") {
                     feedbackUsefulCount += 1;
@@ -863,6 +897,10 @@ export function createObservabilityWriter(options) {
 export function currentTelemetryContext() {
     return telemetryStorage.getStore() ?? null;
 }
+export function currentTelemetrySpanId() {
+    const current = telemetryStorage.getStore();
+    return current?.spans[current.spans.length - 1]?.spanId ?? null;
+}
 export function appendCurrentTelemetryDetails(details) {
     const current = telemetryStorage.getStore();
     current?.spans[current.spans.length - 1]?.addDetails(details);

package/app/server/repositories.js

@@ -1282,6 +1282,17 @@ export class RecallXRepository {
             tags: parseJson(row.tags_json, [])
         }));
     }
+    listActiveNodesByType(type, limit = 20) {
+        const rows = this.db
+            .prepare(`SELECT *
+         FROM nodes
+         WHERE type = ?
+           AND status = 'active'
+         ORDER BY updated_at DESC, id DESC
+         LIMIT ?`)
+            .all(type, limit);
+        return rows.map(mapNode);
+    }
     listInferenceCandidateNodes(targetNodeId, limit = 200) {
         const rows = this.db
             .prepare(`SELECT * FROM nodes

package/app/shared/contracts.js

@@ -69,6 +69,54 @@ export const bundlePresets = [
     "for-writing",
     "for-assistant"
 ];
+export function normalizeBundlePreset(value) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    const normalized = value.trim().toLowerCase().replace(/[_\s]+/g, "-");
+    const aliasMap = {
+        coding: "for-coding",
+        code: "for-coding",
+        "for-code": "for-coding",
+        "for-coding": "for-coding",
+        research: "for-research",
+        "for-research": "for-research",
+        decision: "for-decision",
+        decisions: "for-decision",
+        "for-decision": "for-decision",
+        writing: "for-writing",
+        write: "for-writing",
+        writer: "for-writing",
+        "for-writing": "for-writing",
+        assistant: "for-assistant",
+        default: "for-assistant",
+        general: "for-assistant",
+        "for-assistant": "for-assistant"
+    };
+    return aliasMap[normalized] ?? normalized;
+}
+export function normalizeBundleMode(value) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    const normalized = value.trim().toLowerCase().replace(/[_\s]+/g, "-");
+    const aliasMap = {
+        micro: "micro",
+        tiny: "micro",
+        small: "micro",
+        minimal: "micro",
+        compact: "compact",
+        concise: "compact",
+        medium: "standard",
+        normal: "standard",
+        standard: "standard",
+        full: "deep",
+        detailed: "deep",
+        detail: "deep",
+        deep: "deep"
+    };
+    return aliasMap[normalized] ?? normalized;
+}
 export const sourceSchema = z.object({
     actorType: z.enum(sourceTypes),
     actorLabel: z.string().min(1),
@@ -230,8 +278,8 @@ export const buildContextBundleSchema = z.object({
         id: z.string().min(1)
     })
         .optional(),
-    mode: z.enum(bundleModes).default("compact"),
-    preset: z.enum(bundlePresets).default("for-assistant"),
+    mode: z.preprocess(normalizeBundleMode, z.enum(bundleModes)).default("compact"),
+    preset: z.preprocess(normalizeBundlePreset, z.enum(bundlePresets)).default("for-assistant"),
     options: z
         .object({
         includeRelated: z.boolean().default(true),

package/app/shared/version.js

@@ -1 +1 @@
-export const RECALLX_VERSION = "1.0.4";
+export const RECALLX_VERSION = "1.0.7";