@hyperspell/openclaw-hyperspell 0.19.0 → 0.20.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,18 @@ 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 |
+| `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 +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:**
@@ -232,6 +254,85 @@ 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.
@@ -276,16 +377,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`)
 
-The plugin can automatically build a local knowledge graph from your memories:
+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
+
+- 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 +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/setup.js

@@ -324,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();
@@ -338,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");
                 }
             }
@@ -360,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 });
@@ -375,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");
         }
@@ -588,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");
         }

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

@@ -62,6 +62,39 @@ 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, "_"),
+        };
+    });
+}
 function parseRanking(raw) {
     const r = (raw ?? {});
     const num = (v, d) => (typeof v === "number" ? v : d);
@@ -70,8 +103,16 @@ 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)),
@@ -324,9 +365,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)

package/dist/graph/ops.js

@@ -1,8 +1,31 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { MOOD_WEATHER_SOURCE } from "../lib/filters.js";
 import { getAllUserIds } from "../lib/sender.js";
 import { log } from "../logger.js";
 const ENTITY_TYPES = ["people", "projects", "organizations", "topics"];
+/**
+ * True for memories that came from a Memory Network entity file synced back
+ * to Hyperspell. These must never re-enter a scan as source memories — the
+ * extractor would be fed its own output every cycle (self-scan loop,
+ * proposal/06 §3.3). Two signals, both needed:
+ * - `graph_entity` metadata, propagated from entity-file frontmatter by the
+ *   sync paths (`sync/markdown.ts`) — the contract the extraction prompt states;
+ * - the entity-directory `file_path`, which covers records synced before the
+ *   frontmatter propagation existed (unchanged sections are content-hash
+ *   skipped on re-sync, so their old metadata never gets refreshed).
+ */
+export function isEntityFileMemory(metadata) {
+    if (!metadata)
+        return false;
+    if (metadata.graph_entity === "true" || metadata.graph_entity === true)
+        return true;
+    const filePath = metadata.file_path;
+    if (typeof filePath !== "string")
+        return false;
+    const normalized = filePath.split(path.sep).join("/");
+    return ENTITY_TYPES.some((type) => normalized.includes(`/memory/${type}/`));
+}
 export function slugify(name) {
     return name
         .toLowerCase()
@@ -60,17 +83,27 @@ function summarizeMemoryData(data, source) {
     }
     return parts.join("\n");
 }
