@remnic/plugin-codex 1.0.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "remnic",
+  "description": "Universal memory for AI agents — automatic recall, observation, and cross-agent knowledge sharing",
+  "version": "1.0.0",
+  "author": "Joshua Warren",
+  "homepage": "https://github.com/joshuaswarren/remnic",
+  "repository": "https://github.com/joshuaswarren/remnic"
+}

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "remnic": {
+      "type": "http",
+      "url": "http://localhost:4318/mcp",
+      "headers": {
+        "Authorization": "Bearer {{REMNIC_TOKEN}}",
+        "X-Engram-Client-Id": "codex"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joshua Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/materialize.cjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * @remnic/plugin-codex materialize binary.
+ *
+ * This is the packaged runtime entrypoint the session-end hook calls when a
+ * user runs Remnic inside a published install. The hook used to shell out
+ * to `scripts/codex-materialize.ts` via tsx, but that file is NOT shipped in
+ * any published package payload — only developer source checkouts have it.
+ * See PR #392 review thread PRRT_kwDORJXyws56TOVo.
+ *
+ * This wrapper:
+ *  1. Loads the published `@remnic/core` ESM bundle via dynamic import.
+ *  2. Re-parses argv in the same shape `scripts/codex-materialize.ts` uses
+ *     (`--namespace`, `--codex-home`, `--memory-dir`, `--reason`, `--json`).
+ *  3. Resolves the user's OpenClaw/Remnic config from the same search paths
+ *     the dev script uses, so behavior is identical between dev and
+ *     distributed installs.
+ *  4. Delegates to `runCodexMaterialize` and surfaces the result.
+ *
+ * Exits 0 on success (including intentional skips), non-zero only on hard
+ * failures callers actually need to notice.
+ */
+
+/* eslint-disable no-console */
+
+"use strict";
+
+const path = require("node:path");
+const fs = require("node:fs");
+
+function parseArgs(argv) {
+  const args = {
+    namespace: undefined,
+    codexHome: undefined,
+    memoryDir: undefined,
+    reason: "cli",
+    json: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--namespace":
+      case "-n":
+        args.namespace = argv[++i];
+        break;
+      case "--codex-home":
+        args.codexHome = argv[++i];
+        break;
+      case "--memory-dir":
+        args.memoryDir = argv[++i];
+        break;
+      case "--reason":
+        args.reason = argv[++i] || "cli";
+        break;
+      case "--json":
+        args.json = true;
+        break;
+      case "-h":
+      case "--help":
+        args.help = true;
+        break;
+      default:
+        // ignore unknown tokens — keeps the hook loosely coupled
+        break;
+    }
+  }
+  return args;
+}
+
+/**
+ * Return candidate config file paths to search, in priority order.
+ * The caller is responsible for parsing and entry-resolution.
+ */
+function configCandidates() {
+  const home = process.env.HOME || "";
+  const openclawConfigPath =
+    process.env.OPENCLAW_ENGRAM_CONFIG_PATH ||
+    process.env.OPENCLAW_CONFIG_PATH ||
+    path.join(home, ".openclaw", "openclaw.json");
+  return [
+    process.env.REMNIC_CONFIG,
+    openclawConfigPath,
+    path.join(home, ".config", "remnic", "config.json"),
+    path.join(home, ".config", "engram", "config.json"),
+    path.join(home, ".remnic", "config.json"),
+  ].filter((p) => typeof p === "string" && p.length > 0);
+}
+
+/**
+ * Load the Remnic plugin config block from the first matching config file.
+ *
+ * Entry resolution is delegated to `resolveRemnicPluginEntry` from
+ * `@remnic/core` so the slot → PLUGIN_ID → LEGACY_PLUGIN_ID logic lives
+ * in exactly one place across all five config-loader sites (#403).
+ *
+ * @param {Function} resolveEntry - resolveRemnicPluginEntry from @remnic/core
+ */
+function loadRawConfig(resolveEntry) {
+  for (const candidate of configCandidates()) {
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      const raw = JSON.parse(fs.readFileSync(candidate, "utf-8"));
+      if (!raw || typeof raw !== "object") continue;
+      // Try the structured OpenClaw config layout first (plugins.entries).
+      // resolveEntry returns the full plugin entry (including .config).
+      const entry = resolveEntry(raw);
+      if (entry && typeof entry === "object") {
+        return entry.config && typeof entry.config === "object"
+          ? entry.config
+          : entry;
+      }
+      // Legacy / developer config layout: the top-level object IS the config.
+      // Honour it as long as it has no `plugins` subtree (so we don't
+      // accidentally treat a complete OpenClaw config with an unknown plugin
+      // slot as a flat Remnic config).
+      if (!raw.plugins) {
+        return raw;
+      }
+      // OpenClaw config but no Remnic entry found — skip to next candidate.
+    } catch (_err) {
+      // fall through to next candidate
+    }
+  }
+  return {};
+}
+
+function printHelp() {
+  console.log(
+    [
+      "codex-materialize — render Remnic memories into ~/.codex/memories/",
+      "",
+      "Usage: node bin/materialize.cjs [options]",
+      "",
+      "Options:",
+      "  --namespace <name>    Namespace to materialize (default: config / 'default')",
+      "  --memory-dir <path>   Override memory directory",
+      "  --codex-home <path>   Override <codex_home>",
+      "  --reason <string>     Logged reason tag (cli | session_end | consolidation | manual)",
+      "  --json                Emit the result as JSON",
+      "  -h, --help            Show this help",
+    ].join("\n"),
+  );
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return 0;
+  }
+
+  // Dynamic import because @remnic/core is ESM-only.
+  const core = await import("@remnic/core");
+  const { parseConfig, runCodexMaterialize, resolveRemnicPluginEntry } = core;
+  if (
+    typeof parseConfig !== "function" ||
+    typeof runCodexMaterialize !== "function" ||
+    typeof resolveRemnicPluginEntry !== "function"
+  ) {
+    throw new Error(
+      "codex-materialize: @remnic/core is missing expected exports (parseConfig, runCodexMaterialize, resolveRemnicPluginEntry)",
+    );
+  }
+
+  // Pass the shared resolver so loadRawConfig uses the same slot → id lookup
+  // logic as all other config-loader sites (#403).
+  const rawConfig = loadRawConfig(resolveRemnicPluginEntry);
+  const config = parseConfig(rawConfig);
+  if (args.memoryDir) {
+    // parseConfig already locked in a memoryDir, but the CLI override wins.
+    config.memoryDir = args.memoryDir;
+  }
+
+  const result = await runCodexMaterialize({
+    config,
+    namespace: args.namespace,
+    memoryDir: args.memoryDir,
+    codexHome: args.codexHome,
+    reason: args.reason,
+  });
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result === null) {
+    console.log("codex-materialize: skipped (disabled or guarded)");
+  } else if (result.skippedNoSentinel) {
+    console.log(
+      `codex-materialize: sentinel missing in ${result.memoriesDir}; skipped to honor hand-edits`,
+    );
+  } else if (result.skippedIdempotent) {
+    console.log(
+      `codex-materialize: no changes for namespace=${result.namespace} (hash unchanged)`,
+    );
+  } else {
+    console.log(
+      `codex-materialize: wrote ${result.filesWritten.length} file(s) for namespace=${result.namespace}`,
+    );
+  }
+
+  return 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(
+      `codex-materialize failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+  },
+);

package/hooks/bin/post-tool-observe.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# Remnic PostToolUse hook for Codex.
+# Observes Bash tool executions by sending transcript delta to the
+# observe endpoint. Runs in background, never blocks.
+
+set -euo pipefail
+
+ensure_migrated() {
+  if [ -f "${HOME}/.remnic/.migrated-from-engram" ]; then
+    return 0
+  fi
+  if [ ! -d "${HOME}/.engram" ] && [ ! -f "${HOME}/.config/engram/config.json" ]; then
+    return 0
+  fi
+  if command -v remnic >/dev/null 2>&1; then
+    remnic migrate >/dev/null 2>&1 || true
+  elif command -v engram >/dev/null 2>&1; then
+    engram migrate >/dev/null 2>&1 || true
+  fi
+}
+
+ensure_migrated
+
+REMNIC_HOST="${REMNIC_HOST:-${ENGRAM_HOST:-127.0.0.1}}"
+REMNIC_PORT="${REMNIC_PORT:-${ENGRAM_PORT:-4318}}"
+REMNIC_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/observe"
+
+LOG="${HOME}/.remnic/logs/remnic-post-tool-observe.log"
+mkdir -p "$(dirname "$LOG")"
+log() { echo "$(date '+%F %T') [codex-post-tool] $*" >> "$LOG"; }
+
+# Read token
+REMNIC_TOKEN=""
+for TOKEN_FILE in "${HOME}/.remnic/tokens.json" "${HOME}/.engram/tokens.json"; do
+  [ ! -f "$TOKEN_FILE" ] && continue
+  REMNIC_TOKEN="$(node -e "
+    const fs = require('fs');
+    const tokenFile = process.argv[1];
+    const store = JSON.parse(fs.readFileSync(tokenFile, 'utf8'));
+    const tokens = store.tokens || [];
+    const cxc = tokens.find(t => t.connector === 'codex-cli');
+    const cx = tokens.find(t => t.connector === 'codex');
+    const oc = tokens.find(t => t.connector === 'openclaw');
+    let tok = (cxc && cxc.token) || (cx && cx.token) || (oc && oc.token) || '';
+    if (!tok) { tok = store['codex-cli'] || store['codex'] || store['openclaw'] || ''; }
+    process.stdout.write(tok);
+  " "$TOKEN_FILE" 2>/dev/null || echo "")"
+  [ -n "$REMNIC_TOKEN" ] && break
+done
+[ -z "$REMNIC_TOKEN" ] && REMNIC_TOKEN="${OPENCLAW_REMNIC_ACCESS_TOKEN:-${OPENCLAW_ENGRAM_ACCESS_TOKEN:-}}"
+
+INPUT="$(cat)"
+
+# Return immediately — never block the tool
+echo '{"continue":true}'
+
+[ -z "$REMNIC_TOKEN" ] && exit 0
+
+SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.session_id||'')" "$INPUT" 2>/dev/null || echo "")"
+TRANSCRIPT_PATH="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.transcript_path||'')" "$INPUT" 2>/dev/null || echo "")"
+CWD="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.cwd||'')" "$INPUT" 2>/dev/null || echo "")"
+TOOL_NAME="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.tool_name||'')" "$INPUT" 2>/dev/null || echo "")"
+PROJECT_NAME="$(basename "$CWD" 2>/dev/null || echo "unknown")"
+
+[ -z "$SESSION_ID" ] && exit 0
+{ [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; } && exit 0
+
+LEGACY_CURSOR_FILE="/tmp/engram-cursor-${SESSION_ID}"
+CURSOR_FILE="/tmp/remnic-cursor-${SESSION_ID}"
+LEGACY_LOCK_DIR="/tmp/engram-lock-${SESSION_ID}.d"
+LOCK_DIR="/tmp/remnic-lock-${SESSION_ID}.d"
+
+if [ ! -f "$CURSOR_FILE" ] && { [ -f "$LEGACY_CURSOR_FILE" ] || [ -d "$LEGACY_LOCK_DIR" ]; }; then
+  CURSOR_FILE="$LEGACY_CURSOR_FILE"
+  LOCK_DIR="$LEGACY_LOCK_DIR"
+fi
+
+(
+  # Acquire exclusive lock
+  ACQUIRED=0
+  for _i in $(seq 1 50); do
+    if mkdir "$LOCK_DIR" 2>/dev/null; then ACQUIRED=1; break; fi
+    sleep 0.1
+  done
+  trap 'rmdir "$LOCK_DIR" 2>/dev/null' EXIT INT TERM
+  [ "$ACQUIRED" -eq 0 ] && exit 0
+
+  LAST_COUNT=0
+  [ -f "$CURSOR_FILE" ] && LAST_COUNT="$(cat "$CURSOR_FILE" 2>/dev/null || echo 0)"
+
+  PAYLOAD="$(node -e "
+    const fs = require('fs');
+    const path = process.argv[1];
+    const sessionId = process.argv[2];
+    const lastCount = parseInt(process.argv[3], 10) || 0;
+
+    const lines = fs.readFileSync(path, 'utf8').split('\n').filter(Boolean);
+    const messages = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type !== 'user' && entry.type !== 'assistant') continue;
+        const msg = entry.message;
+        if (!msg || typeof msg !== 'object') continue;
+        const role = msg.role;
+        if (role !== 'user' && role !== 'assistant') continue;
+        let text = '';
+        if (typeof msg.content === 'string') text = msg.content.trim();
+        else if (Array.isArray(msg.content)) {
+          text = msg.content
+            .filter(b => b.type === 'text' && b.text)
+            .map(b => b.text.trim())
+            .join('\n').trim();
+        }
+        if (text) messages.push({ role, content: text });
+      } catch {}
+    }
+
+    const newMessages = messages.slice(lastCount);
+    if (!newMessages.length) {
+      process.stdout.write('CURSOR:' + messages.length);
+    } else {
+      process.stdout.write(JSON.stringify({
+        sessionKey: sessionId,
+        messages: newMessages,
+        __total__: messages.length
+      }));
+    }
+  " "$TRANSCRIPT_PATH" "$SESSION_ID" "$LAST_COUNT" 2>/dev/null)"
+
+  [ -z "$PAYLOAD" ] && { log "parse failed for $SESSION_ID"; exit 0; }
+
+  if echo "$PAYLOAD" | grep -q "^CURSOR:"; then
+    echo "${PAYLOAD#CURSOR:}" > "$CURSOR_FILE"
+    exit 0
+  fi
+
+  TOTAL="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(String(d.__total__||0))" "$PAYLOAD" 2>/dev/null || echo 0)"
+  MSG_COUNT="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(String((d.messages||[]).length))" "$PAYLOAD" 2>/dev/null || echo "?")"
+  CLEAN="$(node -e "const d=JSON.parse(process.argv[1]); delete d.__total__; process.stdout.write(JSON.stringify(d))" "$PAYLOAD" 2>/dev/null)"
+
+  [ -z "$CLEAN" ] && exit 0
+
+  log "observing $MSG_COUNT new messages (cursor $LAST_COUNT->$TOTAL) project=$PROJECT_NAME tool=$TOOL_NAME"
+
+  RAW="$(curl -s -w "\n%{http_code}" --max-time 120 \
+    -X POST "$REMNIC_URL" \
+    -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+    -H "Content-Type: application/json" \
+    -H "X-Engram-Client-Id: codex" \
+    -d "$CLEAN" 2>/dev/null)"
+  CURL_EXIT=$?
+  HTTP_STATUS="$(echo "$RAW" | tail -1)"
+
+  if [ $CURL_EXIT -eq 0 ] && [[ "$HTTP_STATUS" =~ ^2 ]]; then
+    log "observe OK for $SESSION_ID"
+    echo "$TOTAL" > "$CURSOR_FILE"
+  else
+    log "observe failed (curl=$CURL_EXIT http=$HTTP_STATUS) — cursor not advanced"
+  fi
+) >> "$LOG" 2>&1 &
+
+disown $!
+exit 0

package/hooks/bin/session-end.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# Remnic Stop hook for Codex.
+# Performs final observe flush then cleans up cursor/lock files.
+
+set -euo pipefail
+
+ensure_migrated() {
+  if [ -f "${HOME}/.remnic/.migrated-from-engram" ]; then
+    return 0
+  fi
+  if [ ! -d "${HOME}/.engram" ] && [ ! -f "${HOME}/.config/engram/config.json" ]; then
+    return 0
+  fi
+  if command -v remnic >/dev/null 2>&1; then
+    remnic migrate >/dev/null 2>&1 || true
+  elif command -v engram >/dev/null 2>&1; then
+    engram migrate >/dev/null 2>&1 || true
+  fi
+}
+
+ensure_migrated
+
+REMNIC_HOST="${REMNIC_HOST:-${ENGRAM_HOST:-127.0.0.1}}"
+REMNIC_PORT="${REMNIC_PORT:-${ENGRAM_PORT:-4318}}"
+REMNIC_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/observe"
+
+LOG="${HOME}/.remnic/logs/remnic-codex-session-end.log"
+mkdir -p "$(dirname "$LOG")"
+log() { echo "$(date '+%F %T') [codex-stop] $*" >> "$LOG"; }
+
+REMNIC_TOKEN=""
+for TOKEN_FILE in "${HOME}/.remnic/tokens.json" "${HOME}/.engram/tokens.json"; do
+  [ ! -f "$TOKEN_FILE" ] && continue
+  REMNIC_TOKEN="$(node -e "
+    const fs = require('fs');
+    const tokenFile = process.argv[1];
+    const store = JSON.parse(fs.readFileSync(tokenFile, 'utf8'));
+    const tokens = store.tokens || [];
+    const cxc = tokens.find(t => t.connector === 'codex-cli');
+    const cx = tokens.find(t => t.connector === 'codex');
+    const oc = tokens.find(t => t.connector === 'openclaw');
+    let tok = (cxc && cxc.token) || (cx && cx.token) || (oc && oc.token) || '';
+    if (!tok) { tok = store['codex-cli'] || store['codex'] || store['openclaw'] || ''; }
+    process.stdout.write(tok);
+  " "$TOKEN_FILE" 2>/dev/null || echo "")"
+  [ -n "$REMNIC_TOKEN" ] && break
+done
+[ -z "$REMNIC_TOKEN" ] && REMNIC_TOKEN="${OPENCLAW_REMNIC_ACCESS_TOKEN:-${OPENCLAW_ENGRAM_ACCESS_TOKEN:-}}"
+
+INPUT="$(cat)"
+SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.session_id||'')" "$INPUT" 2>/dev/null || echo "")"
+TRANSCRIPT_PATH="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.transcript_path||'')" "$INPUT" 2>/dev/null || echo "")"
+
+echo '{"continue":true}'
+
+# Final observe flush if we have transcript
+if [ -n "$REMNIC_TOKEN" ] && [ -n "$SESSION_ID" ] && [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+  LEGACY_CURSOR_FILE="/tmp/engram-cursor-${SESSION_ID}"
+  CURSOR_FILE="/tmp/remnic-cursor-${SESSION_ID}"
+  if [ ! -f "$CURSOR_FILE" ] && [ -f "$LEGACY_CURSOR_FILE" ]; then
+    CURSOR_FILE="$LEGACY_CURSOR_FILE"
+  fi
+  LAST_COUNT=0
+  [ -f "$CURSOR_FILE" ] && LAST_COUNT="$(cat "$CURSOR_FILE" 2>/dev/null || echo 0)"
+
+  PAYLOAD="$(node -e "
+    const fs = require('fs');
+    const lines = fs.readFileSync(process.argv[1], 'utf8').split('\n').filter(Boolean);
+    const messages = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type !== 'user' && entry.type !== 'assistant') continue;
+        const msg = entry.message;
+        if (!msg || typeof msg !== 'object') continue;
+        const role = msg.role;
+        if (role !== 'user' && role !== 'assistant') continue;
+        let text = typeof msg.content === 'string' ? msg.content.trim() :
+          Array.isArray(msg.content) ? msg.content.filter(b => b.type === 'text' && b.text).map(b => b.text.trim()).join('\n').trim() : '';
+        if (text) messages.push({ role, content: text });
+      } catch {}
+    }
+    const newMessages = messages.slice(parseInt(process.argv[3], 10) || 0);
+    if (newMessages.length) {
+      process.stdout.write(JSON.stringify({ sessionKey: process.argv[2], messages: newMessages }));
+    }
+  " "$TRANSCRIPT_PATH" "$SESSION_ID" "$LAST_COUNT" 2>/dev/null)"
+
+  if [ -n "$PAYLOAD" ]; then
+    log "final flush for $SESSION_ID"
+    curl -s --max-time 30 \
+      -X POST "$REMNIC_URL" \
+      -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+      -H "Content-Type: application/json" \
+      -H "X-Engram-Client-Id: codex" \
+      -d "$PAYLOAD" >/dev/null 2>&1 || log "final flush failed"
+  fi
+fi
+
+# Cleanup
+rm -f "/tmp/remnic-cursor-${SESSION_ID}" 2>/dev/null
+rmdir "/tmp/remnic-lock-${SESSION_ID}.d" 2>/dev/null
+rm -f "/tmp/engram-cursor-${SESSION_ID}" 2>/dev/null
+rmdir "/tmp/engram-lock-${SESSION_ID}.d" 2>/dev/null
+
+# Codex-native memory materialization (#378). The script honors the
+# `codexMaterializeMemories` config flag and the `.remnic-managed` sentinel,
+# so it's safe to run unconditionally here.
+#
+# Entrypoint-resolution order (first hit wins):
+#   1. $REMNIC_CODEX_MATERIALIZE_BIN — explicit override from the environment.
+#      Set this to point at a custom Node wrapper if you need to short-circuit
+#      the search order.
+#   2. The packaged CJS wrapper shipped with @remnic/plugin-codex at
+#      `packages/plugin-codex/bin/materialize.cjs`, resolved relative to this
+#      hook's own filesystem location. This is the preferred path for
+#      published installs — the wrapper imports `@remnic/core` directly and
+#      has zero dependency on the source tree. We resolve the path via
+#      `BASH_SOURCE[0]` + `cd -P` so symlinked checkouts (pnpm hoisted
+#      installs, worktree copies) land on the real file.
+#   3. Dev fallback: `scripts/codex-materialize.ts` at the repo root. Only
+#      present in source checkouts — we use it when the packaged bin isn't
+#      available, so local developers keep working without having to run a
+#      build first. See PR #392 review thread PRRT_kwDORJXyws56TOVo for why
+#      we can't rely on this in distributed installs.
+#   4. If neither yielded a usable path, we log the miss and exit the block
+#      without running the materializer. A verbose log line is strictly
+#      better than a mysterious no-op when `codexMaterializeMemories=true`.
+if [ "${REMNIC_CODEX_MATERIALIZE:-1}" != "0" ]; then
+  HOOK_DIR="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)" || HOOK_DIR=""
+
+  MATERIALIZE_BIN="${REMNIC_CODEX_MATERIALIZE_BIN:-}"
+  if [ -z "$MATERIALIZE_BIN" ] && [ -n "$HOOK_DIR" ]; then
+    # hooks/bin/session-end.sh → ../../bin/materialize.cjs lands at
+    # packages/plugin-codex/bin/materialize.cjs.
+    CANDIDATE_BIN="${HOOK_DIR}/../../bin/materialize.cjs"
+    if [ -f "$CANDIDATE_BIN" ]; then
+      MATERIALIZE_BIN="$(cd -P "$(dirname "$CANDIDATE_BIN")" 2>/dev/null && pwd)/$(basename "$CANDIDATE_BIN")" || MATERIALIZE_BIN=""
+    fi
+  fi
+
+  REMNIC_REPO_ROOT="${REMNIC_REPO_ROOT:-}"
+  if [ -z "$REMNIC_REPO_ROOT" ] && [ -n "$HOOK_DIR" ]; then
+    CANDIDATE_ROOT="$(cd -P "${HOOK_DIR}/../../../.." 2>/dev/null && pwd)" || CANDIDATE_ROOT=""
+    if [ -n "$CANDIDATE_ROOT" ] && [ -f "${CANDIDATE_ROOT}/scripts/codex-materialize.ts" ]; then
+      REMNIC_REPO_ROOT="$CANDIDATE_ROOT"
+    fi
+  fi
+
+  if [ -n "$MATERIALIZE_BIN" ] && [ -f "$MATERIALIZE_BIN" ]; then
+    node "$MATERIALIZE_BIN" --reason session_end >> "$LOG" 2>&1 || \
+      log "codex-materialize session_end failed (packaged bin=${MATERIALIZE_BIN})"
+  elif [ -n "$REMNIC_REPO_ROOT" ] && [ -f "${REMNIC_REPO_ROOT}/scripts/codex-materialize.ts" ]; then
+    (
+      cd "$REMNIC_REPO_ROOT"
+      npx --yes tsx scripts/codex-materialize.ts --reason session_end >> "$LOG" 2>&1 || \
+        log "codex-materialize session_end failed (dev script)"
+    )
+  else
+    log "codex-materialize skipped — could not resolve packaged bin or REMNIC_REPO_ROOT (hook_dir=${HOOK_DIR:-unset})"
+  fi
+fi
+
+exit 0