@hyperspell/openclaw-hyperspell 0.18.1 → 0.20.0

package/README.md

@@ -102,6 +102,34 @@ 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.
+
+### `openclaw openclaw-hyperspell network scan|complete|sync`
+
+Memory Network primitives, used by the extraction cron's isolated session (and handy for
+manual dry-runs — `scan` is read-only). `scan` lists unprocessed memories with content
+summaries, `complete --ids <ids>` marks them processed, `sync` pushes `memory/` entity
+files back to Hyperspell.
+
 ## Configuration Options
 
 | Option | Type | Default | Description |
@@ -109,12 +137,23 @@ 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 |
-| `debug` | boolean | `false` | Enable verbose logging |
+| `relevanceThreshold` | number | `0.6` | Minimum (composite) score a memory needs to be injected by auto-context |
+| `ranking` | object | see below | Composite re-ranking of auto-context results — see [Composite ranking](#composite-ranking--surfacing-your-active-work) |
+| `ranking.storyTerms` | string[] | `[]` | **Off until you set it.** Words/phrases identifying your active creative work, so it outranks conversation chatter (matched at word boundaries, case-insensitive) |
+| `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). |
+| `knowledgeGraph.enabled` | boolean | `false` | Memory Network: extract entities (people, projects, organizations, topics) from memories into `memory/` markdown files. See [Memory Network](#memory-network). |
+| `knowledgeGraph.scanIntervalMinutes` | number | `60` | Extraction cadence the setup wizard bakes into the cron job it creates. The cron job is the runtime source of truth — to change cadence after setup, edit the cron job (and keep this field in sync). |
+| `knowledgeGraph.batchSize` | number | `20` | Memories per extraction scan batch |
+| `debug` | boolean | `false` | Enable diagnostic logging. One-line diagnostics (auto-context ranked/cut/injection summaries, orientation and emotional-context injection counts) are emitted at **info** level, so they appear in `gateway.log` at default host log levels — no host `logging.level` change needed. Verbose output (per-request/response dumps, per-candidate score lines) stays at debug level. |
 | `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). |
 
+Stored emotional-state registers (`emotionalContext`) are fetchable by external processes (e.g. a nightly consolidator reconciling its own day-read) — the verified fetch contract lives in [docs/emotional-state-external-reconciliation.md](docs/emotional-state-external-reconciliation.md).
+
 ## Slash Commands
 
 ### `/getcontext <query>`
@@ -141,6 +180,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.
@@ -154,18 +203,25 @@ When `syncMemories: true`, the plugin syncs markdown files from your agent's wor
 - Startup sync runs in the **background** — the agent boots immediately and sync proceeds without blocking it
 - A per-section content hash is tracked in `<workspace>/.hyperspell-sync-hashes.json`, so unchanged sections are skipped on subsequent syncs (no re-ingestion)
 
+**Provenance:** every synced memory carries an `openclaw_sync_source` metadata key recording where the content came from: `"memory"` for files under `memory/`, and the watchPath's `source` label (or a slug derived from its path, e.g. `notes/brainstem` → `notes_brainstem`) for watchPath files. This lets retrieval distinguish curated memory files from machine-generated content. The key is additive — `openclaw_source` (which pipeline wrote the row) is unchanged. Already-synced content is **not retroactively retagged**: uploads are gated by per-section content hash, so previously synced sections keep their old metadata until their content next changes.
+
 **Tuning sync (object form):**
 
 ```jsonc
 "syncMemories": {
   "enabled": true,
   "sectionize": true,     // split files on ## headings into separate memories
-  "watchPaths": [],        // extra files/dirs to sync beyond memory/
+  "watchPaths": [          // extra files/dirs to sync beyond memory/
+    "notes",                                                  // plain path — tagged with slug "notes"
+    { "path": "notes/brainstem", "source": "brainstem_daily" } // labeled — tagged openclaw_sync_source: "brainstem_daily"
+  ],
   "debounceMs": 2000,      // wait for writes to settle before syncing
   "maxAgeDays": 30          // startup skips already-synced files older than this
 }
 ```
 
+`watchPaths` is how you make **externally generated notes** searchable: tools that write dated markdown reports under the workspace (nightly consolidators, journal generators — e.g. a Brainstem consolidator writing `notes/brainstem/YYYY-MM-DD.md`) are invisible to sync until their file or directory is listed here. Watched paths are picked up by the startup bulk sync. Use the labeled object form so machine-generated content is distinguishable from curated memories at retrieval time. Sectionized mode (the default) is **recommended for external directories**: legacy whole-file mode (`sectionize: false`) writes a `hyperspell_id` frontmatter line back into the source file — i.e. the plugin edits another tool's files — while sectionized mode tracks state in the sync manifest and leaves watched files untouched.
+
 `maxAgeDays` bounds steady-state load: on startup, files whose mtime is older than the cutoff **and** already recorded in the sync manifest are skipped without re-reading. Files not yet in the manifest are always synced once regardless of age, and editing an old file bumps its mtime back into the window. Set to `0` to disable the cutoff.
 
 **Example frontmatter after sync:**
