@botcord/daemon 0.2.71 → 0.2.72

package/dist/daemon.js

@@ -11,6 +11,7 @@ import { adoptDiscoveredOpenclawAgents, collectRuntimeSnapshot, createProvisione
 import { openclawAutoProvisionEnabled } from "./openclaw-discovery.js";
 import { SnapshotWriter } from "./snapshot-writer.js";
 import { createDaemonSystemContextBuilder } from "./system-context.js";
+import { readWorkingMemorySnapshot } from "./working-memory.js";
 import { createRoomStaticContextBuilder } from "./room-context.js";
 import { createRoomContextFetcher } from "./room-context-fetcher.js";
 import { buildLoopRiskPrompt, loopRiskSessionKey, recordInboundText as recordLoopRiskInbound, recordOutboundText as recordLoopRiskOutbound, } from "./loop-risk.js";
@@ -261,6 +262,7 @@ export async function startDaemon(opts) {
         const fallback = scBuilders.get(first);
         return fallback ? fallback(message) : undefined;
     };
+    const buildMemoryContext = (message) => readWorkingMemorySnapshot(message.accountId);
     // Observer runs after ack + before runtime.run. Keeping the side effect
     // outside the system-context builder (option A) means the builder stays
     // pure — a cleaner contract the gateway can also expose to non-daemon
@@ -362,6 +364,7 @@ export async function startDaemon(opts) {
         log: logger,
         turnTimeoutMs: DEFAULT_TURN_TIMEOUT_MS,
         buildSystemContext,
+        buildMemoryContext,
         onInbound,
         onOutbound,
         composeUserTurn: composeBotCordUserTurn,

package/dist/gateway/dispatcher.d.ts

@@ -1,7 +1,7 @@
 import type { GatewayLogger } from "./log.js";
 import { type SessionStore } from "./session-store.js";
 import { type TranscriptWriter } from "./transcript.js";
-import type { ChannelAdapter, GatewayConfig, GatewayInboundEnvelope, GatewayInboundMessage, GatewayRoute, InboundObserver, OutboundObserver, RuntimeAdapter, SystemContextBuilder, TurnStatusSnapshot, UserTurnBuilder } from "./types.js";
+import type { ChannelAdapter, GatewayConfig, GatewayInboundEnvelope, GatewayInboundMessage, GatewayRoute, InboundObserver, MemoryContextBuilder, OutboundObserver, RuntimeAdapter, SystemContextBuilder, TurnStatusSnapshot, UserTurnBuilder } from "./types.js";
 /** Factory signature for building a runtime adapter at turn dispatch time. */
 export type RuntimeFactory = (runtimeId: string, extraArgs?: string[]) => RuntimeAdapter;
 /** Constructor options for `Dispatcher`. */
@@ -24,6 +24,13 @@ export interface DispatcherOptions {
      * swallowed and logged — they never abort the turn.
      */
     buildSystemContext?: SystemContextBuilder;
+    /**
+     * Optional hook returning the current working-memory snapshot/version. When
+     * a resumed runtime session last saw a different version, dispatcher injects
+     * the snapshot into the actual user prompt so resumed transcripts cannot
+     * keep following stale memory.
+     */
+    buildMemoryContext?: MemoryContextBuilder;
     /**
      * Optional side-effect hook invoked after ack, before the turn runs.
      * Intended for bookkeeping (e.g. activity tracking). Errors are logged
@@ -86,6 +93,7 @@ export declare class Dispatcher {
     private readonly log;
     private readonly turnTimeoutMs;
     private readonly buildSystemContext?;
+    private readonly buildMemoryContext?;
     private readonly onInbound?;
     private readonly onOutbound?;
     private readonly composeUserTurn?;

package/dist/gateway/dispatcher.js

@@ -39,6 +39,18 @@ function transcriptBlocksVerbose() {
     return process.env.BOTCORD_TRANSCRIPT_BLOCKS === "verbose" ||
         process.env.BOTCORD_TRACE_VERBOSE === "1";
 }
+function buildMemoryUpdateNotice(args) {
+    return [
+        "[BotCord Memory Update Notice]",
+        `The persistent working memory changed since this runtime session last used it (previous: ${args.previousVersion ?? "none"}, current: ${args.currentVersion}).`,
+        "Before acting on the message below, retrieve the latest working memory through the available BotCord memory tool or CLI, then treat that latest memory as authoritative.",
+        "If using the local daemon CLI, run: botcord-daemon memory get",
+        "The latest memory supersedes older goals, monitoring rules, preferences, and task state in the resumed conversation.",
+        "",
+        "[Current Message]",
+        args.userTurn,
+    ].join("\n");
+}
 function summarizeStreamBlock(block) {
     const summary = { type: block.kind };
     const raw = block.raw;
@@ -126,6 +138,7 @@ export class Dispatcher {
     log;
     turnTimeoutMs;
     buildSystemContext;
+    buildMemoryContext;
     onInbound;
     onOutbound;
     composeUserTurn;
@@ -149,6 +162,7 @@ export class Dispatcher {
         this.log = opts.log;
         this.turnTimeoutMs = opts.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
         this.buildSystemContext = opts.buildSystemContext;
+        this.buildMemoryContext = opts.buildMemoryContext;
         this.onInbound = opts.onInbound;
         this.onOutbound = opts.onOutbound;
         this.composeUserTurn = opts.composeUserTurn;
@@ -749,6 +763,8 @@ export class Dispatcher {
         });
         const entry = this.sessionStore.get(key);
         const sessionId = entry?.runtimeSessionId ?? null;
+        let currentMemoryVersion;
+        let runtimeText = text;
         const trustLevel = route.trustLevel ?? "trusted";
         const streamable = msg.trace?.streamable === true;
         const traceId = msg.trace?.id;
@@ -1008,13 +1024,45 @@ export class Dispatcher {
                 });
             }
         }
+        if (this.buildMemoryContext) {
+            try {
+                const snapshot = await this.buildMemoryContext(msg);
+                if (snapshot &&
+                    typeof snapshot.version === "string" &&
+                    snapshot.version.length > 0) {
+                    currentMemoryVersion = snapshot.version;
+                    const previousMemoryVersion = entry?.memoryVersion ?? null;
+                    if (sessionId && previousMemoryVersion !== currentMemoryVersion) {
+                        runtimeText = buildMemoryUpdateNotice({
+                            previousVersion: previousMemoryVersion,
+                            currentVersion: currentMemoryVersion,
+                            userTurn: text,
+                        });
+                        this.log.info("dispatcher: injected memory update notice", {
+                            agentId: msg.accountId,
+                            roomId: msg.conversation.id,
+                            topicId: msg.conversation.threadId ?? null,
+                            turnId,
+                            previousMemoryVersion,
+                            currentMemoryVersion,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                this.log.warn("buildMemoryContext threw — continuing without memory version check", {
+                    error: err instanceof Error ? err.message : String(err),
+                    messageId: msg.id,
+                });
+            }
+        }
         const runtime = this.runtimeFactory(route.runtime, route.extraArgs);
         let result;
         let threw;
         try {
             try {
                 result = await runtime.run({
-                    text,
+                    text: runtimeText,
                     sessionId,
                     cwd: route.cwd,
                     accountId: msg.accountId,
@@ -1194,6 +1242,7 @@ export class Dispatcher {
                     key,
                     runtime: route.runtime,
                     runtimeSessionId: result.newSessionId,
+                    memoryVersion: currentMemoryVersion ?? entry?.memoryVersion ?? null,
                     channel: msg.channel,
                     accountId: msg.accountId,
                     conversationKind: msg.conversation.kind,

package/dist/gateway/gateway.d.ts

@@ -2,7 +2,7 @@ import { type ChannelBackoffOptions } from "./channel-manager.js";
 import { type RuntimeFactory } from "./dispatcher.js";
 import { type GatewayLogger } from "./log.js";
 import { type TranscriptWriter } from "./transcript.js";
-import type { ChannelAdapter, GatewayChannelConfig, GatewayConfig, GatewayInboundMessage, GatewayOutboundMessage, GatewayRoute, GatewayRuntimeSnapshot, InboundObserver, OutboundObserver, SystemContextBuilder, UserTurnBuilder } from "./types.js";
+import type { ChannelAdapter, GatewayChannelConfig, GatewayConfig, GatewayInboundMessage, GatewayOutboundMessage, GatewayRoute, GatewayRuntimeSnapshot, InboundObserver, MemoryContextBuilder, OutboundObserver, SystemContextBuilder, UserTurnBuilder } from "./types.js";
 /** Constructor options for `Gateway`. */
 export interface GatewayBootOptions {
     config: GatewayConfig;
@@ -20,6 +20,11 @@ export interface GatewayBootOptions {
      * abort the turn.
      */
     buildSystemContext?: SystemContextBuilder;
+    /**
+     * Snapshot/version hook for working memory. Forwarded to dispatcher so
+     * resumed runtime sessions get an explicit prompt when memory changes.
+     */
+    buildMemoryContext?: MemoryContextBuilder;
     /**
      * Observer called after the dispatcher acks each inbound message. Useful
      * for activity tracking or metrics. Errors are logged and swallowed.

package/dist/gateway/gateway.js

@@ -68,6 +68,7 @@ export class Gateway {
             log: this.log,
             turnTimeoutMs: opts.turnTimeoutMs,
             buildSystemContext: opts.buildSystemContext,
+            buildMemoryContext: opts.buildMemoryContext,
             onInbound: opts.onInbound,
             composeUserTurn: opts.composeUserTurn,
             onOutbound: opts.onOutbound,

package/dist/gateway/types.d.ts

@@ -133,6 +133,10 @@ export type InboundObserver = (message: GatewayInboundMessage) => Promise<void>
  * a buggy composer never drops turns.
  */
 export type UserTurnBuilder = (message: GatewayInboundMessage) => string;
+export interface MemoryContextSnapshot {
+    version: string;
+}
+export type MemoryContextBuilder = (message: GatewayInboundMessage) => Promise<MemoryContextSnapshot | null | undefined> | MemoryContextSnapshot | null | undefined;
 /**
  * Optional hook fired after the dispatcher dispatches a reply to a channel.
  * Intended for outbound bookkeeping (loop-risk tracking, metrics). Errors
@@ -382,6 +386,8 @@ export interface GatewaySessionEntry {
     key: string;
     runtime: string;
     runtimeSessionId: string;
+    /** Version of working memory last injected into this runtime session. */
+    memoryVersion?: string | null;
     channel: string;
     accountId: string;
     conversationKind: "direct" | "group";

package/dist/working-memory.d.ts

@@ -4,6 +4,10 @@ export interface WorkingMemory {
     sections: Record<string, string>;
     updatedAt: string;
 }
+export interface WorkingMemorySnapshot {
+    memory: WorkingMemory | null;
+    version: string;
+}
 /** Characters per section; matches the plugin-side limit. */
 export declare const MAX_SECTION_CHARS = 10000;
 export declare const MAX_GOAL_CHARS = 500;
@@ -15,6 +19,8 @@ export declare const DEFAULT_SECTION = "notes";
  */
 export declare function resolveMemoryDir(agentId: string): string;
 export declare function readWorkingMemory(agentId: string): WorkingMemory | null;
+export declare function workingMemoryVersion(memory: WorkingMemory | null): string;
+export declare function readWorkingMemorySnapshot(agentId: string): WorkingMemorySnapshot;
 export declare function writeWorkingMemory(agentId: string, data: WorkingMemory): void;
 export interface SetSectionResult {
     memory: WorkingMemory;

package/dist/working-memory.js

@@ -9,6 +9,7 @@
  * branches) and plugin/src/memory-protocol.ts (prompt builder).
  */
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import path from "node:path";
 import { agentStateDir } from "./agent-workspace.js";
@@ -171,6 +172,28 @@ export function readWorkingMemory(agentId) {
         return null;
     return normalize(readJson(p));
 }
+function canonicalizeWorkingMemory(memory) {
+    const sections = {};
+    for (const [key, value] of Object.entries(memory?.sections ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+        sections[key] = value;
+    }
+    return {
+        version: 2,
+        goal: memory?.goal ?? null,
+        sections,
+    };
+}
+export function workingMemoryVersion(memory) {
+    const canonical = JSON.stringify(canonicalizeWorkingMemory(memory));
+    return `wm-sha256:${createHash("sha256").update(canonical).digest("hex").slice(0, 16)}`;
+}
+export function readWorkingMemorySnapshot(agentId) {
+    const memory = readWorkingMemory(agentId);
+    return {
+        memory,
+        version: workingMemoryVersion(memory),
+    };
+}
 export function writeWorkingMemory(agentId, data) {
     writeJsonAtomic(workingMemoryPath(agentId), data);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/daemon",
-  "version": "0.2.71",
+  "version": "0.2.72",
   "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
   "type": "module",
   "bin": {

package/src/__tests__/working-memory.test.ts

@@ -274,3 +274,33 @@ describe("buildWorkingMemoryPrompt", () => {
     expect(p).toContain("‹current_memory›");
   });
 });
+
+describe("working-memory version", () => {
+  it("is stable for identical content regardless of section insertion order or updatedAt", () => {
+    const a = wm.workingMemoryVersion({
+      version: 2,
+      sections: { b: "two", a: "one" },
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    });
+    const b = wm.workingMemoryVersion({
+      version: 2,
+      sections: { a: "one", b: "two" },
+      updatedAt: "2026-01-02T00:00:00.000Z",
+    });
+    expect(a).toBe(b);
+  });
+
+  it("changes when durable memory content changes", () => {
+    const a = wm.workingMemoryVersion({
+      version: 2,
+      sections: { notes: "old" },
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    });
+    const b = wm.workingMemoryVersion({
+      version: 2,
+      sections: { notes: "new" },
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    });
+    expect(a).not.toBe(b);
+  });
+});

package/src/daemon.ts

@@ -35,6 +35,7 @@ import {
 import { openclawAutoProvisionEnabled } from "./openclaw-discovery.js";
 import { SnapshotWriter } from "./snapshot-writer.js";
 import { createDaemonSystemContextBuilder } from "./system-context.js";
+import { readWorkingMemorySnapshot } from "./working-memory.js";
 import { createRoomStaticContextBuilder } from "./room-context.js";
 import { createRoomContextFetcher } from "./room-context-fetcher.js";
 import {
@@ -400,6 +401,8 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
     const fallback = scBuilders.get(first);
     return fallback ? fallback(message) : undefined;
   };
+  const buildMemoryContext = (message: GatewayInboundMessage) =>
+    readWorkingMemorySnapshot(message.accountId);
 
   // Observer runs after ack + before runtime.run. Keeping the side effect
   // outside the system-context builder (option A) means the builder stays
@@ -511,6 +514,7 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
     log: logger,
     turnTimeoutMs: DEFAULT_TURN_TIMEOUT_MS,
     buildSystemContext,
+    buildMemoryContext,
     onInbound,
     onOutbound,
     composeUserTurn: composeBotCordUserTurn,

package/src/gateway/__tests__/dispatcher.test.ts

@@ -1605,6 +1605,71 @@ describe("Dispatcher", () => {
     ).toBe(true);
   });
 
+  it("injects a memory update notice into resumed sessions when memory version changes", async () => {
+    const seenText: string[] = [];
+    let memoryVersion = "wm-sha256:v1";
+    const runtime = new FakeRuntime({
+      newSessionId: (opts) => opts.sessionId ?? "sid-1",
+      observeRun: (opts) => seenText.push(opts.text),
+    });
+    const { store, dir } = await makeStore();
+    tempDirs.push(dir);
+    const channel = new FakeChannel();
+    const channels = new Map<string, ChannelAdapter>([[channel.id, channel]]);
+    const dispatcher = new Dispatcher({
+      config: baseConfig(),
+      channels,
+      runtime: () => runtime,
+      sessionStore: store,
+      log: silentLogger(),
+      buildMemoryContext: () => ({
+        version: memoryVersion,
+      }),
+    });
+
+    await dispatcher.handle(makeEnvelope({ id: "msg_1", text: "first" }));
+    expect(seenText[0]).toBe("first");
+    expect(store.all()[0].memoryVersion).toBe("wm-sha256:v1");
+
+    memoryVersion = "wm-sha256:v2";
+    await dispatcher.handle(makeEnvelope({ id: "msg_2", text: "second" }));
+    expect(seenText[1]).toContain("[BotCord Memory Update Notice]");
+    expect(seenText[1]).toContain("previous: wm-sha256:v1, current: wm-sha256:v2");
+    expect(seenText[1]).toContain("retrieve the latest working memory");
+    expect(seenText[1]).toContain("botcord-daemon memory get");
+    expect(seenText[1]).not.toContain("[BotCord Working Memory]\nversion wm-sha256:v2");
+    expect(seenText[1]).toContain("[Current Message]\nsecond");
+    expect(store.all()[0].memoryVersion).toBe("wm-sha256:v2");
+  });
+
+  it("does not inject a memory update notice when the resumed session already has the current memory version", async () => {
+    const seenText: string[] = [];
+    const runtime = new FakeRuntime({
+      newSessionId: (opts) => opts.sessionId ?? "sid-1",
+      observeRun: (opts) => seenText.push(opts.text),
+    });
+    const { store, dir } = await makeStore();
+    tempDirs.push(dir);
+    const channel = new FakeChannel();
+    const channels = new Map<string, ChannelAdapter>([[channel.id, channel]]);
+    const dispatcher = new Dispatcher({
+      config: baseConfig(),
+      channels,
+      runtime: () => runtime,
+      sessionStore: store,
+      log: silentLogger(),
+      buildMemoryContext: () => ({
+        version: "wm-sha256:same",
+      }),
+    });
+
+    await dispatcher.handle(makeEnvelope({ id: "msg_1", text: "first" }));
+    await dispatcher.handle(makeEnvelope({ id: "msg_2", text: "second" }));
+
+    expect(seenText).toEqual(["first", "second"]);
+    expect(store.all()[0].memoryVersion).toBe("wm-sha256:same");
+  });
+
   it("onInbound: observer is invoked with the message between ack and runtime.run", async () => {
     const order: string[] = [];
     const runtime = new FakeRuntime({

package/src/gateway/dispatcher.ts

@@ -18,6 +18,7 @@ import type {
   GatewayRoute,
   GatewaySessionEntry,
   InboundObserver,
+  MemoryContextBuilder,
   OutboundObserver,
   QueueMode,
   RuntimeAdapter,
@@ -73,6 +74,23 @@ function transcriptBlocksVerbose(): boolean {
     process.env.BOTCORD_TRACE_VERBOSE === "1";
 }
 
+function buildMemoryUpdateNotice(args: {
+  previousVersion: string | null;
+  currentVersion: string;
+  userTurn: string;
+}): string {
+  return [
+    "[BotCord Memory Update Notice]",
+    `The persistent working memory changed since this runtime session last used it (previous: ${args.previousVersion ?? "none"}, current: ${args.currentVersion}).`,
+    "Before acting on the message below, retrieve the latest working memory through the available BotCord memory tool or CLI, then treat that latest memory as authoritative.",
+    "If using the local daemon CLI, run: botcord-daemon memory get",
+    "The latest memory supersedes older goals, monitoring rules, preferences, and task state in the resumed conversation.",
+    "",
+    "[Current Message]",
+    args.userTurn,
+  ].join("\n");
+}
+
 function summarizeStreamBlock(block: StreamBlock): TranscriptBlockSummary {
   const summary: TranscriptBlockSummary = { type: block.kind };
   const raw = block.raw as {
@@ -150,6 +168,13 @@ export interface DispatcherOptions {
    * swallowed and logged — they never abort the turn.
    */
   buildSystemContext?: SystemContextBuilder;
+  /**
+   * Optional hook returning the current working-memory snapshot/version. When
+   * a resumed runtime session last saw a different version, dispatcher injects
+   * the snapshot into the actual user prompt so resumed transcripts cannot
+   * keep following stale memory.
+   */
+  buildMemoryContext?: MemoryContextBuilder;
   /**
    * Optional side-effect hook invoked after ack, before the turn runs.
    * Intended for bookkeeping (e.g. activity tracking). Errors are logged
@@ -285,6 +310,7 @@ export class Dispatcher {
   private readonly log: GatewayLogger;
   private readonly turnTimeoutMs: number;
   private readonly buildSystemContext?: SystemContextBuilder;
+  private readonly buildMemoryContext?: MemoryContextBuilder;
   private readonly onInbound?: InboundObserver;
   private readonly onOutbound?: OutboundObserver;
   private readonly composeUserTurn?: UserTurnBuilder;
@@ -311,6 +337,7 @@ export class Dispatcher {
     this.log = opts.log;
     this.turnTimeoutMs = opts.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
     this.buildSystemContext = opts.buildSystemContext;
+    this.buildMemoryContext = opts.buildMemoryContext;
     this.onInbound = opts.onInbound;
     this.onOutbound = opts.onOutbound;
     this.composeUserTurn = opts.composeUserTurn;
@@ -990,6 +1017,8 @@ export class Dispatcher {
     });
     const entry = this.sessionStore.get(key);
     const sessionId = entry?.runtimeSessionId ?? null;
+    let currentMemoryVersion: string | undefined;
+    let runtimeText = text;
     const trustLevel = route.trustLevel ?? "trusted";
 
     const streamable = msg.trace?.streamable === true;
@@ -1252,13 +1281,47 @@ export class Dispatcher {
       }
     }
 
+    if (this.buildMemoryContext) {
+      try {
+        const snapshot = await this.buildMemoryContext(msg);
+        if (
+          snapshot &&
+          typeof snapshot.version === "string" &&
+          snapshot.version.length > 0
+        ) {
+          currentMemoryVersion = snapshot.version;
+          const previousMemoryVersion = entry?.memoryVersion ?? null;
+          if (sessionId && previousMemoryVersion !== currentMemoryVersion) {
+            runtimeText = buildMemoryUpdateNotice({
+              previousVersion: previousMemoryVersion,
+              currentVersion: currentMemoryVersion,
+              userTurn: text,
+            });
+            this.log.info("dispatcher: injected memory update notice", {
+              agentId: msg.accountId,
+              roomId: msg.conversation.id,
+              topicId: msg.conversation.threadId ?? null,
+              turnId,
+              previousMemoryVersion,
+              currentMemoryVersion,
+            });
+          }
+        }
+      } catch (err) {
+        this.log.warn("buildMemoryContext threw — continuing without memory version check", {
+          error: err instanceof Error ? err.message : String(err),
+          messageId: msg.id,
+        });
+      }
+    }
+
     const runtime = this.runtimeFactory(route.runtime, route.extraArgs);
     let result: { text: string; newSessionId: string; costUsd?: number; error?: string } | undefined;
     let threw: unknown;
     try {
       try {
         result = await runtime.run({
-          text,
+          text: runtimeText,
           sessionId,
           cwd: route.cwd,
           accountId: msg.accountId,
@@ -1438,6 +1501,7 @@ export class Dispatcher {
           key,
           runtime: route.runtime,
           runtimeSessionId: result.newSessionId,
+          memoryVersion: currentMemoryVersion ?? entry?.memoryVersion ?? null,
           channel: msg.channel,
           accountId: msg.accountId,
           conversationKind: msg.conversation.kind,

package/src/gateway/gateway.ts

@@ -17,6 +17,7 @@ import type {
   GatewayRoute,
   GatewayRuntimeSnapshot,
   InboundObserver,
+  MemoryContextBuilder,
   OutboundObserver,
   SystemContextBuilder,
   UserTurnBuilder,
@@ -39,6 +40,11 @@ export interface GatewayBootOptions {
    * abort the turn.
    */
   buildSystemContext?: SystemContextBuilder;
+  /**
+   * Snapshot/version hook for working memory. Forwarded to dispatcher so
+   * resumed runtime sessions get an explicit prompt when memory changes.
+   */
+  buildMemoryContext?: MemoryContextBuilder;
   /**
    * Observer called after the dispatcher acks each inbound message. Useful
    * for activity tracking or metrics. Errors are logged and swallowed.
@@ -159,6 +165,7 @@ export class Gateway {
       log: this.log,
       turnTimeoutMs: opts.turnTimeoutMs,
       buildSystemContext: opts.buildSystemContext,
+      buildMemoryContext: opts.buildMemoryContext,
       onInbound: opts.onInbound,
       composeUserTurn: opts.composeUserTurn,
       onOutbound: opts.onOutbound,

package/src/gateway/types.ts

@@ -162,6 +162,14 @@ export type InboundObserver = (
  */
 export type UserTurnBuilder = (message: GatewayInboundMessage) => string;
 
+export interface MemoryContextSnapshot {
+  version: string;
+}
+
+export type MemoryContextBuilder = (
+  message: GatewayInboundMessage,
+) => Promise<MemoryContextSnapshot | null | undefined> | MemoryContextSnapshot | null | undefined;
+
 /**
  * Optional hook fired after the dispatcher dispatches a reply to a channel.
  * Intended for outbound bookkeeping (loop-risk tracking, metrics). Errors
@@ -448,6 +456,8 @@ export interface GatewaySessionEntry {
   key: string;
   runtime: string;
   runtimeSessionId: string;
+  /** Version of working memory last injected into this runtime session. */
+  memoryVersion?: string | null;
   channel: string;
   accountId: string;
   conversationKind: "direct" | "group";

package/src/working-memory.ts

@@ -17,6 +17,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import path from "node:path";
 import { agentStateDir } from "./agent-workspace.js";
@@ -30,6 +31,11 @@ export interface WorkingMemory {
   updatedAt: string;
 }
 
+export interface WorkingMemorySnapshot {
+  memory: WorkingMemory | null;
+  version: string;
+}
+
 /** v1 shape kept only for one-way migration on read. */
 interface WorkingMemoryV1 {
   version: 1;
@@ -205,6 +211,33 @@ export function readWorkingMemory(agentId: string): WorkingMemory | null {
   return normalize(readJson<unknown>(p));
 }
 
+function canonicalizeWorkingMemory(memory: WorkingMemory | null): unknown {
+  const sections: Record<string, string> = {};
+  for (const [key, value] of Object.entries(memory?.sections ?? {}).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    sections[key] = value;
+  }
+  return {
+    version: 2,
+    goal: memory?.goal ?? null,
+    sections,
+  };
+}
+
+export function workingMemoryVersion(memory: WorkingMemory | null): string {
+  const canonical = JSON.stringify(canonicalizeWorkingMemory(memory));
+  return `wm-sha256:${createHash("sha256").update(canonical).digest("hex").slice(0, 16)}`;
+}
+
+export function readWorkingMemorySnapshot(agentId: string): WorkingMemorySnapshot {
+  const memory = readWorkingMemory(agentId);
+  return {
+    memory,
+    version: workingMemoryVersion(memory),
+  };
+}
+
 export function writeWorkingMemory(agentId: string, data: WorkingMemory): void {
   writeJsonAtomic(workingMemoryPath(agentId), data);
 }