observation.bufferActivation as absolute retention

Error message

observation.bufferActivation as absolute retention (${this.observationConfig.bufferActivation}) must be less than messageTokens (${observationThreshold})

What it means

When observation.bufferActivation is used in absolute mode (>= 1000), it represents a retention window in tokens and must be smaller than the messageTokens threshold. If the retention window is as large as or larger than the threshold, activation would never fire in a meaningful window relative to message processing, so the constructor rejects the configuration.

Solutions

Lower bufferActivation below the messageTokens threshold.
Raise observation.messageTokens above your desired absolute retention value.
Switch to ratio mode (bufferActivation <= 1) so retention scales with messageTokens automatically.

Example fix

// before
new ObservationalMemory({ observation: { messageTokens: 4000, bufferActivation: 6000 } });
// after
new ObservationalMemory({ observation: { messageTokens: 8000, bufferActivation: 6000 } });

Defensive patterns

Strategy: validation

Validate before calling

const observationThreshold = getMaxThreshold(observationConfig.messageTokens);
if (observationConfig.bufferActivation !== undefined && observationConfig.bufferActivation >= 1000 && observationConfig.bufferActivation >= observationThreshold) {
  throw new Error(`bufferActivation (${observationConfig.bufferActivation}) must be < messageTokens (${observationThreshold})`);
}

Prevention

Tune messageTokens and bufferActivation together, not independently.
Prefer ratio mode (<= 1) to avoid threshold coupling.
Re-validate config after any change to messageTokens.

When it happens

Trigger: new ObservationalMemory({ observation: { messageTokens: 4000, bufferActivation: 4000 } }) or bufferActivation: 10000 with default/lower messageTokens.

Common situations: Raising bufferActivation for more context retention without checking messageTokens; combining a large absolute bufferActivation copied from another project with a smaller messageTokens here.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/e13eec2d0077f821. Report an issue: GitHub.

Appendix: source

Thrown at packages/memory/src/processors/observational-memory/observational-memory.ts:1009

        );
      }
    }

    // Validate observation bufferActivation: (0, 1] for ratio, or >= 1000 for absolute retention tokens
    if (this.observationConfig.bufferActivation !== undefined) {
      if (this.observationConfig.bufferActivation <= 0) {
        throw new Error(`observation.bufferActivation must be > 0, got ${this.observationConfig.bufferActivation}`);
      }
      if (this.observationConfig.bufferActivation > 1 && this.observationConfig.bufferActivation < 1000) {
        throw new Error(
          `observation.bufferActivation must be <= 1 (ratio) or >= 1000 (absolute token retention), got ${this.observationConfig.bufferActivation}`,
        );
      }
      if (
        this.observationConfig.bufferActivation >= 1000 &&
        this.observationConfig.bufferActivation >= observationThreshold
      ) {
        throw new Error(
          `observation.bufferActivation as absolute retention (${this.observationConfig.bufferActivation}) must be less than messageTokens (${observationThreshold})`,
        );
      }
    }

    // Validate observation blockAfter
    if (this.observationConfig.blockAfter !== undefined) {
      if (this.observationConfig.blockAfter < observationThreshold) {
        throw new Error(
          `observation.blockAfter (${this.observationConfig.blockAfter}) must be >= messageTokens (${observationThreshold})`,
        );
      }
      if (!this.observationConfig.bufferTokens) {
        throw new Error(
          `observation.blockAfter requires observation.bufferTokens to be set (blockAfter only applies when async buffering is enabled)`,
        );
      }
    }

View on GitHub (pinned to 75dd419e61)