@clawling/clawchat-plugin-openclaw 2026.10.8-1 → 2026.10.9-1

package/dist/src/runtime.js

@@ -1,3 +1,4 @@
+import { applyDmRecallDefault } from "./dm-recall-default.js";
 import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, EVENT, recallTargetMessageId, } from "./protocol-types.js";
 import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
 import { hasControlCommand } from "openclaw/plugin-sdk/command-detection";
@@ -30,12 +31,14 @@ import { createNotifySignalObserver, createProtocolControlHandler, createReconne
 import { clawChatDbPathForStateDir, getClawChatStore, makeOwnerProfilePersister, } from "./storage.js";
 import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.js";
 import { loadClawChatPromptMetadata, renderClawChatProfilePrompt, resolveSenderRelation, } from "./profile-prompt.js";
+import { buildNoteMemorySection } from "./note-injection.js";
+import { buildGroupCatchUp, CATCH_UP_FETCH_ROWS, DeliveredGroupMessages } from "./group-catch-up.js";
 import { refreshGroupProfile, syncFirstSeenClawChatProfiles } from "./profile-sync.js";
 import { pullGroupMetadata, pullOwnerMetadata } from "./clawchat-metadata.js";
 import { deleteClawChatMemoryFile, readClawChatMemoryFile } from "./clawchat-memory.js";
 import { registerMentionRosterResolver } from "./mention-autolink.js";
 import { clearClawChatPromptInjectionForSession, stageClawChatPromptInjection, } from "./prompt-injection.js";
-import { createGroupMessageCoalescer } from "./group-message-coalescer.js";
+import { createGroupMessageCoalescer, relabelCoalescedGroupBody } from "./group-message-coalescer.js";
 import { openclawLlmContextDebug } from "./llm-context-debug.js";
 import { GroupSettingsCache } from "./group-settings.js";
 import { PermissionCache } from "./permissions.js";
@@ -90,7 +93,6 @@ function activationBootstrapInFlightCount(accountId) {
 // hermes plugin's GROUP_SETTINGS_READY_TIMEOUT_SECONDS (5s).
 const GROUP_SETTINGS_READY_TIMEOUT_MS = 5_000;
 /** Number of recent group messages to prepend as context when the agent is @-mentioned. */
-const MENTION_CONTEXT_N = 10;
 const CLAWCHAT_MEMORY_ROOT_UNAVAILABLE = "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved";
 const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
     "approve",
@@ -936,6 +938,48 @@ export async function startOpenclawClawlingGateway(params) {
             ? runtimeConfig.mutateConfigFile
             : undefined;
     };
+    // OpenClaw >= 2026.8.1 recalls across a single agent's DMs unless DM isolation
+    // is visible in the gateway config; ours is in-memory only. Write the agent's
+    // `rememberAcrossConversations: false` once, unless the owner set it
+    // (dm-recall-default.ts). Fire-and-forget: never blocks or fails startup.
+    void (async () => {
+        const stateDir = runtime.state?.resolveStateDir?.();
+        const mutateConfigFile = resolveMutateConfigFile();
+        const readConfig = runtime.config?.current;
+        if (!stateDir || !mutateConfigFile || typeof readConfig !== "function")
+            return;
+        let agentId;
+        try {
+            agentId = runtime.channel.routing.resolveAgentRoute({
+                cfg: withClawChatSessionScope(cfg),
+                channel: CHANNEL_ID,
+                accountId,
+                peer: { kind: "direct", id: account.ownerUserId || "owner" },
+            }).agentId;
+        }
+        catch (err) {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw rememberAcrossConversations default skipped: agent route unavailable (${err instanceof Error ? err.message : String(err)})`);
+            return;
+        }
+        await applyDmRecallDefault({
+            agentId,
+            hostVersion: runtime.version,
+            stateDir,
+            readConfig: () => readConfig.call(runtime.config),
+            mutateConfigFile: mutateConfigFile,
+            log: {
+                info: (m) => log?.info?.(`[${accountId}] ${m}`),
+                warn: (m) => {
+                    const warn = log?.warn;
+                    if (warn)
+                        warn(`[${accountId}] ${m}`);
+                    else
+                        log?.info?.(`[${accountId}] WARNING ${m}`);
+                },
+                error: (m) => log?.error?.(`[${accountId}] ${m}`),
+            },
+        });
+    })();
     // §0/§C.1 — write the account slot's `token`/`refreshToken` keys. `tokens=null`
     // blanks them (auto-logout); otherwise persists the rotated pair.
     const persistConfigTokens = async (tokens) => {
@@ -2472,12 +2516,27 @@ export async function startOpenclawClawlingGateway(params) {
                 ownerMetadata: promptMetadata.ownerMetadata,
             })
             : [];
+        const noteMemorySection = await buildNoteMemorySection({
+            memoryRoot,
+            chatType: promptChatType,
+            chatId: turn.peer.id,
+            senderId: turn.senderId,
+            senderIsOwner: senderRelation === "owner",
+            selfId: account.userId,
+            speakers: turn.peer.kind === "group"
+                ? (turn.groupMessages && turn.groupMessages.length > 0
+                    ? turn.groupMessages.map((message) => ({ id: message.senderId, name: message.senderName }))
+                    : [{ id: turn.senderId, name: turn.senderNickName }])
+                : [],
+            caps: { user: account.noteCapUser, group: account.noteCapGroup, turn: account.noteCapTurn },
+        });
         return renderClawChatProfilePrompt({
             basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
             ...promptMetadata,
             ownerIdFallback: account.ownerUserId,
             currentAgentIdFallback: account.userId,
             groupParticipants,
+            noteMemorySection,
             turn: {
                 chatType: promptChatType,
                 chatId: turn.peer.id,
@@ -2521,6 +2580,100 @@ export async function startOpenclawClawlingGateway(params) {
     // coalesced batch's transcript ("Alice:" rather than "usr_…:") without
     // touching disk.
     const knownNicknames = new Map();
+    // Group message ids already handed to the agent, per chat (see group-catch-up.ts).
+    const deliveredGroupMessages = new DeliveredGroupMessages();
+    // One catch-up line: `Name (usr_…): text`, the name from the stored frame's
+    // nick_name unless that is just the id, else the cached nickname.
+    const formatCatchUpLine = (row) => {
+        const text = (row.text ?? "").trim() || "(empty message)";
+        let senderId = "";
+        let nickName = "";
+        try {
+            const frame = row.raw_json ? JSON.parse(row.raw_json) : null;
+            senderId = typeof frame?.sender?.id === "string" ? frame.sender.id : "";
+            nickName = typeof frame?.sender?.nick_name === "string" ? frame.sender.nick_name : "";
+        }
+        catch {
+            // A malformed stored frame still yields its text.
+        }
+        if (!senderId)
+            return text;
+        const name = (nickName && nickName !== senderId ? nickName : knownNicknames.get(senderId)) ?? "";
+        return name ? `${name} (${senderId}): ${text}` : `${senderId}: ${text}`;
+    };
+    // The sender id of a stored row whose frame carried no real nickname (its
+    // nick_name is missing or just the id), else "".
+    const bareSenderIdOfRow = (row) => {
+        try {
+            const frame = row.raw_json
+                ? JSON.parse(row.raw_json)
+                : null;
+            const id = typeof frame?.sender?.id === "string" ? frame.sender.id : "";
+            const nick = typeof frame?.sender?.nick_name === "string" ? frame.sender.nick_name : "";
+            return id && (!nick || nick === id) ? id : "";
+        }
+        catch {
+            return "";
+        }
+    };
+    // Last group-metadata pull made only to resolve names, per chat: a sender who
+    // can never be resolved (deleted account) must not refetch on every batch.
+    const nicknameRefreshAt = new Map();
+    const NICKNAME_REFRESH_COOLDOWN_MS = 60_000;
+    const NICKNAME_REFRESH_TIMEOUT_MS = 3_000;
+    // Fill knownNicknames for `ids` from ClawChat memory; if some are still
+    // missing in a group, pull the group's participants once (bounded, with a
+    // cooldown) and read again. Never throws: a name is a nicety, the turn is not.
+    const warmGroupNicknames = async (peer, ids) => {
+        if (peer.kind !== "group")
+            return;
+        try {
+            const memoryRoot = resolveMemoryRootForPeer(peer);
+            if (!memoryRoot)
+                return;
+            const wanted = Array.from(new Set(Array.from(ids).filter((id) => id && id !== account.userId)));
+            const missing = () => wanted.filter((id) => !knownNicknames.has(id));
+            const readCached = async () => {
+                for (const id of missing()) {
+                    const nickname = await cachedNicknameFor(memoryRoot, id);
+                    if (nickname && nickname !== id)
+                        knownNicknames.set(id, nickname);
+                }
+            };
+            await readCached();
+            if (missing().length === 0)
+                return;
+            const now = Date.now();
+            const last = nicknameRefreshAt.get(peer.id);
+            if (last !== undefined && now - last < NICKNAME_REFRESH_COOLDOWN_MS)
+                return;
+            nicknameRefreshAt.set(peer.id, now);
+            let timer;
+            await Promise.race([
+                refreshGroupProfile({
+                    platform: "openclaw",
+                    accountId,
+                    accountUserId: account.userId,
+                    accountOwnerUserId: account.ownerUserId,
+                    conversationId: peer.id,
+                    api: getConversationApiClient(),
+                    store: {},
+                    memoryRoot,
+                    log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+                }),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, NICKNAME_REFRESH_TIMEOUT_MS);
+                }),
+            ]).finally(() => {
+                if (timer)
+                    clearTimeout(timer);
+            });
+            await readCached();
+        }
+        catch (err) {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw group sender name lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
     const withCachedGroupSenderNames = async (turn, memoryRoot) => {
         if (turn.peer.kind !== "group" || !memoryRoot)
             return turn;
@@ -2926,32 +3079,55 @@ export async function startOpenclawClawlingGateway(params) {
                 log?.info?.(`[${accountId}] clawchat-plugin-openclaw coalesced group batch dropped at flush (now mention-only, no mention) chat_id=${turn.peer.id} msg=${turn.messageId}`);
                 return;
             }
+            const chatId = turn.peer.id;
+            const batchIds = new Set(turn.allMessageIds ?? [turn.messageId]);
+            const catchUpRows = turn.wasMentioned && store?.listRecentGroupMessages
+                ? store.listRecentGroupMessages("openclaw", accountId, chatId, CATCH_UP_FETCH_ROWS + batchIds.size) ?? []
+                : [];
+            // Ingest labels a batch from the in-memory nickname map, which is empty
+            // after a restart, and catch-up lines read the same map: resolve every
+            // sender named here before the turn goes out.
+            await warmGroupNicknames(turn.peer, [
+                ...(turn.groupMessages ?? [])
+                    .filter((message) => !message.senderName || message.senderName === message.senderId)
+                    .map((message) => message.senderId),
+                ...(!turn.senderNickName || turn.senderNickName === turn.senderId ? [turn.senderId] : []),
+                ...catchUpRows.map(bareSenderIdOfRow),
+            ]);
+            if (turn.groupMessages?.length) {
+                turn = {
+                    ...turn,
+                    rawBody: relabelCoalescedGroupBody(turn.rawBody, turn.groupMessages, (id) => knownNicknames.get(id)),
+                    groupMessages: turn.groupMessages.map((message) => {
+                        const known = message.senderName === message.senderId ? knownNicknames.get(message.senderId) : undefined;
+                        return known ? { ...message, senderName: known } : message;
+                    }),
+                };
+            }
+            if (turn.senderNickName === turn.senderId && knownNicknames.has(turn.senderId)) {
+                turn = { ...turn, senderNickName: knownNicknames.get(turn.senderId) };
+            }
+            // An @-mention adds the group messages this session has not been given
+            // since its last turn (e.g. ones a mention-only group held back), within
+            // delta-budget-chars. Every batch handed to the agent is recorded as
+            // delivered, so nothing it already has comes back. See group-catch-up.ts.
+            let catchUp = null;
             if (turn.wasMentioned && store?.listRecentGroupMessages) {
-                const chatId = turn.peer.id;
-                // Dedupe: exclude rows whose message_id belongs to the current batch/turn.
-                // For a coalesced multi-message turn this covers every constituent ID,
-                // not just the latest one (turn.messageId), so none of the batched
-                // messages appear twice — once in the coalesced body and once in the
-                // prepended "Prior group context" block.
-                const batchIds = new Set(turn.allMessageIds ?? [turn.messageId]);
-                // Overfetch so the batch's own just-stored messages don't crowd out the
-                // MENTION_CONTEXT_N prior rows: fetch batch-size extra rows, drop the
-                // batch members, then keep the most recent MENTION_CONTEXT_N survivors.
-                const priorRows = store.listRecentGroupMessages("openclaw", accountId, chatId, MENTION_CONTEXT_N + batchIds.size) ?? [];
-                const contextRows = priorRows
-                    .filter((row) => row.message_id != null && !batchIds.has(row.message_id))
-                    .slice(-MENTION_CONTEXT_N);
-                if (contextRows.length > 0) {
-                    const priorContextBody = [
-                        "Prior group context:",
-                        ...contextRows.map((row, i) => `[prior ${i + 1}] ${row.text ?? "(empty)"}`),
-                    ].join("\n");
-                    await dispatchTurnToAgent({
-                        ...turn,
-                        rawBody: `${priorContextBody}\n${turn.rawBody}`,
-                    });
-                    return;
-                }
+                const fetchLimit = CATCH_UP_FETCH_ROWS + batchIds.size;
+                catchUp = buildGroupCatchUp({
+                    chatId,
+                    rows: catchUpRows,
+                    fetchLimit,
+                    batchIds,
+                    delivered: deliveredGroupMessages,
+                    budgetChars: account.deltaBudgetChars,
+                    formatLine: formatCatchUpLine,
+                });
+            }
+            deliveredGroupMessages.remember(chatId, batchIds);
+            if (catchUp) {
+                await dispatchTurnToAgent({ ...turn, rawBody: `${catchUp}\n${turn.rawBody}` });
+                return;
             }
             await dispatchTurnToAgent(turn);
         },
@@ -3236,8 +3412,8 @@ export async function startOpenclawClawlingGateway(params) {
         })();
     });
     // `message.recall` — the sender withdrew a message. Erase our own ledger row
-    // so the "Prior group context" block above (MENTION_CONTEXT_N rows, no time
-    // predicate, no retention) can never read it back into a turn.
+    // so the mention catch-up above (unseen group messages, no time predicate,
+    // no retention) can never read it back into a turn.
     //
     // Ids only: the frame carries no content, and `payload.message_id` is the
     // server's `rcl:<target>` slot — the id to delete is `target_message_id`.

package/dist/src/storage.js

@@ -475,8 +475,8 @@ export class ClawChatStore {
      *
      * **The only DELETE in this store, and deliberately so.** There is no prune
      * and no retention on `clawchat_messages`: without this, a message recalled
-     * ninety seconds after it was sent stays one @-mention away from being read
-     * back aloud under "Prior group context" for as long as the group is quiet.
+     * ninety seconds after it was sent, before the agent was given it, stays
+     * one @-mention away from being read back in the mention catch-up.
      *
      * Scoped to `(platform, account_id)` so one account's recall cannot reach
      * another's rows, and matched on `message_id`, which seeks via the

package/openclaw.plugin.json

@@ -128,6 +128,10 @@
       "awarenessNote": { "type": "boolean" },
       "friendGreeting": { "type": "boolean" },
       "livewareSample": { "type": "boolean" },
+      "note-cap-user": { "type": "integer" },
+      "note-cap-group": { "type": "integer" },
+      "note-cap-turn": { "type": "integer" },
+      "delta-budget-chars": { "type": "integer" },
       "reconnect": {
         "type": "object",
         "additionalProperties": false,
@@ -202,6 +206,10 @@
             "awarenessNote": { "type": "boolean" },
             "friendGreeting": { "type": "boolean" },
             "livewareSample": { "type": "boolean" },
+            "note-cap-user": { "type": "integer" },
+            "note-cap-group": { "type": "integer" },
+            "note-cap-turn": { "type": "integer" },
+            "delta-budget-chars": { "type": "integer" },
             "reconnect": {
               "type": "object",
               "additionalProperties": false,
@@ -282,6 +290,10 @@
           "awarenessNote": { "type": "boolean" },
           "friendGreeting": { "type": "boolean" },
           "livewareSample": { "type": "boolean" },
+          "note-cap-user": { "type": "integer" },
+          "note-cap-group": { "type": "integer" },
+          "note-cap-turn": { "type": "integer" },
+          "delta-budget-chars": { "type": "integer" },
           "reconnect": {
             "type": "object",
             "additionalProperties": false,
@@ -356,6 +368,10 @@
                 "awarenessNote": { "type": "boolean" },
                 "friendGreeting": { "type": "boolean" },
                 "livewareSample": { "type": "boolean" },
+                "note-cap-user": { "type": "integer" },
+                "note-cap-group": { "type": "integer" },
+                "note-cap-turn": { "type": "integer" },
+                "delta-budget-chars": { "type": "integer" },
                 "reconnect": {
                   "type": "object",
                   "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.10.8-1",
+  "version": "2026.10.9-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/config.ts

@@ -120,6 +120,11 @@ export type OpenclawClawlingAccountConfig = {
   friendGreeting?: boolean;
   /** Auto-install the Liveware Sample demo app when no liveware app is registered (default true). */
   livewareSample?: boolean;
+  /** Shared ClawChat session / note keys (hyphenated; see SESSION_INT_KEYS). */
+  "note-cap-user"?: number;
+  "note-cap-group"?: number;
+  "note-cap-turn"?: number;
+  "delta-budget-chars"?: number;
   reconnect?: OpenclawClawlingReconnectConfig;
   heartbeat?: OpenclawClawlingHeartbeatConfig;
   ack?: OpenclawClawlingAckConfig;
@@ -181,6 +186,10 @@ export const openclawClawlingAccountConfigSchema = {
     awarenessNote: { type: "boolean" },
     friendGreeting: { type: "boolean" },
     livewareSample: { type: "boolean" },
+    "note-cap-user": { type: "integer" },
+    "note-cap-group": { type: "integer" },
+    "note-cap-turn": { type: "integer" },
+    "delta-budget-chars": { type: "integer" },
     reconnect: {
       type: "object",
       additionalProperties: false,
@@ -320,6 +329,14 @@ export type ResolvedOpenclawClawlingAccount = {
   awarenessNote: boolean;
   friendGreeting: boolean;
   livewareSample: boolean;
+  /** `note-cap-user`: characters of one person's note shown in a turn. */
+  noteCapUser: number;
+  /** `note-cap-group`: characters of the group's note shown in a group turn. */
+  noteCapGroup: number;
+  /** `note-cap-turn`: characters of all notes shown in one turn together. */
+  noteCapTurn: number;
+  /** `delta-budget-chars`: characters of unseen group messages an @-mention adds. */
+  deltaBudgetChars: number;
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
   heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
@@ -564,6 +581,31 @@ export function effectiveOutputVisibility(
     ?? "normal";
 }
 
+/**
+ * Session / note keys shared with the other ClawChat agent channels (same
+ * hyphenated names, meaning and factory values as the Hermes plugin's
+ * `SESSION_INT_KEYS`). An out-of-range value is clamped to the nearest bound,
+ * a non-number falls back to the factory value. Every key here has a reader;
+ * the shared keys this plugin has no use for are listed in
+ * docs/clawchat-plugin-openclaw.md with the reason.
+ *   key -> [factory, minimum, maximum]
+ */
+export const SESSION_INT_KEYS = {
+  "note-cap-user": [1500, 300, 6000],
+  "note-cap-group": [2000, 300, 8000],
+  "note-cap-turn": [4000, 1000, 16000],
+  "delta-budget-chars": [8000, 2000, 32000],
+} as const satisfies Record<string, readonly [number, number, number]>;
+
+function readSessionInt(channel: Record<string, unknown>, key: keyof typeof SESSION_INT_KEYS): number {
+  const [factory, minimum, maximum] = SESSION_INT_KEYS[key];
+  const raw = channel[key];
+  const parsed =
+    typeof raw === "number" ? raw : typeof raw === "string" && raw.trim() ? Number(raw.trim()) : Number.NaN;
+  if (!Number.isFinite(parsed)) return factory;
+  return Math.max(minimum, Math.min(maximum, Math.trunc(parsed)));
+}
+
 function readReconnect(raw: unknown): Required<OpenclawClawlingReconnectConfig> {
   const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
   return {
@@ -693,6 +735,10 @@ export function resolveOpenclawClawlingAccount(
     awarenessNote,
     friendGreeting,
     livewareSample,
+    noteCapUser: readSessionInt(channel, "note-cap-user"),
+    noteCapGroup: readSessionInt(channel, "note-cap-group"),
+    noteCapTurn: readSessionInt(channel, "note-cap-turn"),
+    deltaBudgetChars: readSessionInt(channel, "delta-budget-chars"),
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),
     heartbeat: readHeartbeat(channel.heartbeat),

package/src/dm-recall-default.ts

@@ -0,0 +1,230 @@
+/**
+ * Turn off OpenClaw's cross-conversation recall for the agent ClawChat routes
+ * to, once, unless the owner already decided.
+ *
+ * OpenClaw >= 2026.8.1 has `memory.search.rememberAcrossConversations`. When it
+ * is not written anywhere, OpenClaw turns it on unless `session.dmScope` or a
+ * binding isolates DMs (`resolveRememberAcrossConversations`,
+ * packages/memory-host-sdk/src/host/config-utils.ts). The plugin isolates
+ * ClawChat DMs only in memory (`withClawChatSessionScope`), which OpenClaw
+ * cannot see, so recall stays on and a friend's DM can recall the owner's.
+ * Active Memory reads the live gateway config each turn, so a per-turn
+ * override does not reach it: the setting has to be in the config file.
+ *
+ * Where it is read (2026.8.1 / 2026.9.x): the agent's `agents.entries.<id>`
+ * or, when the roster is the legacy array, its `agents.list[]` entry (matched
+ * by `id`); then the global `memory.search`. With no roster in the file there
+ * is one implicit agent, so the global layer IS that agent's.
+ *
+ * Rules (relay openclaw-dm-recall, 10-08):
+ * - only on hosts >= 2026.8.1 (older ones have neither the key nor the recall);
+ * - only when neither layer sets it; an explicit `true` is the owner's choice:
+ *   kept, warned once; an explicit `false` is kept silently;
+ * - only once per agent: a marker in the plugin's state dir records it, so
+ *   whatever the owner changes later is never touched again.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const DM_RECALL_MARKER_FILENAME = "clawchat-dm-recall-default.json";
+export const DM_RECALL_MIN_HOST: readonly [number, number, number] = [2026, 8, 1];
+
+export type DmRecallOutcome =
+  | "wrote-false"
+  | "kept-true"
+  | "kept-false"
+  | "already-handled"
+  | "unsupported-host"
+  | "agent-not-in-roster"
+  | "write-failed";
+
+type Rec = Record<string, unknown>;
+
+type MutateConfigFile = (params: {
+  afterWrite: { mode: "none"; reason: string };
+  mutate: (draft: Rec) => void;
+}) => Promise<unknown>;
+
+type Log = {
+  info?: (msg: string) => void;
+  warn?: (msg: string) => void;
+  error?: (msg: string) => void;
+};
+
+function isRec(value: unknown): value is Rec {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeId(id: unknown): string {
+  return typeof id === "string" ? id.trim().toLowerCase() : "";
+}
+
+/** True for a release host >= 2026.8.1. Pre-releases and unknown strings are false. */
+export function hostHasRememberAcrossConversations(version: string | undefined | null): boolean {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec((version ?? "").trim());
+  if (!m) return false;
+  const parts = [Number(m[1]), Number(m[2]), Number(m[3])];
+  for (let i = 0; i < 3; i += 1) {
+    if (parts[i] !== DM_RECALL_MIN_HOST[i]) return parts[i] > DM_RECALL_MIN_HOST[i];
+  }
+  return true;
+}
+
+type AgentSlot =
+  | { kind: "entries"; key: string; entry: Rec }
+  | { kind: "list"; index: number; entry: Rec }
+  | { kind: "no-roster" }
+  | { kind: "missing" };
+
+function findAgentSlot(cfg: Rec, agentId: string): AgentSlot {
+  const agents = isRec(cfg.agents) ? cfg.agents : undefined;
+  const id = normalizeId(agentId);
+  if (agents && Object.hasOwn(agents, "entries") && agents.entries !== undefined) {
+    if (!isRec(agents.entries)) return { kind: "missing" };
+    for (const key of Object.keys(agents.entries)) {
+      const entry = agents.entries[key];
+      if (normalizeId(key) === id && isRec(entry)) return { kind: "entries", key, entry };
+    }
+    return { kind: "missing" };
+  }
+  if (agents && Object.hasOwn(agents, "list") && agents.list !== undefined) {
+    if (!Array.isArray(agents.list)) return { kind: "missing" };
+    const index = agents.list.findIndex((e) => isRec(e) && normalizeId(e.id) === id);
+    return index >= 0 ? { kind: "list", index, entry: agents.list[index] as Rec } : { kind: "missing" };
+  }
+  return { kind: "no-roster" };
+}
+
+function readFlag(holder: unknown): boolean | undefined {
+  if (!isRec(holder) || !isRec(holder.memory) || !isRec(holder.memory.search)) return undefined;
+  const v = holder.memory.search.rememberAcrossConversations;
+  return typeof v === "boolean" ? v : undefined;
+}
+
+/** The value written at each layer, `undefined` where it is not written. */
+export function readRememberAcrossConversations(
+  cfg: Rec,
+  agentId: string,
+): { agent: boolean | undefined; global: boolean | undefined } {
+  const slot = findAgentSlot(cfg, agentId);
+  const agent = slot.kind === "entries" || slot.kind === "list" ? readFlag(slot.entry) : undefined;
+  return { agent, global: readFlag(cfg) };
+}
+
+function setFlagFalse(holder: Rec): void {
+  const memory = isRec(holder.memory) ? holder.memory : {};
+  const search = isRec(memory.search) ? memory.search : {};
+  holder.memory = { ...memory, search: { ...search, rememberAcrossConversations: false } };
+}
+
+/**
+ * Write `rememberAcrossConversations: false` at the agent's own layer of
+ * `cfg` (mutated in place). Returns the dotted path written, or `null` when a
+ * roster exists but does not list the agent (nothing written).
+ */
+export function setAgentRememberAcrossConversationsFalse(cfg: Rec, agentId: string): string | null {
+  const slot = findAgentSlot(cfg, agentId);
+  if (slot.kind === "entries") {
+    setFlagFalse(slot.entry);
+    return `agents.entries.${slot.key}.memory.search`;
+  }
+  if (slot.kind === "list") {
+    setFlagFalse(slot.entry);
+    return `agents.list[${slot.index}].memory.search`;
+  }
+  if (slot.kind === "no-roster") {
+    setFlagFalse(cfg);
+    return "memory.search";
+  }
+  return null;
+}
+
+type Marker = { agents?: Record<string, { outcome: DmRecallOutcome; at: string }> };
+
+function readMarker(file: string): Marker {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+    return isRec(parsed) ? (parsed as Marker) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeMarker(file: string, agentId: string, outcome: DmRecallOutcome): void {
+  const marker = readMarker(file);
+  const agents = isRec(marker.agents) ? marker.agents : {};
+  agents[normalizeId(agentId)] = { outcome, at: new Date().toISOString() };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify({ ...marker, agents }, null, 2)}\n`);
+}
+
+/** Apply the one-time default. Never throws. */
+export async function applyDmRecallDefault(params: {
+  agentId: string;
+  hostVersion: string | undefined | null;
+  stateDir: string;
+  readConfig: () => unknown;
+  mutateConfigFile: MutateConfigFile;
+  log?: Log;
+}): Promise<DmRecallOutcome> {
+  const { agentId, log } = params;
+  const markerFile = path.join(params.stateDir, DM_RECALL_MARKER_FILENAME);
+  try {
+    if (readMarker(markerFile).agents?.[normalizeId(agentId)]) return "already-handled";
+    if (!hostHasRememberAcrossConversations(params.hostVersion)) return "unsupported-host";
+
+    const cfg = params.readConfig();
+    const current = readRememberAcrossConversations(isRec(cfg) ? cfg : {}, agentId);
+    const explicit = current.agent ?? current.global;
+    if (explicit === true) {
+      log?.warn?.(
+        `clawchat-plugin-openclaw: memory.search.rememberAcrossConversations is true for agent '${agentId}', so a ` +
+          "friend's ClawChat direct chat can recall what the owner said in theirs. Kept as set. To turn it off: " +
+          `openclaw config set memory.search.rememberAcrossConversations false (or set it to false on agent '${agentId}'), then restart the gateway.`,
+      );
+      writeMarker(markerFile, agentId, "kept-true");
+      return "kept-true";
+    }
+    if (explicit === false) {
+      writeMarker(markerFile, agentId, "kept-false");
+      return "kept-false";
+    }
+
+    if (findAgentSlot(isRec(cfg) ? cfg : {}, agentId).kind === "missing") {
+      log?.info?.(
+        `clawchat-plugin-openclaw: agent '${agentId}' is not in the agents roster; rememberAcrossConversations left unset`,
+      );
+      return "agent-not-in-roster";
+    }
+
+    let written: string | null = null;
+    let raced: boolean | undefined;
+    await params.mutateConfigFile({
+      afterWrite: { mode: "none", reason: "clawchat-plugin-openclaw: no recall across ClawChat direct chats" },
+      mutate(draft) {
+        // Re-check on the locked, current file: someone may have set it meanwhile.
+        const now = readRememberAcrossConversations(draft, agentId);
+        raced = now.agent ?? now.global;
+        if (raced !== undefined) return;
+        written = setAgentRememberAcrossConversationsFalse(draft, agentId);
+      },
+    });
+    if (written === null) {
+      if (raced === undefined) return "agent-not-in-roster";
+      const outcome: DmRecallOutcome = raced ? "kept-true" : "kept-false";
+      writeMarker(markerFile, agentId, outcome);
+      return outcome;
+    }
+    writeMarker(markerFile, agentId, "wrote-false");
+    log?.info?.(
+      `clawchat-plugin-openclaw: set ${written}.rememberAcrossConversations=false for agent '${agentId}' ` +
+        "(ClawChat direct chats with different people no longer recall each other)",
+    );
+    return "wrote-false";
+  } catch (err) {
+    log?.error?.(
+      `clawchat-plugin-openclaw: could not apply the rememberAcrossConversations default for agent '${agentId}': ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return "write-failed";
+  }
+}