> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastra

> Give Mastra agents persistent, cross-session memory with Memanto tools.

# Mastra + Memanto

<img src="https://mintcdn.com/memanto/quztxulHuDxgL5_H/logo/integrations/mastra.svg?fit=max&auto=format&n=quztxulHuDxgL5_H&q=85&s=b9476ad15375ca01ac1e2cb4d2d63f18" alt="Mastra" width="64" style={{marginBottom: "1.5rem"}} data-path="logo/integrations/mastra.svg" />

Add persistent memory to any [Mastra](https://mastra.ai/) agent with three ready-made tools, shipped as part of the `@moorcheh-ai/memanto` TypeScript SDK.

## Prerequisites

* Node.js 20+
* [`uv`](https://docs.astral.sh/uv/) (ships `uvx`) — the `Memanto` client spawns a local Memanto server via `uvx` on first use unless you pass `baseUrl`
* **Memanto / Moorcheh credentials** — [Moorcheh API key](https://console.moorcheh.ai/api-keys) (cloud) or an [on-prem](/on-prem/overview) backend (no Moorcheh API key). Set `MOORCHEH_API_KEY` or pass `apiKey` to `new Memanto({ ... })`
* **Agent model credentials** — the quick start uses `openai/gpt-4o` for tool orchestration. Configure your OpenAI API key for Mastra (typically `OPENAI_API_KEY`).
* `@mastra/core` and `zod` installed in your app (optional peer dependencies of `@moorcheh-ai/memanto`)

## Install

```bash theme={null}
npm install @moorcheh-ai/memanto @mastra/core zod
```

`@mastra/core` and `zod` are optional peer dependencies of `@moorcheh-ai/memanto` — install them yourself in the host app. Importing `@moorcheh-ai/memanto/mastra` without them installed will fail at module load with a standard Node resolution error.

## Quick Start

```ts theme={null}
import { Agent } from "@mastra/core/agent";
import { Memanto } from "@moorcheh-ai/memanto";
import { createMemantoMastraTools } from "@moorcheh-ai/memanto/mastra";

const memanto = new Memanto({
  agentId: "my-agent",
  apiKey: process.env.MOORCHEH_API_KEY, // omit when using on-prem; see On-Prem below
});

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions:
    "You have long-term memory. Persist durable facts with rememberMemory " +
    "and look them up with recallMemory / answerMemory before answering.",
  model: "openai/gpt-4o", // requires OPENAI_API_KEY — swap for your provider if needed
  tools: createMemantoMastraTools(memanto),
});
```

`createMemantoMastraTools` returns an object with three [Mastra tools](https://mastra.ai/docs/agents/using-tools-and-mcp) — pass it straight into an agent's `tools` map.

Each tool's description is written for the model to decide *when* to call it (e.g. `recallMemory`: "Call this before answering whenever the user refers to information from earlier or from a previous session").

## Available Tools

| Tool             | Backed by                                                  | Description                                                                                                                                           |
| ---------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recallMemory`   | [Recall](/api-reference/search/recall)                     | Semantic search over stored memories. `query` (required), `limit` (1-50), `type` (optional array of memory types to filter by).                       |
| `rememberMemory` | [Remember](/api-reference/data/remember)                   | Persist a durable fact/preference/decision/instruction. `content` (required), `type` (optional — server auto-classifies if omitted), `title`, `tags`. |
| `answerMemory`   | [Generate AI Answer](/api-reference/ai/generate-ai-answer) | RAG-synthesized answer over stored memories. `question` (required), `limit` (1-100).                                                                  |

`answerMemory` calls Memanto's **Generate AI Answer** API (`memanto.answer()` → Moorcheh `answer.generate`). Memanto retrieves relevant memories and synthesizes a grounded response using **Memanto's configured LLM** — not the model you pass to your Mastra `Agent`. Your agent model only decides *when* to call the tool and how to use the result. `recallMemory` and `rememberMemory` do not invoke an LLM.

## Options

```ts theme={null}
createMemantoMastraTools(memanto, {
  include: ["recallMemory", "answerMemory"], // expose a subset — omit for all three
  defaultLimit: 10,                           // default limit for recall/answer when the model doesn't specify one
});
```

## Memory Types

`type` fields are constrained to Memanto's 13 supported types via a shared `MEMORY_TYPES` export:

```ts theme={null}
import { MEMORY_TYPES } from "@moorcheh-ai/memanto/mastra";
// ["fact", "preference", "goal", "decision", "artifact", "learning", "event",
//  "instruction", "relationship", "context", "observation", "commitment", "error"]
```

See the [Memory Types Reference](/reference/memory-types) for what each type means.

## On-Prem

The integration talks to Memanto through the `Memanto` client, so it works identically against an on-prem backend — no code changes, just configure the backend once with the CLI. See [On-Prem Overview](/on-prem/overview) and the [TypeScript SDK Reference](/sdk/typescript#on-prem-no-api-key).

## Next Steps

* [TypeScript SDK Reference](/sdk/typescript) for the full `Memanto` client API
* [Vercel AI SDK Integration](/integrations/vercel-ai-sdk) for the equivalent AI SDK tools
* [OpenAI Integration](/integrations/openai) for the equivalent OpenAI `runTools()` tools
* [Memory Types Reference](/reference/memory-types)