Harden passive bridge extraction

- Recover malformed-but-repairable passive extractor JSON and retry once with stricter JSON-only instructions
- Tighten passive extractor section guidance and report schema validation failures with non-sensitive field-specific reasons
- Make recent fuzzy duplicate suppression section-aware so distinct values and practices themes can both bridge
- Document the customer-friendly Cortex Memory explainer link in the README
- Add focused unit coverage for JSON recovery, schema diagnostics, values-style candidates, duplicate suppression, and bridge send guards

Author: matthewubundi

README.md

@@ -8,6 +8,12 @@
 
 [OpenClaw](https://github.com/openclaw/openclaw) plugin for [Cortex](https://github.com/ubundi/cortex) long-term memory. Gives your agent persistent memory that survives across sessions — who you are, what your project does, decisions you made weeks ago, and how things changed over time.
 
+## Customer-Friendly Explainer
+
+A one-page explainer for companies using the plugin is published at [https://marble-birch-znnf.here.now/](https://marble-birch-znnf.here.now/). It explains what Cortex Memory does for AI agents, how it benefits users and teams, and what controls administrators have.
+
+The source HTML artifact is also stored privately in here.now Drive at `My Drive/openclaw-cortex/cortex-memory-plugin-explainer.html`.
+
 ![Features](assets/readme_assets/Feature%20Cards.png)
 
 - **Auto-Recall** — optional cold-start memory injection before the agent reads workspace notes

src/features/bridge/handler.ts

@@ -77,6 +77,7 @@ interface PassiveRecentCandidate {
   contentKey: string;
   evidenceKey: string;
   evidenceHash: string;
+  suggestedSection: PassiveBridgeRequest["candidates"][number]["suggested_section"];
   sentAt: number;
 }
 
@@ -178,33 +179,35 @@ function passiveTracePrivateFragments(request: PassiveBridgeRequest): string[] {
 
 function isDuplicateRecentPassiveCandidate(
   sessionState: BridgeSessionState,
-  candidate: Pick<PassiveBridgeRequest["candidates"][number], "content" | "evidence_quote">,
+  candidate: Pick<PassiveBridgeRequest["candidates"][number], "content" | "evidence_quote" | "suggested_section">,
   recentCandidates: PassiveRecentCandidate[] = trimPassiveRecentCandidates(sessionState),
 ): boolean {
   const contentKey = passiveCanonicalKey(candidate.content);
   const evidenceKey = passiveCanonicalKey(candidate.evidence_quote);
   const evidenceHash = passiveEvidenceHash(candidate.evidence_quote);
-  return recentCandidates.some((recent) => (
-    recent.evidenceHash === evidenceHash
-    || passiveSimilarity(contentKey, recent.contentKey) >= PASSIVE_CONTENT_DUPLICATE_SIMILARITY
-    || passiveSimilarity(evidenceKey, recent.evidenceKey) >= PASSIVE_EVIDENCE_DUPLICATE_SIMILARITY
-  ));
+  return recentCandidates.some((recent) => {
+    if (recent.evidenceHash === evidenceHash) return true;
+    if (recent.suggestedSection !== candidate.suggested_section) return false;
+    return passiveSimilarity(contentKey, recent.contentKey) >= PASSIVE_CONTENT_DUPLICATE_SIMILARITY
+      || passiveSimilarity(evidenceKey, recent.evidenceKey) >= PASSIVE_EVIDENCE_DUPLICATE_SIMILARITY;
+  });
 }
 
 function passiveRecentCandidateFor(
-  candidate: Pick<PassiveBridgeRequest["candidates"][number], "content" | "evidence_quote">,
+  candidate: Pick<PassiveBridgeRequest["candidates"][number], "content" | "evidence_quote" | "suggested_section">,
 ): PassiveRecentCandidate {
   return {
     contentKey: passiveCanonicalKey(candidate.content),
     evidenceKey: passiveCanonicalKey(candidate.evidence_quote),
     evidenceHash: passiveEvidenceHash(candidate.evidence_quote),
+    suggestedSection: candidate.suggested_section,
     sentAt: Date.now(),
   };
 }
 
 function rememberRecentPassiveCandidate(
   sessionState: BridgeSessionState,
-  candidate: Pick<PassiveBridgeRequest["candidates"][number], "content" | "evidence_quote">,
+  candidate: Pick<PassiveBridgeRequest["candidates"][number], "content" | "evidence_quote" | "suggested_section">,
 ): void {
   const recent = trimPassiveRecentCandidates(sessionState);
   recent.push(passiveRecentCandidateFor(candidate));

src/features/bridge/openclaw-extractor.ts

@@ -75,6 +75,8 @@ type DirectPassiveModelCall = (params: {
   signal?: AbortSignal;
 }) => Promise<string>;
 
+const DIRECT_EXTRACTOR_JSON_RETRY_LIMIT = 1;
+
 type JsonCompatible =
   | null
   | boolean
@@ -369,6 +371,53 @@ function buildDirectExtractorUserPrompt(input: PassiveExtractorInput): string {
   ].join("\n");
 }
 
+function buildStrictJsonRetryInput(input: PassiveExtractorInput): PassiveExtractorInput {
+  return {
+    ...input,
+    prompt: [
+      input.prompt,
+      "",
+      "Your previous response was not parseable JSON.",
+      "Retry now with exactly one strict JSON object matching the requested schema.",
+      "Do not include markdown, comments, explanations, trailing commas, or extra top-level keys.",
+      "If there are no valid candidates, return exactly {\"candidates\":[]}.",
+    ].join("\n"),
+  };
+}
+
+async function runDirectPassiveModelExtractorWithJsonRecovery(params: {
+  input: PassiveExtractorInput;
+  config?: OpenClawConfigLike;
+  modelRef: string;
+  timeoutMs: number;
+  directModelCall: DirectPassiveModelCall;
+  logger: Logger;
+}): Promise<PassiveExtractorOutput> {
+  const startedAt = Date.now();
+  let lastSyntaxError: SyntaxError | undefined;
+  for (let attempt = 0; attempt <= DIRECT_EXTRACTOR_JSON_RETRY_LIMIT; attempt++) {
+    const input = attempt === 0 ? params.input : buildStrictJsonRetryInput(params.input);
+    const remainingMs = Math.max(1, params.timeoutMs - (Date.now() - startedAt));
+    const text = await params.directModelCall({
+      input,
+      config: params.config,
+      modelRef: params.modelRef,
+      timeoutMs: remainingMs,
+    });
+    if (!text.trim()) return { candidates: [] };
+    try {
+      return parsePassiveExtractorJson(text);
+    } catch (err) {
+      if (!(err instanceof SyntaxError)) throw err;
+      lastSyntaxError = err;
+      if (attempt >= DIRECT_EXTRACTOR_JSON_RETRY_LIMIT) break;
+      params.logger.debug?.(`Cortex bridge: passive extractor_json_retry attempt=${attempt + 1} reason=json_parse_failed`);
+    }
+  }
+  params.logger.debug?.("Cortex bridge: passive extractor_json_unrecoverable reason=json_parse_failed");
+  throw lastSyntaxError ?? new SyntaxError("passive extractor JSON parse failed");
+}
+
 function normalizeSecretInput(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
@@ -811,13 +860,13 @@ export function createOpenClawPassiveModelExtractor(
     }
 
     logger.info?.(`Cortex bridge: passive_extractor_model_call_started runner=direct_model timeoutMs=${timeoutMs} maxOutputTokens=${input.maxOutputTokens} model=${modelRef}`);
-    const text = await (options.directModelCall ?? createPiAiDirectModelCall())({
+    return runDirectPassiveModelExtractorWithJsonRecovery({
       input,
       config: directExtractorConfig,
       modelRef,
       timeoutMs,
+      directModelCall: options.directModelCall ?? createPiAiDirectModelCall(),
+      logger,
     });
-    if (!text.trim()) return { candidates: [] };
-    return parsePassiveExtractorJson(text);
   };
 }

src/features/bridge/passive.ts

@@ -227,9 +227,12 @@ export function buildPassiveExtractorPrompt(): string {
     "Candidate wording should be concise, durable, operational, and not include unsupported details.",
     "Evidence quotes must be exact user-authored substrings from the provided messages.",
     "Keep evidence_quote to the shortest exact substring that proves the candidate; do not quote whole long messages.",
+    "suggested_section must be exactly one of: coreValues, beliefs, principles, ideas, dreams, practices, shadows, legacy.",
+    "Use coreValues for personal values, principles for operating principles, practices for concrete recurring work habits, and beliefs for durable beliefs.",
     "If uncertain, return no candidates.",
     "Return JSON only with this shape:",
-    "{\"candidates\":[{\"content\":\"string\",\"suggested_section\":\"practices\",\"evidence_quote\":\"exact user-authored quote\",\"supporting_evidence_quotes\":[\"optional exact user-authored quotes\"],\"confidence\":0.0,\"risk_tier\":\"low\",\"reason\":\"brief internal review note\"}]}",
+    "{\"candidates\":[{\"content\":\"string\",\"suggested_section\":\"coreValues|beliefs|principles|ideas|dreams|practices|shadows|legacy\",\"evidence_quote\":\"exact user-authored quote\",\"supporting_evidence_quotes\":[\"optional exact user-authored quotes\"],\"confidence\":0.0,\"risk_tier\":\"low\",\"reason\":\"brief internal review note\"}]}",
+    "Output must be a single strict JSON object: no markdown fences, no prose, no comments, no trailing commas, and no extra top-level keys.",
   ].join("\n");
 }
 
@@ -262,8 +265,19 @@ export function buildPassiveExtractorInput(rawMessages: unknown[]): PassiveExtra
 }
 
 export function parsePassiveExtractorJson(raw: string): PassiveExtractorOutput {
-  const trimmed = raw.trim().replace(/^```(?:json)?\s*([\s\S]*?)\s*```$/i, "$1").trim();
-  const parsed = JSON.parse(trimmed) as unknown;
+  const trimmed = stripPassiveExtractorJsonWrapper(raw);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed) as unknown;
+  } catch (err) {
+    const repaired = repairPassiveExtractorJsonText(trimmed);
+    if (!repaired || repaired === trimmed) throw err;
+    try {
+      parsed = JSON.parse(repaired) as unknown;
+    } catch {
+      throw err;
+    }
+  }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw new SyntaxError("passive extractor JSON root must be an object");
   }
