@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/src/llm/bedrock/cacheSupport.test.ts

@@ -0,0 +1,99 @@
+import {
+  DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS,
+  isBedrockCacheSupported,
+} from './cacheSupport';
+
+describe('isBedrockCacheSupported', () => {
+  describe('default allowlist — supported models', () => {
+    const supported = [
+      // Anthropic Claude direct
+      'anthropic.claude-3-5-sonnet-20241022-v2:0',
+      'anthropic.claude-3-haiku-20240307-v1:0',
+      'anthropic.claude-opus-4-5-20250514-v1:0',
+      'anthropic.claude-sonnet-4-5-20250929-v1:0',
+      // Anthropic Claude via cross-region inference profile
+      'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+      'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+      'eu.anthropic.claude-3-5-sonnet-20241022-v2:0',
+      // Amazon Nova
+      'amazon.nova-pro-v1:0',
+      'amazon.nova-lite-v1:0',
+      'amazon.nova-canvas-v1:0',
+      'us.amazon.nova-pro-v1:0',
+    ];
+
+    for (const model of supported) {
+      it(`accepts "${model}"`, () => {
+        expect(isBedrockCacheSupported(model)).toBe(true);
+      });
+    }
+  });
+
+  describe('default allowlist — unsupported models', () => {
+    const unsupported = [
+      'amazon.titan-text-premier-v1:0',
+      'amazon.titan-embed-text-v2:0',
+      'meta.llama3-1-405b-instruct-v1:0',
+      'meta.llama3-2-90b-instruct-v1:0',
+      'cohere.command-r-plus-v1:0',
+      'mistral.mistral-large-2402-v1:0',
+      'ai21.j2-ultra-v1',
+      'stability.sd3-5-large-v1:0',
+      // Adversarial — substring match would falsely accept these
+      'meta.llama-claude-killer-v1', // contains "claude" but isn't an Anthropic model
+      'fake.anthropic-impersonator', // contains "anthropic" but wrong vendor
+    ];
+
+    for (const model of unsupported) {
+      it(`rejects "${model}"`, () => {
+        expect(isBedrockCacheSupported(model)).toBe(false);
+      });
+    }
+  });
+
+  describe('edge cases', () => {
+    it('returns false for undefined', () => {
+      expect(isBedrockCacheSupported(undefined)).toBe(false);
+    });
+
+    it('returns false for empty string', () => {
+      expect(isBedrockCacheSupported('')).toBe(false);
+    });
+  });
+
+  describe('consumer extension via additionalPatterns', () => {
+    it('accepts model matching consumer-supplied pattern', () => {
+      expect(
+        isBedrockCacheSupported('mycorp.future-model-v1:0', [
+          /^mycorp\.future-/i,
+        ]),
+      ).toBe(true);
+    });
+
+    it('still rejects models not in default OR consumer allowlist', () => {
+      expect(
+        isBedrockCacheSupported('cohere.command-r-plus-v1:0', [
+          /^mycorp\./i,
+        ]),
+      ).toBe(false);
+    });
+
+    it('default allowlist still works alongside extensions', () => {
+      // Both default + custom pattern work
+      expect(
+        isBedrockCacheSupported('anthropic.claude-3-haiku-20240307-v1:0', [
+          /^mycorp\./i,
+        ]),
+      ).toBe(true);
+    });
+  });
+
+  describe('DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS export', () => {
+    it('is a non-empty readonly array of RegExp', () => {
+      expect(DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS.length).toBeGreaterThan(0);
+      for (const pattern of DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS) {
+        expect(pattern).toBeInstanceOf(RegExp);
+      }
+    });
+  });
+});

package/src/llm/bedrock/cacheSupport.ts