@@ -186,6 +242,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 +254,96 @@ When `autoContext: true` (default), the plugin automatically:
 
 This ensures the AI always has access to relevant information from your connected sources.
 
+### Composite ranking — surfacing your active work
+
+Raw semantic relevance rewards *frequency*: a phrase repeated across a hundred
+auto-saved conversation fragments looks "most similar" to everything and buries
+quieter, truer memory — like the manuscript you're actually writing. When
+`ranking.enabled` is on (default), auto-context re-scores candidates:
+
+```
+composite = relevance
+          + curationBoost   (a memory you deliberately kept: journals, notes, synced files)
+          + storyBoost      (your active story/manuscript — matched via storyTerms)
+          − chatterPenalty  (an auto-saved conversation fragment)
+```
+
+Chatter is additionally capped at `chatterQuota` results per injection,
+regardless of score.
+
+**`storyBoost` does nothing until you set `storyTerms`.** The default is `[]`,
+so no result ever classifies as "story". Set it to the distinctive proper nouns
+of your active work — the title, character names, a project codename, invented
+terminology:
+
+```jsonc
+"config": {
+  "ranking": {
+    "storyTerms": ["lighthouse keeper", "mira", "the shoal chapters"]
+  }
+}
+```
+
+For example: if you're writing a novel called *The Lighthouse Keeper* with a
+protagonist named Mira, the config above makes any memory whose **title or
+highlight excerpt** contains those terms rank as "story" — it gets
+`storyBoost + curationBoost` (+0.35 by default) and is exempt from the chatter
+cap. If you sync the manuscript via `syncMemories` with `sectionize: true`,
+every section is titled `The Lighthouse Keeper — <section>`, so the title term
+alone catches the whole manuscript.
+
+**How matching works:** terms are matched case-insensitively at **word
+boundaries** against the result's title and highlight excerpts. `"mira"`
+matches "Mira", "Mira's", and "mira-class", but **not** "ad**mira**l" or
+"**mira**cle" — a short name can't false-positive inside longer words.
+Multi-word phrases (`"lighthouse keeper"`) match the same way. There is no
+prefix/stem matching: to catch inflected or partial forms, add each full form
+as its own term.
+
+Tips:
+
+- **Use 3–15 distinctive terms.** Every term is checked per result per search;
+  more terms means more false-positive surface, not more recall. Never add a
+  word that appears in unrelated conversation ("book", "chapter", "draft").
+- Terms are normalized on load — trimmed, lowercased, deduplicated — so casing
+  and stray whitespace in your config don't matter.
+- **Update the list when the active story changes.** A stale term is worse than
+  a missing one: it keeps granting the boost to a dead thread's echoes.
+- Ranking (including `storyTerms`) applies only to **auto-context** injection.
+  The `hyperspell_search` tool and `/getcontext` return raw relevance order —
+  don't test `storyTerms` there and conclude it's broken.
+- To verify it's working, enable `debug: true` and watch `gateway.log` for the
+  per-search tally (`auto-context: ranked {...} candidates → selected {...}`) —
+  it appears at default host log levels. The per-candidate lines
+  (`[story] 0.47→0.82 The Lighthouse Keeper — Chapter 3`), which show story
+  matches even when they lose to the threshold, are debug-level and also need
+  host debug logging.
+
+Full knobs and defaults:
+
+```jsonc
+"ranking": {
+  "enabled": true,
+  "curationBoost": 0.2,     // lift for deliberately-kept memory
+  "chatterPenalty": 0.2,    // penalty for auto-saved conversation fragments
+  "storyBoost": 0.15,       // extra lift for storyTerms matches (stacks with curationBoost)
+  "storyTerms": [],         // REQUIRED for storyBoost to do anything
+  "candidateMultiplier": 3, // fetch this × maxResults candidates before re-ranking
+  "chatterQuota": 2         // hard cap on chatter results per injection
+}
+```
+
+### `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
@@ -230,16 +377,84 @@ This ensures the AI always has access to relevant information from your connecte
 ### Other
 - `web_crawler` - Crawled web pages
 
