@mastra/memory 1.20.3 → 1.20.6-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.20.3"
+  version: "1.20.6-alpha.0"
 ---
 
 ## When to use
@@ -18,6 +18,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 - [Agent approval](references/docs-agents-agent-approval.md) - Learn how to require approvals, suspend tool execution, and automatically resume suspended tools while keeping humans in control of agent workflows.
 - [Background tasks](references/docs-agents-background-tasks.md) - Learn how to dispatch long-running tool calls in the background, keep the stream open until they complete, and orchestrate subagents asynchronously.
+- [Goals](references/docs-agents-goals.md) - Learn how to set a durable objective on an agent that is judged in the execution loop, so the agent keeps working until the goal is complete or the run budget is exhausted.
 - [Agent networks](references/docs-agents-networks.md) - Coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 - [Supervisor agents](references/docs-agents-supervisor-agents.md) - Learn how to coordinate multiple agents with delegation hooks, iteration monitoring, message filtering, and task completion scoring.
 - [Evals with memory](references/docs-evals-evals-with-memory.md) - Run scorers against memory-enabled agents — including observational memory in thread scope — using runEvals and dataset experiments.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,120 +1,120 @@
 {
-  "version": "1.20.3",
+  "version": "1.20.6-alpha.0",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 787
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 795
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js"
+      "implementation": "dist/chunk-3I6H2ABM.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 7175
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 7194
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 9747
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 9766
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 6506
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 6525
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 3774
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 3782
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 3045
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 3053
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 879
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 887
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 913
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 921
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 3888
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 3896
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 3500
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 3508
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 9967
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 9986
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 3876
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 3884
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 2593
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 2601
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 3899
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 3907
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 2566
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 2574
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 848
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 856
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 3784
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 3792
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 937
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 945
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 893
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 901
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 2623
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 2631
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 870
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 878
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-YJJXL5KY.js",
-      "line": 841
+      "implementation": "dist/chunk-3I6H2ABM.js",
+      "line": 849
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
@@ -162,7 +162,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-YJJXL5KY.js",
+        "chunk-3I6H2ABM.js",
         "chunk-LSJJAJAF.js"
       ]
     }

package/dist/docs/references/docs-agents-goals.md