@@ -278,6 +292,54 @@ export function parsePassiveExtractorJson(raw: string): PassiveExtractorOutput {
   return { candidates };
 }
 
+function stripPassiveExtractorJsonWrapper(raw: string): string {
+  return raw.trim().replace(/^```(?:json)?\s*([\s\S]*?)\s*```$/i, "$1").trim();
+}
+
+function extractLikelyJsonObject(raw: string): string | undefined {
+  const first = raw.indexOf("{");
+  const last = raw.lastIndexOf("}");
+  if (first < 0 || last <= first) return undefined;
+  return raw.slice(first, last + 1).trim();
+}
+
+function removeTrailingJsonCommas(raw: string): string {
+  let output = "";
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < raw.length; index++) {
+    const char = raw[index];
+    if (escaped) {
+      output += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && inString) {
+      output += char;
+      escaped = true;
+      continue;
+    }
+    if (char === "\"") {
+      inString = !inString;
+      output += char;
+      continue;
+    }
+    if (char === "," && !inString) {
+      let lookahead = index + 1;
+      while (/\s/.test(raw[lookahead] ?? "")) lookahead++;
+      if (raw[lookahead] === "}" || raw[lookahead] === "]") continue;
+    }
+    output += char;
+  }
+  return output;
+}
+
+function repairPassiveExtractorJsonText(raw: string): string | undefined {
+  const candidate = extractLikelyJsonObject(raw) ?? raw;
+  const repaired = removeTrailingJsonCommas(candidate).trim();
+  return repaired ? repaired : undefined;
+}
+
 function exactUserEvidenceSource(
   quote: string,
   messages: PassiveExtractorMessage[],
@@ -313,6 +375,14 @@ function reject(reason: string): { reason: string } {
   return { reason };
 }
 
+function schemaReject(detail: string): { reason: string } {
+  return reject(`schema_invalid:${detail}`);
+}
+
+function schemaKeyReject(key: string): { reason: string } {
+  return schemaReject(`unexpected_key:${key.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 40) || "unknown"}`);
+}
+
 const PASSIVE_PRUNE_STOPWORDS = new Set([
   "a",
   "an",
@@ -462,20 +532,21 @@ export function validatePassiveExtractorCandidates(
       "risk_tier",
       "reason",
     ]);
-    if (Object.keys(typed).some((key) => !allowedKeys.has(key))) {
-      rejected.push(reject("schema_invalid"));
+    const unexpectedKey = Object.keys(typed).find((key) => !allowedKeys.has(key));
+    if (unexpectedKey) {
+      rejected.push(schemaKeyReject(unexpectedKey));
       continue;
     }
     if (typeof typed.supporting_evidence_quotes !== "undefined" && !Array.isArray(typed.supporting_evidence_quotes)) {
-      rejected.push(reject("schema_invalid"));
+      rejected.push(schemaReject("supporting_evidence_quotes"));
       continue;
     }
     if (!content || countWords(content) < 4) {
       rejected.push(reject(BLOCKED_CANDIDATE_RE.test(content ?? "") ? "sensitive_content" : "candidate_text_invalid"));
       continue;
     }
     if (!suggestedSection) {
-      rejected.push(reject("schema_invalid"));
+      rejected.push(schemaReject("suggested_section"));
       continue;
     }
     if (confidence === undefined || confidence < 0.75) {