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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsindex 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.tsindex 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.jsindex 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.tsnew file mode 100644index 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.jsnew file mode 100644index 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 };+}