@memorax/memorax-code 0.1.1 → 0.1.3

package/lib/memorax-code-adapter-common/src/hooks/memory-skill-reminder-hook.mjs

@@ -7,31 +7,43 @@ import {
   stringOption,
   withJsonFileLock,
 } from "../config-utils.mjs";
+import {
+  isMemorySkillReminderDue,
+  memorySkillReminderContext,
+  personalMemoryReminderContext,
+  resolveMemorySkillReminderIntervalTurns,
+} from "./memory-skill-reminder-policy.mjs";
 
-const DEFAULT_REMINDER_INTERVAL_TURNS = 5;
-const DEFAULT_MEMORY_SKILL_INVOCATION = "$memorax-code";
 export const PERSONAL_MEMORY_REMINDER_CONTEXT = personalMemoryReminderContext();
-
-export function personalMemoryReminderContext(memorySkillInvocation) {
-  const invocation = stringOption(memorySkillInvocation) ?? DEFAULT_MEMORY_SKILL_INVOCATION;
-  return [
-    `MemoraX Code personal-memory reminder: Use ${invocation} when the user states a durable current-repo identity or interaction preference, asks to list or recall stored personal memory, or explicitly asks to save, update, forget, or delete it.`,
-    "Route reusable action sequences and work rules to procedure memory; do not store repository facts, one-off task details, or secrets.",
-  ].join(" ");
-}
+export { personalMemoryReminderContext } from "./memory-skill-reminder-policy.mjs";
 
 export async function runMemorySkillReminderHook(options, hookInput) {
   try {
     const input = hookInput ?? await readStdinJson();
+    const result = await evaluateMemorySkillReminder(options, input);
+    if (!result) return;
+    process.stdout.write(`${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: result.additionalContext,
+      },
+    })}\n`);
+    if (result.reminder) await notifyReminder(options, result.reminder);
+  } catch (error) {
+    debugError(options, error);
+  }
+}
+
+export async function evaluateMemorySkillReminder(options, input) {
+  try {
     const sessionId = stringOption(input.session_id) ?? stringOption(input.sessionId);
-    if (!sessionId) return;
+    if (!sessionId) return undefined;
     const transcriptPath = stringOption(input.transcript_path) ?? stringOption(input.transcriptPath);
-    if (options.requireTranscriptPath && !transcriptPath) return;
+    if (options.requireTranscriptPath && !transcriptPath) return undefined;
     const hookEventName = stringOption(input.hook_event_name) ?? stringOption(input.hookEventName) ?? "UserPromptSubmit";
+    if (hookEventName !== "UserPromptSubmit") return undefined;
 
-    const memoraxCodeHome = process.env.MEMORAX_CODE_HOME || defaultMemoraxCodeHome();
-    if (hookEventName !== "UserPromptSubmit") return;
-
+    const memoraxCodeHome = resolveMemoraxCodeHome(options);
     const statePath = join(memoraxCodeHome, "adapters", options.adapterDir, "memory-skill-reminders.json");
     const turnId = stringOption(input.turn_id)
       ?? stringOption(input.turnId)
@@ -48,7 +60,7 @@ export async function runMemorySkillReminderHook(options, hookInput) {
       );
       if (next.duplicate) return next;
       const sessionState = next.state.sessions[sessionId];
-      const memoryReminderDue = shouldRemind(
+      const memoryReminderDue = isMemorySkillReminderDue(
         sessionState?.turnCount,
         intervalTurns,
         options.remindOnFirstTurn !== false,
@@ -64,34 +76,30 @@ export async function runMemorySkillReminderHook(options, hookInput) {
         turnCount: sessionState?.turnCount,
       };
     });
-    if (update.duplicate) return;
+    if (update.duplicate) return undefined;
     const { memoryReminderDue, supplementalReminderDue } = update;
 
     const baseAdditionalContext = stringOption(options.baseAdditionalContext);
-    if (baseAdditionalContext || memoryReminderDue || supplementalReminderDue) {
-      const cadenceReminderContext = memoryReminderDue
-        ? await buildCadenceReminderContext(options, input)
-        : undefined;
-      const personalMemoryContext = supplementalReminderDue || (memoryReminderDue && update.turnCount === 1)
-        ? await buildPersonalMemoryContext(options, input)
-        : undefined;
-      const reminderContext = stringOption(combinedReminderContext(options, {
-        memoryReminderDue,
-        supplementalReminderDue,
-      }, cadenceReminderContext, personalMemoryContext));
-      const additionalContext = [baseAdditionalContext, reminderContext].filter(Boolean).join("\n\n");
-      const triggers = [
-        ...(memoryReminderDue ? ["cadence"] : []),
-        ...(supplementalReminderDue ? ["post_compaction"] : []),
-      ];
-      process.stdout.write(`${JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "UserPromptSubmit",
-          additionalContext,
-        },
-      })}\n`);
-      if (reminderContext) {
-        await notifyReminder(options, {
+    if (!baseAdditionalContext && !memoryReminderDue && !supplementalReminderDue) return undefined;
+    const cadenceReminderContext = memoryReminderDue
+      ? await buildCadenceReminderContext(options, input)
+      : undefined;
+    const personalMemoryContext = supplementalReminderDue || (memoryReminderDue && update.turnCount === 1)
+      ? await buildPersonalMemoryContext(options, input)
+      : undefined;
+    const reminderContext = stringOption(combinedReminderContext(options, {
+      memoryReminderDue,
+      supplementalReminderDue,
+    }, cadenceReminderContext, personalMemoryContext));
+    const additionalContext = [baseAdditionalContext, reminderContext].filter(Boolean).join("\n\n");
+    const triggers = [
+      ...(memoryReminderDue ? ["cadence"] : []),
+      ...(supplementalReminderDue ? ["post_compaction"] : []),
+    ];
+    return {
+      additionalContext,
+      ...(reminderContext ? {
+        reminder: {
           sessionId,
           turnId,
           transcriptPath,
@@ -99,13 +107,12 @@ export async function runMemorySkillReminderHook(options, hookInput) {
           workspaceKind: stringOption(input.workspace_kind) ?? stringOption(input.workspaceKind),
           content: reminderContext,
           triggers,
-        });
-      }
-    }
+        },
+      } : {}),
+    };
   } catch (error) {
-    if (process.env[options.debugEnv] === "1") {
-      console.error(error instanceof Error ? error.message : String(error));
-    }
+    debugError(options, error);
+    return undefined;
   }
 }
 
@@ -125,21 +132,28 @@ export function markSupplementalReminderAfterCompact(options, input) {
     const hookEventName = stringOption(input.hook_event_name) ?? stringOption(input.hookEventName);
     if (hookEventName !== "SessionStart" || stringOption(input.source) !== "compact") return;
     const sessionId = stringOption(input.session_id) ?? stringOption(input.sessionId);
-    if (!sessionId) return;
-    const memoraxCodeHome = process.env.MEMORAX_CODE_HOME || defaultMemoraxCodeHome();
+    markSupplementalReminderForSession(options, sessionId);
+  } catch (error) {
+    debugError(options, error);
+  }
+}
+
+export function markSupplementalReminderForSession(options, sessionId) {
+  try {
+    const normalizedSessionId = stringOption(sessionId);
+    if (!normalizedSessionId) return;
+    const memoraxCodeHome = resolveMemoraxCodeHome(options);
     const statePath = join(memoraxCodeHome, "adapters", options.adapterDir, "memory-skill-reminders.json");
     withJsonFileLock(statePath, () => {
       const existing = readJsonFile(statePath);
       atomicWriteJson(statePath, markSupplementalReminderPending(
         existing?.unreadable ? undefined : existing?.value,
         options.runtime,
-        sessionId,
+        normalizedSessionId,
       ));
     });
   } catch (error) {
-    if (process.env[options.debugEnv] === "1") {
-      console.error(error instanceof Error ? error.message : String(error));
-    }
+    debugError(options, error);
   }
 }
 
