Observational Memory

Observational Memory manages context through a two-block structure: a list of compressed observations and a buffer of raw messages. When new messages arrive, they are appended to the raw block until it reaches a configurable threshold of 30,000 tokens. At that point, an "observer agent" automatically compresses the raw messages into new observations appended to the observation block. Similarly, when observations accumulate to 40,000 tokens, a "reflector agent" performs garbage collection, removing unimportant observations. These thresholds are deliberately conservative to achieve state-of-the-art results on benchmarks while staying well within typical context window limits. This mechanism ensures the context remains stable and predictable, enabling optimal prompt caching. The observer and reflector agents operate autonomously, enforcing memory discipline without developer intervention.

A standout capability of Observational Memory is its integration with prompt caching systems from leading providers like Anthropic and OpenAI. Because the context structure remains consistent—with observations always in the first block and raw messages appended until the threshold—caching hits are maximized. When the observer compresses messages, the existing observation block is updated but the prefix stays the same, yielding partial cache hits. Only during infrequent garbage collection is the entire cache invalidated. This design dramatically reduces token costs and latency in production. Furthermore, Observational Memory is fully open-source under the Mastra framework and requires no external databases or services, making it easy to deploy in existing agent architectures. Compatibility with any text-based LLM ensures broad applicability.

The overall workflow of Observational Memory follows a continuous cycle of observation, compression, and reflection. As an agent interacts with users or tools, all inputs and outputs are recorded as raw messages in the second context block. When the raw message token count exceeds 30,000, the observer agent asynchronously (soon in async mode) compresses the entire set of raw messages into a few observational summaries. These observations are appended to the first block, which grows gradually. When the observation block exceeds 40,000 tokens, the reflector agent reviews all observations and discards those deemed irrelevant or duplicative, based on emoji prioritization and recency. The result is a dynamic yet stable memory system that preserves critical information while shedding noise. This approach mirrors human selective attention, where only salient details are retained for future reasoning.

Concrete use cases for Observational Memory include coding agents that track user sessions over days, compressing progress, errors, and configuration changes into observations. For instance, a coding agent can remember that a user named their app "Acme Dashboard" and that it uses Supabase auth with server components. Browser agents running Playwright can manage thousands of screenshots and page states without exceeding context limits. Deep research agents can browse multiple URLs in parallel, summarizing findings into compact observations. In all these scenarios, the outcome is consistent: agents maintain accurate long-term memory, achieve higher benchmark scores (94.87% on LongMemEval), and drastically reduce token consumption through efficient caching. Developers report simpler debugging and more predictable agent behavior.

Observational Memory targets developers building agentic systems using the Mastra framework, which supports TypeScript and integrates with AI SDKs like @ai-sdk/openai. It is ideal for teams working on coding assistants, browser automation, or research agents that require reliable long-term memory. As an open-source component, it carries no licensing fees and can be self-hosted or deployed in any cloud environment. The current limitation of synchronous observation processing is being addressed with an upcoming async mode. In summary, Observational Memory provides an accessible, high-performance memory solution that sets a new standard for AI agent context management. By mimicking human memory compression, it enables agents to operate efficiently over extended interactions, making it indispensable for advanced autonomous applications.