@@ -0,0 +1,110 @@
+# Goals
+
+**Added in:** `@mastra/core@1.42.0`
+
+A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it is satisfied or a run budget is exhausted. The objective is persisted in thread state, so it survives reloads and is evaluated in-loop — even when a new message arrives in the middle of an already-running turn.
+
+Goals build on the same machinery as [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents): an LLM-as-judge scores the agent's output each iteration and gates the loop. The difference is that a goal is **durable** (stored in thread state, not passed per call) and is set and updated through `Agent` methods rather than per-`stream()` options.
+
+> **Note:** Goals are experimental and may change in a future release.
+
+## When to use goals
+
+Use a goal when you want an agent to keep working toward a single objective across many iterations and messages, without re-supplying the success criteria on every call:
+
+- A standing objective the agent should pursue until a judge says it's done.
+- Work that should continue across mid-run messages (a message delivered into a live run is still judged against the goal).
+- An objective that must persist across thread reloads or process restarts.
+
+For a one-off completion check within a single `stream()` call, use [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents) instead.
+
+## Quickstart
+
+Goals require a configured [storage](https://mastra.ai/docs/memory/storage) backend and a memory-backed thread. Add a `goal` config to the agent — a judge model is required for the goal to do anything — then set an objective for a thread:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+const worker = new Agent({
+  name: 'worker',
+  instructions: 'You complete software tasks end to end.',
+  model: 'openai/gpt-5.5',
+  memory,
+  goal: {
+    judge: 'openai/gpt-5-mini',
+    maxRuns: 50,
+  },
+})
+
+// Set the durable objective for a thread.
+await worker.setObjective('Add and test a /health endpoint', {
+  threadId,
+  resourceId,
+})
+
+// The objective is judged each iteration until it's complete or maxRuns is hit.
+const stream = await worker.stream('Start working on the goal', {
+  memory: { thread: threadId, resource: resourceId },
+})
+```
+
+The `goal` config auto-registers the state-signal projection, so the model always sees the current objective as `<current-objective>` in its context — no extra setup needed.
+
+## How the goal step works
+
+A goal step runs inside the agentic execution loop, right after `isTaskComplete`. On a real candidate answer it scores the conversation against the objective and gates the loop:
+
+- **Not satisfied, budget remaining** → the loop continues; per-evaluation feedback is injected so the agent iterates.
+- **Satisfied** → the loop stops and the objective is marked `done`.
+- **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops but the objective stays `active`, so raising `maxRuns` later can resume it.
+
+The step is a no-op for background-task, mid-tool-loop, and working-memory-only iterations — the same gating as `isTaskComplete`.
+
+**The judge model is the activation switch.** If no judge resolves (neither the per-objective override nor the agent's `goal.judge`), the goal step does nothing: no scoring, no budget consumed, no `goal` chunk. Effective settings resolve as per-objective record value → agent `goal` config → built-in default (`maxRuns` `50`, a default judge prompt).
+
+By default the step uses a built-in LLM-as-judge scorer that returns `1` when the objective is achieved and `0` otherwise. Supply your own scorer with `goal.scorer` to customize judging.
+
+```typescript
+const worker = new Agent({
+  name: 'worker',
+  instructions: 'You complete software tasks end to end.',
+  model: 'openai/gpt-5.5',
+  memory,
+  goal: {
+    // A resolver function lets you inject provider credentials and read the
+    // current judge selection at runtime; returning `undefined` keeps the
+    // goal step a no-op.
+    judge: ({ requestContext }) => resolveJudgeModel(requestContext),
+    maxRuns: 30,
+    prompt: 'Only mark the goal complete when tests pass.',
+  },
+})
+```
+
+Each evaluation emits a typed `goal` stream chunk (`GoalEvaluationPayload`: `objective`, `iteration`, `maxRuns`, `passed`, `status`, `results`, `reason`, `duration`, `timedOut`, `maxRunsReached`, `suppressFeedback`) so a UI can show goal progress mid-run.
+
+## Managing the objective
+
+Control the objective for a thread with `Agent` methods. All of them no-op when the run is not memory-backed (they require storage and a `threadId`):
+
+```typescript
+// Read the current objective record.
+const record = await worker.getObjective({ threadId })
+
+// Update options on the active objective (only provided fields are written;
+// unset fields fall back to the agent's `goal` config).
+await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })
+
+// Drop the objective.
+await worker.clearObjective({ threadId })
+```
+
+Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state.
+
+> **Note:** See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
+
+## Related
+
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) — `isTaskComplete` and the rubric scorer
+- [Signal providers](https://mastra.ai/docs/agents/signal-providers) — how the objective is projected into context
+- [Memory storage](https://mastra.ai/docs/memory/storage) — the storage backend goals require

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk4TZ5SRFX_cjs = require('./chunk-4TZ5SRFX.cjs');
+var chunk2ZNDDQ6X_cjs = require('./chunk-2ZNDDQ6X.cjs');
 var chunk43FJOLKM_cjs = require('./chunk-43FJOLKM.cjs');
 var chunkQ7SFCCGT_cjs = require('./chunk-Q7SFCCGT.cjs');
 var agent = require('@mastra/core/agent');
@@ -10,6 +10,7 @@ var observability = require('@mastra/core/observability');
 var utils = require('@mastra/core/utils');
 var schema = require('@mastra/schema-compat/schema');
 var asyncMutex = require('async-mutex');
+var lruCache = require('lru-cache');
 var xxhash = require('xxhash-wasm');
 var tools = require('@mastra/core/tools');
 var tokenx = require('tokenx');
@@ -20,7 +21,7 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var xxhash__default = /*#__PURE__*/_interopDefault(xxhash);
 
-// ../_vendored/ai_v4/dist/chunk-J65CK2AI.js
+// ../_vendored/ai_v4/dist/chunk-QGLOM3VL.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -22918,7 +22919,7 @@ var ZodFirstPartyTypeKind3;
   ZodFirstPartyTypeKind4["ZodReadonly"] = "ZodReadonly";
 })(ZodFirstPartyTypeKind3 || (ZodFirstPartyTypeKind3 = {}));
 
-// ../_vendored/ai_v5/dist/chunk-LPCSE373.js
+// ../_vendored/ai_v5/dist/chunk-OMTTDYJT.js
 var marker17 = "vercel.ai.error";
 var symbol18 = Symbol.for(marker17);
 var _a19;
@@ -46034,7 +46035,7 @@ function formatTimestamp(date9) {
 }
 function truncateByTokens(text4, maxTokens, hint) {
   if (tokenx.estimateTokenCount(text4) <= maxTokens) return { text: text4, wasTruncated: false };
-  const truncated = chunk4TZ5SRFX_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunk2ZNDDQ6X_cjs.truncateStringByTokens(text4, maxTokens);
   const suffix = hint ? ` [${hint} for more]` : "";
   return { text: truncated + suffix, wasTruncated: true };
 }
@@ -46086,11 +46087,11 @@ ${JSON.stringify(inv.args, null, 2)}`;
             });
           }
           if (inv.state === "result") {
-            const { value: resultValue } = chunk4TZ5SRFX_cjs.resolveToolResultValue(
+            const { value: resultValue } = chunk2ZNDDQ6X_cjs.resolveToolResultValue(
               part,
               inv.result
             );
-            const resultStr = chunk4TZ5SRFX_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const resultStr = chunk2ZNDDQ6X_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
             const fullText = `[Tool Result: ${inv.toolName}]
 ${resultStr}`;
             parts.push(makePart(msg, i, "tool-result", fullText, detail, inv.toolName));
@@ -46117,7 +46118,7 @@ ${typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs, null, 2)}`;
         const toolName = part.toolName;
         if (toolName) {
           const rawResult = part.output ?? part.result;
-          const resultStr = chunk4TZ5SRFX_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunk2ZNDDQ6X_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
           const fullText = `[Tool Result: ${toolName}]
 ${resultStr}`;
           parts.push(makePart(msg, i, "tool-result", fullText, detail, toolName));
@@ -46196,7 +46197,7 @@ function renderFormattedParts(parts, timestamps, options) {
   const text4 = buildRenderedText(parts, timestamps);
   let totalTokens = tokenx.estimateTokenCount(text4);
   if (totalTokens > options.maxTokens) {
-    const truncated = chunk4TZ5SRFX_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunk2ZNDDQ6X_cjs.truncateStringByTokens(text4, options.maxTokens);
     return { text: truncated, truncated: true, tokenOffset: totalTokens - options.maxTokens };
   }
   const truncatedIndices = parts.map((p, i) => ({ part: p, index: i })).filter(({ part }) => part.text !== part.fullText).sort((a, b) => expandPriority(a.part) - expandPriority(b.part));
@@ -46229,7 +46230,7 @@ function renderFormattedParts(parts, timestamps, options) {
   if (expandedTokens <= options.maxTokens) {
     return { text: expanded, truncated: false, tokenOffset: 0 };
   }
-  const hardTruncated = chunk4TZ5SRFX_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunk2ZNDDQ6X_cjs.truncateStringByTokens(expanded, options.maxTokens);
   return { text: hardTruncated, truncated: true, tokenOffset: expandedTokens - options.maxTokens };
 }
 async function recallPart({
@@ -46280,7 +46281,7 @@ async function recallPart({
 
 `;
           const fallbackText = `${fallbackNote}${firstNextPart.text}`;
-          const truncatedText2 = chunk4TZ5SRFX_cjs.truncateStringByTokens(fallbackText, maxTokens);
+          const truncatedText2 = chunk2ZNDDQ6X_cjs.truncateStringByTokens(fallbackText, maxTokens);
           const wasTruncated2 = truncatedText2 !== fallbackText;
           return {
             text: truncatedText2,
@@ -46295,7 +46296,7 @@ async function recallPart({
     }
     throw new Error(`Part index ${partIndex} not found in message ${cursor}. Available indices: ${availableIndices}`);
   }
-  const truncatedText = chunk4TZ5SRFX_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunk2ZNDDQ6X_cjs.truncateStringByTokens(target.text, maxTokens);
   const wasTruncated = truncatedText !== target.text;
   return {
     text: truncatedText,
@@ -47160,6 +47161,7 @@ var CHARS_PER_TOKEN = 4;
 var DEFAULT_MESSAGE_RANGE = { before: 1, after: 1 };
 var DEFAULT_TOP_K = 4;
 var VECTOR_DELETE_BATCH_SIZE = 100;
+var DEFAULT_EMBEDDING_CACHE_MAX_SIZE = 1e3;
 var Memory = class extends memory.MastraMemory {
   _omEngine;
   _omEngineInstance;
@@ -47679,14 +47681,16 @@ ${workingMemory}`;
     return chunks;
   }
   hasher = xxhash__default.default();
-  // embedding is computationally expensive so cache content -> embeddings/chunks
-  embeddingCache = /* @__PURE__ */ new Map();
+  // Embedding is computationally expensive, so cache content -> embeddings/chunks.
+  // Bounded by an LRU so a long-running instance can't retain every embedded
+  // message/query (and its vectors + chunk text) for the life of the process.
+  embeddingCache = new lruCache.LRUCache({ max: DEFAULT_EMBEDDING_CACHE_MAX_SIZE });
   firstEmbed;
   async embedMessageContent(content) {
-    const key = (await this.hasher).h32(content);
+    const key = (await this.hasher).h64(content);
     const cached3 = this.embeddingCache.get(key);
     if (cached3) {
-      this.logger.debug("Embedding cache hit", { contentHash: key, chunks: cached3.chunks.length });
+      this.logger.debug("Embedding cache hit", { contentHash: key.toString(), chunks: cached3.chunks.length });
       return cached3;
     }
     const chunks = this.chunkText(content);
@@ -48116,7 +48120,7 @@ ${workingMemory}`;
         "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
       );
     }
-    const { ObservationalMemory: OMClass } = await import('./observational-memory-6SHFQDPT.cjs');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-XZTKSWPR.cjs');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -49068,7 +49072,7 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-6SHFQDPT.cjs');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-XZTKSWPR.cjs');
     return new ObservationalMemoryProcessor(engine, this, {
       temporalMarkers: effectiveConfig.temporalMarkers
     });
@@ -49095,11 +49099,11 @@ Notes:
 
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunk4TZ5SRFX_cjs.ModelByInputTokens; }
+  get: function () { return chunk2ZNDDQ6X_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunk4TZ5SRFX_cjs.getObservationsAsOf; }
+  get: function () { return chunk2ZNDDQ6X_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "WORKING_MEMORY_STATE_ID", {
   enumerable: true,