Mastra

https://mastra.ai/docs/memory/overview
Admin
Mastra is a TypeScript framework for building AI agents and applications with built-in memory,...
Tokens:6,590
Snippets:68
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install @mastra/memory package

Source: https://mastra.ai/docs/memory/overview

Install the memory package using your preferred package manager.

```bash
npm install @mastra/memory@latest
```

```bash
pnpm add @mastra/memory@latest
```

```bash
yarn add @mastra/memory@latest
```

```bash
bun add @mastra/memory@latest
```

--------------------------------

### Install @mastra/libsql storage provider

Source: https://mastra.ai/docs/memory/overview

Install the LibSQL storage provider to persist message history.

```bash
npm install @mastra/libsql@latest
```

```bash
pnpm add @mastra/libsql@latest
```

```bash
yarn add @mastra/libsql@latest
```

```bash
bun add @mastra/libsql@latest
```

--------------------------------

### Create Mastra entry point and register agent

Source: https://mastra.ai/docs

Defines the Mastra instance in src/mastra/index.ts, registering the weatherAgent. This is the required setup before running the agent.

```TypeScript
import { Mastra } from '@mastra/core'
import { weatherAgent } from './agents/weather-agent.ts'

export const mastra = new Mastra({
  agents: { weatherAgent },
})
```

--------------------------------

### Create an agent with Agent (weather-agent.ts)

Source: https://mastra.ai/docs

Example of creating a Mastra agent using Agent from @mastra/core/agent. The constructor takes { id, name, instructions, model }. The model is a string in provider/model format, e.g., 'openai/gpt-5.6-sol'. The agent uses the weatherTool.

```ts
// src/mastra/agents/weather-agent.ts
import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool.ts'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.

      Your primary function is to help users get weather details for specific locations. When responding:
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  // Use a string in provider/model format, not provider:model or a provider object.
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})
```

--------------------------------

### Define a tool with createTool (weather-tool.ts)

Source: https://mastra.ai/docs

Example of defining a Mastra tool using createTool from @mastra/core/tools. Must include id, description, inputSchema (zod), and execute with signature execute(inputData, context). The execute function returns weather data for a location.

```ts
// src/mastra/tools/weather-tool.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name'),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})
```

--------------------------------

### Run the agent with agent.generate()

Source: https://mastra.ai/docs

Imports the Mastra instance, retrieves the agent by id, and calls generate() to get a response. Requires Node.js 22.18.0+ for direct TypeScript execution; add file extensions for local imports.

```TypeScript
// run.mjs
import { mastra } from './src/mastra/index.ts'

const agent = mastra.getAgentById('weather-agent')
const response = await agent.generate('Weather in SF')
console.log(response.text)
```

--------------------------------

### Create Mastra project with Bun

Source: https://mastra.ai/docs

Scaffolds a new Mastra project using Bun. Creates a general-purpose agent harness with local workspace, shell tools, memory, task tracking, web access, and recurring schedules.

```bash
bunx create-mastra
```

--------------------------------

### Create Mastra project with npm

Source: https://mastra.ai/docs

Scaffolds a new Mastra project using npm. Creates a general-purpose agent harness with local workspace, shell tools, memory, task tracking, web access, and recurring schedules.

```bash
npm create mastra@latest
```

--------------------------------

### Configure LibSQLStore in Mastra instance

Source: https://mastra.ai/docs/memory/overview

Add the LibSQLStore to your Mastra instance, ensuring an id is provided.

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: ':memory:',
  }),
})
```

--------------------------------

### Create Mastra project with pnpm

Source: https://mastra.ai/docs

Scaffolds a new Mastra project using pnpm. Creates a general-purpose agent harness with local workspace, shell tools, memory, task tracking, web access, and recurring schedules.

```bash
pnpm create mastra@latest
```

--------------------------------

### Create Mastra project with Yarn

Source: https://mastra.ai/docs

Scaffolds a new Mastra project using Yarn. Creates a general-purpose agent harness with local workspace, shell tools, memory, task tracking, web access, and recurring schedules.

```bash
yarn create mastra
```

--------------------------------

### Initialize Agent with Memory

Source: https://mastra.ai/docs/memory/overview

Create a Memory instance and assign it to the agent's memory option.

```typescript
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'

export const memoryAgent = new Agent({
  id: 'memory-agent',
  name: 'Memory Agent',
  memory: new Memory({
    options: {
      lastMessages: 20,
    },
  }),
})
```

--------------------------------

### Create tsconfig.json for Mastra project

Source: https://mastra.ai/docs

Required TypeScript configuration for a Mastra project. Sets ES2022 target and module, bundler module resolution, strict mode, and includes src/**/*.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}
```

--------------------------------

### Enable observational memory in agent

Source: https://mastra.ai/docs/memory/overview

Configure observational memory by passing a Memory instance with observationalMemory set to true to the Agent constructor. A storage provider must be configured for this to function.

```typescript
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'

export const memoryAgent = new Agent({
  id: 'memory-agent',
  name: 'Memory Agent',
  memory: new Memory({
    options: {
      observationalMemory: true,
    },
  }),
})
```

--------------------------------

### Share resource-scoped memory between agents

Source: https://mastra.ai/docs/memory/overview

Demonstrates sharing observations, working memory, and embeddings by using the same resource identifier across different agent calls.

```typescript
// Both agents share the same resource-scoped memory
await researcher.generate('Find information about quantum computing.', {
  memory: { resource: 'project-42', thread: 'research-session' },
})

await writer.generate('Write a summary from the research notes.', {
  memory: { resource: 'project-42', thread: 'writing-session' },
})
```

--------------------------------

### Switch memory per request using RequestContext

Source: https://mastra.ai/docs/memory/overview

Use RequestContext to conditionally select between different memory instances based on user-tier metadata.

```typescript
export type UserTier = {
  'user-tier': 'enterprise' | 'pro'
}

const premiumMemory = new Memory()
const standardMemory = new Memory()

export const memoryAgent = new Agent({
  id: 'memory-agent',
  name: 'Memory Agent',
  memory: ({ requestContext }) => {
    const userTier = requestContext.get('user-tier') as UserTier['user-tier']

    return userTier === 'enterprise' ? premiumMemory : standardMemory
  },
})
```

--------------------------------

### Recall information from memory

Source: https://mastra.ai/docs/memory/overview

Retrieve stored information by calling the agent with the same resource and thread identifiers used during the initial conversation.

```typescript
const response = await memoryAgent.generate("What's my favorite color?", {
  memory: {
    resource: 'user-123',
    thread: 'conversation-123',
  },
})

// Response: "Your favorite color is blue."
```

--------------------------------

### Track message history with memory object

Source: https://mastra.ai/docs/memory/overview

Pass a memory object containing a resource identifier and a thread ID to the agent's generate method to track conversation history.

```typescript
const response = await memoryAgent.generate('Remember my favorite color is blue.', {
  memory: {
    resource: 'user-123',
    thread: 'conversation-123',
  },
})
```
Tokens:
Raw