@hyperspell/openclaw-hyperspell 0.19.0 → 0.21.0

package/README.md

@@ -123,6 +123,13 @@ Matching uses the same semantics as the quarantine check itself: exact id or thr
 
 **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 |
@@ -135,10 +142,19 @@ Matching uses the same semantics as the quarantine check itself: exact id or thr
 | `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 |
+| `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). |
-| `debug` | boolean | `false` | Enable verbose logging |
+| `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 |
+| `coverageLog` | boolean | `false` | **Opt-in.** Append a local-only JSONL event whenever auto-context finds no relevant memories, so capture gaps can be told apart from ranking misses. Events include prompt text — see [Coverage log](#coverage-log). |
+| `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>`
@@ -188,18 +204,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:**
@@ -232,6 +255,164 @@ 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.
+
+Provenance is a signal too: an optional `sourceWeights` map multiplies a
+result's **base relevance** (before the kind boosts/penalties are added) by a
+per-source factor, so "a journaled Notion page is more intentional memory than
+a titled Slack aside on the same topic" is expressible. Any source not listed
+— including sources that don't exist yet — is neutral (`1.0`); the shipped
+default is `{}`, a strict no-op. It weights sources already in the result set;
+to *exclude* a source, use the `sources` filter instead (weights of 0 are
+rejected at load with exactly that pointer). Suggested starting points, priors
+to seed your own tuning rather than measured truth: authored systems slightly
+up (`notion` 1.15, drive/box/dropbox 1.1), conversational exhaust slightly
+down (`slack`/`microsoft_teams` 0.85, `trace` 0.8) — magnitudes small enough
+to break ties, never to override a real relevance gap. Typos in weight keys
+are not schema errors (new backend sources must not fail validation); with
+`debug: true` unknown keys are flagged once at startup in `gateway.log`.
+
+Selected results are also checked against each other for **near-duplicates**:
+when the same memory exists in several forms (a re-synced doc section, a
+`remember` note quoting it, a curated copy of a hot-buffer row), every copy
+clears the threshold, none is chatter, and pre-dedup they filled multiple
+injection slots with one piece of information. Each candidate's lead text is
+compared against already-selected results by token overlap; above
+`dedupThreshold` (0.8) the copy is skipped and its slot passes to the
+next-ranked *different* memory. Skipped copies never consume the chatter
+quota. Set `dedupThreshold: 0` to disable. Paraphrased duplicates (same fact,
+different words) are beyond a string measure and out of scope.
+
+Within each selected memory, the second excerpt earns its place: a result
+renders up to two highlight bullets, and the runner-up rides along only when
+its score is within 0.15 of the top one's — a .95/.40 pair renders one bullet
+(the distant second is usually a weaker paraphrase), a .95/.85 pair renders
+both. The top highlight is always kept, so a selected memory never disappears
+from the injection because of this rule.
+
+An optional **elbow cutoff** (`ranking.elbow`, **off by default**) stops
+injecting at a natural score cliff instead of always filling `maxResults`: a
+narrow query backed by 3 genuinely relevant memories no longer pads the
+context with a plateau of marginal ones that happen to clear the threshold.
+It is strictly conservative — it only ever cuts *earlier*, never later, never
+below `minResults` (default 3), and when no clear cliff exists (gradual
+decline, flat plateau) selection is identical to today. A cliff means the
+drop from the last accepted result is both large against the decline seen so
+far (`gapRatio` × mean gap, default 2.5×) *and* material in absolute terms
+(`minGap`, default 0.05). Before enabling, run
+`node --experimental-strip-types docs/elbow-scan.mjs` against your real data
+to check firing rate and cut depth (with `debug: true` the live verdict shows
+in `gateway.log` as `auto-context: elbow stopped at k (ceiling N)`).
+
+Age matters too, gently: results accrue a small **recency penalty** that grows
+with age (exponential decay, 90-day half-life by default) and is hard-capped at
+`recencyMaxPenalty` (0.1) so it can break near-ties toward current information
+but never bury a strong old match. Deliberately-kept memory (curated/story)
+ages at half rate (`recencyCuratedFactor`) — an old truth you chose to keep
+still beats a fresh shallow echo. Results without a timestamp are never
+penalized. Set `recencyHalfLifeDays: 0` to disable.
+
+**`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 {...}`) and the cut tally (threshold / max-results / elbow / near-duplicate / chatter-quota) —
+  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
+  "recencyHalfLifeDays": 90,  // age at which half the recency penalty has accrued (0 = off)
+  "recencyMaxPenalty": 0.1,   // ceiling on the recency penalty — a tiebreaker, never a burial
+  "recencyCuratedFactor": 0.5, // kept memory (curated/story) ages at this fraction of the rate
+  "sourceWeights": {},        // per-source multiplier on base relevance; unlisted = 1.0
+  "dedupThreshold": 0.8,      // token-overlap ratio that skips a near-duplicate (0 = off)
+  "elbow": {                  // stop early at a natural score cliff (opt-in)
+    "enabled": false,
+    "minResults": 3,          // never cut below this many accepted results
+    "gapRatio": 2.5,          // cliff = drop >= this multiple of the mean gap so far...
+    "minGap": 0.05            // ...AND at least this big on the raw composite scale
+  }
+}
+```
+
+### Coverage log
+
+No ranking tweak can surface a memory that was never captured — and by default nothing distinguishes "ranking failed" from "it was never stored." With `coverageLog: true`, every auto-context turn that injects **no** memory sections appends one line to `<workspaceDir>/.hyperspell-coverage.jsonl`:
+
+- `outcome: "empty"` — the search succeeded but returned zero candidates (a capture question: was this ever stored?)
+- `outcome: "below_threshold"` — candidates existed but none cleared `relevanceThreshold`; `topScore` vs `threshold` says how near the miss was (a ranking question)
+
+Failed searches never produce events — backend-unavailable is not "no memories." In multi-user mode there is one event per turn with per-lane detail, and a lane whose search failed is recorded as `status: "error"`, never as zero candidates.
+
+**Local-only guarantee:** the log is written only to the workspace directory and is never sent to Hyperspell or anywhere remote. Because each event carries the triggering prompt (truncated to 500 chars), the feature is **off by default** — prompt text reaches disk only if you explicitly opt in. The file is capped at 5 MB with one `.old` rotation generation (~10 MB total), so content ages out instead of accumulating.
+
+Review with `jq`, e.g.: `jq -r '[.ts, .outcome, .topScore, .prompt] | @tsv' ~/.openclaw/workspace/.hyperspell-coverage.jsonl` — after a week or two of labeling (capture gap / ranking near-miss / correct absence), the tallies say whether the next investment belongs in capture or ranking. Delete the file when done.
+
 ### `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.
