@memorax/memorax-code 0.1.11 → 0.1.12

package/lib/memorax-code-trae-adapter/hooks/runtime-hook.mjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { writeTraeRuntimeObservation } from "../src/runtime-observation.mjs";
+
+const runtimeRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const commonRoot = join(runtimeRoot, "memorax-code-adapter-common", "src");
+const { buildRepoProcedureMemoryContext } = await import(pathToFileURL(join(commonRoot, "repo-memory", "repo-procedure-memory-context.mjs")).href);
+const { buildRepoUserProfilePreferencesContext } = await import(pathToFileURL(join(commonRoot, "repo-memory", "repo-user-profile-context.mjs")).href);
+const { resolveBackendConnection } = await import(pathToFileURL(join(commonRoot, "backend-connection.mjs")).href);
+const {
+  atomicWriteJson,
+  readJsonFile,
+  withJsonFileLock,
+} = await import(pathToFileURL(join(commonRoot, "config-utils.mjs")).href);
+const { ensureBackendAvailable, stringValue: commonStringValue } = await import(pathToFileURL(join(commonRoot, "hooks", "ensure-backend-runner.mjs")).href);
+const {
+  evaluateMemorySkillReminder,
+  markSupplementalReminderAfterCompact,
+  personalMemoryReminderContext,
+} = await import(pathToFileURL(join(commonRoot, "hooks", "memory-skill-reminder-hook.mjs")).href);
+const { isRepoMemoryJobWorker } = await import(pathToFileURL(join(commonRoot, "repo-memory", "repo-memory-job-context.mjs")).href);
+
+if (isRepoMemoryJobWorker()) process.exit(0);
+
+const MEMORY_SKILL_INVOCATION = "the `memorax-code` skill";
+const REMINDER_TRACE_TIMEOUT_MS = 1000;
+const input = await readJsonStdin();
+const event = stringValue(input?.hook_event_name) ?? stringValue(input?.hookEventName);
+const sessionId = stringValue(input?.session_id) ?? stringValue(input?.sessionId);
+if (!event || !sessionId || !["SessionStart", "UserPromptSubmit", "Stop"].includes(event)) process.exit(0);
+
+const packageMetadata = await readRecord(join(runtimeRoot, ".memorax-code-package.json"));
+const home = commonStringValue(process.env.MEMORAX_CODE_HOME)
+  ?? commonStringValue(packageMetadata.memoraxCodeHome)
+  ?? join(homedir(), ".memorax-code");
+const traeHome = commonStringValue(process.env.TRAE_CN_HOME)
+  ?? commonStringValue(process.env.TRAE_HOME)
+  ?? commonStringValue(packageMetadata.traeHome)
+  ?? join(homedir(), ".trae-cn");
+const runtimeDigest = commonStringValue(packageMetadata.runtimeDigest);
+const debugEnabled = process.env.MEMORAX_CODE_TRAE_HOOK_DEBUG === "1";
+if (runtimeDigest) {
+  try {
+    await writeTraeRuntimeObservation({ memoraxCodeHome: home, traeHome, runtimeDigest });
+  } catch (error) {
+    debug(error);
+  }
+}
+
+const reminderOptions = {
+  adapterDir: "trae",
+  debugEnv: "MEMORAX_CODE_TRAE_HOOK_DEBUG",
+  memoraxCodeHome: home,
+  runtime: "trae",
+  supplementalReminderAfterCompact: true,
+};
+const personalMemoryContextOptions = {
+  adapterDir: "trae",
+  debugEnv: "MEMORAX_CODE_TRAE_HOOK_DEBUG",
+  sessionKeyPrefix: "trae",
+};
+const activeTurnsPath = join(home, "adapters", "trae", "active-turns.json");
+
+await ensureBackendAvailable({
+  ensureBackendValue: process.env.MEMORAX_CODE_TRAE_ENSURE_BACKEND
+    ?? process.env.MEMORAX_CODE_TRAE_HOOK_ENSURE_BACKEND,
+  healthTimeoutValue: process.env.MEMORAX_CODE_TRAE_ENSURE_TIMEOUT_MS,
+  startTimeoutValue: process.env.MEMORAX_CODE_TRAE_START_TIMEOUT_MS,
+  memoraxCodeCommand: commonStringValue(process.env.MEMORAX_CODE_TRAE_LIFECYCLE_COMMAND)
+    ?? commonStringValue(process.env.MEMORAX_CODE_COMMAND),
+  pluginRoot: runtimeRoot,
+  resolveHomes: () => ({ memoraxCodeHome: home, traeHome }),
+  buildStartArgs: (homes, recoveryArguments) => [
+    "start",
+    "--home", homes.memoraxCodeHome,
+    "--clients", "trae",
+    "--trae-home", homes.traeHome,
+    ...recoveryArguments,
+  ],
+  debug,
+}, input);
+
+if (event === "SessionStart") {
+  markSupplementalReminderAfterCompact(reminderOptions, input);
+} else if (event === "UserPromptSubmit") {
+  const prompt = contentValue(input.prompt);
+  if (!prompt) process.exit(0);
+  const cwd = stringValue(input.cwd);
+  const workspaceKind = stringValue(input.workspace_kind) ?? stringValue(input.workspaceKind);
+  const activeTurnPlan = prepareActiveTurn({ sessionId, prompt, cwd, workspaceKind });
+  const activeTurn = activeTurnPlan.record;
+  const response = await post("/memory/turn-start", {
+    version: 1,
+    client: "trae",
+    sessionId,
+    turnId: activeTurn.turnId,
+    prompt,
+    cwd,
+    workspaceKind,
+  });
+  if (response?.ok !== true || !commitActiveTurn(activeTurnPlan)) process.exit(0);
+  const repoMemoryWorktree = stringValue(response?.repoMemoryWorktree);
+  const reminderResult = await evaluateMemorySkillReminder({
+    ...reminderOptions,
+    additionalReminderContext: personalMemoryReminderContext(MEMORY_SKILL_INVOCATION),
+    memorySkillInvocation: MEMORY_SKILL_INVOCATION,
+    remindOnFirstTurn: true,
+    requireTranscriptPath: false,
+    ...(repoMemoryWorktree ? {
+      buildCadenceReminderContext: (hookInput) => buildRepoProcedureMemoryContext({
+        ...hookInput,
+        cwd: repoMemoryWorktree,
+      }, personalMemoryContextOptions),
+      buildPersonalMemoryContext: (hookInput) => buildRepoUserProfilePreferencesContext({
+        ...hookInput,
+        cwd: repoMemoryWorktree,
+      }, personalMemoryContextOptions),
+    } : {}),
+  }, { ...input, turnId: activeTurn.turnId, workspaceKind });
+  const context = [
+    stringValue(response?.additionalContext),
+    stringValue(reminderResult?.additionalContext),
+  ].filter(Boolean).join("\n\n");
+  const systemMessage = stringValue(response?.userNotice);
+  if (context || systemMessage) {
+    process.stdout.write(`${JSON.stringify({
+      ...(systemMessage ? { systemMessage } : {}),
+      ...(context ? { hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: context } } : {}),
+    })}\n`);
+  }
+  if (response !== undefined && reminderResult?.reminder) await recordReminder(reminderResult.reminder);
+} else {
+  const lastAssistantMessage = assistantMessage(input);
+  if (!lastAssistantMessage) process.exit(0);
+  const activeTurn = readActiveTurn(sessionId);
+  if (!activeTurn) process.exit(0);
+  const response = await post("/memory/writeback", {
+    version: 1,
+    client: "trae",
+    sessionId,
+    turnId: activeTurn.turnId,
+    prompt: activeTurn.prompt,
+    lastAssistantMessage,
+    cwd: activeTurn.cwd ?? stringValue(input.cwd),
+    workspaceKind: activeTurn.workspaceKind,
+  });
+  if (response?.ok === true && response?.scheduled === true) removeActiveTurn(sessionId, activeTurn.turnId);
+}
+
+function prepareActiveTurn({ sessionId, prompt, cwd, workspaceKind }) {
+  return withJsonFileLock(activeTurnsPath, () => {
+    const state = activeTurnState();
+    pruneActiveTurns(state);
+    const existing = validActiveTurn(state.sessions?.[sessionId], sessionId);
+    const now = Date.now();
+    const record = existing
+      && existing.prompt === prompt
+      && existing.cwd === cwd
+      && existing.workspaceKind === workspaceKind
+      ? { ...existing, updatedAt: now }
+      : {
+          version: 1,
+          sessionId,
+          turnId: createTraeTurnId(sessionId, now, prompt),
+          prompt,
+          ...(cwd ? { cwd } : {}),
+          ...(workspaceKind ? { workspaceKind } : {}),
+          createdAt: now,
+          updatedAt: now,
+        };
+    return { record, expectedTurnId: existing?.turnId };
+  });
+}
+
+function commitActiveTurn({ record, expectedTurnId }) {
+  return withJsonFileLock(activeTurnsPath, () => {
+    const state = activeTurnState();
+    pruneActiveTurns(state);
+    const current = validActiveTurn(state.sessions?.[record.sessionId], record.sessionId);
+    if (current?.turnId !== expectedTurnId && current?.turnId !== record.turnId) return false;
+    state.sessions[record.sessionId] = record;
+    const now = Date.now();
+    state.updatedAt = new Date(now).toISOString();
+    pruneActiveTurns(state);
+    atomicWriteJson(activeTurnsPath, state);
+    return true;
+  });
+}
+
+function readActiveTurn(sessionId) {
+  return withJsonFileLock(activeTurnsPath, () => {
+    const state = activeTurnState();
+    pruneActiveTurns(state);
+    atomicWriteJson(activeTurnsPath, state);
+    return validActiveTurn(state.sessions[sessionId], sessionId);
+  });
+}
+
+function removeActiveTurn(sessionId, turnId) {
+  withJsonFileLock(activeTurnsPath, () => {
+    const state = activeTurnState();
+    if (state.sessions?.[sessionId]?.turnId === turnId) delete state.sessions[sessionId];
+    state.updatedAt = new Date().toISOString();
+    atomicWriteJson(activeTurnsPath, state);
+  });
+}
+
+function activeTurnState() {
+  const value = readJsonFile(activeTurnsPath);
+  if (value?.unreadable) return { version: 1, runtime: "trae", sessions: {} };
+  const state = value?.value;
+  if (!isRecord(state) || state.version !== 1 || state.runtime !== "trae" || !isRecord(state.sessions)) {
+    return { version: 1, runtime: "trae", sessions: {} };
+  }
+  return state;
+}
+
+function pruneActiveTurns(state) {
+  const now = Date.now();
+  for (const [id, record] of Object.entries(state.sessions)) {
+    const valid = validActiveTurn(record, id);
+    if (!valid || now - valid.updatedAt > 24 * 60 * 60 * 1000) delete state.sessions[id];
+  }
+  const ordered = Object.entries(state.sessions)
+    .sort(([, left], [, right]) => Number(left.updatedAt ?? 0) - Number(right.updatedAt ?? 0));
+  while (ordered.length > 200) {
+    const [id] = ordered.shift();
+    delete state.sessions[id];
+  }
+}
+
+function validActiveTurn(value, sessionId) {
+  if (!isRecord(value)
+    || value.version !== 1
+    || value.sessionId !== sessionId
+    || !validTraeTurnId(sessionId, value.turnId, value.prompt)
+    || !contentValue(value.prompt)
+    || !Number.isSafeInteger(value.createdAt)
+    || !Number.isSafeInteger(value.updatedAt)) return undefined;
+  return value;
+}
+
+function createTraeTurnId(sessionId, createdAt, prompt) {
+  const digest = createHash("sha256").update(prompt.trim()).digest("hex");
+  return `${sessionId}:${createdAt}:${digest}`;
+}
+
+function validTraeTurnId(sessionId, turnId, prompt) {
+  if (typeof turnId !== "string" || !turnId.startsWith(`${sessionId}:`)) return false;
+  const match = /^([1-9]\d*):([a-f0-9]{64})$/.exec(turnId.slice(sessionId.length + 1));
+  return Boolean(match
+    && Number.isSafeInteger(Number(match[1]))
+    && match[2] === createHash("sha256").update(String(prompt).trim()).digest("hex"));
+}
+
+async function recordReminder(reminder) {
+  if (!reminder.turnId) return;
+  await post("/memory/skill-reminder", {
+    version: 1,
+    client: "trae",
+    sessionId: reminder.sessionId,
+    turnId: reminder.turnId,
+    cwd: reminder.cwd,
+    workspaceKind: reminder.workspaceKind,
+    content: reminder.content,
+    triggers: reminder.triggers,
+  }, REMINDER_TRACE_TIMEOUT_MS);
+}
+
+async function post(path, body, timeoutMs = 12_000) {
+  let connection;
+  try {
+    connection = resolveBackendConnection({ memoraxCodeHome: home });
+  } catch (error) {
+    debug(error);
+    return undefined;
+  }
+  const headers = { "content-type": "application/json", connection: "close" };
+  if (connection.token) headers["x-memorax-code-backend-token"] = connection.token;
+  try {
+    const response = await fetch(new URL(path, connection.url), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return response.ok ? await response.json().catch(() => undefined) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function assistantMessage(value) {
+  const last = contentValue(value.last_assistant_message) ?? contentValue(value.lastAssistantMessage);
+  const text = contentValue(value.text_content) ?? contentValue(value.textContent);
+  if (last && text && last !== text) {
+    debug(new Error("Trae Stop payload assistant fields do not match"));
+    return undefined;
+  }
+  return last ?? text;
+}
+
+async function readJsonStdin() {
+  try {
+    let text = "";
+    for await (const chunk of process.stdin) text += chunk;
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+async function readRecord(path) {
+  try {
+    const value = JSON.parse(await readFile(path, "utf8"));
+    return isRecord(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+function contentValue(value) {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function debug(error) {
+  if (debugEnabled) console.error(error instanceof Error ? error.message : String(error));
+}

package/lib/memorax-code-trae-adapter/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@memorax-code/trae-adapter",
+  "version": "0.1.12",
+  "private": true,
+  "type": "module",
+  "description": "Trae Hook adapter for MemoraX Code memory services.",
+  "bin": { "memorax-code-trae": "src/cli.mjs" },
+  "scripts": { "test": "node --test test/*.test.mjs" }
+}

package/lib/memorax-code-trae-adapter/skills/memorax-code/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: memorax-code
+description: >-
+  Use this skill as the single router for persistent coding and repository-local
+  memory. Invoke it whenever a request may involve prior-work knowledge,
+  repository memory, reusable procedures or rules, durable profile or
+  interaction preferences, or information worth retaining beyond the current
+  task. This applies without memory wording, including habits, preferences,
+  checklists, action sequences, prerequisites, gates, exceptions, validation
+  rules, communication style, preferred language, or result presentation.
+  Classify the request as coding memory, repository memory, personal procedure
+  memory, personal profile memory, or no persistent memory, then route it to the
+  matching operation. Invoking this router does not require coding-memory
+  search. Reuse a relevant coding-memory result already retrieved in this
+  conversation; otherwise let the matching operation decide on search. Prefer
+  this router over underlying memory workflows. Ask one focused question only when
+  memory authority remains ambiguous.
+---
+
+# MemoraX Code
+
+Classify the requested memory authority first, then its operation. Load only the matching reference unless the request genuinely spans authorities or operations.
+
+After selecting an operation reference, read it completely in a standalone
+tool call and wait for the full result before constructing or executing that
+operation. Never combine reading a required reference with the command or
+action it governs in the same shell command or tool call.
+
+## Authority Router
+
+### MemoraX Code Coding Memory
+
+Use MemoraX Code coding memory for reusable engineering knowledge learned across coding work: prior fixes, failed approaches, coding conventions, implementation pitfalls, validation patterns, and design rationale.
+
+- Read [references/memorax-search.md](references/memorax-search.md) to recall or search coding memory.
+- Read [references/memorax-add.md](references/memorax-add.md) to save a grounded reusable coding lesson.
+
+### Repo Memory
+
+Use repo memory for repository identity, architecture maps, module routing, local commit history, and GitHub or GitLab PR, MR, and issue evidence stored under `.repo_memory/PROFILE.md`, `.repo_memory/resources/`, and `.repo_memory/raw/`.
+
+- Read [references/repo-read.md](references/repo-read.md) to inspect existing repo memory.
+- Read [references/repo-build.md](references/repo-build.md) for first-time creation, full rebuilds, or full refreshes.
+- Read [references/repo-update.md](references/repo-update.md) for incremental updates to an existing bundle.
+- Read [references/repo-templates.md](references/repo-templates.md) only when the build or update operation needs to author repo memory files.
+
+### Personal Memory
+
+Use personal memory for user-owned repository procedures and durable profile or interaction preferences stored under `.repo_memory/procedure-memory/` and `.repo_memory/user-profile/`.
+
+- Read [references/personal-read.md](references/personal-read.md) to list, recall, or apply personal memory.
+- Read [references/personal-write.md](references/personal-write.md) to save, update, forget, or delete personal memory.
+
+## Tie Breakers
+
+- Route ordered actions, checklists, prerequisites, gates, exceptions, and validation rules to personal procedure memory, even when phrased as "I prefer", "I like", "我的习惯", or "我喜欢".
+- Route preferred name, answer language, tone, verbosity, explanation style, and result presentation to personal profile memory.
+- Route task-learned repairs, coding pitfalls, project engineering conventions, and reusable design lessons to MemoraX Code coding memory.
+- Route prior project discussions, experiment conclusions, saved engineering findings, earlier fixes, and reusable project lessons to MemoraX Code coding memory. Do not route them to repo memory merely because they concern a project. Use repo memory for repository identity, architecture, module maps, commits, PRs, MRs, and issues.
+- Route repository architecture, module maps, commit history, PRs, MRs, and issues to repo memory. Verify claims about current behavior against live code.
+- Use both repo memory and MemoraX Code coding memory only when a request genuinely needs distinct repository evidence and reusable engineering lessons. This can apply to implementation, debugging, refactoring, migration planning, or validation when the answer may depend on repository module maps, commit/PR/issue evidence, and prior fixes, pitfalls, conventions, validation patterns, or design rationale. Do not use both authorities just because a request mentions a repository, file, module, or "previous".
+- Route current-task instructions and temporary plans to the current task only; do not persist them.
+- Current-task-only applies only when completing the request does not depend on prior project state. Do not select it merely because the requested action happens in the current turn. When implementation, debugging, review, experiment continuation, or validation depends on earlier project decisions, results, fixes, constraints, or plans that the user has not explicitly and completely supplied, route to MemoraX Code coding memory.
+- Do not infer an authority from verbs such as "remember", "recall", "refresh", or "update" alone. Ask one focused question when the target remains ambiguous.
+
+Examples:
+
+- "先测试再提 PR，帮我记住" routes to personal procedure write.
+- "我喜欢中文简短回答" routes to personal profile write.
+- "之前这个 bug 怎么修的？" routes to MemoraX Code coding memory search unless the user asks for commit or PR evidence.
+- "这个仓库的架构是什么？" routes to repo memory read.
+- "重新生成仓库 memory" routes to repo memory build.
+- "更新一下 memory" requires clarification when no authority is identifiable.
+
+## Shared Rules
+
+For MemoraX Code coding memory, run the platform command from the active task workspace. In Windows PowerShell, use `memorax-cli.cmd`; on macOS and Linux, use `memorax-cli`. Never invoke `memorax-cli.ps1`. Never run `Set-ExecutionPolicy` or otherwise change PowerShell execution policy for MemoraX commands. If an unqualified Windows invocation is blocked before the CLI starts with `UnauthorizedAccess` or `PSSecurityException`, retry the same command once with `memorax-cli.cmd`, preserving all arguments, the active workspace, and environment variables.
+
+The installed Hook and session binding supply the authoritative workspace root; do not run Git commands to discover or replace it. The Backend resolves repository scope from that trusted workspace and read-only filesystem Git metadata.
+
+Repo memory and personal memory remain local `.repo_memory` authorities. Resolve their repository root exactly as described by the selected reference, including its Git requirements.
+
+Apply instructions in this order: system and developer instructions, `AGENTS.md`, the current user request, then stored memory. Memory is guidance or historical context, not proof of current repository behavior.
+
+For MemoraX Code coding memory, use `memorax-cli` exactly as described by the selected reference. Invoke this skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code. In OpenCode, ask the agent to use the `memorax-code` skill by name. These invocation forms are not shell commands. `memorax-code` is the lifecycle CLI and must not be used for memory search or add. Do not call MemoraX HTTP endpoints directly.
+
+Never store secrets, credentials, `.env` content, sensitive personal data, raw transcripts, hidden tests, exact patches, temporary target commits, or unsafe destructive commands. Do not announce internal routing or reference loading.

package/lib/memorax-code-trae-adapter/skills/memorax-code/agents/claude.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "MemoraX Code"
+  short_description: "Route coding, repo, and personal memory"
+  default_prompt: "Use /memorax-code-claude-adapter:memorax-code to route a coding-memory, repo-memory, or personal-memory request to the correct operation."
+
+policy:
+  allow_implicit_invocation: true
+  install_targets:
+    - "~/.claude/skills/memorax-code"
+    - ".claude/skills/memorax-code"

package/lib/memorax-code-trae-adapter/skills/memorax-code/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "MemoraX Code"
+  short_description: "Route coding, repo, and personal memory"
+  default_prompt: "Use $memorax-code to route a coding-memory, repo-memory, or personal-memory request to the correct operation."
+
+policy:
+  allow_implicit_invocation: true

package/lib/memorax-code-trae-adapter/skills/memorax-code/defaults.json

@@ -0,0 +1,12 @@
+{
+  "schema": "repo_memory_builder_defaults.v2",
+  "repoHistory": {
+    "mode": "provider",
+    "limits": {
+      "commits": 30,
+      "prs": 30,
+      "issues": 30
+    }
+  },
+  "summaryChars": 4000
+}

package/lib/memorax-code-trae-adapter/skills/memorax-code/references/memorax-add.md

@@ -0,0 +1,101 @@
+# MemoraX Code Coding Memory Add
+
+Use these instructions only to add reusable coding knowledge through `memorax-cli`. Invoke the skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code. In OpenCode, ask the agent to use the `memorax-code` skill by name. Do not route memory operations through the lifecycle-only `memorax-code` CLI. Do not use this authority for personal procedures, interaction preferences, generated repository facts, or one-off task details.
+
+## Eligible Knowledge
+
+Add a coding memory only when the task yields stable, grounded, reusable engineering knowledge, such as:
+
+- a verified repair invariant or validation pattern;
+- a reusable failed-attempt lesson;
+- a confirmed coding convention, lifecycle boundary, or implementation pitfall;
+- durable design rationale that will help future coding work.
+
+Route user-owned ordered actions, checklists, gates, and work rules to personal procedure memory. Route preferred language, tone, verbosity, name, and presentation to personal profile memory. Route commit, PR, issue, architecture-map, and repository-history facts to repo memory.
+
+Do not add positive repair lessons based only on unverified edits or assistant self-report. Verification may come from a focused test, evaluator, CI check, accepted review, manual reproduction, or deployed behavior. A failed attempt may be saved as negative evidence when the failure itself is clear and reusable.
+
+## Add Workflow
+
+Select the executable before constructing any Add command. In Windows PowerShell, use `memorax-cli.cmd`; on macOS and Linux, use `memorax-cli`. Never invoke `memorax-cli.ps1`. Never run `Set-ExecutionPolicy` or otherwise change PowerShell execution policy for MemoraX commands. If an unqualified Windows invocation is blocked before the CLI starts with `UnauthorizedAccess` or `PSSecurityException`, retry that command once with `memorax-cli.cmd`, preserving all arguments, the active workspace, and environment variables.
+
+For a proactive add, write all generated prose in `--memory`, `--reason`, and the confirmation in the language of the user's current request; preserve exact code, API, path, workflow, and project identifiers.
+
+Run from the active task workspace. Pass the memory and reason directly. Put every dynamically generated `--memory` and `--reason` value in single quotes, never double quotes. Apply the escaping rule for the active shell:
+
+- Windows PowerShell: single quotes keep `$HOME`, backticks, and `$(command)` literal. Replace each literal single quote in a value with two single quotes (`''`); for example, `don't` becomes `'don''t'`.
+- macOS and Linux: Treat `$HOME`, backticks, and `$(command)` as literal text inside the quotes. Replace each literal single quote in a value with the exact POSIX sequence `'\''`.
+
+Windows PowerShell:
+
+```powershell
+memorax-cli.cmd add --memory 'Concise reusable memory.' --type procedural --reason 'Capture reusable coding memory.'
+```
+
+macOS and Linux:
+
+```bash
+memorax-cli add \
+  --memory 'Concise reusable memory.' \
+  --type procedural \
+  --reason 'Capture reusable coding memory.'
+```
+
+Use an appropriate supported type such as `core`, `semantic`, `procedural`, `episodic`, or `unclassified`. Use `preference` only for an engineering convention owned by MemoraX Code coding memory, not for a personal interaction preference.
+
+For a complex verified repair or failed approach, use this compact card when it improves later retrieval:
+
+```text
+CODE_AGENT_MEMORY
+repo: <repository or product area>
+scope: <module/path::symbol/API or lifecycle boundary>
+status: <verified|failed_attempt|candidate>
+signal: <test, CI, review, reproduction, deployment, failure, or unknown>
+problem: <small behavioral symptom or engineering situation>
+technical_context: <stable API, lifecycle, state owner, or data-shape detail>
+surfaces: <observable producer/consumer or setup/runtime/cleanup boundaries>
+failed_shape: <reusable wrong assumption or unsafe patch shape, or none>
+validation: <small reusable check contract>
+principle: <abstract invariant or decision rule>
+anchors: <stable repository source, tests, or public docs>
+```
+
+Keep the card under 1,100 characters when practical. It must guide future investigation while still requiring live-code inspection.
+
+Pass a completed multi-line card as one single-quoted `--memory` argument. On Windows PowerShell, the command must start with `memorax-cli.cmd add`; on macOS and Linux, use the form shown below.
+
+```bash
+memorax-cli add \
+  --memory 'CODE_AGENT_MEMORY
+repo: owner/name
+scope: module/path::symbol
+status: verified
+signal: focused test passed
+problem: concise reusable symptom
+technical_context: stable implementation fact
+surfaces: affected boundary
+failed_shape: reusable pitfall or none
+validation: smallest reusable check
+principle: reusable invariant
+anchors: stable/source/path' \
+  --type procedural \
+  --reason 'Capture verified reusable coding memory.'
+```
+
+Except for the pre-start Windows shim correction above, if add fails, report the exact failure and do not retry automatically, bypass the CLI, or call MemoraX directly. Do not retry Add after the CLI may have started.
+
+If a successful Add result reports `workspaceScopeFallbackReason: git_metadata_invalid`, malformed or incomplete metadata inside a direct `.git` directory was downgraded to the normalized local folder scope. Add has already been submitted with the reported `effectiveUserId`. Present its `userNotice` once without pausing the current task or asking the user to repair Git first, then continue the current task. After the repository or `.git` metadata is repaired, later Search, Add, and automatic writeback in the same client session automatically use the restored Git repository scope.
+
+If `memorax-cli add` reports `workspace_scope_mismatch` or `workspace_scope_unavailable`, do not bypass the scope. Do not change the CLI working directory and retry. Tell the user that the memory was not submitted and no request was sent to MemoraX, then present the CLI's `userAction` in natural language. Continue the current task using only live code and documentation.
+
+## Exclusions
+
+Do not add secrets, credentials, private URLs, raw authorization headers, exact patches, target commits, hidden tests, target diffs, vulnerability details, exploit steps, copied source, long logs, stack traces, raw transcripts, temporary errors, or facts directly recoverable from current files and git history.
+
+Do not add speculation, assistant-only praise, or a current instruction merely because it contains "remember". Return to `SKILL.md` when the content belongs to personal memory or repo memory.
+
+## Output
+
+If a successful Add returns `quotaNotice`, or prints it as a quota-reminder line in the default CLI output, present the complete reminder once and prominently before the normal result summary. Do not reduce it to only a percentage or omit its account URL or anonymous-account claim details. A guest reminder may already contain the local Mark ID; present it once as part of the reminder, but do not repeat or separately quote it. Never run `memorax-code account --show-mark-id` for the user or ask for its output. Treat the reminder as user-facing operational output, not coding memory content, and continue the current task.
+
+After an add request is accepted, confirm briefly that it was submitted for processing and identify the reusable coding lesson at a high level. If add is disabled or fails, report the issue and continue without bypassing the CLI.