@memorax/memorax-code 0.1.1 → 0.1.2

package/bin/memorax-code-plugin-postinstall.mjs

@@ -48,7 +48,7 @@ const codexCommand = codexRuntime.command;
 const claudeRuntime = ensureClaudeCommandEnv();
 const claudeCommand = claudeRuntime.command;
 const updatePostinstall = postinstallUpdateMode();
-const scriptedAnswers = (canPrompt() || canPromptForHookUpdate()) && process.stdin.isTTY !== true
+const scriptedAnswers = (canPrompt() || canPromptForUpdate()) && process.stdin.isTTY !== true
   ? parseScriptedAnswers(readFileSync(0, "utf8"))
   : undefined;
 const previousClients = readPersistedClientSelection();
@@ -70,20 +70,31 @@ try {
   process.exit(0);
 }
 runCommonPreflight();
-const requestedClients = previousClients ?? ["codex", "claude"];
+const requestedClients = ["codex", "claude"];
 const codexPreflight = requestedClients.includes("codex") && !skipCodexPluginInstall
-  ? runCodexPreflight()
+  ? runCodexPreflight({
+      integrationSelected: !updatePostinstall
+        || previousClients === undefined
+        || previousClients.includes("codex"),
+    })
   : { ok: true, pluginCache: { marketplaceName: CLI_MARKETPLACE_NAME, versions: [] } };
 const claudePreflight = requestedClients.includes("claude") && !skipClaudeAdapterInstall
-  ? runClaudePreflight()
+  ? runClaudePreflight({
+      integrationSelected: !updatePostinstall
+        || previousClients === undefined
+        || previousClients.includes("claude"),
+    })
   : { ok: true };
