{"record":{"id":"e13eec2d0077f821","repo":"mastra-ai/mastra","slug":"observation-bufferactivation-as-absolute-retention","errorCode":null,"errorMessage":"observation.bufferActivation as absolute retention (${this.observationConfig.bufferActivation}) must be less than messageTokens (${observationThreshold})","messagePattern":"observation\\.bufferActivation as absolute retention \\((.+?)\\) must be less than messageTokens \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/observational-memory.ts","lineNumber":1009,"sourceCode":"        );\n      }\n    }\n\n    // Validate observation bufferActivation: (0, 1] for ratio, or >= 1000 for absolute retention tokens\n    if (this.observationConfig.bufferActivation !== undefined) {\n      if (this.observationConfig.bufferActivation <= 0) {\n        throw new Error(`observation.bufferActivation must be > 0, got ${this.observationConfig.bufferActivation}`);\n      }\n      if (this.observationConfig.bufferActivation > 1 && this.observationConfig.bufferActivation < 1000) {\n        throw new Error(\n          `observation.bufferActivation must be <= 1 (ratio) or >= 1000 (absolute token retention), got ${this.observationConfig.bufferActivation}`,\n        );\n      }\n      if (\n        this.observationConfig.bufferActivation >= 1000 &&\n        this.observationConfig.bufferActivation >= observationThreshold\n      ) {\n        throw new Error(\n          `observation.bufferActivation as absolute retention (${this.observationConfig.bufferActivation}) must be less than messageTokens (${observationThreshold})`,\n        );\n      }\n    }\n\n    // Validate observation blockAfter\n    if (this.observationConfig.blockAfter !== undefined) {\n      if (this.observationConfig.blockAfter < observationThreshold) {\n        throw new Error(\n          `observation.blockAfter (${this.observationConfig.blockAfter}) must be >= messageTokens (${observationThreshold})`,\n        );\n      }\n      if (!this.observationConfig.bufferTokens) {\n        throw new Error(\n          `observation.blockAfter requires observation.bufferTokens to be set (blockAfter only applies when async buffering is enabled)`,\n        );\n      }\n    }","sourceCodeStart":991,"sourceCodeEnd":1027,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/observational-memory.ts#L991-L1027","documentation":"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.","triggerScenarios":"new ObservationalMemory({ observation: { messageTokens: 4000, bufferActivation: 4000 } }) or bufferActivation: 10000 with default/lower messageTokens.","commonSituations":"Raising bufferActivation for more context retention without checking messageTokens; combining a large absolute bufferActivation copied from another project with a smaller messageTokens here.","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."],"exampleFix":"// before\nnew ObservationalMemory({ observation: { messageTokens: 4000, bufferActivation: 6000 } });\n// after\nnew ObservationalMemory({ observation: { messageTokens: 8000, bufferActivation: 6000 } });","handlingStrategy":"validation","validationCode":"const observationThreshold = getMaxThreshold(observationConfig.messageTokens);\nif (observationConfig.bufferActivation !== undefined && observationConfig.bufferActivation >= 1000 && observationConfig.bufferActivation >= observationThreshold) {\n  throw new Error(`bufferActivation (${observationConfig.bufferActivation}) must be < messageTokens (${observationThreshold})`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Tune messageTokens and bufferActivation together, not independently.","Prefer ratio mode (<= 1) to avoid threshold coupling.","Re-validate config after any change to messageTokens."],"tags":["configuration","validation","observational-memory","token-limits"],"backgroundTag":"invalid-config-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}