@hyperspell/openclaw-hyperspell 0.17.1 → 0.19.0

package/README.md

@@ -102,6 +102,27 @@ Check your current configuration and connection status.
 
 Open the Hyperspell connect page to link your accounts (Notion, Slack, Google Drive, etc.). After connecting, your sources are automatically updated in the config.
 
+### `openclaw openclaw-hyperspell purge-channel <channelId>`
+
+Find — and with `--yes`, delete — memories that were synced from a specific conversation/channel. Use it for retroactive cleanup after adding a channel to `excludeChannels`, which is [forward-only](#excludechannels-is-forward-only).
+
+```
+openclaw openclaw-hyperspell purge-channel 1521620672726438171          # dry run: list what would be deleted
+openclaw openclaw-hyperspell purge-channel 1521620672726438171 --yes    # actually delete
+```
+
+| Flag | Description |
+|------|-------------|
+| `--source <sources>` | Comma-separated Hyperspell sources to scan. Default `vault` — the hot-buffer consolidation target and default `hotBuffer.source`. |
+| `--user <userId>` | `X-As-User` to scan/delete under. Default: the configured `userId`. In `multiUser` deployments, run once per mapped userId. |
+| `--session <ids>` | Comma-separated OpenClaw session ids — matches legacy **untagged** hot-buffer resources through the `resource_id === session id` identity. |
+| `--resource <ids>` | Explicit resource ids to delete (escape hatch for traces or `/remember` memories you identified manually, e.g. via `hyperspell_search`). |
+| `--yes` | Actually delete. Without it the command is a **dry run** that prints the matches and exits. |
+
+Matching uses the same semantics as the quarantine check itself: exact id or thread suffix (`<channelId>:...`), case-insensitive. Discovery enumerates memories and filters client-side on the `openclaw_channel_id` metadata tag — deleted rows are reported per resource, and a resource that is already gone counts as deleted.
+
+**Finding session ids for `--session`:** OpenClaw session keys embed the conversation id (`agent:<agentId>:<provider>:channel:<channelId>[...]` — the same format the plugin's quarantine matching parses). Look up the quarantined conversation's sessions in OpenClaw's session store and pass their session ids; each hot-buffer resource id equals its session id.
+
 ## Configuration Options
 
 | Option | Type | Default | Description |
@@ -109,9 +130,12 @@ Open the Hyperspell connect page to link your accounts (Notion, Slack, Google Dr
 | `apiKey` | string | `${HYPERSPELL_API_KEY}` | Hyperspell API key |
 | `userId` | string | - | User ID for multi-tenant memory (can be your email) |
 | `autoContext` | boolean | `true` | Auto-inject relevant memories before each AI turn |
+| `emotionalContext` | boolean | `false` | Persist an emotional-state register at session end and inject the recent arc at session start |
+| `moodWeatherChance` | number | `0` | Probability (0–1) that a fresh session rolls exogenous "mood weather". `0` disables. Suggested starting value: `0.03`–`0.05` — rare enough to read as weather, not a gimmick. Requires `emotionalContext`. |
 | `syncMemories` | boolean | `false` | Sync markdown files in `workspace/memory/` to Hyperspell |
 | `sources` | string | - | Comma-separated sources to search (e.g., `vault,notion,slack`) |
 | `maxResults` | number | `10` | Maximum memories per context injection |
+| `excludeChannels` | string[] | `[]` | Conversation/channel ids fully quarantined from memory: no context injection, no memory writes, no memory tools. Threads inherit. **Forward-only** — see [below](#excludechannels-is-forward-only). |
 | `debug` | boolean | `false` | Enable verbose logging |
 | `dreaming.enabled` | boolean | `false` | Allow `memory-core` to sidecar-load so Dreaming can consolidate local session transcripts into `workspace/MEMORY.md`. See [Running alongside Dreaming](#running-alongside-dreaming). |
 
@@ -141,6 +165,16 @@ Manually sync all markdown files in `workspace/memory/` to Hyperspell.
 /sync
 ```
 
+### `/previewcontext`
+
+Show exactly what Hyperspell would inject at the start of the next session — the emotional-context arc, the auto-context setting, and the startup-orientation blocks — without starting a session or touching any session state. Read-only and idempotent: run it twice and you get the same report.
+
+Mood weather is shown as its configured chance only (e.g. "configured chance 8% per session") and is **never rolled by the preview** — each real session rolls independently at injection time, so the actual mood (if any) is only observable in the live session.
+
+```
+/previewcontext
+```
+
 ## Memory Sync
 
 When `syncMemories: true`, the plugin syncs markdown files from your agent's workspace memory directory (e.g., `~/.openclaw/workspace/memory/`) to Hyperspell. This includes all `.md` files in subdirectories.
@@ -186,6 +220,7 @@ The plugin registers tools that the AI can use autonomously:
 
 - **hyperspell_search** - Search through connected sources
 - **hyperspell_remember** - Save information to memory
+- **hyperspell_emotional_arc** - Re-fetch the recent emotional arc mid-conversation (requires `emotionalContext: true`); returns the same block injected at session start, e.g. after compaction removed it
 
 ## Auto-Context
 
@@ -197,6 +232,17 @@ When `autoContext: true` (default), the plugin automatically:
 
 This ensures the AI always has access to relevant information from your connected sources.
 
+### `excludeChannels` is forward-only
+
+Adding a channel to `excludeChannels` stops all future injection/writes/tools for that conversation, but does **not** remove content that was synced before the channel was quarantined.
+
+- **Hot-buffer content** written by plugin versions since 2026-07 is tagged with `openclaw_channel_id` and can be removed with [`openclaw openclaw-hyperspell purge-channel <id>`](#openclaw-openclaw-hyperspell-purge-channel-channelid). Older hot-buffer rows are untagged, but each row's resource id equals its OpenClaw session id, so they are reachable via the purge command's `--session` flag.
+- **Auto-trace resources and `/remember` memories** written by current versions carry the same `openclaw_channel_id` tag going forward. Ones written by older versions are not channel-tagged and cannot be automatically purged — identify them manually (e.g. via `hyperspell_search`) and use the purge command's `--resource` escape hatch.
+- **Emotional-state registers** are keyed by relationship, not channel, and live behind the `/emotional-state` API rather than the memories store this command scans — they are never matched by `purge-channel`, and deletion of them is per-relationship, all-or-nothing. (Newer plugin versions tag registers with a `channelId` metadata field for analysis, but that does not make them purgeable per channel.)
+- **Server-side extractions** derived from traces (`extract: ["procedure", "memory", "mood"]`) are created backend-side; whether deleting the parent trace removes them is an open backend question (see `docs/hyperspell-backend-followups.md`).
+
+The purge command prints these standing limitations on every run.
+
 ## Available Sources
 
 ### Documents & Storage

package/dist/commands/preview.js

@@ -0,0 +1,93 @@
+import { buildEmotionalContext, fetchRecentOrLatest, looksLikeRawTranscript, } from "../hooks/emotional-state.js";
+import { gatherOrientation, personalUserId } from "../hooks/startup-orientation.js";
+import { isExcludedChannel } from "../lib/exclude-channels.js";
+import { log } from "../logger.js";
+/**
+ * Assemble a read-only report of what before_agent_start WOULD inject at the
+ * start of the next session. Calls only the pure fetch/format functions the
+ * real hooks are composed from — never the hook handlers themselves — so it
+ * cannot touch the inject-once session caches, and it never calls rollMood
+ * (a debug command must not consume or reveal a mood roll; the roll happens
+ * once, in the real injection path, per session).
+ */
+export async function buildPreviewReport(client, cfg, ctx) {
+    // Quarantined channels get no injected memory of any kind (index.ts guards
+    // before_agent_start with the same check) — report that instead of a bundle.
+    if (isExcludedChannel({ channelId: ctx.channel }, cfg)) {
+        return "This channel is quarantined (excludeChannels): no context would be injected here and no memory would be written.";
+    }
+    const sections = [];
+    // ---- 1. Emotional context (registration order in index.ts: first) ----
+    if (!cfg.emotionalContext) {
+        sections.push("Emotional context: OFF (emotionalContext=false) — no register/arc would be injected.");
+    }
+    else {
+        try {
+            const states = await fetchRecentOrLatest(client, cfg);
+            const usable = states.filter((s) => s.summary && !looksLikeRawTranscript(s.summary));
+            if (usable.length > 0) {
+                const pending = states.length - usable.length;
+                const pendingNote = pending > 0
+                    ? `\n(${pending} more register(s) still extracting — excluded, same as the real hook.)`
+                    : "";
+                sections.push(`Emotional context: would inject ${usable.length} register(s):\n\n${buildEmotionalContext(usable)}${pendingNote}`);
+            }
+            else if (states.length > 0) {
+                sections.push("Emotional context: register(s) exist but are still extracting (raw-transcript placeholder) — the real hook would skip this turn and retry next turn.");
+            }
+            else {
+                sections.push("Emotional context: ON, but no prior emotional state found — nothing to inject yet (first conversation, or register deleted).");
+            }
+        }
+        catch (err) {
+            log.error("/previewcontext: emotional fetch failed", err);
+            sections.push("Emotional context: fetch FAILED — the real hook would log this and inject nothing. Check logs.");
+        }
+        // Mood weather: report configuration only. Deliberately NOT rolled — see
+        // function doc comment. Preview must be idempotent and non-revealing.
+        sections.push(cfg.moodWeatherChance > 0
+            ? `Mood weather: configured chance ${Math.round(cfg.moodWeatherChance * 100)}% per session — NOT rolled by this preview. Each real session rolls independently at injection time; the actual mood (if any) is only observable in the live session.`
+            : "Mood weather: OFF (moodWeatherChance=0).");
+    }
+    // ---- 2. Auto-context (second in registration order) ----
+    sections.push(cfg.autoContext
+        ? "Auto-context: ON — will search memories using the text of your next message. Query-dependent, so not previewable here; use /getcontext <your message> to simulate."
+        : "Auto-context: OFF.");
+    // ---- 3. Startup orientation (third in registration order) ----
+    const so = cfg.startupOrientation;
+    if (!so.enabled) {
+        sections.push("Startup orientation: OFF (startupOrientation.enabled=false).");
+    }
+    else {
+        const { skip, userId } = personalUserId(cfg, ctx);
+        if (skip) {
+            sections.push("Startup orientation: ON, but you are an unknown sender in multi-user mode — the real hook would skip injection for you.");
+        }
+        else {
+            const g = await gatherOrientation(client, cfg, userId);
+            const parts = [];
+            if (g.recentSource === "none") {
+                parts.push("recent-interactions: no source (hotBuffer and autoTrace both off) — block would be empty.");
+            }
+            else if (!g.recentOk) {
+                parts.push(`recent-interactions: fetch FAILED (source=${g.recentSource}) — real hook would retry next turn.`);
+            }
+            else {
+                parts.push(g.recentBlock ?? `recent-interactions: source=${g.recentSource}, 0 results — block omitted.`);
+            }
+            if (!g.loopsOk) {
+                parts.push("unfinished-loops: search FAILED — real hook would retry next turn.");
+            }
+            else {
+                parts.push(g.loopsBlock ??
+                    `unfinished-loops: 0 results for loopsQuery ("${so.loopsQuery}") — block omitted.`);
+            }
+            sections.push(`Startup orientation: ON.\n\n${parts.join("\n\n")}`);
+        }
+    }
+    return [
+        "What the next session would inject (read-only preview — no session state touched, no mood rolled):",
+        "",
+        sections.join("\n\n---\n\n"),
+    ].join("\n");
+}

package/dist/commands/purge-channel.js

@@ -0,0 +1,54 @@
+import { conversationMatchesChannel } from "../lib/exclude-channels.js";
+/**
+ * Enumerate the given sources and return every memory attributable to
+ * `channelId` — via the `openclaw_channel_id` metadata tag (exact or
+ * thread-suffix, same semantics as the quarantine check), or via the
+ * hot-buffer `resourceId === sessionId` identity for legacy untagged rows.
+ */
+export async function findChannelMemories(client, channelId, opts) {
+    const matches = [];
+    const sessionIds = new Set((opts.sessionIds ?? []).map((s) => s.toLowerCase()));
+    for (const source of opts.sources) {
+        for await (const m of client.listMemories({ source, userId: opts.userId })) {
+            const tagged = m.metadata.openclaw_channel_id;
+            if (typeof tagged === "string" && conversationMatchesChannel(tagged, channelId)) {
+                matches.push({ resourceId: m.resourceId, source: m.source, title: m.title, via: "channel_tag" });
+            }
+            else if (sessionIds.has(m.resourceId.toLowerCase())) {
+                // Hot-buffer resource_id === sessionId — rows written before channel
+                // tagging existed are reachable only through this identity.
+                matches.push({ resourceId: m.resourceId, source: m.source, title: m.title, via: "session_id" });
+            }
+        }
+    }
+    return matches;
+}
+/** Delete every match. `deleteMemory` is already 404-tolerant (absent = deleted). */
+export async function deleteMatches(client, matches, opts) {
+    let deleted = 0;
+    let failed = 0;
+    for (const m of matches) {
+        const r = await client.deleteMemory(m.resourceId, { source: m.source, userId: opts.userId });
+        if (r.deleted)
+            deleted++;
+        else
+            failed++;
+    }
+    return { matched: matches, deleted, failed };
+}
+/** Render matches as an aligned `resourceId  source  via  title` table. */
+export function formatMatchTable(matches) {
+    const rows = [
+        ["RESOURCE ID", "SOURCE", "VIA", "TITLE"],
+        ...matches.map((m) => [m.resourceId, m.source, m.via, m.title ?? "-"]),
+    ];
+    const widths = [0, 1, 2].map((i) => Math.max(...rows.map((r) => r[i].length)));
+    return rows
+        .map((r) => `${r[0].padEnd(widths[0])}  ${r[1].padEnd(widths[1])}  ${r[2].padEnd(widths[2])}  ${r[3]}`)
+        .join("\n");
+}
+/** Standing limitations — printed on every run so operators aren't surprised. */
+export const PURGE_LIMITATIONS_FOOTER = "Note: not everything is channel-tagged. Auto-trace resources and /remember memories written by older plugin versions, " +
+    "hot-buffer rows written before 2026-07, and emotional-state registers are NOT matched by this command. " +
+    "Use --session for legacy hot-buffer rows and --resource for manually identified resources; " +
+    'see the "excludeChannels is forward-only" section of the README.';

package/dist/commands/setup.js

@@ -12,6 +12,7 @@ import { getWorkspaceDir, parseConfig, resolveConfigPath } from "../config.js";
 import { buildExtractionPrompt, CRON_JOB_NAME } from "../graph/cron.js";
 import { NetworkStateManager } from "../graph/state.js";
 import { scanMemories, formatScanResults, completeMemories } from "../graph/ops.js";
+import { deleteMatches, findChannelMemories, formatMatchTable, PURGE_LIMITATIONS_FOOTER, } from "./purge-channel.js";
 async function fetchConnectionSources(client, userId) {
     try {
         const userClient = new Hyperspell({
@@ -277,6 +278,8 @@ async function runSetup() {
                     writeAssistant: true,
                 },
                 emotionalContext: false,
+                moodWeatherChance: 0,
+                excludeChannels: [],
                 syncMemories: true,
                 syncMemoriesConfig: {
                     enabled: true,
@@ -522,6 +525,54 @@ export function registerCliCommands(program, pluginConfig) {
         .action(async () => {
         await runConnect(pluginConfig);
     });
+    // Retroactive cleanup for quarantined channels. Dry run by default — no
+    // interactive prompt, so it stays usable from cron/exec like `network`.
+    hyperspellCmd
+        .command("purge-channel <channelId>")
+        .description("Find (and with --yes delete) memories synced from a channel — retroactive cleanup for excludeChannels, which is forward-only")
+        .option("--source <sources>", "Comma-separated Hyperspell sources to scan (default: vault, the hot-buffer consolidation target)", "vault")
+        .option("--user <userId>", "X-As-User to scan/delete under (default: configured userId). In multiUser deployments run once per mapped userId.")
+        .option("--session <ids>", "Comma-separated OpenClaw session ids — matches legacy untagged hot-buffer resources (resource_id === session id)")
+        .option("--resource <ids>", "Comma-separated explicit resource ids to include (escape hatch for traces / remember memories identified manually)")
+        .option("--yes", "Actually delete. Without this flag the command is a dry run.")
+        .action(async (channelId, opts) => {
+        const splitCsv = (v) => typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
+        try {
+            const cfg = parseConfig(pluginConfig);
+            const client = new HyperspellClient(cfg);
+            const sources = splitCsv(opts.source).map((s) => s.toLowerCase());
+            const userId = opts.user ?? cfg.userId;
+            const matches = await findChannelMemories(client, channelId, {
+                sources: sources.length > 0 ? sources : ["vault"],
+                userId,
+                sessionIds: splitCsv(opts.session),
+            });
+            // Explicit ids are operator-asserted; append any not already found.
+            const found = new Set(matches.map((m) => m.resourceId));
+            for (const id of splitCsv(opts.resource)) {
+                if (!found.has(id)) {
+                    matches.push({ resourceId: id, source: sources[0] ?? "vault", title: null, via: "explicit" });
+                }
+            }
+            if (matches.length === 0) {
+                process.stdout.write(`No memories matched channel ${channelId}.\n\n${PURGE_LIMITATIONS_FOOTER}\n`);
+                return;
+            }
+            process.stdout.write(formatMatchTable(matches) + "\n\n");
+            if (!opts.yes) {
+                process.stdout.write(`Dry run: ${matches.length} memor${matches.length === 1 ? "y" : "ies"} would be deleted. Re-run with --yes to delete.\n\n${PURGE_LIMITATIONS_FOOTER}\n`);
+                return;
+            }
+            const result = await deleteMatches(client, matches, { userId });
+            process.stdout.write(`Deleted ${result.deleted} of ${result.matched.length} matched memories (${result.failed} failed).\n\n${PURGE_LIMITATIONS_FOOTER}\n`);
+            if (result.failed > 0)
+                process.exit(1);
+        }
+        catch (err) {
+            process.stderr.write(`Purge failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
     // Memory Network CLI commands (used by isolated cron sessions via exec)
     const networkCmd = hyperspellCmd
         .command("network")

package/dist/commands/slash.js

@@ -2,6 +2,7 @@ import { getWorkspaceDir } from "../config.js";
 import { buildScopeFilter, getCanReadScopes, getDefaultWriteScope, resolveRole, resolveUser, routeWrite, } from "../lib/sender.js";
 import { log } from "../logger.js";
 import { syncAllMemoryFiles } from "../sync/markdown.js";
+import { buildPreviewReport } from "./preview.js";
 /**
  * Strip a `#scope-name` prefix from free text. Returns the scope and the
  * remainder. Used by /remember and /getcontext to let users narrow or route
@@ -156,4 +157,21 @@ export function registerCommands(api, client, cfg) {
             }
         },
     });
+    // /previewcontext - Show what would be injected into the next session
+    api.registerCommand({
+        name: "previewcontext",
+        description: "Preview what Hyperspell would inject at the next session start",
+        acceptsArgs: false,
+        requireAuth: true,
+        handler: async (ctx) => {
+            log.debug("/previewcontext command");
+            try {
+                return { text: await buildPreviewReport(client, cfg, ctx) };
+            }
+            catch (err) {
+                log.error("/previewcontext failed", err);
+                return { text: "Failed to build preview. Check logs for details." };
+            }
+        },
+    });
 }

package/dist/config.js

@@ -18,6 +18,8 @@ const ALLOWED_KEYS = [
     "autoTrace",
     "hotBuffer",
     "emotionalContext",
+    "moodWeatherChance",
+    "excludeChannels",
     "relationshipId",
     "startupOrientation",
     "syncMemories",
@@ -301,6 +303,14 @@ export function parseConfig(raw) {
             writeAssistant: hbRaw.writeAssistant ?? true,
         },
         emotionalContext: cfg.emotionalContext ?? false,
+        // Default 0 (off) so shipping never changes existing installs' behavior.
+        // Clamped to [0,1] so a stray config value can't make every session roll.
+        moodWeatherChance: Math.min(1, Math.max(0, cfg.moodWeatherChance ?? 0)),
+        excludeChannels: Array.isArray(cfg.excludeChannels)
+            ? cfg.excludeChannels
+                .map((c) => String(c).trim())
+                .filter((c) => c.length > 0)
+            : [],
         relationshipId: cfg.relationshipId,
         startupOrientation: {
             enabled: soRaw.enabled ?? false,

package/dist/hooks/auto-context.js

@@ -1,8 +1,10 @@
+import { appendFileSync } from "node:fs";
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
-import { rerank, selectRanked } from "../lib/ranking.js";
+import { explainSelection, rerank, } from "../lib/ranking.js";
 import { classifySearchError, logSearchError } from "../lib/search-error.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
+import { recordSender, senderIdFromCtx } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
 function formatRelativeTime(isoTimestamp) {
     try {
@@ -78,6 +80,49 @@ function formatSelected(selected, threshold) {
         return null;
     return sections.join("\n\n");
 }
+/**
+ * Opt-in score sampling for relevanceThreshold tuning (proposal 02 §3b).
+ * Writes one JSONL line per candidate when HYPERSPELL_SCORE_LOG names a file;
+ * review/analyze with docs/score-review.mjs and docs/score-analyze.mjs.
+ *
+ * The lines carry an 80-char prompt prefix and memory snippets — sensitive
+ * plaintext on disk — so this is OFF by default and never config-driven:
+ * it writes nothing unless the operator explicitly sets the env var (setting
+ * it IS the opt-in), and the log should be deleted after the tuning window.
+ * The env var is read at call time (not module load) so tests can set it.
+ * Must never throw into the retrieval path.
+ */
+function logScoreSamples(prompt, sessionId, scope, explained, threshold) {
+    const path = process.env.HYPERSPELL_SCORE_LOG;
+    if (!path || explained.length === 0)
+        return;
+    const ts = new Date().toISOString();
+    const lines = explained.map((e) => {
+        const r = e.result;
+        const top = [...r.highlights].sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0];
+        return JSON.stringify({
+            ts,
+            sessionId,
+            scope,
+            prompt: prompt.slice(0, 80),
+            resourceId: r.resourceId,
+            title: (r.title ?? "").slice(0, 60),
+            kind: r._kind,
+            base: Number(r._base.toFixed(4)),
+            composite: Number(r._composite.toFixed(4)),
+            threshold,
+            selected: e.selected,
+            cut: e.cut,
+            snippet: (top?.text ?? "").replace(/\s+/g, " ").slice(0, 120),
+        });
+    });
+    try {
+        appendFileSync(path, `${lines.join("\n")}\n`);
+    }
+    catch {
+        // instrumentation must never break retrieval
+    }
+}
 const INTRO = "The following is surfaced from the user's memory and connected sources, including past conversations. Reference it as recalled context, only when relevant to the conversation.";
 const DISCLAIMER = "Draw on it when relevant — including indirect connections — but don't force it into every response or make assumptions beyond what's stated.";
 // A short, CONDITIONAL reminder appended only to a real memory block (not a
@@ -85,10 +130,22 @@ const DISCLAIMER = "Draw on it when relevant — including indirect connections
 // search-as-ritual; the agent's own instructions carry the standing rule). The
 // point here is just: what surfaced is a passive match, not all of memory.
 const SEARCH_REMINDER = "This is a passive match, not all of memory — if the answer turns on a specific past decision, promise, name, or something recorded, search for it directly before concluding, and say so plainly if it isn't there.";
+// Explicit authority precedence: live sender metadata outranks surfaced memory
+// for identity questions. Without this, a high-scoring memory naming a different
+// person than the live sender can silently override who the agent thinks it is
+// talking to — the identity-bleed failure observed live (issue #58).
+// Two carve-outs (issue #59 follow-up):
+//   (1) A memory about the CURRENT sender's own past is not a conflict — use it
+//       as recalled personal context. The guard only applies when the identity in
+//       the memory is clearly a different person from the live sender.
+//   (2) Display names and handles often differ across sessions (e.g. "dithilli"
+//       vs "David S"). Use judgment to identify whether a retrieved name refers
+//       to the current speaker before applying the guard.
+const AUTHORITY_GUARD = "AUTHORITY: The live conversation's sender and session metadata always outrank this recalled context for identity — who is speaking right now, their name, role, or relationship. If a surfaced memory names a different person than the current sender, treat it as historical context about someone else, not a description of the current speaker. Do not adopt a persona, name, or backstory from recalled memory that conflicts with the live sender. Exception: a memory about the current sender's own past (their preferences, history, emotional state) is not a conflict — use it as recalled personal context. Display names and handles may differ across sessions; use judgment to identify whether a retrieved name refers to the current speaker before applying this guard.";
 /** Wrap a real memory block. No memory → no injection (caller returns nothing);
  * the standing search rule lives in the agent's own instructions, not here. */
 function wrapContext(memorySection) {
-    return `<hyperspell-context>\n${INTRO}\n\n${memorySection}\n\n${DISCLAIMER}\n\n${SEARCH_REMINDER}\n</hyperspell-context>`;
+    return `<hyperspell-context>\n${INTRO}\n\n${AUTHORITY_GUARD}\n\n${memorySection}\n\n${DISCLAIMER}\n\n${SEARCH_REMINDER}\n</hyperspell-context>`;
 }
 /**
  * Drop results belonging to the CURRENT session. The hot buffer writes the live
@@ -119,6 +176,11 @@ export function buildAutoContextHandler(client, cfg) {
         // The live session's own just-written turns must not be surfaced back as
         // "recalled memory" (issue #42) — resolve its id once and exclude it below.
         const currentSessionId = resolveCurrentSessionId(event, ctx);
+        // Record the current sender so the speaker-tracker can detect multi-speaker
+        // sessions before any tool calls fire this turn (hot-buffer records on
+        // agent_end, which is too late for tools executed mid-turn).
+        if (currentSessionId)
+            recordSender(currentSessionId, senderIdFromCtx(ctx));
         // Multi-user path
         if (cfg.multiUser) {
             const resolved = resolveUser(ctx, cfg);
@@ -139,11 +201,27 @@ export function buildAutoContextHandler(client, cfg) {
                 const ranked = rerank(results, ranking);
                 // Threshold + chatter quota applied here, so a high-similarity echo can
                 // inform but never flood (the quota bounds count; the penalty bounds rank).
-                const selected = selectRanked(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota);
+                const explained = explainSelection(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota);
+                logScoreSamples(prompt, currentSessionId, "single", explained, cfg.relevanceThreshold);
+                const selected = explained.filter((e) => e.selected).map((e) => e.result);
+                // Cut-reason visibility (proposal 02, absorbs proposal 03): logged
+                // BEFORE the `formatted` check so quota drops stay visible even when
+                // nothing is injected (e.g. chatterQuota 0 with only chatter clearing
+                // the threshold). Stable "auto-context: cut" prefix for log greps.
+                // flatMap (not filter) so TS narrows to the cut member of the union.
+                const cuts = explained.flatMap((e) => (e.selected ? [] : [e]));
+                if (cuts.length > 0) {
+                    const cutTally = cuts.reduce((acc, e) => ((acc[e.cut] = (acc[e.cut] ?? 0) + 1), acc), {});
+                    const topQuotaDrop = cuts.find((e) => e.cut === "chatter-quota");
+                    const quotaNote = topQuotaDrop
+                        ? `, top quota-dropped composite ${topQuotaDrop.result._composite.toFixed(2)}`
+                        : "";
+                    log.debug(`auto-context: cut ${cuts.length} of ${ranked.length} candidates ${JSON.stringify(cutTally)}${quotaNote}`);
+                }
                 formatted = formatSelected(selected, cfg.relevanceThreshold);
                 if (formatted) {
                     const tally = selected.reduce((acc, r) => ((acc[r._kind] = (acc[r._kind] ?? 0) + 1), acc), {});
-                    log.debug(`auto-context: injecting (ranked) ${JSON.stringify(tally)} from ${results.length} candidates (chatter cap ${ranking.chatterQuota})`);
+                    log.debug(`auto-context: injecting (ranked) ${JSON.stringify(tally)} from ${results.length} candidates (chatter cap ${ranking.chatterQuota}, composite ${selected.at(-1)?._composite.toFixed(2)}–${selected[0]?._composite.toFixed(2)})`);
                 }
             }
             else {
@@ -170,6 +248,10 @@ export function buildAutoContextHandler(client, cfg) {
         }
     };
 }
+// Score logging / cut attribution (proposal 02) applies to the ranked
+// single-user path only: this path never runs rerank/explainSelection, so
+// there is no composite score to attribute. If ranking ever lands here, call
+// logScoreSamples with scope "personal" / "shared" per search.
 async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId) {
     const multiUser = cfg.multiUser;
     const isKnownSender = !!resolved?.resolved;
@@ -256,7 +338,7 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
         if (isKnownSender && resolved) {
             const contextLine = resolved.context ? ` ${resolved.context}` : "";
             return {
-                prependContext: `<hyperspell-context>\nYou are speaking with ${resolved.name}.${contextLine}\n</hyperspell-context>`,
+                prependContext: `<hyperspell-context>\nYou are speaking with ${resolved.name}.${contextLine}\n\n${AUTHORITY_GUARD}\n</hyperspell-context>`,
             };
         }
         return;
@@ -264,6 +346,6 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     const totalCount = personalResults.length + sharedResults.length;
     log.debug(`auto-context: injecting ${totalCount} memories (${personalResults.length} personal, ${sharedResults.length} shared)`);
     return {
-        prependContext: `<hyperspell-context>\n${sections.join("\n\n")}\n\n${DISCLAIMER}\n</hyperspell-context>`,
+        prependContext: `<hyperspell-context>\n${sections.join("\n\n")}\n\n${AUTHORITY_GUARD}\n\n${DISCLAIMER}\n</hyperspell-context>`,
     };
 }

package/dist/hooks/auto-trace.js

@@ -1,7 +1,11 @@
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
 import { resolveUser } from "../lib/sender.js";
+import { isMultiSpeaker } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
 const MIN_MESSAGES = 3;
 const MIN_CONVERSATION_LENGTH = 100;
+/** Sessions where we've already emitted the group-chat attribution warning. */
+const warnedGroupTraceSessions = new Set();
 /**
  * Strip transport/injection metadata from a text blob before it's stored as a
  * trace memory. Without this the auto-context and emotional-state hooks'
@@ -110,8 +114,22 @@ export function buildAutoTraceHandler(client, cfg) {
             log.debug(`auto-trace: skipping — conversation too short (${estimate} chars)`);
             return;
         }
-        const sessionId = event.sessionId ?? crypto.randomUUID();
+        // The session id lives on the hook CONTEXT, not the agent_end event (same
+        // contract issue #42 hit in hot-buffer): reading only event.sessionId
+        // yields a fresh random UUID per turn, which breaks multi-speaker
+        // detection keying and makes the openclaw_session_id tag useless for
+        // cleanup. Prefer ctx; keep event/random as fallbacks.
+        const sessionId = ctx?.sessionId ??
+            event.sessionId ??
+            crypto.randomUUID();
         const history = messagesToJSONL(messages, sessionId);
+        // Warn once per session when multiple speakers have no multiUser config:
+        // all turns collapse into a single undifferentiated trace under cfg.userId.
+        // Uses both is_group_chat and sender_id drift detection (issue #59).
+        if (isMultiSpeaker(sessionId, ctx?.is_group_chat === true) && !cfg.multiUser && !warnedGroupTraceSessions.has(sessionId)) {
+            warnedGroupTraceSessions.add(sessionId);
+            log.warn("auto-trace: multi-speaker session detected but multiUser is not configured — trace will mix all speakers under cfg.userId with no attribution (see issues #58/#59)");
+        }
         // Title from first user message
         const firstUser = messages.find((m) => m.role === "user");
         const title = firstUser?.content
@@ -121,12 +139,22 @@ export function buildAutoTraceHandler(client, cfg) {
         // Falls back to sharedUserId for unknown senders (or undefined in single-user mode).
         const resolved = resolveUser(ctx, cfg);
         const userId = resolved?.userId;
+        // Tag traces with the conversation they came from. channelIdFromCtx is the
+        // same resolver the quarantine check uses, so tag-time identity matches
+        // quarantine-time identity — the purge-channel CLI relies on that parity.
+        // session_id is a first-class trace field but is NOT exposed by
+        // listMemories, so it's mirrored into metadata for enumeration.
+        const channelId = channelIdFromCtx(ctx);
         try {
             const result = await client.sendTrace(history, {
                 sessionId,
                 title,
                 extract: cfg.autoTrace.extract,
-                metadata: cfg.autoTrace.metadata,
+                metadata: {
+                    ...cfg.autoTrace.metadata,
+                    ...(channelId ? { openclaw_channel_id: channelId } : {}),
+                    openclaw_session_id: sessionId,
+                },
                 userId,
                 // Auto-trace captures full conversation text — the most sensitive class
                 // of memory. Default to private; users opt into family-visible recall