0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/explorations/longmemeval/scripts
Tyler Barnes 2770921eec
feat: add observational memory (#12599)
Adds Observational Memory (OM) — a system that keeps agent context
windows small while building long-term memory across conversations. Two
background agents handle this: an Observer watches conversations and
extracts observations, and a Reflector periodically
reorganizes/condenses those observations into reflections.

```ts
const memory = new Memory({
  storage: new PostgresStore({ connectionString }),
  options: {
    observationalMemory: true, // that's it
  },
});
```

Three-tier memory: recent messages -> observations (5-40x compression)
-> reflections (full rewrite). Supports thread-scoped (per-conversation)
and resource-scoped (shared across threads) modes. Token thresholds are
configurable.

Extended config example:

```ts
const memory = new Memory({
  storage: new PostgresStore({ connectionString }),
  options: {
    observationalMemory: {
      scope: 'resource', // shared memory across all threads for a user (default: 'thread')
      model: 'google/gemini-2.5-flash', // model for both observer and reflector
      shareTokenBudget: true, // let messages and observations share token space
      observation: {
        // model: 'deepseek/deepseek-chat', // override model for observer only
        messageTokens: 20_000, // trigger observation after this many unobserved tokens (default: 30k)
        maxTokensPerBatch: 10_000, // max tokens per batch in resource scope (default: 10k)
      },
      reflection: {
        // model: 'deepseek/deepseek-reasoner', // override model for reflector only
        observationTokens: 90_000, // trigger reflection after this many observation tokens (default: 40k)
      },
    },
  },
});
```

This is the core/storage/memory portion of OM — playground UI and evals
are separate PRs.

**What's here:**
- `@mastra/core`: OM types, storage interfaces, feature flag, processor
enhancements (state persistence, abort signals, stream writer)
- `@mastra/memory`: `ObservationalMemory` class, observer/reflector
agents, token counting, `observe()` API
- Storage adapters: pg, libsql, mongodb get full OM support; inmemory
for testing; other adapters are unaffected
- `@mastra/server`: OM status endpoint
- `@mastra/client-js`: `getMemoryStatus` updated (backward compatible)

All new interfaces are optional/additive. Storage adapters guard on
`TABLE_OBSERVATIONAL_MEMORY` existence so they work fine with older
`@mastra/core`. `@mastra/memory` checks
`coreFeatures.has('observationalMemory')` before loading OM.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Observational Memory (OM): three-tier memory (recent → observations →
reflections), per-thread/resource scope, manual observe control, OM UI
panel, and new observational-memory API endpoint.
* Client: fetch observational memory and richer memory status/config
responses.
  * Agent: find processor by ID.

* **Improvements**
* Processors: abort propagation, custom streaming events, and persistent
processor state across turns.
* Storage: OM support in in-memory, Postgres/LibSQL, and MongoDB
adapters.

* **Bug Fixes**
* Sealed messages preserved during merges; safer system-message
replacement.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Daniel Lew <danielshlomolew@gmail.com>
Co-authored-by: Mastra Code <noreply@mastra.ai>
History 2026-02-03 20:32:02 -08:00
..
download.ts feat: add observational memory (#12599) 2026-02-03 20:32:02 -08:00
find-failed.ts add longmemeval benchmark data preparation + benchmark runner (#5925) 2025-07-15 09:50:02 -07:00
generate-embeddings.ts add longmemeval benchmark data preparation + benchmark runner (#5925) 2025-07-15 09:50:02 -07:00
generate-wm-templates.ts Start adding ids to Agent (#9593) 2025-10-31 19:06:54 -07:00
setup.ts add longmemeval benchmark data preparation + benchmark runner (#5925) 2025-07-15 09:50:02 -07:00