Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

refactor(agent-runtime): share the memory nudge text and cadence between the hosted loop and the local runtime

nirholas9f50f90cc438
diff --git a/api/_lib/agent-learning/nudge.js b/api/_lib/agent-learning/nudge.js
index 536faa834..6eb8ebce3 100644
--- a/api/_lib/agent-learning/nudge.js
+++ b/api/_lib/agent-learning/nudge.js
@@ -1,17 +1,21 @@
-// The memory nudge: a short reminder the runtime hands the agent at the end of
-// a run and every N turns of a conversation, asking it to persist anything
-// worth keeping.
+// The memory nudge on the hosted side.
//
-// The text itself lives in the model-facing operating skill
+// The text and cadence live in @three-ws/agent-runtime (utils/memoryNudge.js)
+// so the hosted loop and the local runtime (@three-ws/agent) share one module.
+// The model-facing operating skill publishes the same text to MCP clients
// (community-skills/skills/three-ws-mcp/SKILL.md, between the memory-nudge
-// markers) so the reminder a runtime injects and the guidance a connected MCP
-// client reads are one document that cannot drift apart. It is read once per
-// process.
+// markers); extractNudge() reads that block so a test can prove the two match.
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import {
+ MEMORY_NUDGE,
+ DEFAULT_NUDGE_EVERY_TURNS,
+ countUserTurns,
+ shouldNudge,
+ memoryNudgeMessage,
+} from '@three-ws/agent-runtime';
+
+export { MEMORY_NUDGE, DEFAULT_NUDGE_EVERY_TURNS, countUserTurns, shouldNudge, memoryNudgeMessage };
-const SKILL_PATH = fileURLToPath(new URL('../../../community-skills/skills/three-ws-mcp/SKILL.md', import.meta.url));
const START = '<!-- memory-nudge:start -->';
const END = '<!-- memory-nudge:end -->';
@@ -20,26 +24,11 @@ export function extractNudge(markdown) {
const text = String(markdown || '');
const a = text.indexOf(START);
const b = text.indexOf(END);
- if (a === -1 || b === -1 || b <= a) {
- throw new Error(`memory nudge markers not found in ${SKILL_PATH}`);
- }
+ if (a === -1 || b === -1 || b <= a) throw new Error('memory nudge markers not found');
return text.slice(a + START.length, b).replace(/\s+/g, ' ').trim();
}
-let cached = null;
-
-/** The nudge text, loaded from the operating skill on first use. */
+/** The nudge text. */
export function memoryNudge() {
- if (cached == null) cached = extractNudge(readFileSync(SKILL_PATH, 'utf8'));
- return cached;
-}
-
-/**
- * Whether a conversation turn should carry the nudge: every `every` user
- * turns, counting the current one. Turn 1 never does (nothing learned yet).
- */
-export function shouldNudge(userTurns, every) {
- const n = Number(userTurns) || 0;
- const k = Math.max(2, Number(every) || 6);
- return n >= k && n % k === 0;
+ return MEMORY_NUDGE;
}
diff --git a/packages/agent-runtime/src/utils/index.d.ts b/packages/agent-runtime/src/utils/index.d.ts
index 353a34754..85f3b9afd 100644
--- a/packages/agent-runtime/src/utils/index.d.ts
+++ b/packages/agent-runtime/src/utils/index.d.ts
@@ -2,3 +2,4 @@ export * from './importanceScorer.js';
export * from './receiptService.js';
export * from './stepContextComputer.js';
export * from './tokenCounter.js';
+export * from './memoryNudge.js';
diff --git a/packages/agent-runtime/src/utils/index.js b/packages/agent-runtime/src/utils/index.js
index 353a34754..85f3b9afd 100644
--- a/packages/agent-runtime/src/utils/index.js
+++ b/packages/agent-runtime/src/utils/index.js
@@ -2,3 +2,4 @@ export * from './importanceScorer.js';
export * from './receiptService.js';
export * from './stepContextComputer.js';
export * from './tokenCounter.js';
+export * from './memoryNudge.js';
diff --git a/packages/agent-runtime/src/utils/memoryNudge.d.ts b/packages/agent-runtime/src/utils/memoryNudge.d.ts
new file mode 100644
index 000000000..d33f27cd6
--- /dev/null
+++ b/packages/agent-runtime/src/utils/memoryNudge.d.ts
@@ -0,0 +1,14 @@
+/** The reminder a runtime hands the model to persist anything worth keeping. */
+export declare const MEMORY_NUDGE: string;
+/** Default cadence: a nudge every this many user turns. */
+export declare const DEFAULT_NUDGE_EVERY_TURNS = 6;
+/** How many user messages a transcript holds (the current one included). */
+export declare function countUserTurns(messages: Array<{ role: string }> | null | undefined): number;
+/** True every `every` user turns (never on turn 1). */
+export declare function shouldNudge(userTurns: number, every?: number): boolean;
+/** The nudge as a system message, or null when this turn should not carry it. */
+export declare function memoryNudgeMessage(o?: {
+ messages?: Array<{ role: string }>;
+ every?: number;
+ final?: boolean;
+}): { role: 'system'; content: string } | null;
diff --git a/packages/agent-runtime/src/utils/memoryNudge.js b/packages/agent-runtime/src/utils/memoryNudge.js
new file mode 100644
index 000000000..581ad76d3
--- /dev/null
+++ b/packages/agent-runtime/src/utils/memoryNudge.js
@@ -0,0 +1,45 @@
+// The memory nudge: the reminder an agent runtime hands the model at the end
+// of a run and every N turns of a conversation, asking it to persist anything
+// worth keeping through its memory tools.
+//
+// One module, two runtimes: the hosted loop (api/agent/run.js, agent runs and
+// the chat copilot on three.ws) and the local runtime (@three-ws/agent) both
+// import it from here, so the text and the cadence cannot drift between them.
+// The same text is published to connected MCP clients in the operating skill
+// (community-skills/skills/three-ws-mcp/SKILL.md, between the memory-nudge
+// markers); tests/agent-learning.test.js fails if the two ever differ.
+
+export const MEMORY_NUDGE =
+ 'Before you finish: is there anything from this exchange worth remembering next time? Save only what is durable and specific: a preference the person stated or showed (kind preference), a fact about their situation or goals (kind user-model, with a section), a correction to something you believed, or the steps of a task that worked (kind procedure). One idea per memory, written so it makes sense with no other context. Skip small talk, one-off details, anything already in memory, and secrets such as keys, passwords or seed phrases. If nothing qualifies, save nothing and do not mention memory.';
+
+/** Default cadence: a nudge every this many user turns. */
+export const DEFAULT_NUDGE_EVERY_TURNS = 6;
+
+/** How many user messages a transcript holds (the current one included). */
+export function countUserTurns(messages) {
+ let n = 0;
+ for (const m of messages || []) if (m && m.role === 'user') n++;
+ return n;
+}
+
+/**
+ * Whether a conversation turn should carry the nudge: every `every` user
+ * turns, counting the current one. Turn 1 never does (nothing learned yet).
+ */
+export function shouldNudge(userTurns, every = DEFAULT_NUDGE_EVERY_TURNS) {
+ const n = Number(userTurns) || 0;
+ const k = Math.max(2, Number(every) || DEFAULT_NUDGE_EVERY_TURNS);
+ return n >= k && n % k === 0;
+}
+
+/**
+ * The nudge as a system message, or null when this turn should not carry it.
+ * `final: true` is the end-of-run nudge and always fires.
+ *
+ * @param {{ messages?: Array<{role:string}>, every?: number, final?: boolean }} o
+ * @returns {{ role: 'system', content: string } | null}
+ */
+export function memoryNudgeMessage({ messages = [], every = DEFAULT_NUDGE_EVERY_TURNS, final = false } = {}) {
+ if (!final && !shouldNudge(countUserTurns(messages), every)) return null;
+ return { role: 'system', content: MEMORY_NUDGE };
+}