@@ -0,0 +1,53 @@
+/**
+ * Bedrock prompt-cache model support detection.
+ * ===============================================
+ *
+ * Bedrock prompt caching (via `cachePoint` blocks) is only supported on
+ * specific model families. Other families silently reject or ignore the
+ * markers. We maintain an allowlist instead of a substring heuristic so
+ * a future model with an unfortunate name (e.g. `llama-claude-killer`)
+ * doesn't accidentally match.
+ *
+ * Consumers can extend the allowlist with `bedrockCacheModelPatterns` in
+ * `clientOptions` for proprietary or pre-release model IDs not yet in
+ * the reference library.
+ */
+
+/**
+ * Default allowlist of Bedrock model ID patterns that support cachePoint.
+ * Sourced from AWS Bedrock documentation (verified against us-east-1
+ * 2026-05).
+ *
+ * Adding a new model: append a RegExp here AND add a regression test in
+ * `cacheSupport.test.ts` covering at least one full model ID for that
+ * family. Removing a model: do not remove without operator confirmation
+ * — silent removal would suddenly stop emitting cachePoint markers and
+ * regress cost savings.
+ */
+export const DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS: readonly RegExp[] = [
+  // Anthropic Claude family (anthropic.claude-* and us.anthropic.claude-*)
+  /(?:^|[/.])anthropic\.claude-/i,
+  /(?:^|\.)us\.anthropic\.claude-/i,
+  // Amazon Nova family (nova-pro, nova-lite, nova-canvas, etc.)
+  /(?:^|[/.])amazon\.nova-/i,
+  /(?:^|\.)us\.amazon\.nova-/i,
+];
+
+/**
+ * Returns true when the given Bedrock model ID belongs to a family that
+ * supports cachePoint blocks. `additionalPatterns` lets consumers extend
+ * the allowlist for models the library doesn't know about yet.
+ *
+ * @param modelId  Bedrock model ID (e.g. `us.anthropic.claude-sonnet-4-5-20250929-v1:0`)
+ * @param additionalPatterns  Extra patterns from consumer config
+ */
+export function isBedrockCacheSupported(
+  modelId: string | undefined,
+  additionalPatterns?: readonly RegExp[],
+): boolean {
+  if (!modelId) return false;
+  const allPatterns = additionalPatterns
+    ? [...DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS, ...additionalPatterns]
+    : DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS;
+  return allPatterns.some((p) => p.test(modelId));
+}

package/src/llm/bedrock/index.ts

@@ -38,6 +38,7 @@ import type { BaseMessage } from '@langchain/core/messages';
 import { ChatGenerationChunk, ChatResult } from '@langchain/core/outputs';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { ChatBedrockConverseInput } from '@langchain/aws';