-const installClients = requestedClients.filter((client) => {
+const detectedClients = requestedClients.filter((client) => {
   if (client === "codex") return !skipCodexPluginInstall && codexPreflight.ok;
   return !skipClaudeAdapterInstall && claudePreflight.ok;
 });
-const selectedClients = previousClients ?? installClients;
-if (previousClients) {
-  log(clientSelectionMessage(previousClients));
+const selectedClients = updatePostinstall && previousClients !== undefined
+  ? await chooseUpdateClients(previousClients, detectedClients, scriptedAnswers)
+  : detectedClients;
+const installClients = detectedClients.filter((client) => selectedClients.includes(client));
+if (updatePostinstall && previousClients !== undefined) {
+  log(clientSelectionMessage(selectedClients));
 } else {
   log(detectedClientMessage(installClients));
 }
@@ -110,7 +121,11 @@ if (memoraxConfigResult === "configured") {
 }
 const codexClientEnabled = installClients.includes("codex");
 const claudeClientEnabled = installClients.includes("claude");
-const codexHooksBeforeUpdate = codexClientEnabled && updatePostinstall
+const codexClientNewlyEnabled = codexClientEnabled
+  && updatePostinstall
+  && previousClients !== undefined
+  && !previousClients.includes("codex");
+const codexHooksBeforeUpdate = codexClientEnabled && updatePostinstall && !codexClientNewlyEnabled
   ? inspectCodexPluginHooksForUpdate()
   : undefined;
 const result = codexClientEnabled
@@ -122,8 +137,13 @@ if (codexClientEnabled && result.status !== 0 && process.env.npm_lifecycle_event
 }
 
 if (codexClientEnabled && result.status === 0) {
-  if (updatePostinstall) await maybeTrustUpdatedCodexPluginHooks(scriptedAnswers, codexHooksBeforeUpdate);
-  else await maybeActivateCodexPluginHooks(scriptedAnswers);
+  if (codexClientNewlyEnabled) {
+    await maybeActivateCodexPluginHooks(scriptedAnswers, { updatePrompt: true });
+  } else if (updatePostinstall) {
+    await maybeTrustUpdatedCodexPluginHooks(scriptedAnswers, codexHooksBeforeUpdate);
+  } else {
+    await maybeActivateCodexPluginHooks(scriptedAnswers);
+  }
 }
 const skipCodexAdapter = !codexClientEnabled;
 const skipClaudeAdapter = !claudeClientEnabled;
@@ -194,6 +214,45 @@ async function maybeConfigureMemoraxMemory(scriptedAnswers) {
   }
 }
 
+async function chooseUpdateClients(previousClients, detectedClients, scriptedAnswers) {
+  const selected = new Set(previousClients);
+  const availableDisabledClients = detectedClients.filter((client) => !selected.has(client));
+  if (availableDisabledClients.length === 0) return [...previousClients];
+
+  if (!canPromptForUpdate()) {
+    for (const client of availableDisabledClients) {
+      const label = client === "codex" ? "Codex" : "Claude Code";
+      log(`${label} runtime is available, but its integration remains disabled because this update cannot prompt. Rerun \`memorax-code update\` from an interactive terminal to choose whether to enable it.`);
+    }
+    return [...previousClients];
+  }
+
+  let rl;
+  try {
+    for (const client of availableDisabledClients) {
+      const label = client === "codex" ? "Codex" : "Claude Code";
+      const question = `${label} runtime is available, but its integration is disabled in [clients]. Enable it now? [Y/n]`;
+      let answer;
+      if (scriptedAnswers) {
+        log(question);
+        answer = String(scriptedAnswers.shift() ?? "").trim();
+      } else {
+        rl ??= createInterface({ input: process.stdin, output: process.stderr });
+        answer = (await rl.question(`${PREFIX} ${question} `)).trim();
+      }
+      if (/^n(?:o)?$/i.test(answer)) {
+        log(`Keeping the ${label} integration disabled.`);
+      } else {
+        selected.add(client);
+        logGreen(`Enabling the ${label} integration.`);
+      }
+    }
+  } finally {
+    rl?.close();
+  }
+  return ["codex", "claude"].filter((client) => selected.has(client));
+}
+
 async function configureMemoraxMemoryFromAnswers(answers) {
   if (answers.length === 0) {
     log(`No MemoraX connection response was received. Register at ${MEMORAX_ACCOUNT_URL}, then edit \`~/.memorax-code/config.toml\` or rerun interactively with \`--foreground-scripts\`.`);
@@ -350,7 +409,7 @@ async function maybeTrustUpdatedCodexPluginHooks(scriptedAnswers, previousHooks)
   if (report.hooks.length === 0) return "unchanged";
 
   printUpdatedCodexHooks(report.hooks, previousHooks);
-  if (!canPromptForHookUpdate()) {
+  if (!canPromptForUpdate()) {
     warnUpdatedHookTrustSkipped("This update is running without an interactive terminal, so the new or changed Hooks remain untrusted.");
     return "skipped";
   }
@@ -470,8 +529,8 @@ function warnUpdatedHookTrustSkipped(message) {
   logRed("Review and authorize the current MemoraX Code Codex Hooks with `memorax-code codex-plugin trust-hooks`.");
 }
 
-async function maybeActivateCodexPluginHooks(scriptedAnswers) {
-  if (!canPrompt()) {
+async function maybeActivateCodexPluginHooks(scriptedAnswers, { updatePrompt = false } = {}) {
+  if (!(updatePrompt ? canPromptForUpdate() : canPrompt())) {
     log("Codex hook activation was not prompted. Run `memorax-code codex-plugin activate --yes` later to activate and trust MemoraX Code Codex Adapter hooks.");
     return "skipped";
   }
@@ -512,7 +571,7 @@ function canPrompt() {
   return canPromptOnStderr();
 }
 
-function canPromptForHookUpdate() {
+function canPromptForUpdate() {
   return updatePostinstall && canPromptOnStderr();
 }
 
@@ -705,7 +764,7 @@ function tomlString(value) {
 function runCommonPreflight() {
   log("Checking local install state...");
   if (updatePostinstall) {
-    log("Package update detected; refreshing MemoraX Code assets without interactive setup prompts.");
+    log("Package update detected; refreshing MemoraX Code assets and checking client availability.");
   }
   const memoraxCodeVersion = runNodeMemoraxCodeCommand(["--version"], { print: false });
   log(`MemoraX Code backend package: ${commandSummary(memoraxCodeVersion) ?? packageVersionSummary()}`);
@@ -718,7 +777,7 @@ function runCommonPreflight() {
   return {};
 }
 
-function runCodexPreflight() {
+function runCodexPreflight({ integrationSelected = true } = {}) {
   const version = runExternalCommand(codexCommand, ["--version"], { print: false, timeout: 10_000 });
   const runtimeLabel = codexRuntime.source === "app-bundled"
     ? "Codex App runtime"
@@ -732,16 +791,24 @@ function runCodexPreflight() {
   const pluginCache = installedPluginCache();
   log(`Existing Codex plugin cache: ${pluginCache.versions.length > 0 ? `found (${pluginCache.versions.join(", ")})` : "not installed"}`);
   log(`Codex client process: ${codexClientRunning() ? "running" : "not detected"}`);
-  log("Keeping Codex provider config unchanged and enabling the shared memory hook integration.");
+  log(integrationSelected
+    ? "Keeping Codex provider config unchanged and enabling the shared memory hook integration."
+    : "Keeping Codex provider config unchanged while checking whether to enable its integration.");
   return { ok: true, pluginCache };
 }
 
-function runClaudePreflight() {
+function runClaudePreflight({ integrationSelected = true } = {}) {
   const version = runExternalCommand(claudeCommand, ["--version"], { print: false, timeout: 10_000 });
-  const runtimeLabel = claudeRuntime.source === "vscode-bundled" ? "Claude VS Code runtime" : "Claude CLI";
+  const runtimeLabel = claudeRuntime.source === "app-bundled"
+    ? "Claude Code App runtime"
+    : claudeRuntime.source === "vscode-bundled"
+      ? "Claude VS Code runtime"
+      : "Claude CLI";
   log(`${runtimeLabel}: ${commandSummary(version) ?? "not runnable"}`);
   if (version.status !== 0) return { ok: false };
-  log("Keeping Claude Code provider config unchanged and enabling the shared memory Hook integration.");
+  log(integrationSelected
+    ? "Keeping Claude Code provider config unchanged and enabling the shared memory Hook integration."
+    : "Keeping Claude Code provider config unchanged while checking whether to enable its integration.");
   return { ok: true };
 }
 

package/docs/configuration.md

@@ -59,6 +59,16 @@ disabled. The command-line override is:
 --clients codex|claude|codex,claude|all|none
 ```
 
+A normal npm install or reinstall refreshes `[clients]` from the runnable
+clients detected at that time. Update-mode postinstall runs preserve enabled
+clients and also probe each disabled client. An interactive update offers each
+runnable disabled integration for activation with a default of yes. Declining
+the prompt, or running non-interactively, keeps that integration disabled. A
+selected client that is temporarily unavailable also remains selected in the
+configuration instead of being permanently disabled. When an update newly
+enables Codex, it requests initial Hook activation after the client-selection
+prompt.
+
 Client selection controls plugin and Hook lifecycle only. It does not change
 Codex or Claude Code provider settings. `--clients none` runs the Backend
 without managing either client integration.
@@ -167,6 +177,11 @@ Supported policies are `every-commit`, `commit-count`, `daily`,
 `pull-request`, `pull-request-or-daily`, and `adaptive`. Invalid policy values
 fall back to `adaptive`.
 
+The first eligible prompt starts a background build only when the Backend has
+authorized a Git worktree and that worktree has no `.repo_memory/PROFILE.md`.
+If the Backend or workspace authority is unavailable, the Hook skips the
+initial build instead of falling back to its local `cwd`.
+
 ## Local traces
 
 `[trace.codex]` and `[trace.claude]` support the same fields:

package/docs/troubleshooting.md

@@ -147,6 +147,32 @@ MemoraX Code reads filesystem Git metadata without executing Git. Linked
 worktrees share the remote repository identity; non-Git workspaces use the
 normalized folder name. Resolution never falls back to the bare base user ID.
 
+A live Codex or Claude Code session remains pinned to the repository or local
+workspace resolved at the start of the session. Starting the client from a
+parent workspace and then entering a nested Git repository does not rebind the
+session. The only in-session scope upgrade is from a direct `.git` directory
+whose internal metadata was malformed or incomplete to a verified Git
+repository at the same canonical workspace root and for the same Base User ID.
+
+During that degraded state, MemoraX Code reports
+`workspaceScopeFallbackReason: git_metadata_invalid` for manual CLI operations
+and continues Search and Add with the normalized local folder name. Automatic
+writeback also continues under that fallback scope without interrupting the
+client task. The reported `effectiveUserId` identifies the fallback namespace
+and may differ from the restored Git repository namespace. Repair the
+repository or restore valid `.git` metadata, and later Search, Add, and
+automatic writeback in the same client session automatically use the verified
+Git repository scope. Memories already accepted under the fallback namespace
+are not migrated. Any unsent automatic-writeback buffer for the fallback scope
+is discarded instead of being flushed into either namespace.
+
+Invalid or unreadable Git marker files, symlinked markers, and session scope
+conflicts do not use this fallback. If Search or Add reports
+`workspace_scope_mismatch` or `workspace_scope_unavailable`, start a new
+session from the target repository or local workspace and verify that its
+`.git` metadata is readable and valid. These failures stop Search or Add before
+any request is sent to MemoraX.
+
 Codex projectless tasks under its canonical dated-task location intentionally
 use the shared `Codex-General` memory name. Open a task in a real workspace
 when repository isolation matters.

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

@@ -182,7 +182,7 @@ function combinedReminderContext(options, due, cadenceReminderContext, personalM
 
 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.`;
+  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.`;
 }
 
 function defaultMemoraxCodeHome() {

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(process.execPath, [jobHookPath, "maintain", "--repo", repoPath], {
+      cwd: repoPath,
+      detached: true,
+      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-backend/dist/automatic-memory-writeback.js

@@ -20,6 +20,13 @@ export function createAutomaticMemoryWritebackRuntime(options = {}) {
         enqueue(options) {
             return enqueueAutomaticMemoryWritebackForRuntime(state, options);
         },
+        discardForScopeUpgrade(upgrade) {
+            return state.writebackBuffer.discardForScopeUpgrade({
+                client: upgrade.client,
+                sessionKey: upgrade.sessionId,
+                currentScope: upgrade.currentScope,
+            });
+        },
         drain() {
             if (state.drainPromise)
                 return state.drainPromise;

package/lib/memorax-code-backend/dist/claude-memory-hook-runtime.js

@@ -2,7 +2,7 @@ import { readClaudeInterruptedTranscriptTurn, readClaudeTranscriptTurn, } from "
 import { retrieveAutomaticMemoryContext } from "./automatic-memory-retrieval.js";
 import { createAutomaticMemoryWritebackRuntime, } from "./automatic-memory-writeback.js";
 import { createMemoryTurnCoordinator, } from "./memory-turn-coordinator.js";
-import { createRepositoryMemorySessionRuntime, } from "./repository-memory-context.js";
+import { createRepositoryMemorySessionRuntime, resolvedRepoMemoryWorktree, } from "./repository-memory-context.js";
 import { traceContextFromClaudeHookBody } from "./trace-context.js";
 import { markCurrentClaudeTurnOutcome, readOpenClaudeTurn, recordClaudeTraceEvent, traceTurnEventId, writeCurrentClaudeTurn, } from "./trace-store.js";
 const CLAUDE_MEMORY_TURN_CLIENT = "claude-code";
@@ -23,7 +23,9 @@ export function createClaudeMemoryHookRuntime(options = {}) {
         cleanupIntervalMs: options.cleanupIntervalMs,
     });
     const ownsTurnCoordinator = options.turnCoordinator === undefined;
-    const repositoryMemorySession = options.repositoryMemorySession ?? createRepositoryMemorySessionRuntime();
+    const repositoryMemorySession = options.repositoryMemorySession ?? createRepositoryMemorySessionRuntime({
+        onScopeUpgrade: automaticWritebackRuntime?.discardForScopeUpgrade,
+    });
     const ownsRepositoryMemorySession = options.repositoryMemorySession === undefined;
     const automaticRetrievalPrompts = new Set();
     const automaticRetrievalPromptLimit = positiveInteger(options.maxEntries, 256);
@@ -45,6 +47,7 @@ export function createClaudeMemoryHookRuntime(options = {}) {
             await reconcilePreviousInterruptedTurn(turnCoordinator, turn, options, now);
             turnCoordinator.pruneExpired();
             const repositoryMemory = await resolveHookRepositoryMemory(turn, options, repositoryMemorySession);
+            const repoMemoryWorktree = resolvedRepoMemoryWorktree(repositoryMemory);
             turnCoordinator.recordTurnStart({
                 client: CLAUDE_MEMORY_TURN_CLIENT,
                 sessionId: turn.sessionId,
@@ -84,7 +87,10 @@ export function createClaudeMemoryHookRuntime(options = {}) {
                 now: () => new Date(now()),
             }), options.diagnosticLogger);
             if (!claimAutomaticRetrievalPrompt(automaticRetrievalPrompts, automaticRetrievalPromptLimit, turn.sessionId, turn.promptId)) {
-                return { ok: true };
+                return {
+                    ok: true,
+                    ...(repoMemoryWorktree ? { repoMemoryWorktree } : {}),
+                };
             }
             const retrieval = await retrieveAutomaticMemoryContext({
                 diagnosticLogger: options.diagnosticLogger,
@@ -99,6 +105,7 @@ export function createClaudeMemoryHookRuntime(options = {}) {
             });
             return {
                 ok: true,
+                ...(repoMemoryWorktree ? { repoMemoryWorktree } : {}),
                 ...(retrieval.context ? { additionalContext: retrieval.context } : {}),
             };
         },

package/lib/memorax-code-backend/dist/codex-memory-hook-runtime.js

@@ -4,7 +4,7 @@ import { retrieveAutomaticMemoryContext } from "./automatic-memory-retrieval.js"
 import { readCodexSessionTurnIndex } from "./codex-session-turn-index.js";
 import { resolveCodexWorkspaceRoot } from "./codex-workspace-links.js";
 import { createMemoryTurnCoordinator, } from "./memory-turn-coordinator.js";
-import { createRepositoryMemorySessionRuntime, } from "./repository-memory-context.js";
+import { createRepositoryMemorySessionRuntime, resolvedRepoMemoryWorktree, } from "./repository-memory-context.js";
 import { traceContextFromHookBody } from "./trace-context.js";
 import { markCurrentCodexTurnOutcome, readCurrentCodexTurn, readOpenCodexTurn, recordCodexTraceEvent, traceTurnEventId, writeCurrentCodexTurn, } from "./trace-store.js";
 const CODEX_MEMORY_TURN_CLIENT = "codex";
@@ -23,7 +23,9 @@ export function createCodexMemoryHookRuntime(options = {}) {
         cleanupIntervalMs: options.cleanupIntervalMs,
     });
     const ownsTurnCoordinator = options.turnCoordinator === undefined;
-    const repositoryMemorySession = options.repositoryMemorySession ?? createRepositoryMemorySessionRuntime();
+    const repositoryMemorySession = options.repositoryMemorySession ?? createRepositoryMemorySessionRuntime({
+        onScopeUpgrade: automaticWritebackRuntime?.discardForScopeUpgrade,
+    });
     const ownsRepositoryMemorySession = options.repositoryMemorySession === undefined;
     const automaticRetrievalTurns = new Set();
     const automaticRetrievalTurnLimit = positiveInteger(options.maxEntries, 256);
@@ -44,6 +46,7 @@ export function createCodexMemoryHookRuntime(options = {}) {
                 resolveHookRepositoryMemory(turn, options, repositoryMemorySession),
                 resolveSessionTurnIndex(turn, options.diagnosticLogger),
             ]);
+            const repoMemoryWorktree = resolvedRepoMemoryWorktree(repositoryMemory);
             if (turn.turnId) {
                 turnCoordinator.recordTurnStart({
                     client: CODEX_MEMORY_TURN_CLIENT,
@@ -90,7 +93,10 @@ export function createCodexMemoryHookRuntime(options = {}) {
             }), options.diagnosticLogger);
             if (!turn.turnId
                 || !claimAutomaticRetrievalTurn(automaticRetrievalTurns, automaticRetrievalTurnLimit, turn.sessionId, turn.turnId)) {
-                return { ok: true };
+                return {
+                    ok: true,
+                    ...(repoMemoryWorktree ? { repoMemoryWorktree } : {}),
+                };
             }
             const retrieval = await retrieveAutomaticMemoryContext({
                 diagnosticLogger: options.diagnosticLogger,
@@ -105,6 +111,7 @@ export function createCodexMemoryHookRuntime(options = {}) {
             });
             return {
                 ok: true,
+                ...(repoMemoryWorktree ? { repoMemoryWorktree } : {}),
                 ...(retrieval.context ? { additionalContext: retrieval.context } : {}),
             };
         },

package/lib/memorax-code-backend/dist/memorax-cli.js

@@ -2,6 +2,8 @@
 import { runMemoryCli } from "./memory-cli.js";
 runMemoryCli(process.argv.slice(2)).then((result) => {
     if (!process.argv.includes("--json") && result.ok && result.action === "memory.search") {
+        if (result.userNotice)
+            console.warn(`Warning: ${result.userNotice}`);
         console.log(result.answer?.trim() || "No memory context returned.");
     }
     else {

package/lib/memorax-code-backend/dist/memory-cli.js

@@ -72,7 +72,7 @@ async function memorySearch(args, options) {
     const query = queryResult.text;
     const repositoryMemory = await resolveMemoryCliRepositoryMemory(options);
     if (!repositoryMemory.ok) {
-        return { ok: false, action: "memory.search", query, error: repositoryMemory.error };
+        return memoryCliRepositoryFailure("memory.search", repositoryMemory, { query });
     }
     const observability = await memoryCliObservability(options.env);
     const response = await invokeMemoraxMemoryProvider({ sessionId: memoryCliSessionId(args, options.env), prompt: query }, {
@@ -135,7 +135,7 @@ async function memoryAdd(args, options) {
         return { ok: false, action: "memory.add", error: contentOptions.error };
     const repositoryMemory = await resolveMemoryCliRepositoryMemory(options);
     if (!repositoryMemory.ok)
-        return { ok: false, action: "memory.add", error: repositoryMemory.error };
+        return memoryCliRepositoryFailure("memory.add", repositoryMemory);
     const sessionId = memoryCliSessionId(args, env);
     const observability = await memoryCliObservability(env);
     const response = await invokeMemoraxMemoryProvider({ sessionId, prompt: memory }, {
@@ -226,6 +226,24 @@ async function resolveMemoryCliRepositoryMemory(options) {
     }
     return commandMemory;
 }
+function memoryCliRepositoryFailure(action, failure, fields = {}) {
+    const userAction = failure.reason === "workspace_scope_mismatch"
+        ? "Start a new Codex or Claude Code session from the target repository or local workspace."
+        : failure.reason === "workspace_scope_unavailable"
+            ? "Start a new Codex or Claude Code session from the target repository or local workspace. If the problem continues, make sure its .git metadata is readable and valid."
+            : undefined;
+    return {
+        ok: false,
+        action,
+        ...fields,
+        ...(userAction ? {
+            workspaceScope: "unavailable",
+            workspaceScopeReason: failure.reason,
+            userAction,
+        } : {}),
+        error: failure.error,
+    };
+}
 function memoryCliIdentityFields(memory) {
     return {
         baseUserId: memory.config.userId,
@@ -234,6 +252,10 @@ function memoryCliIdentityFields(memory) {
             scopeKind: repositoryMemoryScopeKind(memory.scope),
             effectiveUserId: memory.scope.effectiveUserId,
             workspaceScope: "bound",
+            ...(memory.scope.fallbackReason === "git_metadata_invalid" ? {
+                workspaceScopeFallbackReason: memory.scope.fallbackReason,
+                userNotice: `Git repository metadata is invalid or incomplete. MemoraX Code is using the local folder name "${memory.scope.repositorySlug}" for memory scope, so Search and Add use "${memory.scope.effectiveUserId}". Repair the repository or restore valid .git metadata. Later Search, Add, and automatic writeback in the same client session will automatically use the restored Git repository scope.`,
+            } : {}),
         } : {
             workspaceScope: "unavailable",
         }),

package/lib/memorax-code-backend/dist/memory-service.js

@@ -7,7 +7,9 @@ export function createMemoryService(options = {}) {
     const automaticWriteback = createAutomaticMemoryWritebackRuntime({
         diagnosticLogger: options.diagnosticLogger,
     });
-    const repositoryMemorySession = createRepositoryMemorySessionRuntime();
+    const repositoryMemorySession = createRepositoryMemorySessionRuntime({
+        onScopeUpgrade: automaticWriteback.discardForScopeUpgrade,
+    });
     const turnCoordinator = createMemoryTurnCoordinator({
         automaticWriteback: automaticWriteback.enqueue,
         now: options.now,

package/lib/memorax-code-backend/dist/memory-turn-coordinator.js

@@ -1,4 +1,4 @@
-import { repositoryMemoryScopesMatch, } from "./repository-memory-scope.js";
+import { repositoryMemoryScopeCanUpgradeFromDegradedGit, repositoryMemoryScopesMatch, } from "./repository-memory-scope.js";
 const DEFAULT_TTL_MS = 5 * 60 * 1000;
 const DEFAULT_MAX_ENTRIES = 256;
 const DEFAULT_CLEANUP_INTERVAL_MS = 60 * 1000;
@@ -72,10 +72,13 @@ export function createMemoryTurnCoordinator(options) {
             if (!currentScope) {
                 return reject(input.metadata ? "workspace_scope_mismatch" : "workspace_scope_unavailable");
             }
-            const repositoryScope = input.metadata?.repositoryScope ?? currentScope;
+            let repositoryScope = input.metadata?.repositoryScope ?? currentScope;
             if (input.metadata?.repositoryScope
                 && !repositoryMemoryScopesMatch(input.metadata.repositoryScope, currentScope)) {
-                return reject("workspace_scope_mismatch");
+                if (!repositoryMemoryScopeCanUpgradeFromDegradedGit(input.metadata.repositoryScope, currentScope)) {
+                    return reject("workspace_scope_mismatch");
+                }
+                repositoryScope = currentScope;
             }
             const acceptance = options.automaticWriteback({
                 ...input.writeback,

package/lib/memorax-code-backend/dist/memory-viewer-icon.js

@@ -0,0 +1 @@
+export const MEMORAX_ICON_DATA_URL = "data:image/png;base64,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";

package/lib/memorax-code-backend/dist/memory-viewer-user-html.js

@@ -5,6 +5,7 @@ export function memoryViewerUserHtml() {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width,initial-scale=1">
   <meta name="theme-color" content="#f7f8fc">
+  <link rel="icon" type="image/png" sizes="64x64" href="/memory-viewer/favicon.png">
   <title>MemoraX Code Memory Viewer</title>
   <script>
     const THEME_STORAGE_KEY='memorax-code-memory-viewer-theme',LANGUAGE_STORAGE_KEY='memorax-code-memory-viewer-language';
@@ -27,8 +28,8 @@ export function memoryViewerUserHtml() {
           cardTurns:'会话',cardSearch:'搜索',cardAdd:'写入',cardRepo:'仓库记忆',loading:'正在加载',checking:'正在检查',repoLoading:'仓库知识状态',recentActivity:'最近活动',
           empty:'当前范围还没有会话、搜索或写入活动',error:'暂时无法加载记忆活动，请稍后重试。',selectProject:'选择仓库',selectProjectForStatus:'选择仓库后查看状态',noProjects:'暂无可识别仓库',unassignedProject:'未归属仓库',systemActivity:'系统活动',
           turnNote:'轮客户端会话',searchUnit:'次搜索',addUnit:'次写入',processingUnit:'个处理中',unknownUnit:'个数量未知',activityUnit:'条',
-          repoStates:{ready:'可用',preparing:'准备中',not_ready:'未就绪',unknown:'未知'},
-          reasons:{usable:'仓库知识可以使用',active_job:'正在生成或更新',bundle_missing:'尚未生成仓库知识',bundle_invalid:'仓库知识需要重新生成',project_unresolved:'无法定位仓库',validator_unavailable:'暂时无法检查'},
+          repoStates:{ready:'可用',preparing:'生成中',not_ready:'未就绪',unknown:'未知'},
+          reasons:{usable:'仓库知识可以使用',active_job:'正在生成或更新',bundle_missing:'正在生成仓库知识',bundle_invalid:'仓库知识需要重新生成',project_unresolved:'无法定位仓库',validator_unavailable:'暂时无法检查'},
           statuses:{completed:'完成',saved:'已保存',skipped:'未写入',processing:'进行中',interrupted:'已中断',failed:'失败',unknown:'数量未知'},
           sources:{client:'客户端会话',assistant:'助手主动',automatic:'系统自动'}
         },
@@ -39,8 +40,8 @@ export function memoryViewerUserHtml() {
           cardTurns:'Turns',cardSearch:'Search',cardAdd:'Add',cardRepo:'Repo Memory',loading:'Loading',checking:'Checking',repoLoading:'Repository knowledge status',recentActivity:'Recent activity',
           empty:'No turn, Search, or Add activity in the current scope',error:'Memory activity is temporarily unavailable. Please try again later.',selectProject:'Select a repository',selectProjectForStatus:'Select a repository to view its status',noProjects:'No repositories found',unassignedProject:'Unassigned repository',systemActivity:'System activity',
           turnNote:'client turns',searchUnit:'searches',addUnit:'adds',processingUnit:'processing',unknownUnit:'with unknown counts',activityUnit:'items',
-          repoStates:{ready:'Ready',preparing:'Preparing',not_ready:'Not Ready',unknown:'Unknown'},
-          reasons:{usable:'Repository knowledge is ready',active_job:'Generating or updating repository knowledge',bundle_missing:'Repository knowledge has not been generated',bundle_invalid:'Repository knowledge needs to be regenerated',project_unresolved:'Repository could not be resolved',validator_unavailable:'Status is temporarily unavailable'},
+          repoStates:{ready:'Ready',preparing:'Generating',not_ready:'Not Ready',unknown:'Unknown'},
+          reasons:{usable:'Repository knowledge is ready',active_job:'Generating or updating repository knowledge',bundle_missing:'Generating repository knowledge',bundle_invalid:'Repository knowledge needs to be regenerated',project_unresolved:'Repository could not be resolved',validator_unavailable:'Status is temporarily unavailable'},
           statuses:{completed:'Completed',saved:'Saved',skipped:'No Add',processing:'Processing',interrupted:'Interrupted',failed:'Failed',unknown:'Count unknown'},
           sources:{client:'Client session',assistant:'Assistant initiated',automatic:'Automatic'}
         }
@@ -54,7 +55,7 @@ export function memoryViewerUserHtml() {
       function setTheme(next,persist=true){theme=next;document.documentElement.dataset.theme=theme;document.querySelector('meta[name="theme-color"]').content=theme==='dark'?'#10121a':'#f7f8fc';if(persist)writePreference(THEME_STORAGE_KEY,theme);syncThemeButton()}
       function setLanguage(next,persist=true){language=next;if(persist)writePreference(LANGUAGE_STORAGE_KEY,language);syncStaticCopy();if(lastBody)render(lastBody);if(connectionState!==null)connection(connectionState)}
       function syncProjects(items){const current=selected;project.innerHTML='<option value="">'+esc(copy().allProjects)+'</option>'+items.map(item=>'<option value="'+esc(item.projectId)+'">'+esc(item.projectLabel)+'</option>').join('');project.value=items.some(item=>item.projectId===current)?current:'';selected=project.value}
-      function repoState(items){const current=copy(),target=selected?items.find(item=>item.projectId===selected):items.length===1?items[0]:null,state=target?.repoMemory||{status:'unknown',reason:'project_unresolved'};E('repo-state').className='repo-state';E('repo-dot').className='state-dot '+state.status;E('repo-label').textContent=target?(current.repoStates[state.status]||current.repoStates.unknown):current.selectProject;E('repo-note').classList.remove('skeleton','loading-copy');E('repo-note').textContent=target?(target.projectLabel+' · '+(current.reasons[state.reason]||current.reasons.validator_unavailable)):items.length?current.selectProjectForStatus:current.noProjects}
+      function repoState(items){const current=copy(),target=selected?items.find(item=>item.projectId===selected):items.length===1?items[0]:null,state=target?.repoMemory||{status:'unknown',reason:'project_unresolved'},displayStatus=state.reason==='bundle_missing'?'preparing':state.status;E('repo-state').className='repo-state';E('repo-dot').className='state-dot '+displayStatus;E('repo-label').textContent=target?(current.repoStates[displayStatus]||current.repoStates.unknown):current.selectProject;E('repo-note').classList.remove('skeleton','loading-copy');E('repo-note').textContent=target?(target.projectLabel+' · '+(current.reasons[state.reason]||current.reasons.validator_unavailable)):items.length?current.selectProjectForStatus:current.noProjects}
       function memoryCount(value){if(language==='zh')return value+' 条记忆';return value+' '+(value===1?'memory':'memories')}
       function activityTitle(item){if(language==='zh'){if(item.kind==='turn')return item.status==='processing'?'会话进行中':item.status==='interrupted'?'会话已中断':'完成一轮会话';if(item.kind==='search')return item.status==='failed'?'搜索失败':'搜索 · '+memoryCount(item.count??0);if(item.status==='saved')return item.count===null?'写入 · 数量未知':'写入 · '+memoryCount(item.count);if(item.status==='skipped')return '写入 · 没有新记忆';if(item.status==='processing')return '写入处理中';if(item.status==='failed')return '写入失败';return '写入完成 · 数量未知'}if(item.kind==='turn')return item.status==='processing'?'Session in progress':item.status==='interrupted'?'Session interrupted':'Session turn completed';if(item.kind==='search')return item.status==='failed'?'Search failed':'Search · '+memoryCount(item.count??0);if(item.status==='saved')return item.count===null?'Add · Count unknown':'Add · '+memoryCount(item.count);if(item.status==='skipped')return 'Add · No new memory';if(item.status==='processing')return 'Add in progress';if(item.status==='failed')return 'Add failed';return 'Add completed · Count unknown'}
       function metaItem(value){return '<span class="meta-item">'+esc(value)+'</span>'}

package/lib/memorax-code-backend/dist/memory-writeback-buffer.js

@@ -1,5 +1,6 @@
 import { writebackMessagesContentChars } from "./memory-writeback-chunk.js";
 import { memoryWritebackBufferConfig } from "./memorax-config.js";
+import { repositoryMemoryScopeCanUpgradeFromDegradedGit, } from "./repository-memory-scope.js";
 const SYSTEM_CLOCK = {
     now: () => Date.now(),
     setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
@@ -11,6 +12,9 @@ export function createMemoryWritebackBufferRuntime() {
         enqueue(decision, options, deps) {
             enqueueMemoryWritebackBufferForRuntime(writebackBuffers, decision, options, deps);
         },
+        discardForScopeUpgrade(upgrade) {
+            return discardDegradedGitBuffersForUpgrade(writebackBuffers, upgrade);
+        },
         flushAll(flushReason) {
             let flushed = 0;
             for (const [bufferKey, buffer] of [...writebackBuffers.entries()]) {
@@ -34,6 +38,11 @@ function enqueueMemoryWritebackBufferForRuntime(writebackBuffers, decision, opti
     const config = memoryWritebackBufferConfig(env);
     if (!options.repositoryScope)
         return;
+    discardDegradedGitBuffersForUpgrade(writebackBuffers, {
+        client: decision.client,
+        sessionKey: decision.sessionKey,
+        currentScope: options.repositoryScope,
+    });
     const bufferKey = memoryWritebackBufferKey(decision.client, decision.sessionKey, options.repositoryScope);
     let buffer = writebackBuffers.get(bufferKey);
     if (buffer?.turnKeys.has(decision.idempotencyKey)) {
@@ -85,6 +94,26 @@ function enqueueMemoryWritebackBufferForRuntime(writebackBuffers, decision, opti
         resetMemoryWritebackIdleTimer(writebackBuffers, buffer, config.maxAgeMs, deps);
     }
 }
+function discardDegradedGitBuffersForUpgrade(writebackBuffers, upgrade) {
+    let discarded = 0;
+    for (const [bufferKey, buffer] of writebackBuffers.entries()) {
+        if (buffer.client !== upgrade.client
+            || buffer.sessionKey !== upgrade.sessionKey
+            || !repositoryMemoryScopeCanUpgradeFromDegradedGit(buffer.repositoryScope, upgrade.currentScope))
+            continue;
+        writebackBuffers.delete(bufferKey);
+        if (buffer.timer)
+            buffer.clock.clearTimeout(buffer.timer);
+        buffer.deps.debug("memory.automatic_writeback", {
+            scheduled: false,
+            skipReason: "buffer_scope_upgraded",
+            sessionKey: upgrade.sessionKey,
+            discardedTurnCount: buffer.turns.length,
+        });
+        discarded += 1;
+    }
+    return discarded;
+}
 function createMemoryWritebackBuffer(bufferKey, client, sessionKey, env, options, repositoryScope, clock, deps) {
     const now = clock.now();
     const buffer = {