@hyperspell/openclaw-hyperspell 0.19.0 → 0.20.0

package/dist/hooks/memory-sync.js

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import { getWorkspaceDir } from "../config.js";
 import { log } from "../logger.js";
-import { syncMarkdownFile, syncMarkdownFileSectionized, syncAllMemoryFiles, syncAllFilesSectionized, } from "../sync/markdown.js";
+import { resolveSyncSource, resolveWatchPath, syncMarkdownFile, syncMarkdownFileSectionized, syncAllMemoryFiles, syncAllFilesSectionized, } from "../sync/markdown.js";
 /**
  * Build a handler for file change events that syncs markdown files to Hyperspell.
  *
@@ -21,17 +21,27 @@ export function buildFileSyncHandler(client, cfg) {
     const debounceMs = cfg.syncMemoriesConfig.debounceMs;
     const ignoreDirs = new Set(cfg.syncMemoriesConfig.ignorePaths);
     // Resolve additional watch paths to absolute paths for matching
-    const resolvedWatchPaths = (watchPaths ?? []).map((wp) => wp.startsWith("/") ? wp : path.join(workspaceDir, wp));
+    const resolvedWatchPaths = (watchPaths ?? []).map((wp) => resolveWatchPath(workspaceDir, wp.path));
     /**
      * Mirror the bulk walk's exclusions on the live path: a file under a
      * dot-directory (e.g. .dreams) or an ignored directory (e.g. dreaming) must
      * not live-sync either, or an edit would re-ingest exactly what the walk
-     * skips.
+     * skips. Applies against every watch root (memory/ AND each watchPath), so
+     * e.g. notes/brainstem/.drafts/x.md is excluded like the walk excludes it.
+     * The longest containing root wins: segments inside an explicitly configured
+     * watchPath are judged, the watchPath's own path is not.
      */
     function isIgnoredPath(filePath) {
-        const rel = path.relative(memoryDir, filePath);
-        if (rel.startsWith("..") || path.isAbsolute(rel))
+        let root;
+        for (const candidate of [memoryDir, ...resolvedWatchPaths]) {
+            if (filePath === candidate || filePath.startsWith(candidate + path.sep)) {
+                if (!root || candidate.length > root.length)
+                    root = candidate;
+            }
+        }
+        if (!root)
             return false;
+        const rel = path.relative(root, filePath);
         const segments = rel.split(path.sep).slice(0, -1); // directory segments only
         return segments.some((seg) => seg.startsWith(".") || ignoreDirs.has(seg));
     }