-## Knowledge Graph
+## Memory Network
+
+The Memory Network (config key: `knowledgeGraph`) automatically builds a local knowledge
+graph from your memories. A periodic cron job runs in an isolated session and:
+
+1. **Scans** unprocessed memories (`hyperspell_network_scan` / `network scan`)
+2. **Extracts** people, projects, organizations, and topics with relationships
+3. **Writes** one markdown file per entity into `memory/people/`, `memory/projects/`,
+   `memory/organizations/`, `memory/topics/` (`hyperspell_network_write`)
+4. **Marks** the batch processed so it is never re-scanned (`hyperspell_network_complete`;
+   state lives in `memory/.network-state.json`)
+5. **Syncs** the entity files back to Hyperspell so they are searchable (`network sync`)
+
+If you also maintain a hand-written people/projects reference file, this feature
+automates most of that by hand-off — see
+[Migrating from a hand-maintained archive](docs/memory-network-migration.md) for a safe
+dry-run and comparison procedure before adopting it.
+
+### Enabling it
+
+The easiest path is the setup wizard, which flips the config, writes the extraction
+prompt to `<workspace>/HYPERSPELL-MEMORY-NETWORK.md`, and creates the extraction cron
+(interval from `knowledgeGraph.scanIntervalMinutes`, default 60 minutes):
+
+```bash
+openclaw openclaw-hyperspell setup   # answer "yes" at the Memory Network step
+```
+
+Or manually: set the plugin config and create the cron yourself:
+
+```json
+"knowledgeGraph": { "enabled": true }
+```
+
+```bash
+openclaw cron add --name "Hyperspell Memory Network" --every 60m --session isolated \
+  --message "Read the file at <workspace>/HYPERSPELL-MEMORY-NETWORK.md and follow the instructions inside it."
+```
 
-The plugin can automatically build a local knowledge graph from your memories:
+The `hyperspell_network_*` tools only register when `knowledgeGraph.enabled` is true.
+
+### What an extracted entity file looks like
+
+`memory/people/alice-chen.md`:
+
+```markdown
+---
+title: Alice Chen
+type: person
+graph_entity: true
+email: alice@hyperspell.com
+source_memories: {"slack":["C073WR69EPM"],"google_mail":["19bbe68026553623"]}
+relationships: ["works-at:organizations/hyperspell","leads:projects/memory-network"]
+last_extracted: 2026-07-07T12:00:00Z
+---
+# Alice Chen
+
+Engineering Manager at Hyperspell. Leads the Memory Network project.
+
+## Contact
+
+- Email: alice@hyperspell.com
+
+## Relationships
+
+- works-at: [hyperspell](../organizations/hyperspell.md)
+- leads: [memory network](../projects/memory-network.md)
+```
 
-1. **Scan** memories for entities (people, organizations, projects, topics)
-2. **Extract** structured information and relationships
-3. **Write** entity files to `memory/people/`, `memory/organizations/`, etc.
-4. **Link** entities via markdown relationship references
+Re-extraction **merges**: existing `source_memories`, `relationships`, and
+`hyperspell_id` are preserved and unioned, so files are safe to hand-edit between runs.
 