-export async function scanMemories(client, stateManager, batchSize, cfg) {
+export async function scanMemories(client, stateManager, batchSize, 
+// Required (not optional) so no caller can silently bypass the multiUser
+// fan-out again — the CLI `network scan` did exactly that (proposal/06 §3.3).
+cfg) {
     const unprocessed = [];
-    const userIds = cfg ? getAllUserIds(cfg) : [undefined];
+    // Single-user installs without a configured userId resolve to no ids;
+    // scan under the API key's default identity in that case.
+    const configuredIds = getAllUserIds(cfg);
+    const userIds = configuredIds.length > 0 ? configuredIds : [undefined];
     outer: for (const userId of userIds) {
         for await (const mem of client.listMemories({ userId })) {
             if (stateManager.isProcessed(mem.resourceId))
                 continue;
-            if (mem.metadata?.graph_entity === "true" || mem.metadata?.graph_entity === true)
+            if (isEntityFileMemory(mem.metadata))
                 continue;
             if (mem.metadata?.status !== "completed")
                 continue;
+            // Mood-weather roll records are observability-only (issue #71): the graph
+            // feeds context, so ingesting them would leak the rolls back into recall.
+            if (mem.metadata?.openclaw_source === MOOD_WEATHER_SOURCE)
+                continue;
             let summary = "";
             try {
                 const full = await client.getMemory(mem.resourceId, mem.source, { userId });

package/dist/hooks/auto-context.js

@@ -1,7 +1,7 @@
 import { appendFileSync } from "node:fs";
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
-import { explainSelection, rerank, } from "../lib/ranking.js";
+import { explainSelection, kindTally, 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";
@@ -204,6 +204,14 @@ export function buildAutoContextHandler(client, cfg) {
                 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);
+                // Candidates → selected kind tally, logged UNCONDITIONALLY (unlike the
+                // "injecting" line below): a story/curated match that loses to the
+                // threshold is exactly the case an operator tuning storyTerms needs to
+                // see, and it never reaches the formatted branch (proposal 01 §3.4).
+                log.diag(`auto-context: ranked ${JSON.stringify(kindTally(ranked))} candidates → selected ${JSON.stringify(kindTally(selected))} (chatter cap ${ranking.chatterQuota})`);
+                for (const r of ranked.slice(0, 10)) {
+                    log.debug(`  [${r._kind}] ${r._base.toFixed(2)}→${r._composite.toFixed(2)} ${(r.title ?? r.resourceId).slice(0, 60)}`);
+                }
                 // 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
@@ -216,12 +224,11 @@ export function buildAutoContextHandler(client, cfg) {
                     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}`);
+                    log.diag(`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}, composite ${selected.at(-1)?._composite.toFixed(2)}–${selected[0]?._composite.toFixed(2)})`);
+                    log.diag(`auto-context: injecting (ranked) ${JSON.stringify(kindTally(selected))} from ${results.length} candidates (chatter cap ${ranking.chatterQuota}, composite ${selected.at(-1)?._composite.toFixed(2)}–${selected[0]?._composite.toFixed(2)})`);
                 }
             }
             else {

package/dist/hooks/emotional-state.js

@@ -3,7 +3,7 @@ import { resolveCurrentSessionId } from "../lib/session.js";
 import { isMultiSpeaker } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
 import { sanitizeTraceText } from "./auto-trace.js";
-import { buildMoodWeatherContext, rollMood } from "./mood-weather.js";
+import { buildMoodWeatherContext, recordMoodRoll, rollMood, } from "./mood-weather.js";
 /** How many recent registers to surface as the "arc" at session start. */
 export const EMOTIONAL_ARC_LIMIT = 3;
 const MIN_MESSAGES = 3;
@@ -15,6 +15,12 @@ const MIN_CONVERSATION_LENGTH = 100;
  * heartbeat overwrite the register from a deep conversation (the whipsaw).
  * `ctx.trigger` is one of cron|heartbeat|manual|memory|overflow|user; we store
  * only for user-driven turns (and `overflow`, a continuation of a user run).
+ *
+ * Lifetime (verified against openclaw core, issue #70): `trigger` is PER-RUN,
+ * not session-fixed — core rebuilds the hook ctx from each run's own params
+ * (embedded-agent-runner/run.ts), and inbound human replies always start a new
+ * run with trigger="user" even inside a cron-originated session. So a scheduled
+ * check-in that becomes a real conversation IS stored on the human turns.
  */
 const NON_CONVERSATIONAL_TRIGGERS = new Set(["cron", "heartbeat", "memory"]);
 /**
@@ -224,12 +230,15 @@ export function buildEmotionalStateFetchHandler(client, cfg, deps = {}) {
                 if (sessionKey)
                     sessionMoods.set(sessionKey, mood);
                 log.info(`mood-weather: rolled "${mood.id}" this session`);
-                // Coordination with issue #71 (mood-weather observability): if #71's
-                // recordMoodRoll(client, mood, {...}) has landed, its call belongs
-                // HERE — inside this `!priorMood` guard — not on a bare `if (mood)`
-                // at the two return sites below. A priorMood replay (post-compaction
-                // re-injection of an already-rolled mood) is not a new roll; calling
-                // recordMoodRoll on replay would log the same event twice.
+                // Observability record (issue #71) — fire-and-forget, recall-excluded.
+                // Stays inside the !priorMood guard: a post-compaction replay of an
+                // already-rolled mood is NOT a new roll and must not double-log. Rolls
+                // only happen past the still-extracting early return above, so every
+                // recorded roll is one that actually lands in this session's context.
+                recordMoodRoll(client, mood, {
+                    sessionKey,
+                    relationshipId: cfg.relationshipId,
+                });
             }
             const moodBlock = mood ? buildMoodWeatherContext(mood) : "";
             if (usable.length === 0) {
@@ -239,7 +248,9 @@ export function buildEmotionalStateFetchHandler(client, cfg, deps = {}) {
                     injectedSessions.add(sessionKey);
                 return moodBlock ? { prependContext: moodBlock } : undefined;
             }
-            log.debug(`emotional-context: injecting ${usable.length} recent register(s)`);
+            // log.diag, not debug: the exact line issue #118's live audit proved
+            // invisible — one line per injection, operator-meaningful.
+            log.diag(`emotional-context: injecting ${usable.length} recent register(s)`);
             // Mood block comes AFTER the arc so it reads as today's override on top
             // of the remembered trajectory — not blended into it.
             const context = moodBlock