@@ -169,7 +183,7 @@ async function buildPersonalMemoryContext(options, input) {
 
 function combinedReminderContext(options, due, cadenceReminderContext, personalMemoryContext) {
   const contexts = [];
-  if (due.memoryReminderDue) contexts.push(memoryReminderContext(options));
+  if (due.memoryReminderDue) contexts.push(memorySkillReminderContext(options.memorySkillInvocation));
   if (due.supplementalReminderDue || personalMemoryContext) {
     const additionalReminderContext = stringOption(options.additionalReminderContext);
     if (additionalReminderContext) contexts.push(additionalReminderContext);
@@ -180,15 +194,22 @@ function combinedReminderContext(options, due, cadenceReminderContext, personalM
   return contexts.join("\n\n");
 }
 
-function memoryReminderContext(options) {
-  const invocation = stringOption(options.memorySkillInvocation) ?? DEFAULT_MEMORY_SKILL_INVOCATION;
-  return `MemoraX Code reminder: proactively invoke ${invocation} whenever coding memory might help, even when uncertain; when in doubt, run one focused coding-memory search for relevant prior knowledge. Also use ${invocation} for repository-scoped personal memory, and classify the authority before reading or writing.`;
-}
-
 function defaultMemoraxCodeHome() {
   return process.env.HOME ? join(process.env.HOME, ".memorax-code") : ".memorax-code";
 }
 
+function resolveMemoraxCodeHome(options) {
+  return stringOption(options.memoraxCodeHome)
+    ?? process.env.MEMORAX_CODE_HOME
+    ?? defaultMemoraxCodeHome();
+}
+
+function debugError(options, error) {
+  if (process.env[options.debugEnv] === "1") {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+}
+
 function nextReminderState(existing, runtime, sessionId, turnId) {
   const state = reminderState(existing, runtime);
   const current = state.sessions[sessionId] && typeof state.sessions[sessionId] === "object" && !Array.isArray(state.sessions[sessionId])
@@ -231,47 +252,17 @@ function reminderState(existing, runtime) {
   return state;
 }
 
-function shouldRemind(turnCount, intervalTurns, remindOnFirstTurn) {
-  if (!Number.isInteger(turnCount) || turnCount <= 0) return false;
-  if (remindOnFirstTurn) return (turnCount - 1) % intervalTurns === 0;
-  return turnCount > intervalTurns && (turnCount - 1) % intervalTurns === 0;
-}
-
 function reminderIntervalTurns(memoraxCodeHome) {
-  return positiveInteger(process.env.MEMORAX_CODE_MEMORY_SKILL_REMINDER_INTERVAL_TURNS)
-    ?? configReminderIntervalTurns(join(memoraxCodeHome, "config.toml"))
-    ?? DEFAULT_REMINDER_INTERVAL_TURNS;
+  return resolveMemorySkillReminderIntervalTurns({
+    environmentValue: process.env.MEMORAX_CODE_MEMORY_SKILL_REMINDER_INTERVAL_TURNS,
+    configText: configReminderText(join(memoraxCodeHome, "config.toml")),
+  });
 }
 
-function configReminderIntervalTurns(path) {
+function configReminderText(path) {
   try {
-    return parseReminderIntervalTurns(readFileSync(path, "utf8"));
+    return readFileSync(path, "utf8");
   } catch {
     return undefined;
   }
 }
-
-function parseReminderIntervalTurns(text) {
-  let section = "";
-  for (const rawLine of text.split(/\r?\n/)) {
-    const line = rawLine.split("#", 1)[0].trim();
-    if (!line) continue;
-    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
-    if (sectionMatch) {
-      section = sectionMatch[1].trim();
-      continue;
-    }
-    if (section !== "memory.skill_reminder") continue;
-    const fieldMatch = line.match(/^interval_turns\s*=\s*(.+)$/);
-    if (fieldMatch) return positiveInteger(fieldMatch[1]);
-  }
-  return undefined;
-}
-
-function positiveInteger(value) {
-  if (typeof value !== "string") return undefined;
-  const normalized = value.trim().replaceAll("_", "");
-  if (!/^[1-9]\d*$/.test(normalized)) return undefined;
-  const parsed = Number(normalized);
-  return Number.isSafeInteger(parsed) ? parsed : undefined;
-}

package/lib/memorax-code-adapter-common/src/hooks/memory-skill-reminder-policy.mjs

@@ -0,0 +1,58 @@
+export const DEFAULT_MEMORY_SKILL_REMINDER_INTERVAL_TURNS = 5;
+const DEFAULT_MEMORY_SKILL_INVOCATION = "$memorax-code";
+
+export function memorySkillReminderContext(memorySkillInvocation) {
+  const invocation = nonEmptyString(memorySkillInvocation) ?? DEFAULT_MEMORY_SKILL_INVOCATION;
+  return `MemoraX Code reminder: proactively invoke ${invocation} whenever coding memory might help, even when uncertain; follow the skill's router to decide whether any memory operation is needed. Also use ${invocation} for repository-scoped personal memory, and classify the authority before reading or writing.`;
+}
+
+export function personalMemoryReminderContext(memorySkillInvocation) {
+  const invocation = nonEmptyString(memorySkillInvocation) ?? DEFAULT_MEMORY_SKILL_INVOCATION;
+  return [
+    `MemoraX Code personal-memory reminder: Use ${invocation} when the user states a durable current-repo identity or interaction preference, asks to list or recall stored personal memory, or explicitly asks to save, update, forget, or delete it.`,
+    "Route reusable action sequences and work rules to procedure memory; do not store repository facts, one-off task details, or secrets.",
+  ].join(" ");
+}
+
+export function resolveMemorySkillReminderIntervalTurns(input = {}) {
+  return positiveInteger(input.environmentValue)
+    ?? parseMemorySkillReminderIntervalTurns(input.configText)
+    ?? DEFAULT_MEMORY_SKILL_REMINDER_INTERVAL_TURNS;
+}
+
+export function isMemorySkillReminderDue(turnCount, intervalTurns, remindOnFirstTurn = true) {
+  if (!Number.isInteger(turnCount) || turnCount <= 0) return false;
+  if (!Number.isInteger(intervalTurns) || intervalTurns <= 0) return false;
+  if (remindOnFirstTurn) return (turnCount - 1) % intervalTurns === 0;
+  return turnCount > intervalTurns && (turnCount - 1) % intervalTurns === 0;
+}
+
+export function parseMemorySkillReminderIntervalTurns(text) {
+  if (typeof text !== "string") return undefined;
+  let section = "";
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.split("#", 1)[0].trim();
+    if (!line) continue;
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      section = sectionMatch[1].trim();
+      continue;
+    }
+    if (section !== "memory.skill_reminder") continue;
+    const fieldMatch = line.match(/^interval_turns\s*=\s*(.+)$/);
+    if (fieldMatch) return positiveInteger(fieldMatch[1]);
+  }
+  return undefined;
+}
+
+function positiveInteger(value) {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().replaceAll("_", "");
+  if (!/^[1-9]\d*$/.test(normalized)) return undefined;
+  const parsed = Number(normalized);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/lib/memorax-code-adapter-common/src/repo-memory/repo-memory-auto-build.mjs

@@ -0,0 +1,38 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function scheduleMissingRepoMemoryBuild(repo, options = {}) {
+  try {
+    const repoPath = nonEmptyString(repo);
+    const pluginRoot = nonEmptyString(options.pluginRoot);
+    if (!repoPath || !pluginRoot) return false;
+    if (existsSync(join(repoPath, ".repo_memory", "PROFILE.md"))) return false;
+
+    const jobHookPath = join(pluginRoot, "hooks", "repo-memory-job.mjs");
+    if (!existsSync(jobHookPath)) return false;
+    const child = spawn(options.nodePath ?? process.execPath, [jobHookPath, "maintain", "--repo", repoPath], {
+      cwd: repoPath,
+      detached: true,
+      env: options.env ?? process.env,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.once("error", (error) => debug(options, error));
+    child.unref();
+    return true;
+  } catch (error) {
+    debug(options, error);
+    return false;
+  }
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function debug(options, error) {
+  if (process.env[options.debugEnv] === "1") {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+}

package/lib/memorax-code-adapter-common/src/repo-memory/repo-memory-job-supervisor.mjs

@@ -517,7 +517,7 @@ function buildPrompt(repo, snapshotHead, memorySkillInvocation) {
 }
 
 function updatePrompt(repo, snapshotHead, memorySkillInvocation) {
-  return `This invocation is the authorized background repo-memory worker. Complete the requested operation yourself; do not inspect, launch, or defer to another repo-memory job.\n\nUse ${memorySkillInvocation} and select the Repo Memory repo-update operation to incrementally update this repository's existing .repo_memory.\n\nRepository: ${repo}\nSnapshot HEAD: ${snapshotHead}\n\nDefault behavior:\n- Treat existing .repo_memory as the baseline.\n- Detect local commit delta from the stored baseline to the exact snapshot SHA above.\n- Also try GitHub/GitLab PR, MR, and issue evidence when provider CLIs and authentication are available.\n- If provider evidence is unavailable, continue with local git evidence and preserve existing provider resources.\n- Do not rebuild unless updater reports the baseline is unusable; if a full rebuild is required, stop and report that.\n- Keep file writes scoped to ${repo}/.repo_memory and necessary repo-memory ignore/config entries.\n- Do not modify source code, dependency files, global config, or files outside the target repo unless explicitly required by repo-memory tooling.\n- Ensure PROFILE.md local_head resolves to the snapshot SHA above.\n- Run the packaged repo-memory validator before finishing.\n- Write a concise final summary with changed files, provider evidence status, and any follow-up needed.\n`;
+  return `This invocation is the authorized background repo-memory worker. Complete the requested operation yourself; do not inspect, launch, or defer to another repo-memory job.\n\nUse ${memorySkillInvocation} and select the Repo Memory repo-update operation to incrementally update this repository's existing .repo_memory.\n\nRepository: ${repo}\nSnapshot HEAD: ${snapshotHead}\n\nDefault behavior:\n- Treat existing .repo_memory as the baseline.\n- Run and follow the packaged repo-update detector's effective history policy.\n- Do not re-enable commit or provider evidence channels disabled by repoHistory.mode.\n- If provider evidence is unavailable when provider history is enabled, preserve existing provider resources.\n- Do not rebuild unless updater reports the baseline is unusable; if a full rebuild is required, stop and report that.\n- Keep file writes scoped to ${repo}/.repo_memory and necessary repo-memory ignore/config entries.\n- Do not modify source code, dependency files, global config, or files outside the target repo unless explicitly required by repo-memory tooling.\n- Ensure PROFILE.md local_head resolves to the snapshot SHA above.\n- Run the packaged repo-memory validator before finishing.\n- Write a concise final summary with changed files, provider evidence status, and any follow-up needed.\n`;
 }
 
 function gitSnapshot(repo) {

package/lib/memorax-code-adapter-common/src/windows-cli-invocation.mjs

@@ -37,7 +37,11 @@ export function resolveWindowsCliInvocation(command, args, options = {}) {
     .filter(isNodeEntrypoint)
     .find((candidate) => fileExists(candidate));
   if (!cli) {
-    const override = name === "claude" ? "MEMORAX_CODE_CLAUDE_CLI_JS" : "MEMORAX_CODE_CODEX_CLI_JS";
+    const override = name === "claude"
+      ? "MEMORAX_CODE_CLAUDE_CLI_JS"
+      : name === "dsh"
+        ? "MEMORAX_CODE_DSH_CLI_JS"
+        : "MEMORAX_CODE_CODEX_CLI_JS";
     throw new Error(
       `refusing to execute ${pathApi.basename(resolvedCommand)} through a command shell; `
       + `set ${override} to its Node entrypoint`,
@@ -75,6 +79,14 @@ function cliEntrypointCandidates(name, command, env, pathApi) {
       pathApi.join(root, "..", "@anthropic-ai", "claude-code", "cli.js"),
     ];
   }
+  if (name === "dsh") {
+    return [
+      env.MEMORAX_CODE_DSH_CLI_JS,
+      env.DSH_CLI_JS,
+      pathApi.join(root, "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js"),
+      pathApi.join(root, "..", "@deepseek-ai", "dsh", "lib", "bin.js"),
+    ];
+  }
   return [];
 }
 

package/lib/memorax-code-backend/dist/app/backend-server.js

@@ -0,0 +1,210 @@
+import { createServer, } from "node:http";
+import { backendDebug } from "../shared/debug-log.js";
+import { createMemoryReminderTraceRecorder } from "../memory/reminder-trace-recorder.js";
+import { handleMemoryViewerRequest } from "../viewer/http/public-routes.js";
+import { handleMemoryHookRequest } from "../transport/http/memory-hook.js";
+import { createBackendMemoryObservability } from "./memory-observability.js";
+import { createMemoryService } from "../memory/service.js";
+import { handleHealthRequest } from "../transport/http/health.js";
+import { authorized, memoryViewerSessionCookieHeader, publicErrorMessage, statusCodeFromError } from "../transport/http/request.js";
+import { json } from "../transport/http/json.js";
+import { createBackendState } from "./state.js";
+import { TRACE_CLIENTS } from "../trace/config.js";
+import { pruneExpiredTraceSessionsForClient } from "../trace/store.js";
+import { startMemoryWritebackReconciler } from "../memory/writeback-reconciler.js";
+import { createMemoryWritebackTaskProjection } from "../memory/writeback-task-projection.js";
+import { readActiveManagedClients } from "../lifecycle/active-clients.js";
+const DEFAULT_BACKEND_SHUTDOWN_TIMEOUT_MS = 4_000;
+export function createBackendServer(state = createBackendState(), options = {}) {
+    const memoryEnv = { ...process.env, MEMORAX_CODE_HOME: state.sessionHome };
+    const memoryWritebackTaskProjections = TRACE_CLIENTS.map((client) => createMemoryWritebackTaskProjection({
+        memoraxCodeHome: state.sessionHome,
+        client,
+    }));
+    const memoryObservability = createBackendMemoryObservability(state.sessionHome, options.memoryObservability, memoryEnv, memoryWritebackTaskProjections.map((projection) => projection.observabilityHook));
+    const memoryService = createMemoryService({
+        diagnosticLogger: backendDebug,
+        env: memoryEnv,
+        memoraxCodeHome: state.sessionHome,
+        memoryObservability,
+    });
+    const memoryHookDependencies = {
+        memoryService,
+        memoryReminderTraceRecorder: createMemoryReminderTraceRecorder({
+            diagnosticLogger: backendDebug,
+            env: memoryEnv,
+            memoraxCodeHome: state.sessionHome,
+        }),
+    };
+    for (const client of TRACE_CLIENTS) {
+        void pruneExpiredTraceSessionsForClient({
+            client,
+            memoraxCodeHome: state.sessionHome,
+        }).catch((error) => {
+            backendDebug(`${client}_trace.retention_cleanup_failed`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    }
+    const memoryWritebackReconcilers = memoryWritebackTaskProjections.map((taskProjection) => (startMemoryWritebackReconciler({
+        memoraxCodeHome: state.sessionHome,
+        env: memoryEnv,
+        taskProjection,
+    })));
+    const handleRequest = async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "127.0.0.1"}`);
+        backendDebug("http.request", {
+            method: req.method,
+            path: url.pathname,
+        });
+        try {
+            if (req.method === "GET" && url.pathname === "/health")
+                return handleHealthRequest(state, res);
+            if (!authorized(state, req, url))
+                return json(res, 401, { ok: false, error: "unauthorized" });
+            if (url.pathname === "/memory-viewer"
+                || url.pathname.startsWith("/memory-viewer/")) {
+                if (await handleMemoryViewerRequest(url, req, res, {
+                    memoraxCodeHome: state.sessionHome,
+                    claudeProjectsRoot: readActiveManagedClients(state.sessionHome)?.claude === true
+                        ? state.claudeProjectsRoot
+                        : false,
+                    sessionCookie: memoryViewerSessionCookieHeader(state, req, url),
+                }))
+                    return;
+            }
+            if (await handleMemoryHookRequest(memoryHookDependencies, url, req, res))
+                return;
+            return json(res, 404, { ok: false, error: "not found" });
+        }
+        catch (error) {
+            const status = statusCodeFromError(error);
+            const publicMessage = publicErrorMessage(error);
+            if (status >= 500)
+                console.error("request failed", error);
+            if (res.headersSent) {
+                return res.end();
+            }
+            return json(res, status, { ok: false, error: publicMessage });
+        }
+    };
+    const activeRequests = new Set();
+    const server = createServer((req, res) => {
+        const request = handleRequest(req, res);
+        activeRequests.add(request);
+        void request.then(() => activeRequests.delete(request), () => activeRequests.delete(request));
+    });
+    return attachBackendShutdown(server, {
+        activeRequests,
+        memoryObservability,
+        memoryService,
+        memoryWritebackReconcilers,
+        timeoutMs: positiveShutdownTimeout(options.shutdownTimeoutMs),
+    });
+}
+function attachBackendShutdown(server, resources) {
+    const closeHttpServer = server.close.bind(server);
+    const backendServer = server;
+    let shutdownPromise;
+    backendServer.shutdown = () => {
+        shutdownPromise ??= shutdownBackend(backendServer, closeHttpServer, resources);
+        return shutdownPromise;
+    };
+    backendServer.close = ((callback) => {
+        void backendServer.shutdown().then(() => callback?.(), (error) => callback?.(error instanceof Error ? error : new Error(String(error))));
+        return backendServer;
+    });
+    return backendServer;
+}
+async function shutdownBackend(server, closeHttpServer, resources) {
+    const deadline = Date.now() + resources.timeoutMs;
+    const reconcilerDrain = settleShutdownWork("memory_writeback_reconcilers", Promise.all(resources.memoryWritebackReconcilers.map((reconciler) => reconciler.close())));
+    try {
+        await waitForShutdownPhase("http_server", closeBackendHttpServer(server, closeHttpServer, resources.timeoutMs), deadline);
+        await waitForShutdownPhase("http_requests", waitForActiveRequests(resources.activeRequests), deadline);
+        if (Date.now() < deadline) {
+            await waitForShutdownPhase("memory_service", settleShutdownWork("memory_service", resources.memoryService.drain()), deadline);
+        }
+        if (Date.now() < deadline && resources.memoryObservability?.drain) {
+            await waitForShutdownPhase("memory_observability", settleShutdownWork("memory_observability", resources.memoryObservability.drain()), deadline);
+        }
+        await waitForShutdownPhase("background_work", reconcilerDrain, deadline);
+    }
+    finally {
+        resources.memoryService.close();
+    }
+}
+function closeBackendHttpServer(server, closeHttpServer, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const forceTimer = setTimeout(() => {
+            backendDebug("shutdown.http_connections_forced", { timeoutMs });
+            try {
+                server.closeAllConnections();
+            }
+            catch (error) {
+                backendDebug("shutdown.http_connections_force_failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }, timeoutMs);
+        const done = (error) => {
+            clearTimeout(forceTimer);
+            if (error && error.code !== "ERR_SERVER_NOT_RUNNING") {
+                reject(error);
+                return;
+            }
+            resolve();
+        };
+        try {
+            closeHttpServer(done);
+            server.closeIdleConnections();
+        }
+        catch (error) {
+            done(error instanceof Error ? error : new Error(String(error)));
+        }
+    });
+}
+async function waitForActiveRequests(activeRequests) {
+    while (activeRequests.size > 0) {
+        await Promise.allSettled([...activeRequests]);
+    }
+}
+async function waitForShutdownPhase(phase, work, deadline) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+        backendDebug("shutdown.phase_timed_out", { phase, remainingMs: 0 });
+        return false;
+    }
+    let timer;
+    const result = await Promise.race([
+        work.then(() => ({ completed: true }), (error) => ({ completed: true, error })),
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ completed: false }), remainingMs);
+        }),
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (!result.completed) {
+        backendDebug("shutdown.phase_timed_out", { phase, remainingMs });
+        return false;
+    }
+    if ("error" in result)
+        throw result.error;
+    return true;
+}
+async function settleShutdownWork(label, work) {
+    try {
+        await work;
+    }
+    catch (error) {
+        backendDebug("shutdown.work_failed", {
+            label,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function positiveShutdownTimeout(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+        return value;
+    return DEFAULT_BACKEND_SHUTDOWN_TIMEOUT_MS;
+}

package/lib/memorax-code-backend/dist/{server-observability.js → app/memory-observability.js}

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { backendDebug } from "./debug-log.js";
-import { TRACE_CLIENTS, clientTraceConfigFromEnv, } from "./trace-config.js";
-import { recordTraceEvent } from "./trace-store.js";
-import { memoryViewerObservabilityHook } from "./memory-viewer-observability.js";
+import { backendDebug } from "../shared/debug-log.js";
+import { TRACE_CLIENTS, clientTraceConfigFromEnv, } from "../trace/config.js";
+import { recordTraceEvent } from "../trace/store.js";
+import { memoryViewerObservabilityHook } from "../viewer/projection/observability.js";
 export function createBackendMemoryObservability(memoraxCodeHome, existingHook, env = process.env, additionalDefaultHooks = []) {
     if (existingHook)
         return existingHook;

package/lib/memorax-code-backend/dist/{backend-state.js → app/state.js}

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { backendEnv } from "./backend-env.js";
+import { backendEnv } from "../config/backend-env.js";
 export function createBackendState(host = "127.0.0.1", options = {}) {
     const authToken = options.authToken ?? backendEnv("TOKEN");
     const sessionHome = options.sessionHome ?? process.env.MEMORAX_CODE_HOME ?? join(homedir(), ".memorax-code");

package/lib/memorax-code-backend/dist/{claude-adapter-lifecycle.js → clients/claude/lifecycle.js}

@@ -120,10 +120,10 @@ function claudeAdapterOptions(argv, serviceOptions, backendUrl) {
     };
 }
 async function loadClaudeAdapterConfig() {
-    return await import(new URL("../../memorax-code-claude-adapter/src/config.mjs", import.meta.url).href);
+    return await import(new URL("../../../../memorax-code-claude-adapter/src/config.mjs", import.meta.url).href);
 }
 async function loadClaudePluginInstaller() {
-    return await import(new URL("../../memorax-code-claude-adapter/src/plugin-install.mjs", import.meta.url).href);
+    return await import(new URL("../../../../memorax-code-claude-adapter/src/plugin-install.mjs", import.meta.url).href);
 }
 function argValue(argv, name) {
     const index = argv.indexOf(name);