@memorax/memorax-code 0.1.0

package/lib/memorax-code-codex-adapter/hooks/repo-memory-job.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveHookCodexCommand } from "../../memorax-code-adapter-common/src/clients/codex-command.mjs";
+import { runRepoMemoryJob } from "../../memorax-code-adapter-common/src/repo-memory/repo-memory-job-supervisor.mjs";
+import { evaluateRepository } from "../../memorax-code-adapter-common/src/repo-memory/repo-memory-update-policy-evaluator.mjs";
+
+const hookDir = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = dirname(hookDir);
+
+try {
+  const payload = runRepoMemoryJob(process.argv.slice(2), {
+    runner: "codex",
+    finalMessageSource: "file",
+    validatorPath: resolve(pluginRoot, "skills/memorax-code/scripts/validate_memory.py"),
+    evaluateRepository,
+    createCommand({ finalMessagePath, prompt, repo }) {
+      const codex = resolveHookCodexCommand({
+        pluginRoot: process.env.PLUGIN_ROOT || pluginRoot,
+      });
+      return [
+        codex,
+        "exec",
+        "--cd",
+        repo,
+        "--sandbox",
+        "danger-full-access",
+        "--output-last-message",
+        finalMessagePath,
+        prompt,
+      ];
+    },
+  });
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+}

package/lib/memorax-code-codex-adapter/hooks/repo-memory-update-policy.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runRepoMemoryUpdatePolicy } from "../../memorax-code-adapter-common/src/repo-memory/repo-memory-update-policy-evaluator.mjs";
+
+try {
+  const payload = runRepoMemoryUpdatePolicy(process.argv.slice(2));
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+}

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

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCodexHookComponent } from "./hook-launcher.mjs";
+
+await runCodexHookComponent(process.argv[2]);

package/lib/memorax-code-codex-adapter/hooks/runtime-shell.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "shellVersion": "0.1.0",
+  "runtimeAbi": 1
+}

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

