open-memex 0.2.0-alpha → 0.3.0-alpha

package/src/index.ts

@@ -63,19 +63,26 @@ const plugin: Plugin = async ({ worktree, directory }) => {
 
       const hits = detectKeywords(text, cfg);
       for (const h of hits) {
-        const { content, hadSecret } = redact(h.content, cfg.redactPatterns);
-        if (hadSecret || content.length === 0) continue;
+        const { content, hadSecret, matchedPattern } = redact(h.content, cfg.redactPatterns);
+        // Secrets are masked (first 4 chars kept) and the capture proceeds;
+        // skip only when nothing usable remains.
+        if (content.length === 0) continue;
+        if (hadSecret && cfg.logLevel === "debug") {
+          console.log(`[open-memex] keyword capture masked secret (${matchedPattern})`);
+        }
+        // Personal patterns ("remember for me" / "记住（个人）") force the personal scope.
+        const target = h.personal ? PERSONAL_SCOPE : scope;
         // Dedup (§3.4): skip exact duplicates captured before.
-        if (findDuplicates(scope.key, content).exact) continue;
+        if (findDuplicates(target.key, content).exact) continue;
         const now = Date.now();
         const rfc = msToRfc3339(now);
         const fm: Frontmatter = {
           id: ulid(),
           schema_version: 2,
-          scope_key: scope.key,
-          scope: scope.kind === "project" ? "project" : "personal",
-          visibility: scope.kind === "project" ? "internal" : "private",
-          project_name: scope.projectName,
+          scope_key: target.key,
+          scope: target.kind === "project" ? "project" : "personal",
+          visibility: target.kind === "project" ? "internal" : "private",
+          project_name: target.projectName,
           type: "fact",
           role: "knowledge",
           importance: "normal",
@@ -91,9 +98,11 @@ const plugin: Plugin = async ({ worktree, directory }) => {
           const { filePath } = writeMemoryFile(fm, content);
           const mf = readMemoryFile(filePath);
           if (mf) upsertFromFile(mf);
-          if (cfg.logLevel === "debug") {
-            console.log(`[open-memex] captured keyword memory ${fm.id}`);
-          }
+          // Capture feedback: always visible (not debug-only) — the user said
+          // "记住…", they should see that it landed. The opencode plugin API
+          // offers no toast channel, so the plugin log is the feedback surface.
+          const preview = content.length > 60 ? content.slice(0, 60) + "…" : content;
+          console.log(`[open-memex] remembered → ${target.kind} scope: "${preview}"`);
         } catch (err) {
           console.error("[open-memex] keyword capture failed:", err);
         }

package/src/init.ts

@@ -0,0 +1,304 @@
+// `open-memex init` — one-command project setup (§17 adoption path).
+// Pure file operation: no DB, no network. Safe to run in any directory.
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_CONFIG, saveConfig } from "./config.ts";
+
+const MARKER = "<!-- open-memex -->";
+
+/** npm dist-tag carrying the 0.3.x preview line. */
+const ALPHA_TAG = "open-memex@alpha";
+
+export interface McpCommand {
+  command: string;
+  args: string[];
+  /** false when no durable bin exists (e.g. one-shot npx) and we fell back to npx. */
+  durable: boolean;
+}
+
+/**
+ * Resolve the MCP server command to write into client configs.
+ *
+ * A one-shot `npx open-memex@alpha init` runs from npm's ephemeral `_npx` cache,
+ * so `open-memex` resolving on PATH *inside that process* does not mean it will be
+ * there tomorrow. Only a bin found on PATH outside `_npx` cache dirs counts as
+ * durable; otherwise fall back to an npx-based command (slower startup, zero install).
+ */
+export function resolveMcpCommand(): McpCommand {
+  const pathEnv = process.env.PATH ?? "";
+  const dirs = pathEnv.split(path.delimiter).filter((d) => d && !d.includes("_npx"));
+  const names = process.platform === "win32" ? ["open-memex.cmd", "open-memex"] : ["open-memex"];
+  const durable = dirs.some((d) =>
+    names.some((n) => {
+      try {
+        return fs.existsSync(path.join(d, n));
+      } catch {
+        return false;
+      }
+    }),
+  );
+  if (durable) return { command: "open-memex", args: ["mcp"], durable: true };
+  return { command: "npx", args: ["-y", ALPHA_TAG, "mcp"], durable: false };
+}
+
+const INSTRUCTIONS = `${MARKER}
+# OpenMemex memory
+
+You have a local memory MCP server (\`open-memex\`) with five tools:
+\`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`, \`memory_forget\`.
+
+- BE PROACTIVE. When the user shares something worth remembering across sessions
+  (a decision, a preference, a project convention, a fix and its cause), call
+  \`memory_add\` without being asked. Keep each memory to one self-contained statement.
+- Before asking the user about past decisions, conventions, or preferences they may
+  have told you before, call \`memory_search\` first — try a few keyword variants
+  (including the user's own language) when the first search comes up empty.
+- Memories default to this project's scope; use the \`personal\` scope for facts about
+  the user that hold across all projects. When a saved fact becomes outdated, call
+  \`memory_supersede\` instead of adding a duplicate.
+`;
+
+/** Project root: git top-level, falling back to cwd. */
+function projectRoot(): string {
+  try {
+    const top = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (top) return top;
+  } catch {
+    /* not a git repo — use cwd */
+  }
+  return process.cwd();
+}
+
+function writeMcpJson(root: string, client: string, force: boolean): string | null {
+  if (client === "opencode") return writeOpencodeMcpJson(root, force);
+  if (client === "visualstudio") return writeVisualStudioMcpJson(root, force);
+  const dir = client === "cursor" ? path.join(root, ".cursor") : path.join(root, ".vscode");
+  const file = path.join(dir, "mcp.json");
+  const sectionKey = client === "cursor" ? "mcpServers" : "servers";
+
+  let doc: Record<string, unknown> = {};
+  if (fs.existsSync(file)) {
+    try {
+      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    } catch {
+      console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      return null;
+    }
+  }
+
+  const section = ((doc[sectionKey] ??= {}) as Record<string, unknown>);
+  if (section["open-memex"] && !force) {
+    console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
+    return file;
+  }
+  // D17: resolve the server command at init time — a one-shot npx leaves no bin behind.
+  const mc = resolveMcpCommand();
+  section["open-memex"] =
+    client === "cursor"
+      ? { command: mc.command, args: mc.args }
+      : {
+          type: "stdio",
+          command: mc.command,
+          args: mc.args,
+          cwd: "${workspaceFolder}",
+        };
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`  + ${file}`);
+  if (!mc.durable) {
+    console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
+    console.log(`    For faster startup: \`npm i -g ${ALPHA_TAG}\`, then re-run \`open-memex init --force\`.`);
+  }
+  return file;
+}
+
+/** opencode MCP config: project-level opencode.jsonc, `type: "local"` + command array (v1 format). */
+function writeOpencodeMcpJson(root: string, force: boolean): string | null {
+  const file = path.join(root, "opencode.jsonc");
+  let doc: Record<string, unknown> = {};
+  if (fs.existsSync(file)) {
+    try {
+      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    } catch {
+      console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      return null;
+    }
+  }
+  const section = ((doc["mcp"] ??= {}) as Record<string, unknown>);
+  if (section["open-memex"] && !force) {
+    console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
+    return file;
+  }
+  // D17: resolve the server command at init time — a one-shot npx leaves no bin behind.
+  const mc = resolveMcpCommand();
+  section["open-memex"] = {
+    type: "local",
+    command: [mc.command, ...mc.args],
+    enabled: true,
+  };
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`  + ${file}`);
+  if (!mc.durable) {
+    console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
+    console.log(`    For faster startup: \`npm i -g ${ALPHA_TAG}\`, then re-run \`open-memex init --force\`.`);
+  }
+  return file;
+}
+
+/** Visual Studio (Windows-only, 2022 17.14+ / 2026): solution-level `.mcp.json`
+ * with the `"servers"` section, per Microsoft Learn. Source-controllable.
+ * (VS also auto-discovers `.vscode/mcp.json` and `.cursor/mcp.json`.) */
+function writeVisualStudioMcpJson(root: string, force: boolean): string | null {
+  const file = path.join(root, ".mcp.json");
+  let doc: Record<string, unknown> = {};
+  if (fs.existsSync(file)) {
+    try {
+      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    } catch {
+      console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      return null;
+    }
+  }
+  const section = ((doc["servers"] ??= {}) as Record<string, unknown>);
+  if (section["open-memex"] && !force) {
+    console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
+    return file;
+  }
+  // D17: resolve the server command at init time — a one-shot npx leaves no bin behind.
+  const mc = resolveMcpCommand();
+  section["open-memex"] = {
+    type: "stdio",
+    command: mc.command,
+    args: mc.args,
+  };
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`  + ${file}`);
+  if (!mc.durable) {
+    console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
+    console.log(`    For faster startup: \`npm i -g ${ALPHA_TAG}\`, then re-run \`open-memex init --force\`.`);
+  }
+  return file;
+}
+
+function writeInstructions(root: string): string {
+  const dir = path.join(root, ".github");
+  const file = path.join(dir, "copilot-instructions.md");
+  if (fs.existsSync(file)) {
+    const cur = fs.readFileSync(file, "utf8");
+    if (cur.includes(MARKER)) {
+      console.log(`  = ${file} already has open-memex instructions — left as is`);
+      return file;
+    }
+    fs.writeFileSync(file, cur.replace(/\s+$/, "") + "\n\n" + INSTRUCTIONS);
+  } else {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, INSTRUCTIONS);
+  }
+  console.log(`  + ${file}`);
+  return file;
+}
+
+export const INIT_CLIENTS = ["vscode", "cursor", "opencode", "visualstudio"] as const;
+
+/** Normalize --client values; accepts "visual-studio" as an alias. */
+export function normalizeClient(c: string): string {
+  const lower = c.toLowerCase();
+  return lower === "visual-studio" ? "visualstudio" : lower;
+}
+
+/** Ask a yes/no question. Only called on a TTY when --yes was not passed. */
+async function askBool(q: string, def: boolean): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const hint = def ? "Y/n" : "y/N";
+    const ans = (await rl.question(`${q} [${hint}]: `)).trim().toLowerCase();
+    if (!ans) return def;
+    return ans === "y" || ans === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptClient(): Promise<string | null> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ans = (
+      await rl.question(
+        "Which editor? (1) VS Code  (2) Cursor  (3) opencode  (4) Visual Studio  (5) skip [1]: ",
+      )
+    ).trim();
+    switch (ans) {
+      case "":
+      case "1":
+        return "vscode";
+      case "2":
+        return "cursor";
+      case "3":
+        return "opencode";
+      case "4":
+        return "visualstudio";
+      case "5":
+        return null;
+      default:
+        console.log(`  ? unknown choice "${ans}" — editor setup skipped`);
+        return null;
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+export async function initProject(opts: {
+  client?: string;
+  force: boolean;
+  yes: boolean;
+}): Promise<void> {
+  const interactive = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+  let client = normalizeClient(opts.client ?? "");
+  if (client && !(INIT_CLIENTS as readonly string[]).includes(client)) {
+    console.error(`unknown client "${opts.client}" (${INIT_CLIENTS.join("|")})`);
+    process.exit(1);
+  }
+  if (!client && interactive) client = (await promptClient()) ?? "";
+  if (!client && !interactive) client = "vscode"; // historical default for scripts / one-shot npx
+  if (interactive) {
+    // Install-time settings (D19). Non-default answers persist to the JSONC
+    // config file; `open-memex config set` changes them later.
+    const patch: Record<string, unknown> = {};
+    const keywordCaptureEnabled = await askBool(
+      "Auto-capture keywords like 记住… / remember… into memory?",
+      DEFAULT_CONFIG.keywordCaptureEnabled,
+    );
+    if (keywordCaptureEnabled !== DEFAULT_CONFIG.keywordCaptureEnabled)
+      patch.keywordCaptureEnabled = keywordCaptureEnabled;
+    const injectOnFirstTurn = await askBool(
+      "Inject relevant memories when a session starts?",
+      DEFAULT_CONFIG.injectOnFirstTurn,
+    );
+    if (injectOnFirstTurn !== DEFAULT_CONFIG.injectOnFirstTurn)
+      patch.injectOnFirstTurn = injectOnFirstTurn;
+    if (Object.keys(patch).length > 0) {
+      const file = saveConfig(patch);
+      console.log(
+        `  + settings saved to ${file} (change later with \`open-memex config set <key> <value>\`)`,
+      );
+    }
+  }
+  const root = projectRoot();
+  console.log(`open-memex init — project root: ${root}`);
+  if (client) {
+    writeMcpJson(root, client, opts.force);
+    // copilot-instructions.md is VS Code/Cursor-shaped; opencode as a plain MCP
+    // consumer already gets the guidance from the tool descriptions (D16).
+    if (client !== "opencode") writeInstructions(root);
+  } else {
+    console.log("  - editor setup skipped");
+  }
+  console.log(`\nDone. Reload your editor window to start the open-memex MCP server.`);
+}

package/src/mcp.ts

@@ -0,0 +1,133 @@
+/**
+ * open-memex generic MCP server (stdio transport).
+ *
+ * Exposes the same five memory tools as the opencode plugin
+ * (memory_add / memory_search / memory_list / memory_supersede /
+ * memory_forget) over the Model Context Protocol, so any MCP client —
+ * VS Code Copilot Chat, Cursor, Claude Code, etc. — can use open-memex
+ * without a host-specific plugin.
+ *
+ * Run:  node --experimental-strip-types src/mcp.ts
+ *        (or: npm run mcp)
+ *
+ * The project scope is resolved from the process working directory, so
+ * launch the server with cwd set to the project root (VS Code, Cursor and
+ * Claude Code all do this for workspace-configured MCP servers).
+ *
+ * IMPORTANT: stdout is the MCP protocol channel. Never log to stdout here;
+ * diagnostics go to stderr.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "./config.ts";
+import { resolveProjectScope, PERSONAL_SCOPE, type Scope } from "./scope.ts";
+import { db } from "./store/db.ts";
+import { syncScope } from "./store/sync.ts";
+import {
+  addMemory,
+  searchMemories,
+  listMemories,
+  supersedeMemory,
+  forgetMemory,
+  memoryAddArgs,
+  memorySearchArgs,
+  memoryListArgs,
+  memorySupersedeArgs,
+  memoryForgetArgs,
+  TOOL_DESCRIPTIONS,
+  type ToolResult,
+} from "./tools/ops.ts";
+
+const SERVER_VERSION = "0.2.0-alpha";
+
+/** Adapt a framework-agnostic op result to an MCP tool response. */
+function toMcp(p: Promise<ToolResult>) {
+  return p.then(
+    (r) => ({ content: [{ type: "text" as const, text: r.output }] }),
+    (e: unknown) => ({
+      content: [
+        {
+          type: "text" as const,
+          text: `open-memex error: ${(e as Error)?.message ?? String(e)}`,
+        },
+      ],
+      isError: true as const,
+    }),
+  );
+}
+
+export async function runMcpServer() {
+  const cfg = loadConfig();
+  const scope: Scope = resolveProjectScope(process.cwd());
+  const getScope = () => scope;
+
+  // Init DB and one-shot sync of markdown -> index, mirroring the plugin.
+  db();
+  syncScope(scope.key);
+  syncScope(PERSONAL_SCOPE.key);
+  console.error(`[open-memex] MCP server up. scope=${scope.key}`);
+
+  const server = new McpServer({ name: "open-memex", version: SERVER_VERSION });
+
+  server.registerTool(
+    "memory_add",
+    {
+      description: TOOL_DESCRIPTIONS.memory_add,
+      inputSchema: z.object(memoryAddArgs),
+    },
+    (args) => toMcp(addMemory(getScope, cfg, args)),
+  );
+
+  server.registerTool(
+    "memory_search",
+    {
+      description: TOOL_DESCRIPTIONS.memory_search,
+      inputSchema: z.object(memorySearchArgs),
+      annotations: { readOnlyHint: true },
+    },
+    (args) => toMcp(searchMemories(getScope, args)),
+  );
+
+  server.registerTool(
+    "memory_list",
+    {
+      description: TOOL_DESCRIPTIONS.memory_list,
+      inputSchema: z.object(memoryListArgs),
+      annotations: { readOnlyHint: true },
+    },
+    (args) => toMcp(listMemories(getScope, args)),
+  );
+
+  server.registerTool(
+    "memory_supersede",
+    {
+      description: TOOL_DESCRIPTIONS.memory_supersede,
+      inputSchema: z.object(memorySupersedeArgs),
+    },
+    (args) => toMcp(supersedeMemory(cfg, args)),
+  );
+
+  server.registerTool(
+    "memory_forget",
+    {
+      description: TOOL_DESCRIPTIONS.memory_forget,
+      inputSchema: z.object(memoryForgetArgs),
+      annotations: { destructiveHint: true },
+    },
+    (args) => toMcp(forgetMemory(args)),
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// Standalone entry: `node --experimental-strip-types src/mcp.ts`.
+// The CLI (`open-memex mcp`) imports runMcpServer() instead.
+import { pathToFileURL } from "node:url";
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runMcpServer().catch((err) => {
+    console.error("[open-memex] MCP server failed:", err);
+    process.exit(1);
+  });
+}

package/src/redact.ts

@@ -1,7 +1,8 @@
 /**
- * Redaction: secrets must never land in memory files or the index.
+ * Redaction: secrets must never land in memory files or the index in
+ * readable form.
  *
- * Three layers, checked in order by redact():
+ * Layers, in order:
  *   1. <private>...</private> regions are stripped first (explicit opt-out —
  *      the author marked this span as sensitive, so it is replaced with
  *      [REDACTED] before any detection runs).
@@ -10,8 +11,11 @@
  *   4. High-entropy assignment heuristic (catches secrets whose provider we
  *      don't have a pattern for, e.g. `deploy_key = "aB3d..."`).
  *
- * Any hit refuses the whole write — a memory with a hole in it is worse
- * than no memory, because the hole invites reconstruction.
+ * A detected secret does NOT refuse the write: the matched string is masked
+ * in place — first 4 characters kept, the rest replaced with 'x' — and the
+ * write proceeds with the masked content. hadSecret reports that masking
+ * happened so callers can surface a notice. A partially-masked memory still
+ * identifies which credential it referred to without storing the secret.
  */
 
 export interface SecretPattern {
@@ -21,6 +25,13 @@ export interface SecretPattern {
   source: string;
   /** Optional RegExp flags, e.g. "i". */
   flags?: string;
+  /**
+   * Capture-group index holding the secret value. When set, masking replaces
+   * only that group — the credential name stays readable (D14: a masked
+   * memory should still identify which key it referred to). Default: mask
+   * the whole match.
+   */
+  valueGroup?: number;
 }
 
 /**
@@ -56,8 +67,9 @@ export const BUILTIN_SECRET_PATTERNS: SecretPattern[] = [
   {
     id: "aws-secret-access-key",
     source:
-      "aws[_-]?secret[_-]?access[_-]?key[\"']?\\s*[:=]\\s*[\"']?[A-Za-z0-9/+=]{40}",
+      "(aws[_-]?secret[_-]?access[_-]?key)([\"']?\\s*[:=]\\s*[\"']?)([A-Za-z0-9/+=]{40})",
     flags: "i",
+    valueGroup: 3,
   },
   { id: "slack-token", source: `${TOKEN_BOUNDARY}xox[baprs]-[A-Za-z0-9-]{10,}` },
   { id: "google-api-key", source: `${TOKEN_BOUNDARY}AIza[0-9A-Za-z_-]{30,}` },
@@ -71,7 +83,19 @@ export const BUILTIN_SECRET_PATTERNS: SecretPattern[] = [
     id: "stripe-webhook-secret",
     source: `${TOKEN_BOUNDARY}whsec_[A-Za-z0-9]{20,}`,
   },
-  { id: "private-key-block", source: "-----BEGIN [A-Z ]*PRIVATE KEY-----" },
+  {
+    id: "private-key-block",
+    // Whole block: masking only the BEGIN header would leave the base64 body
+    // readable in the memory file. Non-greedy so two blocks mask separately.
+    source:
+      "-----BEGIN [A-Z ]*PRIVATE KEY-----[\\s\\S]*?-----END [A-Z ]*PRIVATE KEY-----",
+  },
+  {
+    id: "private-key-truncated",
+    // No END marker: mask from the header to end of text. A header without a
+    // body is still key material; over-masking is the safe direction.
+    source: "-----BEGIN [A-Z ]*PRIVATE KEY-----[\\s\\S]*$",
+  },
   {
     id: "jwt",
     source: `${TOKEN_BOUNDARY}eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}`,
@@ -79,8 +103,9 @@ export const BUILTIN_SECRET_PATTERNS: SecretPattern[] = [
   {
     id: "generic-secret-assignment",
     source:
-      "(api[_-]?key|secret|passwd|password|auth[_-]?token|access[_-]?token)[\"']?\\s*[:=]\\s*[\"']?[A-Za-z0-9_\\-./+=]{16,}[\"']?",
+      "(api[_-]?key|secret|passwd|password|auth[_-]?token|access[_-]?token)([\"']?\\s*[:=]\\s*[\"']?)([A-Za-z0-9_\\-./+=]{16,})([\"']?)",
     flags: "i",
+    valueGroup: 3,
   },
 ];
 
@@ -139,12 +164,31 @@ export function findHighEntropySecret(text: string): string | null {
   for (const m of text.matchAll(ASSIGNMENT_RE)) {
     const name = m[1];
     const value = m[2];
-    if (value.includes("://")) continue; // URL, not a secret
-    if (shannonEntropy(value) >= 4.5) return `high-entropy-secret:${name}`;
+    if (!isSuspectAssignmentValue(value, m[0], m.index ?? 0, text)) continue;
+    return `high-entropy-secret:${name}`;
   }
   return null;
 }
 
+/**
+ * Shared benign-value rule for detection AND masking: a URL (e.g. the value
+ * after "https:") or a low-entropy value must never be touched. Note the
+ * "://" check: ASSIGNMENT_RE consumes the colon of "https:" as the separator,
+ * so the captured value starts with "//..." — check for "://" in the
+ * original text around the match, not just inside the value.
+ */
+function isSuspectAssignmentValue(value: string, fullMatch: string, offset: number, text: string): boolean {
+  // Bare URL: ASSIGNMENT_RE consumed the scheme colon ("https:") as the
+  // separator, so the match itself starts with "scheme://".
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(fullMatch)) return false;
+  if (value.includes("://")) return false;
+  // Reconstruct what preceded the value inside the match (name + separator);
+  // if the text right before the value looks like scheme://, it is a URL.
+  const before = text.slice(Math.max(0, offset - 12), offset);
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:(\/\/)?$/.test(before.trim()) || before.includes("://")) return false;
+  return shannonEntropy(value) >= 4.5;
+}
+
 export function stripPrivate(text: string): string {
   // Closed pairs first...
   let out = text.replace(/<private>[\s\S]*?<\/private>/gi, "[REDACTED]");
@@ -154,18 +198,78 @@ export function stripPrivate(text: string): string {
   return out;
 }
 
+/**
+ * Mask a matched secret: keep the first 4 characters, replace the rest
+ * with 'x' (length-preserving). "sk-1234567890abcdefghij" → "sk-1xxxxxxxxxxxxx".
+ */
+function maskMatch(m: string): string {
+  return m.slice(0, 4) + "x".repeat(Math.max(0, m.length - 4));
+}
+
+/** Apply the builtin patterns as masking (global, all matches). */
+function maskBuiltin(content: string): string {
+  let out = content;
+  for (const p of BUILTIN_SECRET_PATTERNS) {
+    const re = compile(p);
+    if (!re) continue;
+    const g = new RegExp(re.source, re.flags + "g");
+    if (p.valueGroup == null) {
+      out = out.replace(g, (m) => maskMatch(m));
+    } else {
+      // Mask only the secret-value group; the credential name stays readable.
+      out = out.replace(g, (...args: unknown[]) => {
+        const m = args[0] as string;
+        const val = args[p.valueGroup as number] as string | undefined;
+        if (!val) return m;
+        const idx = m.lastIndexOf(val);
+        if (idx < 0) return m;
+        return m.slice(0, idx) + maskMatch(val) + m.slice(idx + val.length);
+      });
+    }
+  }
+  return out;
+}
+
+/** Apply user patterns as masking. Invalid regexes are ignored. */
+function maskUser(content: string, patterns: string[]): string {
+  let out = content;
+  for (const p of patterns) {
+    try {
+      out = out.replace(new RegExp(p, "g"), (m) => maskMatch(m));
+    } catch {
+      // ignore malformed regex
+    }
+  }
+  return out;
+}
+
+/** Mask the value side of high-entropy assignments (name stays readable).
+ *  Uses the exact same benign-value rule as detection, so URLs and
+ *  low-entropy values are never touched even when another secret triggers. */
+function maskEntropy(content: string): string {
+  return content.replace(
+    ASSIGNMENT_RE,
+    (m, name: string, value: string, offset: number) => {
+      if (!isSuspectAssignmentValue(value, m, offset, content)) return m;
+      return m.split(value).join(maskMatch(value));
+    },
+  );
+}
+
 export function redact(
   text: string,
   patterns: string[],
 ): { content: string; hadSecret: boolean; matchedPattern: string | null } {
   const stripped = stripPrivate(text);
+  // Detection (for reporting) runs in priority order: builtin → user → entropy.
   const builtin = findBuiltinSecret(stripped);
-  if (builtin)
-    return { content: stripped, hadSecret: true, matchedPattern: builtin };
-  const user = findSecret(stripped, patterns);
-  if (user) return { content: stripped, hadSecret: true, matchedPattern: user };
-  const entropic = findHighEntropySecret(stripped);
-  if (entropic)
-    return { content: stripped, hadSecret: true, matchedPattern: entropic };
-  return { content: stripped, hadSecret: false, matchedPattern: null };
+  const user = builtin ? null : findSecret(stripped, patterns);
+  const entropic =
+    builtin || user ? null : findHighEntropySecret(stripped);
+  const matched = builtin ?? user ?? entropic;
+  if (!matched) return { content: stripped, hadSecret: false, matchedPattern: null };
+  // Masking runs every family over the text (not just the reported one) so
+  // multiple credentials in one memory are all masked.
+  const masked = maskEntropy(maskUser(maskBuiltin(stripped), patterns));
+  return { content: masked, hadSecret: true, matchedPattern: matched };
 }