@@ -276,16 +457,84 @@ The purge command prints these standing limitations on every run.
 ### 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 `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
 
-The plugin can automatically build a local knowledge graph from your memories:
+- 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.
 
 ---
 
@@ -303,7 +552,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/setup.js

@@ -293,6 +293,7 @@ async function runSetup() {
                 maxResults: 10,
                 relevanceThreshold: 0.6,
                 ranking: DEFAULT_RANKING,
+                coverageLog: false,
                 debug: false,
                 knowledgeGraph: { enabled: false, scanIntervalMinutes: 60, batchSize: 20 },
                 startupOrientation: {
@@ -324,12 +325,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();
@@ -338,7 +345,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");
                 }
             }
@@ -360,7 +367,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 });
@@ -375,14 +382,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");
         }
@@ -588,7 +595,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");
         }

package/dist/commands/slash.js

@@ -1,4 +1,6 @@
 import { getWorkspaceDir } from "../config.js";
+import { MOOD_WEATHER_COLLECTION } from "../hooks/mood-weather.js";
+import { MOOD_WEATHER_SOURCE } from "../lib/filters.js";
 import { buildScopeFilter, getCanReadScopes, getDefaultWriteScope, resolveRole, resolveUser, routeWrite, } from "../lib/sender.js";
 import { log } from "../logger.js";
 import { syncAllMemoryFiles } from "../sync/markdown.js";
@@ -157,6 +159,44 @@ export function registerCommands(api, client, cfg) {
             }
         },
     });