@@ -59,9 +69,12 @@ export function buildFileSyncHandler(client, cfg) {
     async function doSync(filePath) {
         const fileName = path.basename(filePath);
         log.info(`Memory file changed: ${fileName}`);
+        // Same provenance the startup bulk sync stamps, so a file gets identical
+        // openclaw_sync_source metadata whichever path ingests it first.
+        const syncSource = resolveSyncSource(filePath, workspaceDir, watchPaths ?? []);
         try {
             if (sectionize) {
-                const result = await syncMarkdownFileSectionized(client, filePath, workspaceDir, { userId: syncUserId });
+                const result = await syncMarkdownFileSectionized(client, filePath, workspaceDir, { userId: syncUserId, syncSource });
                 if (result.synced > 0 || result.removed > 0) {
                     log.info(`Section-synced ${fileName}: ${result.synced} synced, ${result.skipped} unchanged, ${result.removed} removed`);
                 }
@@ -77,7 +90,10 @@ export function buildFileSyncHandler(client, cfg) {
             }
             else {
                 // Legacy whole-file sync
-                const result = await syncMarkdownFile(client, filePath, { userId: syncUserId });
+                const result = await syncMarkdownFile(client, filePath, {
+                    userId: syncUserId,
+                    syncSource,
+                });
                 if (result.success) {
                     log.info(`Synced ${fileName} -> ${result.resourceId}`);
                 }

package/dist/hooks/mood-weather.js

@@ -22,11 +22,16 @@
  *    store path. One random cold morning must NOT calcify into "we've been
  *    distant lately." One day's weather, then gone. (The store handler in
  *    emotional-state.ts is untouched, so this is enforced by construction.)
+ *    A private, recall-excluded observability record IS written per roll
+ *    (issue #71) — see recordMoodRoll below; it is invisible to every
+ *    injection/recall path, so the guarantee holds.
  *  - BOUNDED. The dice can make her *difficult* — short, contrary, melancholy,
  *    flat. They do NOT get to make her hurtful on purpose. "In a mood" is alive;
  *    "mean" is just a bad feature. Mood descriptions below stay on the right side
  *    of that line.
  */
+import { MOOD_WEATHER_SOURCE } from "../lib/filters.js";
+import { log } from "../logger.js";
 /**
  * The weather table. Warmer/lighter moods are weighted a touch heavier than the
  * darker ones — not to defang it, but because a person who woke up cold *every*
@@ -111,3 +116,43 @@ export function buildMoodWeatherContext(mood) {
         "</hyperspell-mood-weather>",
     ].join("\n");
 }
+/** Collection the roll records live in, so /moodweather can list them without a search. */
+export const MOOD_WEATHER_COLLECTION = "mood-weather";
+/**
+ * Fire-and-forget observability record for a mood roll (issue #71).
+ *
+ * This does NOT weaken the "does not write forward" contract above: the record
+ * goes to the generic vault store tagged openclaw_source="mood_weather", which
+ * excludeFilterFor() drops from every recall path (auto-context, the
+ * hyperspell_search tool, startup-orientation loops, knowledge graph). The
+ * emotional-state arc fetch reads a different endpoint entirely (GET
+ * /emotional-state[/recent], written only by storeEmotionalState), so it can
+ * never surface there. Queryable only via the dedicated /moodweather command.
+ *
+ * Written via client.addMemory (memories.add) — NEVER POST /messages: a
+ * /messages write carrying metadata renders the row non-retrievable (see the
+ * warning in lib/filters.ts), while memories.add metadata is proven to persist
+ * and be filterable (canary A in docs/filter-dialect-test.mjs).
+ *
+ * Deliberately not awaited: this sits on the first-turn injection hot path, and
+ * a logging write must never delay or break the session.
+ */
+export function recordMoodRoll(client, mood, opts) {
+    const rolledAt = new Date().toISOString();
+    void client
+        .addMemory(`Mood weather roll: woke up "${mood.id}" (${rolledAt}). Exogenous session mood — uncaused, session-only, never part of the relational register.`, {
+        title: `Mood weather — ${mood.id} (${rolledAt.slice(0, 10)})`,
+        collection: MOOD_WEATHER_COLLECTION,
+        metadata: {
+            openclaw_source: MOOD_WEATHER_SOURCE,
+            mood: mood.id,
+            rolled_at: rolledAt,
+            ...(opts.sessionKey ? { session: opts.sessionKey } : {}),
+            ...(opts.relationshipId ? { relationship_id: opts.relationshipId } : {}),
+        },
+    })
+        .catch((err) => {
+        // Fire-and-forget — observability must never break the session.
+        log.warn("mood-weather: roll record write failed (non-fatal)", err);
+    });
+}

package/dist/hooks/startup-orientation.js

@@ -1,3 +1,4 @@
+import { excludeFilterFor } from "../lib/filters.js";
 import { resolveUser } from "../lib/sender.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { isMultiSpeaker } from "../lib/speaker-tracker.js";
@@ -219,9 +220,14 @@ export async function gatherOrientation(client, cfg, userId) {
             : Promise.resolve([]);
     const [recentSettled, loopsSettled] = await Promise.allSettled([
         recentFetch,
+        // Loops feed agent context, so tagged observability rows (agent_end
+        // traces, mood_weather rolls) must be dropped like on every other recall
+        // path — this also closes a pre-existing gap where agent_end traces
+        // could surface in the loops block.
         client.search(so.loopsQuery, {
             limit: so.loopsLimit,
             userId,
+            filter: excludeFilterFor(cfg),
         }),
     ]);
     const recentOk = recentSettled.status === "fulfilled";
@@ -310,7 +316,10 @@ export function buildStartupOrientationHandler(client, cfg) {
             return;
         }
         const blocks = [gathered.recentBlock, gathered.loopsBlock].filter((b) => b !== null);
-        log.debug(`startup-orientation: injecting recent=${gathered.recentCount} loops=${gathered.loopsCount}`);
+        // log.diag, not debug: this one-line injection summary is the operator's
+        // only live signal that orientation fired (issue #118 — host drops plugin
+        // debug output from gateway.log).
+        log.diag(`startup-orientation: injecting recent=${gathered.recentCount} loops=${gathered.loopsCount}`);
         return { prependContext: blocks.join("\n\n") };
     };
 }

package/dist/index.js

@@ -170,6 +170,22 @@ export default {
         if (cfg.knowledgeGraph.enabled) {
             registerNetworkTools(api, client, cfg);
         }
+        else {
+            // Discoverability (issue #81): the Memory Network ships fully built but
+            // default-off. If memories are accumulating (hot buffer / auto-trace /
+            // emotional state) and the operator never made a knowledgeGraph decision,
+            // say so once at startup — otherwise the feature is undetectable without
+            // reading source. Keyed off the RAW config: an explicit `knowledgeGraph`
+            // key (even { enabled: false }) is a decision and suppresses this.
+            const memoryAccumulating = cfg.hotBuffer.enabled || cfg.autoTrace.enabled || cfg.emotionalContext;
+            if (rawConfig?.knowledgeGraph === undefined && memoryAccumulating) {
+                log.info("memories are accumulating but the Memory Network (knowledgeGraph) is not configured — " +
+                    "no entity extraction into memory/people|projects|organizations|topics will run. " +
+                    "Enable it via 'openclaw openclaw-hyperspell setup' (Memory Network step) or set " +
+                    "knowledgeGraph.enabled: true, or silence this note with knowledgeGraph: { enabled: false }. " +
+                    "See README § Memory Network.");
+            }
+        }
         // Register slash commands
         registerCommands(api, client, cfg);
         // Register service for lifecycle management

package/dist/lib/filters.js

@@ -6,6 +6,10 @@
  * Filters match against memory METADATA keys by their bare name — the same
  * convention `buildScopeFilter` uses (`openclaw_scope`, `openclaw_user`).
  */
+/** Metadata tag on auto-trace session-end rows (see `sendTrace` in client.ts). */
+export const AGENT_END_SOURCE = "agent_end";
+/** Metadata tag on mood-weather roll records (see `recordMoodRoll` in hooks/mood-weather.ts). */
+export const MOOD_WEATHER_SOURCE = "mood_weather";
 /**
  * Memories produced by the auto-trace session-end hook are tagged in metadata
  * as `openclaw_source: "agent_end"` (see `sendTrace` in client.ts). Those should
@@ -34,22 +38,46 @@
  * "openclaw_agent_end" — wrong on BOTH counts (the tag lives in metadata under
  * `openclaw_source`, value `"agent_end"`), so it silently matched nothing.
  */
-export const EXCLUDE_SESSION_END_FILTER = {
-    openclaw_source: { $ne: "agent_end" },
-};
 /**
  * The exclude clause to apply for a given config — or `undefined` to skip the
- * filter. `agent_end` rows are written ONLY by the auto-trace hook, so when
- * auto-trace is OFF there are none to hide and we skip the filter to avoid its
- * ~1s/search latency cost (pure overhead otherwise — verified live against an
- * auto-trace-off agent with zero `agent_end` rows).
+ * filter. Each excluded tag is gated on the feature that writes it, for
+ * PERFORMANCE, not correctness (see the header comment): with the feature off
+ * there are no tagged rows to hide, so the ~1s predicate would be pure latency.
  *
- * When auto-trace is ON we apply `{$ne:"agent_end"}`, which post-#1921 drops the
- * traces while KEEPING untagged hot-buffer rows — so that path is correct now
- * (the old #40 hot-row-drop is fixed by the backend, not by gating).
+ *  - `agent_end` rows are written ONLY by the auto-trace hook → gate on
+ *    `autoTrace.enabled` (verified live against an auto-trace-off agent with
+ *    zero `agent_end` rows).
+ *  - `mood_weather` rolls are recorded ONLY when the emotional-context handler
+ *    is registered AND the dice are live → gate on both flags.
+ *
+ * Shape: a single excluded value keeps the proven plain-`$ne` form (byte-
+ * identical to the shipped filter, and post-#1921 it drops the tag while
+ * KEEPING untagged hot-buffer rows). Two values use `$nin`.
+ *
+ * ⚠️ The `$nin` two-value shape has NOT been re-verified live post-#1921 (the
+ * pre-#1921 truth table showed `$nin` diverging from `$ne`). Owner's post-merge
+ * step: run `node docs/filter-dialect-test.mjs` — the `$nin[agent_end,mood_weather]`
+ * row must show U=Y, A=N, M=N. Fallback plan if it fails: try the
+ * `$and[$ne,$ne]` probe row; if that also fails, gate back to single-value
+ * `$ne` for the two common one-feature-on configs, log a warning when both
+ * features are enabled, and file a backend dialect follow-up
+ * (docs/hyperspell-backend-followups.md style) for the both-on combo.
  */
 export function excludeFilterFor(cfg) {
-    return cfg.autoTrace.enabled ? EXCLUDE_SESSION_END_FILTER : undefined;
+    const excluded = [];
+    if (cfg.autoTrace.enabled)
+        excluded.push(AGENT_END_SOURCE);
+    // Mood rolls are recorded only when the emotional-context handler is
+    // registered AND the dice are live — same "no rows to hide → skip the
+    // ~1s predicate" gate as auto-trace.
+    if (cfg.emotionalContext && cfg.moodWeatherChance > 0) {
+        excluded.push(MOOD_WEATHER_SOURCE);
+    }
+    if (excluded.length === 0)
+        return undefined;
+    if (excluded.length === 1)
+        return { openclaw_source: { $ne: excluded[0] } };
+    return { openclaw_source: { $nin: excluded } };
 }
 /**
  * Combine a caller-supplied filter with the session-end exclude via `$and`.