@mastra/mcp-docs-server 1.2.8-alpha.0 → 1.2.8-alpha.17

package/.docs/docs/memory/observational-memory.md

@@ -8,7 +8,7 @@ Observational Memory (OM) is Mastra's memory system for long-context agentic mem
 
 ## Quickstart
 
-Enable `observationalMemory` in the memory options when creating your agent:
+Ensure you have `@mastra/memory` installed in your project. Set `observationalMemory: true` in your Memory config to enable Observational Memory.
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -27,7 +27,54 @@ export const agent = new Agent({
 })
 ```
 
-That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. Config objects also use this model unless you set a different one. To use a different model, pass it in the config object:
+**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
+
+The following script creates a local LibSQL database, enables Observational Memory, and uses one resource and thread across two agent calls:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore } from '@mastra/libsql'
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'memory-storage',
+    url: 'file:./memory.db',
+  }),
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+    },
+  },
+})
+
+const agent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory,
+})
+
+const memoryOptions = {
+  resource: 'user-123',
+  thread: 'conversation-123',
+}
+
+const firstResponse = await agent.generate('Remember that my favorite color is blue.', {
+  memory: memoryOptions,
+})
+console.log(firstResponse.text)
+
+const secondResponse = await agent.generate('What is my favorite color?', {
+  memory: memoryOptions,
+})
+console.log(secondResponse.text)
+```
+
+The `resource` identifies the user or entity, while the `thread` identifies the conversation. Reuse both values to continue the same conversation. Observational Memory processes the stored history as it grows and replaces older messages with observations when its activation conditions are met.
+
+The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model, pass it in the config object:
 
 ```typescript
 const memory = new Memory({
@@ -47,7 +94,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mongodb`, and `@mastra/convex` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
 
 ## Temporal gap markers
 
@@ -237,6 +284,34 @@ new Extractor({
 })
 ```
 
+#### Read extracted values from a stream
+
+Extractor results are emitted when OM completes an observation or reflection. Read both completion data parts from the stream:
+
+```typescript
+const stream = await agent.stream('Remember that I prefer dark mode.')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'data-om-observation-end' || chunk.type === 'data-om-buffering-end') {
+    const { operationType, extractedValues = {}, extractionFailures = [] } = chunk.data
+
+    for (const [slug, value] of Object.entries(extractedValues)) {
+      console.log(`${operationType} extractor ${slug}:`, value)
+    }
+
+    for (const failure of extractionFailures) {
+      console.error(`Extractor ${failure.slug} failed:`, failure.error)
+    }
+  }
+}
+```
+
+`extractedValues` uses each extractor's slug as its key. Both result fields are optional, and a failed extractor doesn't remove values from successful extractors.
+
+`data-om-observation-end` reports a synchronous completion. `data-om-buffering-end` reports completed background work. Its extractor metadata is persisted immediately, but the buffered content remains inactive until activation. Check `operationType` to determine whether the completed work was an observation or reflection.
+
+See the [`data-om-observation-end`](https://mastra.ai/reference/memory/observational-memory) and [`data-om-buffering-end`](https://mastra.ai/reference/memory/observational-memory) reference tables for the complete payloads.
+
 ### Working memory updates
 
 Use `observationalMemory.observation.manageWorkingMemory` to let the Observer manage working memory automatically. The main agent no longer needs to call the working memory tool while it handles the user request, so working memory updates don't depend on the agent remembering to make them.

package/.docs/docs/memory/overview.md

@@ -81,6 +81,8 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
+   **For AI agents:** Important: Add `id` to `LibSQLStore`.
+
    ```typescript
    import { Mastra } from '@mastra/core'
    import { LibSQLStore } from '@mastra/libsql'