@@ -0,0 +1,13 @@
+{
+  "name": "@memorax-code/codex-adapter",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Codex Hook and memory integration for MemoraX Code.",
+  "bin": {
+    "memorax-code-codex": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/lib/memorax-code-codex-adapter/runtime-hooks/capture-cwd.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { runCaptureCwdHook } from "../../memorax-code-adapter-common/src/hooks/capture-cwd-hook.mjs";
+import { markSupplementalReminderAfterCompact } from "../../memorax-code-adapter-common/src/hooks/memory-skill-reminder-hook.mjs";
+import { isRepoMemoryJobWorker } from "../../memorax-code-adapter-common/src/repo-memory/repo-memory-job-context.mjs";
+
+if (isRepoMemoryJobWorker()) process.exit(0);
+
+const options = {
+  adapterDir: "codex",
+  debugEnv: "MEMORAX_CODE_CODEX_HOOK_DEBUG",
+  requireTranscriptPathForTurnEvents: true,
+  runtime: "codex",
+  sessionIdField: "codexSessionId",
+  sessionKeyPrefix: "codex",
+};
+
+const input = await runCaptureCwdHook(options);
+markSupplementalReminderAfterCompact(options, input);

package/lib/memorax-code-codex-adapter/runtime-hooks/ensure-backend.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  runEnsureBackendHook,
+  stringValue,
+} from "../../memorax-code-adapter-common/src/hooks/ensure-backend-runner.mjs";
+
+const DEBUG = process.env.MEMORAX_CODE_CODEX_HOOK_DEBUG === "1";
+
+try {
+  await runEnsureBackendHook({
+    ensureBackendValue: process.env.MEMORAX_CODE_CODEX_ENSURE_BACKEND
+      ?? process.env.MEMORAX_CODE_CODEX_HOOK_ENSURE_BACKEND,
+    healthTimeoutValue: process.env.MEMORAX_CODE_CODEX_ENSURE_TIMEOUT_MS,
+    startTimeoutValue: process.env.MEMORAX_CODE_CODEX_START_TIMEOUT_MS,
+    memoraxCodeCommand: stringValue(process.env.MEMORAX_CODE_CODEX_LIFECYCLE_COMMAND)
+      ?? stringValue(process.env.MEMORAX_CODE_COMMAND),
+    pluginRoot: pluginRoot(),
+    resolveHomes: hookHomes,
+    buildStartArgs: startArgs,
+    onHealthy: async ({ homes, backendUrl }) => {
+      const reconciled = await reconcileAdapter(homes, backendUrl);
+      if (!reconciled.ok) {
+        debug(`Codex Hook adapter reconcile failed: ${reconciled.error ?? reconciled.reason ?? "unknown error"}`);
+      }
+    },
+    debug,
+  });
+} catch (error) {
+  debug(error instanceof Error ? error.message : String(error));
+}
+process.exit(0);
+
+async function reconcileAdapter(homes, backendUrl) {
+  try {
+    const config = await import(new URL("../src/config.mjs", import.meta.url).href);
+    const status = config.readCodexAdapterStatus({
+      codexHome: homes.codexHome,
+      memoraxCodeHome: homes.memoraxCodeHome,
+      backendUrl,
+      codexPluginSkillsRoot: join(pluginRoot(), "skills"),
+    });
+    if (status.enabled === true && status.codexSkills?.ok === true) return { ok: true, skipped: true };
+    const result = config.enableCodexAdapter({
+      codexHome: homes.codexHome,
+      memoraxCodeHome: homes.memoraxCodeHome,
+      backendUrl,
+      codexPluginSkillsRoot: join(pluginRoot(), "skills"),
+    });
+    return result?.ok === false ? result : { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function pluginRoot() {
+  return stringValue(process.env.PLUGIN_ROOT) ?? dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function hookHomes(input = {}) {
+  const memoraxCodeHome = stringValue(process.env.MEMORAX_CODE_HOME) ?? join(homedir(), ".memorax-code");
+  const codexHome = stringValue(process.env.CODEX_HOME)
+    ?? stringValue(input.codex_home)
+    ?? stringValue(input.codexHome)
+    ?? join(homedir(), ".codex");
+  return { memoraxCodeHome, codexHome };
+}
+
+function startArgs(homes, recoveryArguments) {
+  return [
+    "start",
+    "--home", homes.memoraxCodeHome,
+    "--codex-home", homes.codexHome,
+    ...recoveryArguments,
+  ];
+}
+
+function debug(message) {
+  if (DEBUG) console.error(message);
+}

package/lib/memorax-code-codex-adapter/runtime-hooks/memory-skill-reminder.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import {
+  PERSONAL_MEMORY_REMINDER_CONTEXT,
+  runMemorySkillReminderHook,
+} from "../../memorax-code-adapter-common/src/hooks/memory-skill-reminder-hook.mjs";
+import { resolveBackendConnection } from "../../memorax-code-adapter-common/src/backend-connection.mjs";
+import { readStdinJson, stringOption } from "../../memorax-code-adapter-common/src/config-utils.mjs";
+import { isRepoMemoryJobWorker } from "../../memorax-code-adapter-common/src/repo-memory/repo-memory-job-context.mjs";
+import { buildRepoProcedureMemoryContext } from "../../memorax-code-adapter-common/src/repo-memory/repo-procedure-memory-context.mjs";
+import { buildRepoUserProfilePreferencesContext } from "../../memorax-code-adapter-common/src/repo-memory/repo-user-profile-context.mjs";
+import { resolveCodexWorkspaceKind } from "../src/workspace-kind.mjs";
+
+if (isRepoMemoryJobWorker()) process.exit(0);
+
+const personalMemoryContextOptions = {
+  adapterDir: "codex",
+  debugEnv: "MEMORAX_CODE_CODEX_HOOK_DEBUG",
+  sessionKeyPrefix: "codex",
+};
+const RETRIEVAL_BACKEND_TIMEOUT_MS = 12_000;
+const DEFAULT_BACKEND_TIMEOUT_MS = 5_000;
+
+try {
+  const input = await readStdinJson();
+  const turnStart = turnStartBody(input);
+  if (turnStart) {
+    const turnStartResult = await recordTurnStart(turnStart);
+    const normalizedInput = turnStart.workspaceKind
+      ? { ...input, workspaceKind: turnStart.workspaceKind }
+      : input;
+    await runMemorySkillReminderHook({
+      additionalReminderContext: PERSONAL_MEMORY_REMINDER_CONTEXT,
+      adapterDir: "codex",
+      baseAdditionalContext: turnStartResult.additionalContext,
+      buildCadenceReminderContext: (hookInput) => buildRepoProcedureMemoryContext(hookInput, personalMemoryContextOptions),
+      buildPersonalMemoryContext: (hookInput) => buildRepoUserProfilePreferencesContext(hookInput, personalMemoryContextOptions),
+      debugEnv: "MEMORAX_CODE_CODEX_HOOK_DEBUG",
+      onReminder: turnStartResult.recorded ? recordReminder : undefined,
+      remindOnFirstTurn: true,
+      requireTranscriptPath: true,
+      runtime: "codex",
+      supplementalReminderAfterCompact: true,
+    }, normalizedInput);
+  }
+} catch (error) {
+  debugHookError(error);
+}
+
+function turnStartBody(input) {
+  const sessionId = stringOption(input.session_id) ?? stringOption(input.sessionId);
+  const prompt = stringOption(input.prompt) ?? stringOption(input.user_prompt) ?? stringOption(input.userPrompt);
+  const transcriptPath = stringOption(input.transcript_path) ?? stringOption(input.transcriptPath);
+  if (!sessionId || !prompt || !transcriptPath) return undefined;
+  return {
+    version: 1,
+    client: "codex",
+    sessionId,
+    turnId: stringOption(input.turn_id) ?? stringOption(input.turnId),
+    prompt,
+    cwd: stringOption(input.cwd),
+    workspaceKind: resolveCodexWorkspaceKind(input),
+    transcriptPath,
+  };
+}
+
+async function recordTurnStart(body) {
+  try {
+    const response = await postBackend("/memory/turn-start", body);
+    return {
+      recorded: true,
+      additionalContext: stringValue(response?.additionalContext),
+    };
+  } catch (error) {
+    debugHookError(error);
+    return { recorded: false };
+  }
+}
+
+async function recordReminder(reminder) {
+  if (!reminder.turnId || !reminder.transcriptPath) return;
+  await postBackend("/memory/skill-reminder", {
+    version: 1,
+    client: "codex",
+    sessionId: reminder.sessionId,
+    turnId: reminder.turnId,
+    transcriptPath: reminder.transcriptPath,
+    cwd: reminder.cwd,
+    workspaceKind: reminder.workspaceKind,
+    content: reminder.content,
+    triggers: reminder.triggers,
+  });
+}
+
+async function postBackend(path, body) {
+  const connection = resolveBackendConnection();
+  const timeoutMs = parsePositiveInt(
+    process.env.MEMORAX_CODE_CODEX_MEMORY_HOOK_TIMEOUT_MS,
+    path === "/memory/turn-start" ? RETRIEVAL_BACKEND_TIMEOUT_MS : DEFAULT_BACKEND_TIMEOUT_MS,
+  );
+  const headers = { "content-type": "application/json", connection: "close" };
+  if (connection.token) headers["x-memorax-code-backend-token"] = connection.token;
+  const response = await fetch(new URL(path, connection.url), {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) throw new Error(`Backend ${path} returned HTTP ${response.status}`);
+  return await response.json().catch(() => undefined);
+}
+
+function debugHookError(error) {
+  if (process.env.MEMORAX_CODE_CODEX_HOOK_DEBUG === "1") {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+}
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/lib/memorax-code-codex-adapter/runtime-hooks/memory-writeback.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { resolveBackendConnection } from "../../memorax-code-adapter-common/src/backend-connection.mjs";
+import { readStdinJson } from "../../memorax-code-adapter-common/src/config-utils.mjs";
+import { isRepoMemoryJobWorker } from "../../memorax-code-adapter-common/src/repo-memory/repo-memory-job-context.mjs";
+import { resolveCodexWorkspaceKind } from "../src/workspace-kind.mjs";
+
+if (isRepoMemoryJobWorker()) process.exit(0);
+
+try {
+  const input = await readStdinJson();
+  const sessionId = stringValue(input.session_id) ?? stringValue(input.sessionId);
+  const lastAssistantMessage = stringValue(input.last_assistant_message) ?? stringValue(input.lastAssistantMessage);
+  const transcriptPath = stringValue(input.transcript_path) ?? stringValue(input.transcriptPath);
+  if (!sessionId || !lastAssistantMessage) process.exit(0);
+
+  await postBackend("/memory/writeback", {
+    version: 1,
+    client: "codex",
+    sessionId,
+    turnId: stringValue(input.turn_id) ?? stringValue(input.turnId),
+    lastAssistantMessage,
+    cwd: stringValue(input.cwd),
+    workspaceKind: resolveCodexWorkspaceKind(input),
+    transcriptPath,
+  });
+} catch {
+  // Hooks must not block Codex turns when the local Backend is unavailable.
+}
+
+process.exit(0);
+
+async function postBackend(path, body) {
+  const connection = resolveBackendConnection();
+  const timeoutMs = parsePositiveInt(process.env.MEMORAX_CODE_CODEX_MEMORY_HOOK_TIMEOUT_MS, 5000);
+  const headers = { "content-type": "application/json", connection: "close" };
+  if (connection.token) headers["x-memorax-code-backend-token"] = connection.token;
+  await fetch(new URL(path, connection.url), {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+}
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

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

@@ -0,0 +1,83 @@
+---
+name: memorax-code
+description: >-
+  Use this skill as the single entry point for persistent coding and
+  repository-local memory work, regardless of type, wording, or operation. Use
+  it whenever a request may involve information that should persist beyond the
+  current task,
+  knowledge remembered from prior work, repository memory,
+  reusable procedures or working rules, or durable user profile and interaction
+  preferences. This applies even when the user does not call it memory,
+  including naturally stated habits, preferences,
+  checklists, action sequences, prerequisites, gates, exceptions, validation
+  rules, communication style, preferred language, or result presentation.
+  Determine whether the request belongs to MemoraX Code coding memory,
+  repository memory, personal procedure memory, personal profile
+  memory, or no persistent memory, then route it to the appropriate operation.
+  Prefer this router over any underlying memory workflow. Ask one focused
+  question only when the memory authority remains ambiguous after routing.
+---
+
+# MemoraX Code
+
+Classify the requested memory authority first, then its operation. Load only the matching reference unless the request genuinely spans authorities or operations.
+
+## 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 repository architecture, module maps, commit history, PRs, MRs, and issues to repo memory. Verify claims about current behavior against live code.
+- Route current-task instructions and temporary plans to the current task only; do not persist them.
+- 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 `memorax-cli` from the active task workspace. 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; neither invocation is a shell command. `memorax-code` is the lifecycle CLI and must not be used for memory search or add. Do not call MemoraX HTTP endpoints directly.
+
+When explaining Memory Viewer, describe only `/memory-viewer`. It is a
+content-free local summary and must not expose conversation or memory text,
+session or turn identifiers, paths, or trace details. The page never queries
+MemoraX directly; client Hooks are the trace ingress authority.
+
+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-codex-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-codex-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-codex-adapter/skills/memorax-code/defaults.json

@@ -0,0 +1,9 @@
+{
+  "schema": "repo_memory_builder_defaults.v1",
+  "limits": {
+    "commits": 30,
+    "prs": 30,
+    "issues": 30
+  },
+  "summaryChars": 4000
+}

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

@@ -0,0 +1,82 @@
+# 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; 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
+
+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. Treat `$HOME`, backticks, and `$(command)` as literal text inside those quotes. Replace each literal single quote in a value with the exact POSIX sequence `'\''`.
+
+```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:
+
+```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.'
+```
+
+If add fails, report the exact failure and do not retry automatically, bypass the CLI, or call MemoraX directly.
+
+## 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
+
+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.

package/lib/memorax-code-codex-adapter/skills/memorax-code/references/memorax-search.md

@@ -0,0 +1,61 @@
+# MemoraX Code Coding Memory Search
+
+Use these instructions only to search reusable coding memory through `memorax-cli`. Invoke the skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code; do not route memory operations through the lifecycle-only `memorax-code` CLI. Do not call MemoraX HTTP endpoints directly, print credentials, or edit memory storage by hand.
+
+## Scope
+
+Run the CLI from the active task workspace. The installed Hook and session binding supply the authoritative workspace root; do not run `git rev-parse`, infer the root from Git metadata, or substitute an unrelated working directory. Do not make `memorax-cli status` a mandatory preflight; use it only to diagnose a configuration or scope failure.
+
+Coding memory uses `<MemoraX base user ID>@<normalized repository name>` for Git workspaces and the normalized folder name for genuine non-Git directories. MemoraX Code resolves `.git`, `gitdir`, and `commondir` without executing Git. Linked worktrees share one repository scope; another clone, repository, or non-Git directory retains a different local session key even when its readable name matches.
+
+Require a readable active workspace binding. A CLI command from a linked worktree of the bound repository is valid. If the CLI reports `workspace_scope_mismatch`, ask the user to start a task in the target repository or local workspace. Do not retry from an unrelated scope or fall back to an unscoped user id.
+
+If `memorax-cli` is not on `PATH`, or memory is disabled, unconfigured, or unavailable, report that briefly and continue with live code or documentation. Authenticate through MemoraX Code configuration; never recover credentials from shell history or place tokens in prompts. Treat injected memory as a hypothesis and verify it against the current checkout.
+
+## Search Decision
+
+Search when prior coding memory may change localization, implementation, review, validation, or explanation. Typical triggers include:
+
+- a request for a previous fix, failed approach, coding convention, design decision, or reusable lesson;
+- implementation, review, planning, API, schema, parser, workflow-contract, or migration work where prior project guidance may matter;
+- explicit instructions to follow previous agreements or remembered engineering conventions.
+
+Skip search for simple current-code facts, tiny edits, typo fixes, one-shot commands, or behavior directly established by a clear live source.
+
+Choose the closest coding scene to shape the query:
+
+- **Development:** implementation, debugging, refactoring, test repair, build failures, feature work, API design, or migration planning.
+- **Review:** diff, commit, PR, patch, audit, risk assessment, or review-comment handling.
+- **Understanding:** implementation location, module explanation, architecture rationale, or repository comprehension when repo memory is not the requested authority.
+
+If the user asks for commit, PR, MR, issue, or repository architecture evidence, return to `SKILL.md` and route to repo memory instead.
+
+## Query Workflow
+
+Run at most one focused search before answering or editing. A development task may run one additional materially different search only after a failed test or dead-end investigation.
+
+Write each query as one short natural-language question or intent statement, not a keyword list. Derive it from the user's retrieval goal instead of copying or concatenating nouns from the prompt. Follow the user's language for the prose while preserving exact code, API, path, workflow, and project identifiers. State what prior knowledge is needed and the relationship, decision, constraint, behavior, or risk being investigated. Include 2-5 stable exact identifiers when they are relevant and known, but integrate them grammatically instead of appending search tags or filler.
+
+Pass the query directly with `--query`. Put every dynamically generated query in single quotes, never double quotes. Treat `$HOME`, backticks, and `$(command)` as literal text inside those quotes. Replace each literal single quote in the value with the exact POSIX sequence `'\''`.
+
+For example:
+
+```bash
+memorax-cli search --query 'What prior decisions define the memorax-code parser API failure boundary for malformed input?'
+memorax-cli search --query 'What prior review policies and regression risks apply to the memorax-code parser API cleanup boundary?'
+memorax-cli search --query 'memorax-code 中 Backend、Codex adapter 与 memory 层的职责如何衔接，之前为什么这样划分？'
+```
+
+Keep queries under 25 words when practical for the language, but do not shorten them into ungrammatical fragments. Exclude secrets, private URLs, full prompts, raw transcripts, copied files, long logs, stack traces, and one-off task details.
+
+Read or summarize at most two relevant items. Prefer memories matching the current repository, module, API, lifecycle surface, ownership boundary, behavior, and failure mode. Treat verified memories as routing and validation hints, not patch recipes. Treat failed-attempt memories as negative evidence. Ignore stale or unrelated items and anything conflicting with current source, tests, or durable documentation.
+
+## Transport Failures
+
+If search fails with `fetch failed`, `This operation was aborted`, a timeout, DNS failure, `ENOTFOUND`, `EAI_AGAIN`, or a similar transport or sandbox error, retry the same `memorax-cli search` once in an approved network-enabled execution mode when one is available. Preserve the same query, workspace, and environment variables.
+
+Do not apply this retry to `memorax-cli add`, authentication or configuration failures, or HTTP errors. If no approved mode is available or the one retry fails, report the exact CLI failure and continue with live evidence. Do not interpret a transport failure as an empty result, bypass the CLI, or call MemoraX directly.
+
+## Output
+
+Mention only an invariant, pitfall, convention, or validation idea that materially affects the answer. Ground claims about current implementation behavior in live code and checks.