@mastra/memory 0.10.2 → 0.10.3-alpha.1

package/.turbo/turbo-build.log

@@ -1,9 +1,9 @@
 
-> @mastra/memory@0.10.2-alpha.2 build /home/runner/work/mastra/mastra/packages/memory
+> @mastra/memory@0.10.3-alpha.1 build /home/runner/work/mastra/mastra/packages/memory
 > pnpm run check && tsup --silent src/index.ts src/processors/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
 
 
-> @mastra/memory@0.10.2-alpha.2 check /home/runner/work/mastra/mastra/packages/memory
+> @mastra/memory@0.10.3-alpha.1 check /home/runner/work/mastra/mastra/packages/memory
 > tsc --noEmit
 
 Analysis will use the bundled TypeScript version 5.8.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @mastra/memory
 
+## 0.10.3-alpha.1
+
+### Patch Changes
+
+- 48eddb9: update filter logic in Memory class to support semantic recall search scope
+- Updated dependencies [48eddb9]
+  - @mastra/core@0.10.4-alpha.2
+
+## 0.10.3-alpha.0
+
+### Patch Changes
+
+- 1ccccff: dependencies updates:
+  - Updated dependency [`zod@^3.25.56` ↗︎](https://www.npmjs.com/package/zod/v/3.25.56) (from `^3.24.3`, in `dependencies`)
+- 1ccccff: dependencies updates:
+  - Updated dependency [`zod@^3.25.56` ↗︎](https://www.npmjs.com/package/zod/v/3.25.56) (from `^3.24.3`, in `dependencies`)
+- a382d3b: Fix token limiter estimations after recent MessageList work changed message structure
+- Updated dependencies [f6fd25f]
+- Updated dependencies [dffb67b]
+- Updated dependencies [f1309d3]
+- Updated dependencies [f7f8293]
+  - @mastra/core@0.10.4-alpha.1
+
 ## 0.10.2
 
 ### Patch Changes

package/dist/_tsup-dts-rollup.d.cts

@@ -21,6 +21,7 @@ import type { UIMessage } from 'ai';
 export declare class Memory extends MastraMemory {
     constructor(config?: SharedMemoryConfig);
     private validateThreadIsOwnedByResource;
+    private checkStorageFeatureSupport;
     query({ threadId, resourceId, selectBy, threadConfig, }: StorageGetMessagesArg & {
         threadConfig?: MemoryConfig;
     }): Promise<{
@@ -91,7 +92,6 @@ declare class TokenLimiter extends MemoryProcessor {
     private encoder;
     private maxTokens;
     TOKENS_PER_MESSAGE: number;
-    TOKENS_PER_TOOL: number;
     TOKENS_PER_CONVERSATION: number;
     /**
      * Create a token limiter for messages.

package/dist/_tsup-dts-rollup.d.ts

@@ -21,6 +21,7 @@ import type { UIMessage } from 'ai';
 export declare class Memory extends MastraMemory {
     constructor(config?: SharedMemoryConfig);
     private validateThreadIsOwnedByResource;
+    private checkStorageFeatureSupport;
     query({ threadId, resourceId, selectBy, threadConfig, }: StorageGetMessagesArg & {
         threadConfig?: MemoryConfig;
     }): Promise<{
@@ -91,7 +92,6 @@ declare class TokenLimiter extends MemoryProcessor {
     private encoder;
     private maxTokens;
     TOKENS_PER_MESSAGE: number;
-    TOKENS_PER_TOOL: number;
     TOKENS_PER_CONVERSATION: number;
     /**
      * Create a token limiter for messages.

package/dist/index.cjs

@@ -56,6 +56,7 @@ var Memory = class extends memory.MastraMemory {
       }
     });
     this.threadConfig = mergedConfig;
+    this.checkStorageFeatureSupport(mergedConfig);
   }
   async validateThreadIsOwnedByResource(threadId, resourceId) {
     const thread = await this.storage.getThreadById({ threadId });
@@ -68,6 +69,13 @@ var Memory = class extends memory.MastraMemory {
       );
     }
   }
+  checkStorageFeatureSupport(config) {
+    if (typeof config.semanticRecall === `object` && config.semanticRecall.scope === `resource` && !this.storage.supports.selectByIncludeResourceScope) {
+      throw new Error(
+        `Memory error: Attached storage adapter "${this.storage.name || "unknown"}" doesn't support semanticRecall: { scope: "resource" } yet and currently only supports per-thread semantic recall.`
+      );
+    }
+  }
   async query({
     threadId,
     resourceId,
@@ -82,6 +90,7 @@ var Memory = class extends memory.MastraMemory {
       threadConfig
     });
     const config = this.getMergedThreadConfig(threadConfig || {});
+    this.checkStorageFeatureSupport(config);
     const defaultRange = DEFAULT_MESSAGE_RANGE;
     const defaultTopK = DEFAULT_TOP_K;
     const vectorConfig = typeof config?.semanticRecall === `boolean` ? {
@@ -91,7 +100,8 @@ var Memory = class extends memory.MastraMemory {
       topK: config?.semanticRecall?.topK ?? defaultTopK,
       messageRange: config?.semanticRecall?.messageRange ?? defaultRange
     };
-    if (config?.semanticRecall && selectBy?.vectorSearchString && this.vector && !!selectBy.vectorSearchString) {
+    const resourceScope = typeof config?.semanticRecall === "object" && config?.semanticRecall?.scope === `resource`;
+    if (config?.semanticRecall && selectBy?.vectorSearchString && this.vector) {
       const { embeddings, dimension } = await this.embedMessageContent(selectBy.vectorSearchString);
       const { indexName } = await this.createEmbeddingIndex(dimension);
       await Promise.all(
@@ -106,7 +116,9 @@ var Memory = class extends memory.MastraMemory {
               indexName,
               queryVector: embedding,
               topK: vectorConfig.topK,
-              filter: {
+              filter: resourceScope ? {
+                resource_id: resourceId
+              } : {
                 thread_id: threadId
               }
             })
@@ -116,12 +128,14 @@ var Memory = class extends memory.MastraMemory {
     }
     const rawMessages = await this.storage.getMessages({
       threadId,
+      resourceId,
       format: "v2",
       selectBy: {
         ...selectBy,
         ...vectorResults?.length ? {
           include: vectorResults.map((r) => ({
             id: r.metadata?.message_id,
+            threadId: r.metadata?.thread_id,
             withNextMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.after,
             withPreviousMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.before
           }))
@@ -161,6 +175,7 @@ var Memory = class extends memory.MastraMemory {
       };
     }
     const messagesResult = await this.query({
+      resourceId,
       threadId,
       selectBy: {
         last: threadConfig.lastMessages,

package/dist/index.js

@@ -50,6 +50,7 @@ var Memory = class extends MastraMemory {
       }
     });
     this.threadConfig = mergedConfig;
+    this.checkStorageFeatureSupport(mergedConfig);
   }
   async validateThreadIsOwnedByResource(threadId, resourceId) {
     const thread = await this.storage.getThreadById({ threadId });
@@ -62,6 +63,13 @@ var Memory = class extends MastraMemory {
       );
     }
   }
+  checkStorageFeatureSupport(config) {
+    if (typeof config.semanticRecall === `object` && config.semanticRecall.scope === `resource` && !this.storage.supports.selectByIncludeResourceScope) {
+      throw new Error(
+        `Memory error: Attached storage adapter "${this.storage.name || "unknown"}" doesn't support semanticRecall: { scope: "resource" } yet and currently only supports per-thread semantic recall.`
+      );
+    }
+  }
   async query({
     threadId,
     resourceId,
@@ -76,6 +84,7 @@ var Memory = class extends MastraMemory {
       threadConfig
     });
     const config = this.getMergedThreadConfig(threadConfig || {});
+    this.checkStorageFeatureSupport(config);
     const defaultRange = DEFAULT_MESSAGE_RANGE;
     const defaultTopK = DEFAULT_TOP_K;
     const vectorConfig = typeof config?.semanticRecall === `boolean` ? {
@@ -85,7 +94,8 @@ var Memory = class extends MastraMemory {
       topK: config?.semanticRecall?.topK ?? defaultTopK,
       messageRange: config?.semanticRecall?.messageRange ?? defaultRange
     };
-    if (config?.semanticRecall && selectBy?.vectorSearchString && this.vector && !!selectBy.vectorSearchString) {
+    const resourceScope = typeof config?.semanticRecall === "object" && config?.semanticRecall?.scope === `resource`;
+    if (config?.semanticRecall && selectBy?.vectorSearchString && this.vector) {
       const { embeddings, dimension } = await this.embedMessageContent(selectBy.vectorSearchString);
       const { indexName } = await this.createEmbeddingIndex(dimension);
       await Promise.all(
@@ -100,7 +110,9 @@ var Memory = class extends MastraMemory {
               indexName,
               queryVector: embedding,
               topK: vectorConfig.topK,
-              filter: {
+              filter: resourceScope ? {
+                resource_id: resourceId
+              } : {
                 thread_id: threadId
               }
             })
@@ -110,12 +122,14 @@ var Memory = class extends MastraMemory {
     }
     const rawMessages = await this.storage.getMessages({
       threadId,
+      resourceId,
       format: "v2",
       selectBy: {
         ...selectBy,
         ...vectorResults?.length ? {
           include: vectorResults.map((r) => ({
             id: r.metadata?.message_id,
+            threadId: r.metadata?.thread_id,
             withNextMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.after,
             withPreviousMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.before
           }))
@@ -155,6 +169,7 @@ var Memory = class extends MastraMemory {
       };
     }
     const messagesResult = await this.query({
+      resourceId,
       threadId,
       selectBy: {
         last: threadConfig.lastMessages,

package/dist/processors/index.cjs

@@ -18,9 +18,7 @@ var TokenLimiter = class extends memory.MemoryProcessor {
   // Every message follows <|start|>{role/name}\n{content}<|end|>
   TOKENS_PER_MESSAGE = 3.8;
   // tokens added for each message (start & end tokens)
-  TOKENS_PER_TOOL = 2.2;
-  // empirical adjustment for tool calls
-  TOKENS_PER_CONVERSATION = 25;
+  TOKENS_PER_CONVERSATION = 24;
   // fixed overhead for the conversation
   /**
    * Create a token limiter for messages.
@@ -74,38 +72,41 @@ var TokenLimiter = class extends memory.MemoryProcessor {
       return this.encoder.encode(message).length;
     }
     let tokenString = message.role;
-    if (typeof message.content === "string") {
+    let overhead = 0;
+    if (typeof message.content === "string" && message.content) {
       tokenString += message.content;
     } else if (Array.isArray(message.content)) {
       for (const part of message.content) {
-        tokenString += part.type;
         if (part.type === "text") {
           tokenString += part.text;
-        } else if (part.type === "tool-call") {
-          tokenString += part.toolName;
-          if (part.args) {
-            tokenString += typeof part.args === "string" ? part.args : JSON.stringify(part.args);
+        } else if (part.type === "tool-call" || part.type === `tool-result`) {
+          if (`args` in part && part.args && part.type === `tool-call`) {
+            tokenString += part.toolName;
+            if (typeof part.args === "string") {
+              tokenString += part.args;
+            } else {
+              tokenString += JSON.stringify(part.args);
+              overhead -= 12;
+            }
           }
-        } else if (part.type === "tool-result") {
-          if (part.result !== void 0) {
-            tokenString += typeof part.result === "string" ? part.result : JSON.stringify(part.result);
+          if (`result` in part && part.result !== void 0 && part.type === `tool-result`) {
+            if (typeof part.result === "string") {
+              tokenString += part.result;
+            } else {
+              tokenString += JSON.stringify(part.result);
+              overhead -= 12;
+            }
           }
         } else {
           tokenString += JSON.stringify(part);
         }
       }
     }
-    const messageOverhead = this.TOKENS_PER_MESSAGE;
-    let toolOverhead = 0;
-    if (Array.isArray(message.content)) {
-      for (const part of message.content) {
-        if (part.type === "tool-call" || part.type === "tool-result") {
-          toolOverhead += this.TOKENS_PER_TOOL;
-        }
-      }
+    if (typeof message.content === `string` || // if the message included non-tool parts, add our message overhead
+    message.content.some((p) => p.type !== `tool-call` && p.type !== `tool-result`)) {
+      overhead += this.TOKENS_PER_MESSAGE;
     }
-    const totalMessageOverhead = messageOverhead + toolOverhead;
-    return this.encoder.encode(tokenString).length + totalMessageOverhead;
+    return this.encoder.encode(tokenString).length + overhead;
   }
 };
 var ToolCallFilter = class extends core.MemoryProcessor {

package/dist/processors/index.js

@@ -12,9 +12,7 @@ var TokenLimiter = class extends MemoryProcessor {
   // Every message follows <|start|>{role/name}\n{content}<|end|>
   TOKENS_PER_MESSAGE = 3.8;
   // tokens added for each message (start & end tokens)
-  TOKENS_PER_TOOL = 2.2;
-  // empirical adjustment for tool calls
-  TOKENS_PER_CONVERSATION = 25;
+  TOKENS_PER_CONVERSATION = 24;
   // fixed overhead for the conversation
   /**
    * Create a token limiter for messages.
@@ -68,38 +66,41 @@ var TokenLimiter = class extends MemoryProcessor {
       return this.encoder.encode(message).length;
     }
     let tokenString = message.role;
-    if (typeof message.content === "string") {
+    let overhead = 0;
+    if (typeof message.content === "string" && message.content) {
       tokenString += message.content;
     } else if (Array.isArray(message.content)) {
       for (const part of message.content) {
-        tokenString += part.type;
         if (part.type === "text") {
           tokenString += part.text;
-        } else if (part.type === "tool-call") {
-          tokenString += part.toolName;
-          if (part.args) {
-            tokenString += typeof part.args === "string" ? part.args : JSON.stringify(part.args);
+        } else if (part.type === "tool-call" || part.type === `tool-result`) {
+          if (`args` in part && part.args && part.type === `tool-call`) {
+            tokenString += part.toolName;
+            if (typeof part.args === "string") {
+              tokenString += part.args;
+            } else {
+              tokenString += JSON.stringify(part.args);
+              overhead -= 12;
+            }
           }
-        } else if (part.type === "tool-result") {
-          if (part.result !== void 0) {
-            tokenString += typeof part.result === "string" ? part.result : JSON.stringify(part.result);
+          if (`result` in part && part.result !== void 0 && part.type === `tool-result`) {
+            if (typeof part.result === "string") {
+              tokenString += part.result;
+            } else {
+              tokenString += JSON.stringify(part.result);
+              overhead -= 12;
+            }
           }
         } else {
           tokenString += JSON.stringify(part);
         }
       }
     }
-    const messageOverhead = this.TOKENS_PER_MESSAGE;
-    let toolOverhead = 0;
-    if (Array.isArray(message.content)) {
-      for (const part of message.content) {
-        if (part.type === "tool-call" || part.type === "tool-result") {
-          toolOverhead += this.TOKENS_PER_TOOL;
-        }
-      }
+    if (typeof message.content === `string` || // if the message included non-tool parts, add our message overhead
+    message.content.some((p) => p.type !== `tool-call` && p.type !== `tool-result`)) {
+      overhead += this.TOKENS_PER_MESSAGE;
     }
-    const totalMessageOverhead = messageOverhead + toolOverhead;
-    return this.encoder.encode(tokenString).length + totalMessageOverhead;
+    return this.encoder.encode(tokenString).length + overhead;
   }
 };
 var ToolCallFilter = class extends MemoryProcessor$1 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/memory",
-  "version": "0.10.2",
+  "version": "0.10.3-alpha.1",
   "description": "",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,20 +40,20 @@
     "postgres": "^3.4.5",
     "redis": "^4.7.0",
     "xxhash-wasm": "^1.1.0",
-    "zod": "^3.24.3"
+    "zod": "^3.25.56"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^1.3.3",
-    "@microsoft/api-extractor": "^7.52.5",
-    "@types/node": "^20.17.27",
+    "@microsoft/api-extractor": "^7.52.8",
+    "@types/node": "^20.17.57",
     "@types/pg": "^8.11.11",
-    "eslint": "^9.23.0",
-    "tsup": "^8.4.0",
+    "eslint": "^9.28.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.2",
     "typescript-eslint": "^8.26.1",
-    "vitest": "^3.1.2",
-    "@internal/lint": "0.0.8",
-    "@mastra/core": "0.10.2"
+    "vitest": "^3.2.2",
+    "@internal/lint": "0.0.10",
+    "@mastra/core": "0.10.4-alpha.2"
   },
   "peerDependencies": {
     "@mastra/core": "^0.10.2-alpha.0"

package/src/index.ts

@@ -35,6 +35,8 @@ export class Memory extends MastraMemory {
       },
     });
     this.threadConfig = mergedConfig;
+
+    this.checkStorageFeatureSupport(mergedConfig);
   }
 
   private async validateThreadIsOwnedByResource(threadId: string, resourceId: string) {
@@ -49,6 +51,18 @@ export class Memory extends MastraMemory {
     }
   }
 
+  private checkStorageFeatureSupport(config: MemoryConfig) {
+    if (
+      typeof config.semanticRecall === `object` &&
+      config.semanticRecall.scope === `resource` &&
+      !this.storage.supports.selectByIncludeResourceScope
+    ) {
+      throw new Error(
+        `Memory error: Attached storage adapter "${this.storage.name || 'unknown'}" doesn't support semanticRecall: { scope: "resource" } yet and currently only supports per-thread semantic recall.`,
+      );
+    }
+  }
+
   async query({
     threadId,
     resourceId,
@@ -74,6 +88,8 @@ export class Memory extends MastraMemory {
 
     const config = this.getMergedThreadConfig(threadConfig || {});
 
+    this.checkStorageFeatureSupport(config);
+
     const defaultRange = DEFAULT_MESSAGE_RANGE;
     const defaultTopK = DEFAULT_TOP_K;
 
@@ -88,7 +104,9 @@ export class Memory extends MastraMemory {
             messageRange: config?.semanticRecall?.messageRange ?? defaultRange,
           };
 
-    if (config?.semanticRecall && selectBy?.vectorSearchString && this.vector && !!selectBy.vectorSearchString) {
+    const resourceScope = typeof config?.semanticRecall === 'object' && config?.semanticRecall?.scope === `resource`;
+
+    if (config?.semanticRecall && selectBy?.vectorSearchString && this.vector) {
       const { embeddings, dimension } = await this.embedMessageContent(selectBy.vectorSearchString!);
       const { indexName } = await this.createEmbeddingIndex(dimension);
 
@@ -105,9 +123,13 @@ export class Memory extends MastraMemory {
               indexName,
               queryVector: embedding,
               topK: vectorConfig.topK,
-              filter: {
-                thread_id: threadId,
-              },
+              filter: resourceScope
+                ? {
+                    resource_id: resourceId,
+                  }
+                : {
+                    thread_id: threadId,
+                  },
             })),
           );
         }),
@@ -117,6 +139,7 @@ export class Memory extends MastraMemory {
     // Get raw messages from storage
     const rawMessages = await this.storage.getMessages({
       threadId,
+      resourceId,
       format: 'v2',
       selectBy: {
         ...selectBy,
@@ -124,6 +147,7 @@ export class Memory extends MastraMemory {
           ? {
               include: vectorResults.map(r => ({
                 id: r.metadata?.message_id,
+                threadId: r.metadata?.thread_id,
                 withNextMessages:
                   typeof vectorConfig.messageRange === 'number'
                     ? vectorConfig.messageRange
@@ -188,6 +212,7 @@ export class Memory extends MastraMemory {
     }
 
     const messagesResult = await this.query({
+      resourceId,
       threadId,
       selectBy: {
         last: threadConfig.lastMessages,

package/src/processors/index.test.ts

@@ -85,7 +85,7 @@ describe('TokenLimiter', () => {
     const { messages, fakeCore, counts } = generateConversationHistory(config);
 
     const estimate = estimateTokens(messages);
-    const used = (await agent.generate(fakeCore.slice(0, -1))).usage.totalTokens;
+    const used = (await agent.generate(fakeCore)).usage.promptTokens;
 
     console.log(`Estimated ${estimate} tokens, used ${used} tokens.\n`, counts);
 
@@ -100,7 +100,8 @@ describe('TokenLimiter', () => {
       expression: z.string().describe('The mathematical expression to calculate'),
     }),
     execute: async ({ context: { expression } }) => {
-      return `The result of ${expression} is ${eval(expression)}`;
+      // Don't actually eval the expression. The model is dumb and sometimes passes "banana" as the expression because that's one of the sample tokens we're using in input messages lmao
+      return `The result of ${expression} is 10`;
     },
   });
 
@@ -178,16 +179,23 @@ describe('TokenLimiter', () => {
       );
     });
 
-    it(`101 messages, 49 tool calls`, async () => {
-      await expectTokenEstimate(
-        {
-          messageCount: 50,
-          toolFrequency: 1,
-          threadId: '5',
-        },
-        agent,
-      );
-    });
+    it(
+      `101 messages, 49 tool calls`,
+      async () => {
+        await expectTokenEstimate(
+          {
+            messageCount: 50,
+            toolFrequency: 1,
+            threadId: '5',
+          },
+          agent,
+        );
+      },
+      {
+        // for some reason AI SDK randomly returns 2x token count here
+        retry: 3,
+      },
+    );
   });
 });
 

package/src/processors/token-limiter.ts

@@ -26,8 +26,7 @@ export class TokenLimiter extends MemoryProcessor {
   // See: https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken#6-counting-tokens-for-chat-completions-api-calls
   // Every message follows <|start|>{role/name}\n{content}<|end|>
   public TOKENS_PER_MESSAGE = 3.8; // tokens added for each message (start & end tokens)
-  public TOKENS_PER_TOOL = 2.2; // empirical adjustment for tool calls
-  public TOKENS_PER_CONVERSATION = 25; // fixed overhead for the conversation
+  public TOKENS_PER_CONVERSATION = 24; // fixed overhead for the conversation
 
   /**
    * Create a token limiter for messages.
@@ -107,24 +106,35 @@ export class TokenLimiter extends MemoryProcessor {
     }
 
     let tokenString = message.role;
+    let overhead = 0;
 
-    if (typeof message.content === 'string') {
+    if (typeof message.content === 'string' && message.content) {
       tokenString += message.content;
     } else if (Array.isArray(message.content)) {
       // Calculate tokens for each content part
       for (const part of message.content) {
-        tokenString += part.type;
         if (part.type === 'text') {
           tokenString += part.text;
-        } else if (part.type === 'tool-call') {
-          tokenString += part.toolName as any;
-          if (part.args) {
-            tokenString += typeof part.args === 'string' ? part.args : JSON.stringify(part.args);
+        } else if (part.type === 'tool-call' || part.type === `tool-result`) {
+          if (`args` in part && part.args && part.type === `tool-call`) {
+            tokenString += part.toolName as any;
+            if (typeof part.args === 'string') {
+              tokenString += part.args;
+            } else {
+              tokenString += JSON.stringify(part.args);
+              // minus some tokens for JSON
+              overhead -= 12;
+            }
           }
-        } else if (part.type === 'tool-result') {
           // Token cost for result if present
-          if (part.result !== undefined) {
-            tokenString += typeof part.result === 'string' ? part.result : JSON.stringify(part.result);
+          if (`result` in part && part.result !== undefined && part.type === `tool-result`) {
+            if (typeof part.result === 'string') {
+              tokenString += part.result;
+            } else {
+              tokenString += JSON.stringify(part.result);
+              // minus some tokens for JSON
+              overhead -= 12;
+            }
           }
         } else {
           tokenString += JSON.stringify(part);
@@ -132,22 +142,16 @@ export class TokenLimiter extends MemoryProcessor {
       }
     }
 
-    // Ensure we account for message formatting tokens
-    // See: https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken#6-counting-tokens-for-chat-completions-api-calls
-    const messageOverhead = this.TOKENS_PER_MESSAGE;
-
-    // Count tool calls for additional overhead
-    let toolOverhead = 0;
-    if (Array.isArray(message.content)) {
-      for (const part of message.content) {
-        if (part.type === 'tool-call' || part.type === 'tool-result') {
-          toolOverhead += this.TOKENS_PER_TOOL;
-        }
-      }
+    if (
+      typeof message.content === `string` ||
+      // if the message included non-tool parts, add our message overhead
+      message.content.some(p => p.type !== `tool-call` && p.type !== `tool-result`)
+    ) {
+      // Ensure we account for message formatting tokens
+      // See: https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken#6-counting-tokens-for-chat-completions-api-calls
+      overhead += this.TOKENS_PER_MESSAGE;
     }
 
-    const totalMessageOverhead = messageOverhead + toolOverhead;
-
-    return this.encoder.encode(tokenString).length + totalMessageOverhead;
+    return this.encoder.encode(tokenString).length + overhead;
   }
 }