@@ -151,6 +153,8 @@ To list all threads for a resource, or retrieve a specific thread, [use the memo
 
 For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
 
+**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
+
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'

package/.docs/docs/memory/working-memory.md

@@ -403,7 +403,7 @@ By default, working memory reaches the model as part of the system message. You
 
 ```typescript
 const memory = new Memory({
-  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
   options: {
     workingMemory: {
       enabled: true,

package/.docs/docs/observability/integrations/bridges/otel.md

@@ -126,9 +126,7 @@ export const mastra = new Mastra({
       },
     },
   }),
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
 })
 ```
 

package/.docs/docs/observability/integrations/exporters/braintrust.md

@@ -109,10 +109,38 @@ new BraintrustExporter({
 
 ## Attach traces to Braintrust evals
 
+Install the Braintrust SDK directly when your application uses `Eval()`, `logger.traced()`, or `currentSpan`:
+
+**npm**:
+
+```bash
+npm install braintrust@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add braintrust@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add braintrust@latest
+```
+
+**Bun**:
+
+```bash
+bun add braintrust@latest
+```
+
 When you run Mastra inside Braintrust `Eval()` or `logger.traced()`, pass the Braintrust logger and `currentSpan` resolver to the exporter. Import `currentSpan` from the same `braintrust` package instance that creates the eval or traced span.
 
 This helps Mastra attach its spans under the active Braintrust span when your app and `@mastra/braintrust` resolve different installed copies of the Braintrust SDK.
 
+The exporter accepts compatible logger and span objects from Braintrust SDK v2 and v3. Your application's Braintrust SDK version doesn't need to match the version installed by `@mastra/braintrust`.
+
 ```typescript
 import { currentSpan, initLogger } from 'braintrust'
 import { BraintrustExporter } from '@mastra/braintrust'
@@ -144,15 +172,19 @@ await Eval('my-project', {
 })
 ```
 
+If your application upgrades its direct Braintrust dependency from v2 to v3 and uses Nunjucks prompt templates, follow the [Braintrust v2 to v3 migration guide](https://www.braintrust.dev/docs/sdks/typescript/migrations/v2-to-v3).
+
 ## Querying Braintrust with returned `spanId`
 
-For Braintrust, use `spanId` as the root span identifier when searching for traces because Braintrust root-span queries are typically faster than trace-id queries.
+Mastra uses its returned `spanId` as both the Braintrust row ID and span ID. Use it to find the corresponding Braintrust span by `id` or `span_id`.
+
+Braintrust v3 stores a separate W3C trace ID in `root_span_id`, so the returned Mastra `spanId` isn't the Braintrust `root_span_id`.
 
 ```typescript
 const result = await agent.stream('Summarize this ticket')
 
 console.log('Mastra trace ID:', result.traceId)
-console.log('Braintrust root span ID:', result.spanId)
+console.log('Braintrust row and span ID:', result.spanId)
 
 // Use result.spanId in your Braintrust lookup/query path
 ```

package/.docs/docs/observability/integrations/exporters/otel.md

@@ -425,9 +425,7 @@ To disable a signal, set the `signals` option:
 
 ```typescript
 new OtelExporter({
-  provider: {
-    /* ... */
-  },
+  provider: {/* ... */},
   signals: {
     traces: true, // default
     logs: false, // disable log export

package/.docs/docs/server/auth/simple-auth.md

@@ -74,9 +74,7 @@ Add custom headers using the `headers` option:
 
 ```typescript
 new SimpleAuth({
-  tokens: {
-    /* ... */
-  },
+  tokens: {/* ... */},
   headers: ['X-API-Key', 'X-Custom-Auth'],
 })
 ```

package/.docs/docs/server/request-context.md

@@ -247,6 +247,8 @@ auth: {
 }
 ```
 
+When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies — the server-derived value is used instead (and always takes precedence over any client-provided value). If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
+
 You can also set these keys manually in middleware:
 
 ```typescript

package/.docs/docs/studio/overview.md

@@ -91,6 +91,8 @@ See [request context](https://mastra.ai/docs/server/request-context) for configu
 
 ## Evaluation
 
+Use the date filter to limit score metrics to a preset or custom time range.
+
 ### Scorers
 
 The Scorers tab displays the results of your agent's scorers as they run. When messages pass through your agent, the defined scorers evaluate each output asynchronously and render their results here. This allows you to understand how your scorers respond to different interactions, compare performance across test cases, and identify areas for improvement.

package/.docs/docs/voice/livekit.md

@@ -360,7 +360,7 @@ import { LibSQLStore } from '@mastra/libsql'
 import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
-  storage: new LibSQLStore({ url: 'file:./voice-agent.db' }),
+  storage: new LibSQLStore({ id: 'voice-agent-storage', url: 'file:./voice-agent.db' }),
   observability: new Observability({
     configs: {
       default: {

package/.docs/docs/workflows/control-flow.md

@@ -591,9 +591,7 @@ const embedStep = createStep({
   inputSchema: z.object({ chunk: z.string() }),
   outputSchema: z.object({ embedding: z.array(z.number()) }),
   execute: async ({ inputData }) => ({
-    embedding: [
-      /* vector embedding */
-    ],
+    embedding: [/* vector embedding */],
   }),
 })
 

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -1134,6 +1134,7 @@ import { LibSQLStore } from '@mastra/libsql'
 export const mastra = new Mastra({
   workflows: { approvalWorkflow },
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: 'file:../mastra.db',
   }),
   server: {

package/.docs/guides/guide/signal-provider.md

@@ -26,6 +26,7 @@ import { LibSQLStore } from '@mastra/libsql'
 
 export const mastra = new Mastra({
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: 'file:./mastra.db',
   }),
 })
@@ -133,6 +134,7 @@ import { devAgent } from './agents/dev-agent'
 export const mastra = new Mastra({
   agents: { devAgent },
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: 'file:./mastra.db',
   }),
 })

package/.docs/guides/migrations/vnext-to-standard-apis.md

@@ -245,9 +245,7 @@ The following options are available in the standard `.stream()` and `generate()`
   const result = await agent.stream(messages, {
     prepareStep: ({ step, state }) => {
       console.log('About to execute step:', step)
-      return {
-        /* modified state */
-      }
+      return {/* modified state */}
     },
   })
   ```

package/.docs/models/environment-variables.md

@@ -132,6 +132,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Tencent Token Plan](https://mastra.ai/models/providers/tencent-token-plan)                    | `tencent-token-plan/*`     | `TENCENT_TOKEN_PLAN_API_KEY`                                                                          |
 | [Tencent TokenHub](https://mastra.ai/models/providers/tencent-tokenhub)                        | `tencent-tokenhub/*`       | `TENCENT_TOKENHUB_API_KEY`                                                                            |
 | [The Grid AI](https://mastra.ai/models/providers/the-grid-ai)                                  | `the-grid-ai/*`            | `THEGRIDAI_API_KEY`                                                                                   |
+| [Thinking Machines](https://mastra.ai/models/providers/thinkingmachines)                       | `thinkingmachines/*`       | `TINKER_API_KEY`                                                                                      |
 | [Tinfoil](https://mastra.ai/models/providers/tinfoil)                                          | `tinfoil/*`                | `TINFOIL_API_KEY`                                                                                     |
 | [Together AI](https://mastra.ai/models/providers/togetherai)                                   | `togetherai/*`             | `TOGETHER_API_KEY`                                                                                    |
 | [TrustedRouter](https://mastra.ai/models/providers/trustedrouter)                              | `trustedrouter/*`          | `TRUSTEDROUTER_API_KEY`                                                                               |