-Enable the graph tools by using `hyperspell_network_scan`, `hyperspell_network_write`, and `hyperspell_network_complete` in your agent workflows.
+Re-extraction is idempotent by design (the cron agent re-derives the same entities and
+marks rows complete). A previously known gap meant entity files synced back to Hyperspell
+re-entered future scans as unprocessed source memories; the fix lands alongside
+[`proposal/06-knowledge-graph-enablement`](docs/proposals/06-knowledge-graph-enablement.md)
+(PR #99), which propagates the `graph_entity` frontmatter into sync metadata and makes
+the scanner skip memories synced from the entity directories.
 
 ---
 
@@ -257,7 +472,8 @@ Enable the graph tools by using `hyperspell_network_scan`, `hyperspell_network_w
 
 ### Auto-context not injecting
 - Verify `autoContext: true` in your config
-- Enable `debug: true` to see what queries are being made
+- Enable `debug: true` — the ranked/cut/injection summary lines land in
+  `gateway.log` at default host log levels
 - Check that you have memories matching your conversation topics
 
 ### Enabling `memory-core` disabled Hyperspell

package/dist/client.js

@@ -2,6 +2,14 @@ import Hyperspell from "hyperspell";
 import { normalizeScope } from "./config.js";
 import { log } from "./logger.js";
 const API_BASE_URL = "https://api.hyperspell.com";
+/**
+ * The backend metadata echo must be a plain object to map onto
+ * `EmotionalStateLatest.metadata`; anything else (absent, null, array,
+ * scalar) is dropped so a malformed echo can't poison callers.
+ */
+function isMetadataObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 export class HyperspellClient {
     client;
     config;
@@ -396,6 +404,10 @@ export class HyperspellClient {
             extractedAt: data.extracted_at,
             sessionId: data.session_id ?? null,
             relationshipId: data.relationship_id ?? null,
+            // Metadata echo maps through only when present and object-shaped —
+            // absent today (backend #116) and on legacy rows, so this is invisible
+            // until the backend ships the echo.
+            ...(isMetadataObject(data.metadata) ? { metadata: data.metadata } : {}),
         };
         log.debugResponse("emotional-state.get", { found: true, resourceId: result.resourceId });
         return result;
@@ -433,6 +445,8 @@ export class HyperspellClient {
             extractedAt: d.extracted_at ?? "",
             sessionId: d.session_id ?? null,
             relationshipId: d.relationship_id ?? null,
+            // Same conditional echo as getEmotionalState — see the note there.
+            ...(isMetadataObject(d.metadata) ? { metadata: d.metadata } : {}),
         }));
         log.debugResponse("emotional-state.recent", { count: list.length });
         return list;

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({
@@ -323,12 +324,18 @@ async function runSetup() {
     // Step 8: Memory Network setup
     p.note("The Memory Network automatically extracts entities (people, projects,\n" +
         "organizations, topics) from your memories into structured markdown\n" +
-        "files. This runs as a periodic cron job in the main session.", "Memory Network");
+        "files. This runs as a periodic cron job in an isolated session.", "Memory Network");
     const enableNetwork = await p.confirm({
         message: "Enable the Memory Network?",
         initialValue: false,
     });
     if (!p.isCancel(enableNetwork) && enableNetwork) {
+        // The wizard is the only place the extraction cron is created, so the
+        // config knob and the cron are born in agreement: one interval feeds both
+        // `--every` and the persisted `scanIntervalMinutes`. Runtime never
+        // reschedules — to change cadence later, edit the cron job (and keep the
+        // config field in sync so it stays an honest record of the cron).
+        const scanIntervalMinutes = 60;
         // Update config to enable knowledgeGraph
         try {
             const configPath = resolveConfigPath();
@@ -337,7 +344,7 @@ async function runSetup() {
                 const config = JSON.parse(configContent);
                 const pluginEntry = config?.plugins?.entries?.["openclaw-hyperspell"]?.config;
                 if (pluginEntry) {
-                    pluginEntry.knowledgeGraph = { enabled: true };
+                    pluginEntry.knowledgeGraph = { enabled: true, scanIntervalMinutes };
                     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
                 }
             }
@@ -359,7 +366,7 @@ async function runSetup() {
             const output = execFileSync("openclaw", [
                 "cron", "add",
                 "--name", CRON_JOB_NAME,
-                "--every", "1h",
+                "--every", `${scanIntervalMinutes}m`,
                 "--session", "isolated",
                 "--message", `Read the file at ${promptPath} and follow the instructions inside it.`,
             ], { stdio: ["pipe", "pipe", "pipe"], timeout: 10_000 });
@@ -374,14 +381,14 @@ async function runSetup() {
                 }
                 catch { }
             }
-            s4.stop("Cron job created — Memory Network will scan every hour");
+            s4.stop(`Cron job created — Memory Network will scan every ${scanIntervalMinutes} minutes`);
         }
         catch (cronErr) {
             s4.stop("Could not create cron job automatically");
             p.log.warn(`Cron creation failed. Create it manually:`);
             p.note(`openclaw cron add \\\n` +
                 `  --name "${CRON_JOB_NAME}" \\\n` +
-                `  --every 1h \\\n` +
+                `  --every ${scanIntervalMinutes}m \\\n` +
                 `  --session isolated \\\n` +
                 `  --message "Read the file at ${promptPath} and follow the instructions inside it."`, "Manual cron setup");
         }
@@ -524,6 +531,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")
@@ -539,7 +594,10 @@ export function registerCliCommands(program, pluginConfig) {
             const workspaceDir = getWorkspaceDir();
             const stateManager = new NetworkStateManager(workspaceDir);
             const batchSize = Number.parseInt(opts.batchSize, 10) || 20;
-            const memories = await scanMemories(client, stateManager, batchSize);
+            // cfg drives the multiUser fan-out inside scanMemories; omitting it
+            // made the CLI scan the default user only, silently skipping every
+            // mapped user's memories on multiUser installs.
+            const memories = await scanMemories(client, stateManager, batchSize, cfg);
             const text = formatScanResults(memories, stateManager.getProcessedCount(), stateManager.getLastScanAt());
             process.stdout.write(text + "\n");
         }