+import { isBedrockCacheSupported } from './cacheSupport';
 import {
   convertToConverseMessages,
   handleConverseStreamContentBlockStart,
@@ -52,19 +53,72 @@ import {
  */
 export type ServiceTierType = 'priority' | 'default' | 'flex' | 'reserved';
 
+/**
+ * Tool cachePoint allocation strategy.
+ *
+ *   - 'single':  one cachePoint at the END of the tools array (whole array
+ *                cached as one unit). Lightest budget use (1 cachePoint).
+ *   - 'split':   split tools into groups via `toolGroupSelector`. Each
+ *                non-empty group gets its own cachePoint. Use when groups
+ *                have different volatility (e.g. stable core tools vs
+ *                volatile MCP tools). Costs more cachePoint budget.
+ *   - 'none':    no cachePoint on tools array. Use when tool definitions
+ *                change every request anyway.
+ */
+export type ToolCacheStrategy = 'single' | 'split' | 'none';
+
+/**
+ * Group selector for `toolCacheStrategy: 'split'`. Receives the tool name
+ * and returns a stable group key — tools with the same key are grouped
+ * together. Group order in the output array follows first-encounter order.
+ */
+export type ToolGroupSelector = (toolName: string) => string;
+
+/**
+ * Default group selector — puts all tools in a single group named 'core'.
+ * Equivalent to 'single' strategy but explicit. Consumers override this
+ * to enable per-source grouping (e.g. by inspecting tool-name substrings
+ * to separate stable framework tools from volatile MCP-sourced tools).
+ */
+export const DEFAULT_TOOL_GROUP_SELECTOR: ToolGroupSelector = () => 'core';
+
 /**
  * Extended input interface with additional features:
  * - promptCache: Enable Bedrock prompt caching for tool definitions
  * - applicationInferenceProfile: Use an inference profile ARN instead of model ID
  * - serviceTier: Specify service tier (Priority, Standard, Flex, Reserved)
+ * - toolCacheStrategy: How to allocate cachePoints across tools array
+ * - toolGroupSelector: Group key resolver for the 'split' strategy
  */
 export interface IllumaBedrockConverseInput extends ChatBedrockConverseInput {
   /**
    * Enable Bedrock prompt caching for tool definitions.
-   * When true, adds cachePoint markers to tools array.
+   * When true, adds cachePoint marker(s) to tools array per
+   * `toolCacheStrategy`. Defaults to 'single'.
    */
   promptCache?: boolean;
 
+  /**
+   * Tool cachePoint allocation. Defaults to 'single' — one cachePoint at
+   * the end of the tools array. Set to 'split' (with `toolGroupSelector`)
+   * when different tool groups have different volatility.
+   */
+  toolCacheStrategy?: ToolCacheStrategy;
+
+  /**
+   * Group selector for 'split' strategy. Receives a tool name, returns
+   * a stable group key. Defaults to a one-group selector (equivalent
+   * to 'single').
+   */
+  toolGroupSelector?: ToolGroupSelector;
+
+  /**
+   * Additional model ID patterns to consider Bedrock-cache-supported.
+   * Defaults are in `src/llm/bedrock/cacheSupport.ts`. Use this when
+   * AWS adds a new model family before the next library release.
+   */
+  bedrockCacheModelPatterns?: readonly RegExp[];
+
   /**
    * Application Inference Profile ARN to use for the model.
    * For example, "arn:aws:bedrock:eu-west-1:123456789102:application-inference-profile/fm16bt65tzgx"
@@ -108,11 +162,24 @@ export class IllumaBedrockConverse extends ChatBedrockConverse {
   /** Service tier for model invocation */
   serviceTier?: ServiceTierType;
 
+  /** Tool cachePoint allocation strategy. */
+  toolCacheStrategy: ToolCacheStrategy;
+
+  /** Group selector for 'split' strategy. */
+  toolGroupSelector: ToolGroupSelector;
+
+  /** Optional consumer extensions to the cache-supported model allowlist. */
+  bedrockCacheModelPatterns?: readonly RegExp[];
+
   constructor(fields?: IllumaBedrockConverseInput) {
     super(fields);
     this.promptCache = fields?.promptCache ?? false;
     this.applicationInferenceProfile = fields?.applicationInferenceProfile;
     this.serviceTier = fields?.serviceTier;
+    this.toolCacheStrategy = fields?.toolCacheStrategy ?? 'single';
+    this.toolGroupSelector =
+      fields?.toolGroupSelector ?? DEFAULT_TOOL_GROUP_SELECTOR;
+    this.bedrockCacheModelPatterns = fields?.bedrockCacheModelPatterns;
 
     // Fix: Force supportsToolChoiceValues for Claude models
     // The parent constructor checks `model.includes('claude-3')` but this fails when:
@@ -183,56 +250,64 @@ export class IllumaBedrockConverse extends ChatBedrockConverse {
       }
     }
 
-    // Only Claude models support cachePoint - check model name
-    const modelId = this.model.toLowerCase();
-    const isClaudeModel =
-      modelId.includes('claude') || modelId.includes('anthropic');
+    /* Allowlist-based gate (see cacheSupport.ts). Replaces the old
+     * substring heuristic — same default behavior for Claude/Anthropic/
+     * Nova models, plus extension via `bedrockCacheModelPatterns`. */
+    const cacheSupported = isBedrockCacheSupported(
+      this.model,
+      this.bedrockCacheModelPatterns,
+    );
 
     if (
       this.promptCache &&
-      isClaudeModel &&
+      cacheSupported &&
+      this.toolCacheStrategy !== 'none' &&
       params.toolConfig?.tools &&
       Array.isArray(params.toolConfig.tools) &&
       params.toolConfig.tools.length > 0
     ) {
-      // Separate core tools from MCP tools
-      // MCP tools have '_mcp_' in their name (e.g., 'search_emails_mcp_Google-Workspace')
-      const coreTools: typeof params.toolConfig.tools = [];
-      const mcpTools: typeof params.toolConfig.tools = [];
-
-      for (const tool of params.toolConfig.tools) {
-        // Check if tool has a name property with '_mcp_' pattern
-        const toolName =
-          (tool as { toolSpec?: { name?: string } }).toolSpec?.name ?? '';
-        if (toolName.includes('_mcp_')) {
-          mcpTools.push(tool);
-        } else {
-          coreTools.push(tool);
+      const tools = params.toolConfig.tools;
+
+      if (this.toolCacheStrategy === 'single') {
+        /* SINGLE: one cachePoint at the end of the tools array. Lightest
+         * budget use; appropriate when the entire tools array is treated
+         * as one unit and changes together. */
+        const toolsWithCache = [
+          ...tools,
+          { cachePoint: { type: 'default' } } as (typeof tools)[number],
+        ];
+        params.toolConfig.tools = toolsWithCache;
+      } else if (this.toolCacheStrategy === 'split') {
+        /* SPLIT: group tools by `toolGroupSelector` and emit a cachePoint
+         * after each non-empty group. Group order follows first-encounter
+         * order in the input. Use when groups have different volatility
+         * (e.g. stable core tools + volatile MCP tools). */
+        const groupOrder: string[] = [];
+        const groupMap = new Map<string, typeof tools>();
+        for (const tool of tools) {
+          const toolName =
+            (tool as { toolSpec?: { name?: string } }).toolSpec?.name ?? '';
+          const groupKey = this.toolGroupSelector(toolName);
+          let group = groupMap.get(groupKey);
+          if (!group) {
+            group = [];
+            groupMap.set(groupKey, group);
+            groupOrder.push(groupKey);
+          }
+          group.push(tool);
         }
-      }
-
-      // Build tools array with strategic cachePoints:
-      // [CoreTool1, CoreTool2, cachePoint] + [MCPTool1, MCPTool2, cachePoint]
-      const toolsWithCache: typeof params.toolConfig.tools = [];
-
-      // Add core tools with cachePoint (if any)
-      if (coreTools.length > 0) {
-        toolsWithCache.push(...coreTools);
-        toolsWithCache.push({ cachePoint: { type: 'default' } });
-      }
 
-      // Add MCP tools with their own cachePoint (if any)
-      if (mcpTools.length > 0) {
-        toolsWithCache.push(...mcpTools);
-        toolsWithCache.push({ cachePoint: { type: 'default' } });
-      }
-
-      // If no tools at all (shouldn't happen but safety check)
-      if (toolsWithCache.length === 0) {
-        toolsWithCache.push({ cachePoint: { type: 'default' } });
+        const toolsWithCache: typeof tools = [];
+        for (const groupKey of groupOrder) {
+          const group = groupMap.get(groupKey);
+          if (!group || group.length === 0) continue;
+          toolsWithCache.push(...group);
+          toolsWithCache.push(
+            { cachePoint: { type: 'default' } } as (typeof tools)[number],
+          );
+        }
+        params.toolConfig.tools = toolsWithCache;
       }
-
-      params.toolConfig.tools = toolsWithCache;
     }
 
     // Add serviceTier support

package/src/llm/openai/index.ts

@@ -896,8 +896,8 @@ export interface XAIUsageMetadata
 }
 
 export class ChatMoonshot extends ChatOpenAI {
-  static lc_name(): 'LibreChatMoonshot' {
-    return 'LibreChatMoonshot';
+  static lc_name(): 'IllumaMoonshot' {
+    return 'IllumaMoonshot';
   }
 
   protected _convertMessages(messages: BaseMessage[]): OpenAICompletionParam[] {

package/src/llm/openai/utils/index.ts

@@ -302,6 +302,10 @@ export function _convertMessagesToOpenAIParams(
   model?: string,
   options?: ConvertMessagesOptions
 ): OpenAICompletionParam[] {
+  /* DeepSeek reasoning roundtrip (PR #136): reasoning_content on
+   * an AI message must be re-sent only when the message participates in a
+   * tool-call exchange. Track context across the message flat-map. */
+  let hasReasoningToolCallContext = false;
   // TODO: Function messages do not support array content, fix cast
   return messages.flatMap((message) => {
     let role = messageToOpenAIRole(message);
@@ -332,6 +336,8 @@ export function _convertMessagesToOpenAIParams(
       role,
       content,
     };
+    let messageHasToolCalls = false;
+    let messageIsToolResult = false;
     if (message.name != null) {
       completionParam.name = message.name;
     }
@@ -340,17 +346,11 @@ export function _convertMessagesToOpenAIParams(
       completionParam.content = '';
     }
     if (isAIMessage(message) && !!message.tool_calls?.length) {
+      messageHasToolCalls = true;
       completionParam.tool_calls = message.tool_calls.map(
         convertLangChainToolCallToOpenAI
       );
       completionParam.content = hasAnthropicThinkingBlock ? content : '';
-      if (
-        options?.includeReasoningContent === true &&
-        message.additional_kwargs.reasoning_content != null
-      ) {
-        completionParam.reasoning_content =
-          message.additional_kwargs.reasoning_content;
-      }
       if (
         options?.includeReasoningDetails === true &&
         message.additional_kwargs.reasoning_details != null
@@ -398,14 +398,10 @@ export function _convertMessagesToOpenAIParams(
       }
     } else {
       if (message.additional_kwargs.tool_calls != null) {
+        messageHasToolCalls =
+          !Array.isArray(message.additional_kwargs.tool_calls) ||
+          message.additional_kwargs.tool_calls.length > 0;
         completionParam.tool_calls = message.additional_kwargs.tool_calls;
-        if (
-          options?.includeReasoningContent === true &&
-          message.additional_kwargs.reasoning_content != null
-        ) {
-          completionParam.reasoning_content =
-            message.additional_kwargs.reasoning_content;
-        }
         if (
           options?.includeReasoningDetails === true &&
           message.additional_kwargs.reasoning_details != null
@@ -453,10 +449,31 @@ export function _convertMessagesToOpenAIParams(
         }
       }
       if ((message as ToolMessage).tool_call_id != null) {
+        messageIsToolResult = true;
         completionParam.tool_call_id = (message as ToolMessage).tool_call_id;
       }
     }
 
+    /* DeepSeek reasoning roundtrip (PR #136): emit
+     * reasoning_content only when the message is part of a tool-call
+     * exchange — either the message itself has tool_calls, or a previous
+     * AI/tool message established the context. Skipping the gate causes
+     * DeepSeek to drop reasoning content during multi-turn replays. */
+    if (
+      options?.includeReasoningContent === true &&
+      isAIMessage(message) &&
+      (hasReasoningToolCallContext || messageHasToolCalls) &&
+      typeof message.additional_kwargs.reasoning_content === 'string' &&
+      message.additional_kwargs.reasoning_content !== ''
+    ) {
+      completionParam.reasoning_content =
+        message.additional_kwargs.reasoning_content;
+    }
+
+    if (messageHasToolCalls || messageIsToolResult) {
+      hasReasoningToolCallContext = true;
+    }
+
     if (
       message.additional_kwargs.audio &&
       typeof message.additional_kwargs.audio === 'object' &&

package/src/memory/citations.ts

@@ -1,7 +1,7 @@
 /**
  * Citation decoration — Phase 2.
  *
- * Ported from upstream `extensions/memory-core/src/tools.citations.ts`.
+ * Ported from a reference implementation `extensions/memory-core/src/tools.citations.ts`.
  * Decorates memory_search hits with `[path#L{start}-L{end}]` markers so
  * the model can attribute claims back to specific memory files when it
  * uses them in its answer.
@@ -10,7 +10,7 @@
  * compute line ranges from the returned content block on the fly:
  *   - `startLine` = 1 (line 1 of the file)
  *   - `endLine`   = total number of lines in the block
- * This matches upstream's output format exactly while keeping the pg
+ * This matches the standard output format exactly while keeping the pg
  * schema chunk-free.
  */
 
@@ -48,7 +48,7 @@ function formatCitation(
 }
 
 /**
- * Decorate each hit with a citation marker. Mirrors upstream's behavior:
+ * Decorate each hit with a citation marker. Mirrors the standard behavior:
  * appends `\n\nSource: <citation>` to the content and sets `citation`.
  * When `include=false`, clears any existing citation field.
  */
@@ -69,7 +69,7 @@ export function decorateCitations<T extends CitationCandidate>(
 /**
  * Whether citations should be emitted for this call.
  *
- * Upstream keys `auto` off the session type (direct/group/channel). In
+ * The reference implementation keys `auto` off the session type (direct/group/channel). In
  * Phase 1 we only have direct chat, so `auto` => `on`. Callers that
  * later distinguish session types can pass `mode` explicitly.
  */

package/src/memory/constants.ts

@@ -26,14 +26,14 @@ export const MEMORY_PHASE_NORMAL = 'normal';
 export const MEMORY_PHASE_FLUSHING = 'memory_flushing';
 
 /**
- * Search defaults — aligned with upstream's upstream defaults.
+ * Search defaults — aligned with the standard defaults.
  *
  * Sources:
- * - `upstream reference` → maxResults=6
- * - `upstream reference` → maxInjectedChars=4000
+ * - `reference` → maxResults=6
+ * - `reference` → maxInjectedChars=4000
  *
- * Keeping these in lockstep with upstream means the mandatory-recall tool
- * description, budget clamps, and eval corpora line up with upstream's
+ * Keeping these in lockstep with means the mandatory-recall tool
+ * description, budget clamps, and eval corpora line up with the standard
  * tuning — we inherit their calibration instead of re-tuning from scratch.
  */
 export const DEFAULT_MAX_SEARCH_RESULTS = 6;
@@ -45,11 +45,11 @@ export const HYBRID_VECTOR_WEIGHT = 0.7;
 export const HYBRID_TEXT_WEIGHT = 0.3;
 
 /**
- * Phase 2 rerank defaults — ported from upstream.
+ * Phase 2 rerank defaults — ported from a reference implementation.
  *
  * Sources:
- * - `upstream reference` → lambda=0.7
- * - `upstream reference` → halfLifeDays=30
+ * - `reference` → lambda=0.7
+ * - `reference` → halfLifeDays=30
  *
  * Both features are opt-in (enabled=false by default) — the Phase 2
  * features are layered on top of hybrid search and don't change default
@@ -63,11 +63,11 @@ export const DEFAULT_RECALL_TRACKING_ENABLED = false;
 export const DEFAULT_CITATIONS_MODE = 'auto' as const;
 
 /**
- * Flush trigger margins (token counts) — aligned with upstream upstream.
+ * Flush trigger margins (token counts) — aligned with standard.
  *
  * Sources:
- * - `upstream reference` → softThreshold=4000
- * - `upstream reference` → reserveFloor=20000
+ * - `reference` → softThreshold=4000
+ * - `reference` → reserveFloor=20000
  */
 export const DEFAULT_FLUSH_SOFT_THRESHOLD_TOKENS = 4000;
 export const DEFAULT_FLUSH_RESERVE_FLOOR_TOKENS = 20000;
@@ -79,7 +79,7 @@ export const DEFAULT_MAX_APPENDS_PER_FLUSH = 20;
  * Hard cap on agentic loop iterations inside {@link runMemoryFlush}.
  *
  * Each iteration = one model.invoke() followed by execution of any
- * `memory_append` tool_calls it emits. Mirrors upstream's flush-plan
+ * `memory_append` tool_calls it emits. Mirrors the standard flush-plan
  * loop cap; 8 is enough for ~2–3 reflections of batched notes while
  * protecting against runaway cycles if the model refuses to stop.
  */
@@ -97,9 +97,9 @@ export const MEMORY_APPEND_TOOL_NAME = 'memory_append';
  * Mandatory-recall description — the single most load-bearing line in the
  * whole memory system. Do not soften, shorten, or reword without an eval run.
  *
- * Ported VERBATIM from upstream `extensions/memory-core/src/tools.ts:186`.
+ * Ported VERBATIM from a reference implementation `extensions/memory-core/src/tools.ts:186`.
  * The wiki/corpus clause is retained even though Phase 1 doesn't ship
- * compiled-wiki supplements — keeping the string identical means upstream's
+ * compiled-wiki supplements — keeping the string identical means the standard
  * eval corpora remain drop-in valid.
  */
 export const MEMORY_SEARCH_DESCRIPTION =
@@ -111,7 +111,7 @@ export const MEMORY_SEARCH_DESCRIPTION =
   'unavailable and should be surfaced to the user.';
 
 /**
- * Ported VERBATIM from upstream `extensions/memory-core/src/tools.ts:322`.
+ * Ported VERBATIM from a reference implementation `extensions/memory-core/src/tools.ts:322`.
  */
 export const MEMORY_GET_DESCRIPTION =
   'Safe snippet read from MEMORY.md or memory/*.md with optional from/lines; ' +
@@ -122,7 +122,7 @@ export const MEMORY_GET_DESCRIPTION =
  * `memory_append` tool description.
  *
  * Phase 1 historically wrote to a single date-keyed file
- * (`memory/YYYY-MM-DD.md`), ported verbatim from upstream. That scheme
+ * (`memory/YYYY-MM-DD.md`), ported verbatim from a reference implementation. That scheme
  * is now replaced by an 8-path canonical whitelist — see
  * {@link ./paths.MEMORY_ALL_PATHS}. The tool description no longer
  * names a specific file; the flush-turn prompt renders the full rubric
@@ -137,7 +137,7 @@ export const MEMORY_APPEND_DESCRIPTION =
 
 /**
  * Reply token that signals the flush turn produced no user-visible output.
- * Ported VERBATIM from upstream `src/auto-reply/tokens.ts:4`.
+ * Ported VERBATIM from a reference implementation `src/auto-reply/tokens.ts:4`.
  */
 export const SILENT_REPLY_TOKEN = 'NO_REPLY';
 

package/src/memory/mmr.ts

@@ -1,7 +1,7 @@
 /**
  * Maximal Marginal Relevance (MMR) re-ranking — Phase 2.
  *
- * Ported from upstream `extensions/memory-core/src/memory/mmr.ts` with
+ * Ported from a reference implementation `extensions/memory-core/src/memory/mmr.ts` with
  * minor adaptation for our `MemoryEntry` shape (content vs snippet, id vs
  * path+startLine). Behavior is identical: normalize scores, iteratively
  * pick the item that maximizes `λ * relevance - (1-λ) * max_similarity`
@@ -11,9 +11,9 @@
  */
 
 export interface MMRConfig {
-  /** Opt-in. Upstream default is false. */
+  /** Opt-in. Default is false. */
   enabled: boolean;
-  /** 0 = max diversity, 1 = max relevance. Upstream default 0.7. */
+  /** 0 = max diversity, 1 = max relevance. Default 0.7. */
   lambda: number;
 }
 

package/src/memory/paths.ts

@@ -8,7 +8,7 @@
  *
  * ## Why a whitelist?
  *
- * Earlier upstream-faithful designs used date-keyed files
+ * Earlier historical designs used date-keyed files
  * (`memory/YYYY-MM-DD.md`), which have three problems for a persistent
  * multi-user agent:
  *

package/src/memory/recallTracking.ts

@@ -1,9 +1,9 @@
 /**
  * Recall tracking — Phase 2.
  *
- * Lightweight adaptation of upstream
+ * Lightweight adaptation of an external recall-tracking module
  * `extensions/memory-core/src/short-term-promotion.ts::recordShortTermRecalls`.
- * Upstream stores recalls in a JSON file under `memory/.dreams/`; we store
+ * The reference implementation stores recalls in a JSON file under `memory/.dreams/`; we store
  * them in a Postgres table `agent_memory_recalls`. Schema captures what the
  * future Phase 3 dreaming/promotion algorithm will need:
  *   - which memory row was surfaced (`memory_id`)
@@ -90,7 +90,7 @@ export class PgvectorRecallTracker implements RecallTracker {
     const bucket = dayBucket(nowMs);
 
     // [recall-tracking] debug: upsert one row per (agent, memory, query, day)
-    // Upstream dedupes per-day per-query so repeated searches don't inflate counts.
+    // The reference implementation dedupes per-day per-query so repeated searches don't inflate counts.
     const values: string[] = [];
     const args: unknown[] = [];
     let i = 1;

package/src/memory/temporalDecay.ts

@@ -1,14 +1,14 @@
 /**
  * Temporal decay — Phase 2.
  *
- * Ported from upstream `extensions/memory-core/src/memory/temporal-decay.ts`.
+ * Ported from a reference implementation `extensions/memory-core/src/memory/temporal-decay.ts`.
  * Ages dated memory files (`memory/YYYY-MM-DD.md`) using exponential decay
  * `multiplier = exp(-ln(2) / halfLifeDays * ageInDays)`. At half-life, the
  * score is exactly halved.
  *
  * Evergreen files (MEMORY.md, memory/topics.md, any non-dated file inside
  * memory/) do NOT decay — they represent durable knowledge and should stay
- * hot regardless of age. This mirrors upstream's `isEvergreenMemoryPath`.
+ * hot regardless of age. This mirrors the standard `isEvergreenMemoryPath`.
  *
  * Since our pgvector rows carry `createdAt`, we don't need filesystem stat
  * fallback — the row timestamp is authoritative for any file without a