@memorax/memorax-code 0.1.0

package/bin/memorax-code.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stagePackagedClientHookRuntime } from "../lib/client-hook-runtime.mjs";
+import { unsupportedNodeVersionMessage } from "../lib/node-version.mjs";
+import { resolveNpmInvocation } from "../lib/npm-invocation.mjs";
+import { runBackendEntrypoint } from "../lib/run-entrypoint.mjs";
+
+const nodeVersionError = unsupportedNodeVersionMessage();
+if (nodeVersionError) {
+  console.error(`memorax-code: ${nodeVersionError}`);
+  process.exit(1);
+}
+
+function packageRoot() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function readPackageJson() {
+  return JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8"));
+}
+
+function printUpdateHelp() {
+  console.log(`Usage: memorax-code update [--preview | --latest] [--force] [--home DIR] [--dry-run]
+
+Update the globally installed MemoraX Code npm package.
+
+Options:
+  --preview   Follow the npm preview dist-tag
+  --latest    Follow the npm latest dist-tag
+  --force     Reinstall the selected channel with npm install --force
+  --home DIR  Update the Backend managed under this MemoraX Code home
+  --dry-run   Print the npm command without running it
+  -h, --help  Show this help message`);
+}
+
+function printCommand(command, args) {
+  console.log([command, ...args].join(" "));
+}
+
+function npmCommandCwd() {
+  for (const candidate of [process.env.HOME, homedir(), "/"]) {
+    if (candidate && existsSync(candidate)) return candidate;
+  }
+  return "/";
+}
+
+async function runUpdateCommand(args) {
+  let dryRun = false;
+  let force = false;
+  let requestedChannel;
+  let requestedHome;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--force") {
+      force = true;
+    } else if (arg === "--home") {
+      const value = args[++index];
+      if (!value || value.startsWith("--")) {
+        console.error("memorax-code update: --home requires a directory");
+        printUpdateHelp();
+        return 2;
+      }
+      requestedHome = resolve(value);
+    } else if (arg.startsWith("--home=")) {
+      const value = arg.slice("--home=".length).trim();
+      if (!value) {
+        console.error("memorax-code update: --home requires a directory");
+        printUpdateHelp();
+        return 2;
+      }
+      requestedHome = resolve(value);
+    } else if (arg === "--preview" || arg === "--latest") {
+      const channel = arg.slice(2);
+      if (requestedChannel && requestedChannel !== channel) {
+        console.error("memorax-code update: --preview and --latest cannot be used together");
+        printUpdateHelp();
+        return 2;
+      }
+      requestedChannel = channel;
+    } else if (arg === "--help" || arg === "-h") {
+      printUpdateHelp();
+      return 0;
+    } else {
+      console.error(`memorax-code update: unknown option ${arg}`);
+      printUpdateHelp();
+      return 2;
+    }
+  }
+
+  const pkg = readPackageJson();
+  const channel = requestedChannel ?? (pkg.version.includes("-") ? "preview" : "latest");
+  const npmArgs = ["install", "-g", `${pkg.name}@${channel}`];
+  if (force) npmArgs.push("--force");
+  npmArgs.push("--foreground-scripts");
+
+  if (dryRun) {
+    printCommand("npm", npmArgs);
+    return 0;
+  }
+
+  console.error(`memorax-code update: running ${["npm", ...npmArgs].join(" ")}`);
+  const cwd = npmCommandCwd();
+  let invocation;
+  try {
+    invocation = resolveNpmInvocation(npmArgs);
+  } catch (error) {
+    console.error(`memorax-code update: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  const child = spawn(invocation.command, invocation.args, {
+    stdio: "inherit",
+    cwd,
+    env: {
+      ...process.env,
+      PWD: cwd,
+      MEMORAX_CODE_NPM_POSTINSTALL_UPDATE: "1",
+      ...(requestedHome ? { MEMORAX_CODE_HOME: requestedHome } : {}),
+    },
+  });
+  return await new Promise((resolve) => {
+    child.on("error", (error) => {
+      console.error(`memorax-code update: failed to start npm: ${error.message}`);
+      resolve(1);
+    });
+    child.on("close", (code, signal) => {
+      if (signal) {
+        console.error(`memorax-code update: npm exited from signal ${signal}`);
+        resolve(1);
+      } else {
+        resolve(code ?? 1);
+      }
+    });
+  });
+}
+
+if (process.argv[2] === "update") {
+  process.exit(await runUpdateCommand(process.argv.slice(3)));
+}
+
+if (process.argv[2] === "--version" || process.argv[2] === "-v") {
+  const pkg = readPackageJson();
+  console.log(`memorax-code ${pkg.version}`);
+  process.exit(0);
+}
+
+if (shouldStageClientHookRuntime(process.argv.slice(2))
+  && !truthyEnv(process.env.MEMORAX_CODE_DEFER_CLIENT_HOOK_RUNTIME_ACTIVATION)) {
+  try {
+    const memoraxCodeHome = requestedMemoraxCodeHome(process.argv.slice(2));
+    const generation = await stagePackagedClientHookRuntime({
+      packageRoot: packageRoot(),
+      memoraxCodeHome,
+    });
+    process.env.MEMORAX_CODE_PENDING_CLIENT_HOOK_RUNTIME_V1 = JSON.stringify({
+      version: 1,
+      memoraxCodeHome,
+      generation: {
+        version: generation.version,
+        runtimeAbi: generation.runtimeAbi,
+        generationId: generation.generationId,
+        packageVersion: generation.packageVersion,
+        contentDigest: generation.contentDigest,
+        createdAt: generation.createdAt,
+      },
+    });
+  } catch (error) {
+    console.error(`memorax-code: failed to stage client Hook runtime: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+
+await runBackendEntrypoint("memorax-code.js");
+
+function shouldStageClientHookRuntime(args) {
+  if (args.includes("--help") || args.includes("-h")) return false;
+  return args[0] === "start" || args[0] === "restart";
+}
+
+function requestedMemoraxCodeHome(args) {
+  const inline = args.find((arg) => arg.startsWith("--home="));
+  if (inline) {
+    const value = inline.slice("--home=".length);
+    if (!value.trim()) throw new Error("--home requires a directory");
+    return resolve(value);
+  }
+  const index = args.indexOf("--home");
+  if (index >= 0) {
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) throw new Error("--home requires a directory");
+    return resolve(value);
+  }
+  return resolve(process.env.MEMORAX_CODE_HOME || join(homedir(), ".memorax-code"));
+}
+
+function truthyEnv(value) {
+  return ["1", "true", "yes"].includes(String(value ?? "").trim().toLowerCase());
+}

package/docs/configuration.md

@@ -0,0 +1,232 @@
+# Configuration
+
+MemoraX Code reads persistent configuration from:
+
+```text
+$MEMORAX_CODE_HOME/config.toml
+```
+
+`MEMORAX_CODE_HOME` defaults to `~/.memorax-code`. There is no separate
+configuration-path setting. Treat the whole file as private: it can contain a
+MemoraX API key and must not be committed or pasted into public issues.
+
+## Precedence and reload behavior
+
+Where a setting supports every layer, precedence is:
+
+```text
+explicit command/context value > environment variable > config.toml > code fallback
+```
+
+Use `config.toml` for durable choices and environment variables for temporary
+overrides or credentials that should not be written to disk. After editing the
+file, run:
+
+```sh
+memorax-code start
+memorax-code status
+memorax-cli status
+```
+
+This reconciles the managed Backend and client integrations. Some Hook and CLI
+processes reread configuration sooner, but `memorax-code start` is the
+supported consistency boundary.
+
+TOML booleans are `true` or `false`. Environment booleans accept
+`true/false`, `1/0`, `yes/no`, and `on/off`. Unknown fields are ignored and
+are not a compatibility contract.
+
+## New configuration
+
+The generated template selects both clients, disables automatic retrieval,
+enables automatic writeback, sets the preferred language to Chinese (`zh`),
+uses a five-turn skill reminder and the adaptive repository-update policy, and
+enables content-bearing local traces for both clients. npm installation may
+narrow `[clients]` to clients detected on the host. The tables below list all
+fallbacks, including tuning fields omitted from the generated file.
+
+On POSIX systems MemoraX Code creates `$MEMORAX_CODE_HOME` with mode `0700`
+and a new `config.toml` with mode `0600`. Windows relies on the current user's
+filesystem ACLs.
+
+## Client selection
+
+If `[clients]` is absent, lifecycle commands select both clients. If it is
+present, `codex` and `claude` are boolean fields and an omitted client is
+disabled. The command-line override is:
+
+```text
+--clients codex|claude|codex,claude|all|none
+```
+
+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.
+
+## MemoraX connection
+
+MemoraX is the required remote-memory service:
+
+```toml
+[memorax]
+endpoint = "https://platform.memorax.net"
+user_id = "your-base-user-id"
+api_key = "your-api-key"
+# timeout_ms = 5000
+# startup_timeout_ms = 3000
+```
+
+| Field | Environment override | Fallback |
+| --- | --- | --- |
+| `endpoint` | `MEMORAX_CODE_MEMORAX_ENDPOINT` | `https://platform.memorax.net` |
+| `user_id` | `MEMORAX_CODE_MEMORAX_USER_ID` | required |
+| `api_key` | `MEMORAX_CODE_MEMORAX_API_KEY` | required |
+| `timeout_ms` | `MEMORAX_CODE_MEMORAX_TIMEOUT_MS` | `5000` ms |
+| `startup_timeout_ms` | `MEMORAX_CODE_MEMORAX_STARTUP_TIMEOUT_MS` | `3000` ms |
+
+MemoraX requests send the API key and the query or content required by the
+selected memory operation to the HTTPS endpoint. Override `endpoint` only with
+a compatible MemoraX service you trust.
+
+`startup_timeout_ms` controls synchronous automatic retrieval and is capped at
+10 seconds. `user_id` is a base identity; MemoraX Code derives a
+repository-scoped identity for Git workspaces and a folder-scoped identity for
+non-Git workspaces. It never falls back to the unscoped base identity.
+
+## Retrieval
+
+Automatic prompt retrieval is disabled by default.
+
+| Field | Environment override | Fallback |
+| --- | --- | --- |
+| `enabled` | `MEMORAX_CODE_MEMORY_RETRIEVAL_ENABLED` | `false` |
+| `top_k` | `MEMORAX_CODE_MEMORAX_TOP_K` | `6` |
+| `k_dense` | `MEMORAX_CODE_MEMORAX_K_DENSE` | effective `top_k` |
+| `k_sparse` | `MEMORAX_CODE_MEMORAX_K_SPARSE` | effective `top_k`; `0` disables sparse |
+| `min_score` | `MEMORAX_CODE_MEMORAX_MIN_SCORE` | unset; range `0..1` |
+| `max_context_chars` | `MEMORAX_CODE_MEMORAX_MAX_CONTEXT_CHARS` | `4000` |
+| `max_item_chars` | `MEMORAX_CODE_MEMORAX_MAX_ITEM_CHARS` | `1000` |
+| `render_by_memory_type` | `MEMORAX_CODE_MEMORAX_RENDER_BY_MEMORY_TYPE` | `true` |
+| `memory_type_order` | `MEMORAX_CODE_MEMORAX_MEMORY_TYPE_ORDER` | `core,episodic,semantic,procedural,unclassified` |
+
+The TOML form of `memory_type_order` is an array of strings; the environment
+form is comma-separated. `enabled` controls automatic `UserPromptSubmit`
+retrieval only. Explicit `memorax-cli search` remains available when
+credentials and a trusted workspace scope resolve.
+
+## Writeback and explicit add
+
+New configurations explicitly set automatic transcript writeback to enabled.
+An existing configuration without `enabled` remains disabled.
+
+| Field | Environment override | Fallback |
+| --- | --- | --- |
+| `enabled` | `MEMORAX_CODE_MEMORY_WRITEBACK_ENABLED` | `false` when absent |
+| `buffer_enabled` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_ENABLED` | `true` |
+| `buffer_max_turns` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_TURNS` | `8`; `-1` disables automatic Hook writeback |
+| `buffer_max_age_ms` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_AGE_MS` | `600000` |
+| `buffer_max_chars` | `MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_CHARS` | `128000` |
+| `max_message_chars` | `MEMORAX_CODE_MEMORY_WRITEBACK_MAX_MESSAGE_CHARS` | `64000` |
+| `chunk_enabled` | `MEMORAX_CODE_MEMORY_WRITEBACK_CHUNK_ENABLED` | `true` |
+| `chunk_max_chars` | `MEMORAX_CODE_MEMORY_WRITEBACK_CHUNK_MAX_CHARS` | `8000` |
+| `chunk_overlap_ratio` | `MEMORAX_CODE_MEMORY_WRITEBACK_CHUNK_OVERLAP_RATIO` | `0.05`; range `0 <= x < 1` |
+
+The global kill switch
+`MEMORAX_CODE_MEMORAX_WRITEBACK_ENABLED=false` disables automatic writeback and
+explicit `memory add`.
+
+| Field | Environment override | Fallback |
+| --- | --- | --- |
+| `memory.add.content_type` | `MEMORAX_CODE_MEMORAX_ADD_CONTENT_TYPE` | command-dependent |
+| `memory.add.mode` | `MEMORAX_CODE_MEMORAX_ADD_MODE` | command-dependent |
+| `memory.add.output_language` | `MEMORAX_CODE_MEMORY_OUTPUT_LANGUAGE` | `zh` |
+| `memory.cli.add_enabled` | `MEMORAX_CODE_MEMORY_CLI_ADD_ENABLED` | `true` |
+| `memory.cli.max_memory_chars` | `MEMORAX_CODE_MEMORY_CLI_MAX_MEMORY_CHARS` | `2000` |
+
+`output_language` accepts only `zh` or `en`. It is a local user preference,
+not a model-controlled request option; every automatic and explicit add sends
+the resolved value to MemoraX. Invalid values fail closed instead of silently
+selecting another language. The setting affects newly generated content;
+`raw` input and client-supplied `pre_summarized` text are not translated.
+Command arguments override the other add defaults.
+
+## Skill reminder and repository maintenance
+
+`[memory.skill_reminder].interval_turns` defaults to `5`; its environment
+override is `MEMORAX_CODE_MEMORY_SKILL_REMINDER_INTERVAL_TURNS`. A positive
+value controls the reminder cadence for both clients, beginning with the first
+eligible prompt.
+
+| Field | Environment override | Fallback |
+| --- | --- | --- |
+| `policy` | `MEMORAX_CODE_REPO_MEMORY_UPDATE_POLICY` | `adaptive` |
+| `commit_threshold` | `MEMORAX_CODE_REPO_MEMORY_STALE_COMMIT_THRESHOLD` | `5` |
+| `cooldown_hours` | `MEMORAX_CODE_REPO_MEMORY_UPDATE_COOLDOWN_HOURS` | `24` |
+
+Supported policies are `every-commit`, `commit-count`, `daily`,
+`pull-request`, `pull-request-or-daily`, and `adaptive`. Invalid policy values
+fall back to `adaptive`.
+
+## Local traces
+
+`[trace.codex]` and `[trace.claude]` support the same fields:
+
+| Field | Codex environment | Claude environment | Fallback |
+| --- | --- | --- | --- |
+| `enabled` | `MEMORAX_CODE_CODEX_TRACE_ENABLED` | `MEMORAX_CODE_CLAUDE_TRACE_ENABLED` | `true` |
+| `capture_content` | `MEMORAX_CODE_CODEX_TRACE_CAPTURE_CONTENT` | `MEMORAX_CODE_CLAUDE_TRACE_CAPTURE_CONTENT` | `true` |
+| `retention_days` | `MEMORAX_CODE_CODEX_TRACE_RETENTION_DAYS` | `MEMORAX_CODE_CLAUDE_TRACE_RETENTION_DAYS` | `7` |
+| `max_event_chars` | `MEMORAX_CODE_CODEX_TRACE_MAX_EVENT_CHARS` | `MEMORAX_CODE_CLAUDE_TRACE_MAX_EVENT_CHARS` | `20000` |
+| `max_file_bytes` | `MEMORAX_CODE_CODEX_TRACE_MAX_FILE_BYTES` | `MEMORAX_CODE_CLAUDE_TRACE_MAX_FILE_BYTES` | `52428800` |
+
+Content capture can include prompts, responses, recalled memory, writeback
+content, reminder text, and local paths. Set `capture_content=false` for
+metadata-only local traces, or `enabled=false` to disable a client's trace.
+Trace files stay under `$MEMORAX_CODE_HOME`; MemoraX Code has no trace upload,
+export, or public collector.
+
+## Backend runtime settings
+
+Backend connection and process authority is not stored in `config.toml`.
+Common operator settings are:
+
+| Environment | Purpose |
+| --- | --- |
+| `MEMORAX_CODE_HOME` | Select the state and configuration root |
+| `MEMORAX_CODE_BACKEND_URL` | Override the Backend URL for one command or Hook |
+| `MEMORAX_CODE_BACKEND_HOST` / `MEMORAX_CODE_BACKEND_PORT` | Select the managed bind; default `127.0.0.1:8787` |
+| `MEMORAX_CODE_BACKEND_TOKEN` | Supply a transient Backend token |
+| `MEMORAX_CODE_BACKEND_MODE` | Select explicit local or server behavior |
+| `MEMORAX_CODE_BACKEND_ALLOW_EXTERNAL` | Allow an explicitly intended non-loopback bind |
+| `MEMORAX_CODE_BACKEND_LOOPBACK_AUTH` | Control token use on loopback |
+| `MEMORAX_CODE_BACKEND_LOG` | Override the managed Backend log path |
+
+External binds fail unless explicitly allowed and protected by a Backend
+token. Persistent connection, token, and PID records live under
+`$MEMORAX_CODE_HOME/runtime/backend/`; do not hand-edit them.
+
+## Failure behavior and diagnostics
+
+- Missing `config.toml` is treated as an empty configuration and can be seeded
+  on startup.
+- Malformed TOML, a non-table root, or invalid `[clients]` types block
+  lifecycle mutations before adapters or processes are changed.
+- Ordinary memory and trace readers use safe fallbacks when the file cannot be
+  read or parsed; memory readers may also warn. Unsupported field types are
+  ignored.
+- Targeted configuration updates preserve unrelated and unknown TOML content.
+- Invalid or unsupported Backend runtime records fail closed instead of
+  silently falling back to `127.0.0.1:8787`.
+
+Use these commands before editing state manually:
+
+```sh
+memorax-code status
+memorax-code status --json
+memorax-cli status
+memorax-cli status --json
+memorax-code-codex doctor
+memorax-code-claude doctor
+```
+
+The status commands do not print the MemoraX API key or Backend token.

package/docs/troubleshooting.md

@@ -0,0 +1,179 @@
+# Troubleshooting
+
+Start with the user-facing diagnostics:
+
+```sh
+memorax-code status
+memorax-cli status
+memorax-code-codex doctor
+memorax-code-claude doctor
+memorax-code logs
+```
+
+`status` checks the Backend and client integrations. `memory status` checks
+credentials, scope, and memory switches without printing secrets. Each client
+`doctor` checks its plugin, skill, workspace, and Backend connection.
+
+## Installed, but memory is unavailable
+
+The package and Backend can be healthy while MemoraX remains unconfigured. Run:
+
+```sh
+memorax-cli status
+```
+
+Configure `endpoint`, `user_id`, and `api_key` under `[memorax]` in
+`$MEMORAX_CODE_HOME/config.toml`, or set their environment equivalents. The
+current default endpoint is `https://platform.memorax.net`.
+
+After changing persistent configuration:
+
+```sh
+memorax-code start
+memorax-cli status
+```
+
+Automatic retrieval is disabled by default and is independent from explicit
+search. Automatic writeback requires `[memory.writeback] enabled = true` and
+must not be disabled by
+`MEMORAX_CODE_MEMORAX_WRITEBACK_ENABLED=false`.
+
+## Backend does not start
+
+```sh
+memorax-code status
+memorax-code logs
+memorax-code start
+```
+
+Check the reported bind address, port, and error code. The default is
+`127.0.0.1:8787`; another process may already own that port. A non-loopback
+bind is rejected unless external access is explicitly enabled and a Backend
+token is configured.
+
+If `status` reports an invalid or unsupported connection authority, MemoraX
+Code deliberately does not fall back to port 8787. `memorax-code stop` remains
+available. After confirming the intended local address, recover with:
+
+```sh
+memorax-code start --host 127.0.0.1 --port <intended-port>
+```
+
+The persisted authority changes only after the Backend becomes healthy. A
+one-off `--backend-url` or `MEMORAX_CODE_BACKEND_URL` override does not rewrite
+it.
+
+To rotate a Backend token:
+
+```sh
+memorax-code stop
+memorax-code token --rotate
+memorax-code start
+```
+
+Rotation is rejected while the managed Backend is running.
+
+Lifecycle state and locks fail closed when process ownership is uncertain.
+Do not delete PID or lock files while a process or lifecycle command may still
+be active. Let concurrent work finish, then rerun `memorax-code status`.
+
+## Codex plugin or Hook is inactive
+
+```sh
+memorax-code codex-plugin install
+memorax-code codex-plugin activate --yes
+memorax-code codex-plugin trust-hooks
+memorax-code start --clients codex
+memorax-code-codex doctor
+```
+
+Codex requires review for new or changed Hook command hashes. A declined or
+non-interactive update can leave Hooks untrusted even though the update
+succeeded. Do not write trust entries directly. If the skill is missing, rerun
+`memorax-code start --clients codex`, then restart or refresh Codex.
+
+## Claude Code plugin or Hook is inactive
+
+```sh
+memorax-code start --clients claude
+memorax-code-claude doctor
+```
+
+This reconciles the Claude Code marketplace plugin and Hooks. If the plugin is
+still missing or stale, restart or refresh Claude Code. Do not manually copy
+Hooks into Claude settings.
+
+An already-open client may keep its loaded plugin shell while a later prompt
+uses the updated Hook runtime. Restart or refresh the client to load a changed
+plugin manifest, icon, or bundled skill.
+
+## Hooks cannot reach localhost on macOS
+
+If shell requests work but Hook diagnostics fail, a global proxy or client
+environment may be intercepting `127.0.0.1` or `localhost`.
+
+```sh
+memorax-code start
+memorax-code-codex doctor
+memorax-code-claude doctor
+/usr/sbin/scutil --proxy
+/bin/launchctl getenv NO_PROXY
+/bin/launchctl getenv no_proxy
+```
+
+Correct the proxy or process environment, then fully quit and reopen the
+client. MemoraX Code does not edit system proxy settings or login
+environments. Redact proxy details before sharing diagnostics.
+
+## MemoraX search, add, or scope fails
+
+```sh
+memorax-cli status
+memorax-cli search --query 'test'
+memorax-code-codex doctor
+memorax-code-claude doctor
+```
+
+Common causes are:
+
+- missing or invalid MemoraX endpoint, base user ID, or API key;
+- the global writeback kill switch or CLI add switch disabling `memory add`;
+- no trusted workspace for the current session;
+- an unreadable, malformed, or symlinked Git marker;
+- one live session attempting to change to a different repository/workspace;
+- local DNS, proxy, or network failure.
+
+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.
+
+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.
+
+## Model-provider requests fail while MemoraX Code is healthy
+
+MemoraX Code does not proxy Codex or Claude Code model requests. If
+`memorax-code status` and the relevant client doctor are healthy, inspect the
+provider URL, credentials, model selection, and network settings owned by that
+client. Do not copy model-provider credentials into
+`$MEMORAX_CODE_HOME`.
+
+## Safe issue reports
+
+Collect structured, redacted output:
+
+```sh
+memorax-code status --json
+memorax-cli status --json
+memorax-code-codex doctor --json
+memorax-code-claude doctor --json
+```
+
+Include the MemoraX Code version, operating system, affected client,
+reproduction steps, failing command, and the smallest relevant log excerpt.
+
+Never attach API keys, Backend tokens, environment files, complete client
+configuration, private transcripts, raw trace files, or unreviewed local
+paths. Redact usernames, workspace paths, remote URLs, and content before
+sharing.

package/lib/client-hook-runtime.mjs

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export async function stagePackagedClientHookRuntime(options) {
+  const runtime = await loadRuntimeModule(options.packageRoot);
+  return runtime.stageClientHookRuntimeGeneration(options);
+}
+
+export async function activatePackagedClientHookRuntime(options) {
+  const runtime = await loadRuntimeModule(options.packageRoot);
+  return runtime.activateClientHookRuntimeGeneration(options);
+}
+
+export async function preparePackagedClientHookRuntime(options) {
+  const runtime = await loadRuntimeModule(options.packageRoot);
+  return runtime.prepareClientHookRuntimeGeneration(options);
+}
+
+async function loadRuntimeModule(packageRoot) {
+  const root = resolve(packageRoot);
+  const path = join(
+    root,
+    "lib",
+    "memorax-code-adapter-common",
+    "src",
+    "hooks",
+    "hook-runtime-generation.mjs",
+  );
+  if (!existsSync(path)) throw new Error("packaged client Hook runtime installer is missing");
+  return await import(pathToFileURL(path).href);
+}