+    // /moodweather — private roll history (operator retrospection only; these rows
+    // are excluded from all agent recall, so this command is the ONLY reader).
+    api.registerCommand({
+        name: "moodweather",
+        description: "Show recent mood-weather rolls (never fed back into tone)",
+        acceptsArgs: false,
+        requireAuth: true,
+        handler: async () => {
+            log.debug("/moodweather command");
+            try {
+                const rows = [];
+                for await (const mem of client.listMemories({
+                    collection: MOOD_WEATHER_COLLECTION,
+                    pageSize: 50,
+                })) {
+                    if (mem.metadata?.openclaw_source !== MOOD_WEATHER_SOURCE)
+                        continue;
+                    rows.push({
+                        mood: String(mem.metadata.mood ?? "?"),
+                        rolledAt: String(mem.metadata.rolled_at ?? ""),
+                    });
+                    if (rows.length >= 20)
+                        break;
+                }
+                if (rows.length === 0) {
+                    return { text: "No mood-weather rolls recorded." };
+                }
+                const lines = rows.map((r) => `• ${r.rolledAt.slice(0, 16).replace("T", " ")} — ${r.mood}`);
+                return {
+                    text: `Recent mood-weather rolls (newest first):\n${lines.join("\n")}`,
+                };
+            }
+            catch (err) {
+                log.error("/moodweather failed", err);
+                return { text: "Failed to fetch mood-weather history. Check logs for details." };
+            }
+        },
+    });
     // /previewcontext - Show what would be injected into the next session
     api.registerCommand({
         name: "previewcontext",

package/dist/config.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { DEFAULT_RANKING } from "./lib/ranking.js";
+import { DEFAULT_ELBOW, DEFAULT_RANKING, } from "./lib/ranking.js";
 /**
  * Convert user-facing scope names (which may contain hyphens) to SDK-safe
  * metadata values (alphanumeric + underscore only). Must be applied at every
@@ -27,12 +27,13 @@ const ALLOWED_KEYS = [
     "maxResults",
     "relevanceThreshold",
     "ranking",
+    "coverageLog",
     "debug",
     "knowledgeGraph",
     "multiUser",
     "dreaming",
 ];
-const VALID_SOURCES = [
+export const VALID_SOURCES = [
     "reddit",
     "notion",
     "slack",
@@ -62,6 +63,60 @@ function resolveEnvVars(value) {
         return envValue;
     });
 }
+/**
+ * Normalize `syncMemories.watchPaths` entries: the shipped/documented string
+ * form stays valid and is additive-upgraded to `{ path }`; the object form
+ * carries an optional provenance `source` label. Labels are sanitized with the
+ * same character rule as normalizeScope — metadata values must be alphanumeric
+ * + underscore or Hyperspell metadata filters silently miss.
+ */
+function parseWatchPaths(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((wp) => {
+        if (typeof wp === "string") {
+            if (!wp.trim()) {
+                throw new Error("hyperspell.syncMemories.watchPaths[] entry needs a non-empty path");
+            }
+            return { path: wp };
+        }
+        if (typeof wp !== "object" || wp === null || Array.isArray(wp)) {
+            throw new Error("hyperspell.syncMemories.watchPaths[] entries must be a string or { path, source? }");
+        }
+        const entry = wp;
+        assertAllowedKeys(entry, ["path", "source"], "hyperspell.syncMemories.watchPaths[]");
+        if (typeof entry.path !== "string" || !entry.path.trim()) {
+            throw new Error("hyperspell.syncMemories.watchPaths[] entry needs a non-empty path");
+        }
+        if (!entry.source)
+            return { path: entry.path };
+        return {
+            path: entry.path,
+            source: String(entry.source).replace(/[^a-zA-Z0-9_]/g, "_"),
+        };
+    });
+}
+/** Per-source multipliers: non-numeric values silently skip (num()'s
+ * convention); explicit non-positive values throw (a 0 weight is a filtering
+ * decision wearing a weighting costume — the sources filter is the right
+ * tool, and the error says so). Keys lowercase but are NOT validated against
+ * VALID_SOURCES: the backend adds sources independently of plugin releases,
+ * and an unmatched key is a harmless neutral no-op (startup diag logs it). */
+function parseSourceWeights(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v !== "number")
+            continue;
+        if (!Number.isFinite(v) || v <= 0) {
+            throw new Error(`ranking.sourceWeights.${k} must be a positive number (got ${v}); ` +
+                `to exclude a source entirely, use the "sources" filter instead`);
+        }
+        out[k.trim().toLowerCase()] = v;
+    }
+    return out;
+}
 function parseRanking(raw) {
     const r = (raw ?? {});
     const num = (v, d) => (typeof v === "number" ? v : d);
@@ -70,11 +125,37 @@ function parseRanking(raw) {
         curationBoost: num(r.curationBoost, DEFAULT_RANKING.curationBoost),
         chatterPenalty: num(r.chatterPenalty, DEFAULT_RANKING.chatterPenalty),
         storyBoost: num(r.storyBoost, DEFAULT_RANKING.storyBoost),
+        // Trim + lowercase + dedupe, drop whitespace-only entries. Before this a
+        // stray " " entry passed the length filter and (under the old substring
+        // matcher) classified EVERY result as story, silently disabling the
+        // chatter penalty and quota (issue #82's footgun).
         storyTerms: Array.isArray(r.storyTerms)
-            ? r.storyTerms.map((t) => String(t)).filter((t) => t.length > 0)
+            ? [
+                ...new Set(r.storyTerms
+                    .map((t) => String(t).trim().toLowerCase())
+                    .filter((t) => t.length > 0)),
+            ]
             : DEFAULT_RANKING.storyTerms,
         candidateMultiplier: Math.max(1, num(r.candidateMultiplier, DEFAULT_RANKING.candidateMultiplier)),
         chatterQuota: Math.max(0, num(r.chatterQuota, DEFAULT_RANKING.chatterQuota)),
+        recencyHalfLifeDays: Math.max(0, num(r.recencyHalfLifeDays, DEFAULT_RANKING.recencyHalfLifeDays)),
+        recencyMaxPenalty: Math.max(0, num(r.recencyMaxPenalty, DEFAULT_RANKING.recencyMaxPenalty)),
+        recencyCuratedFactor: Math.min(1, Math.max(0, num(r.recencyCuratedFactor, DEFAULT_RANKING.recencyCuratedFactor))),
+        sourceWeights: parseSourceWeights(r.sourceWeights),
+        dedupThreshold: Math.min(1, Math.max(0, num(r.dedupThreshold, DEFAULT_RANKING.dedupThreshold))),
+        elbow: parseElbow(r.elbow),
+    };
+}
+function parseElbow(raw) {
+    const e = (raw ?? {});
+    const num = (v, d) => (typeof v === "number" ? v : d);
+    return {
+        enabled: e.enabled ?? DEFAULT_ELBOW.enabled,
+        // >= 2: at least one gap must exist before meanGap is defined (the
+        // first accepted result never records a gap).
+        minResults: Math.max(2, num(e.minResults, DEFAULT_ELBOW.minResults)),
+        gapRatio: Math.max(1, num(e.gapRatio, DEFAULT_ELBOW.gapRatio)),
+        minGap: Math.max(0, num(e.minGap, DEFAULT_ELBOW.minGap)),
     };
 }
 function parseSources(raw) {
@@ -324,9 +405,7 @@ export function parseConfig(raw) {
         syncMemoriesConfig: {
             enabled: syncMemoriesEnabled,
             sectionize: smObj.sectionize ?? true,
-            watchPaths: Array.isArray(smObj.watchPaths)
-                ? smObj.watchPaths
-                : [],
+            watchPaths: parseWatchPaths(smObj.watchPaths),
             debounceMs: smObj.debounceMs ?? 2000,
             maxAgeDays: smObj.maxAgeDays ?? 30,
             ignorePaths: Array.isArray(smObj.ignorePaths)
@@ -337,6 +416,10 @@ export function parseConfig(raw) {
         maxResults: cfg.maxResults ?? 10,
         relevanceThreshold: cfg.relevanceThreshold ?? 0.6,
         ranking: parseRanking(cfg.ranking),
+        // Default OFF (deviates from proposal 15 §6 by maintainer decision):
+        // coverage events carry prompt text, so nothing is written to disk
+        // unless the operator explicitly opts in.
+        coverageLog: cfg.coverageLog ?? false,
         debug: cfg.debug ?? false,
         knowledgeGraph: {
             enabled: kgRaw.enabled ?? false,