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

# Mastra Agent Memory Integration

> Build stateful Node.js/TypeScript agents with Mastra using @sovseal/sdk's local store/recall memory, wrapped as Mastra-native tools.

Integrate **Mastra** with **sovseal** to build stateful TypeScript agents that recall customer details, previous tool decisions, and workflow context across runs.

<Info>
  Mastra exposes a lightweight `createTool` API. Wrapping `@sovseal/sdk`'s `store()`/`recall()` in Mastra tools lets models dynamically read from and write to the local ONEBRAIN memory engine during execution — no network round-trip, no encryption key to manage in the tool.
</Info>

## Installation

Install the Mastra core and `@sovseal/sdk` dependencies:

```bash theme={null}
npm install @mastra/core @sovseal/sdk @ai-sdk/openai zod
```

***

## Tool Definitions

Create your tool files wrapping `AgentStateClient.store()`/`.recall()` (`src/agent/tools.ts`):

```typescript theme={null}
import { createTool } from "@mastra/core/tools";
import { AgentStateClient, EngineUnavailableError } from "@sovseal/sdk";
import { z } from "zod";

// store/recall need no endpoint/apiKey — they talk to the local native host.
const client = new AgentStateClient();

export const recallMemoryTool = createTool({
  id: "sovseal-recall",
  description: "Search the local memory store for user preferences, previous decisions, and system history.",
  inputSchema: z.object({
    query: z.string().describe("The search query to match against memories."),
  }),
  outputSchema: z.object({
    context: z.string().describe("The recalled memory text, newline-separated."),
  }),
  execute: async ({ context }) => {
    try {
      const hits = await client.recall(context.query, { topK: 5 });
      return { context: hits.map((h) => h.text).join("\n") || "No memories found." };
    } catch (err) {
      if (err instanceof EngineUnavailableError) {
        return { context: `Recall unavailable: ${err.reason}` };
      }
      throw err;
    }
  },
});

export const storeMemoryTool = createTool({
  id: "sovseal-store",
  description: "Store a new preference, convention, or fact in persistent memory.",
  inputSchema: z.object({
    fact: z.string().describe("The declarative fact to save."),
  }),
  execute: async ({ context }) => {
    try {
      const result = await client.store(context.fact);
      return { success: true, reinforced: result.reinforced };
    } catch (err) {
      if (err instanceof EngineUnavailableError) {
        return { success: false, reason: err.reason };
      }
      throw err;
    }
  },
});
```

***

## Agent Setup

Wire the memory tools into your Mastra agent definition (`src/agent/index.ts`):

```typescript theme={null}
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { recallMemoryTool, storeMemoryTool } from "./tools";

export const memoryAgent = new Agent({
  name: "SovereignAssistant",
  instructions: `
    You are a personalized AI helper.
    Always call the 'sovseal-recall' tool first on starting a chat to search for user context.
    Use the 'sovseal-store' tool whenever the user volunteers useful personal preferences or workflow guidelines.
  `,
  model: openai("gpt-4o"),
  tools: { recallMemoryTool, storeMemoryTool },
});
```

<Note>
  `store`/`recall` require the native host launcher at `~/.sovseal/native-host/run.sh`. Run `npx -y @sovseal/mcp-server` once to provision it — see [SDK Reference: Overview](/sdk-reference/overview). If you need full encrypted state checkpointing (audit lineage, point-in-time rollback) rather than semantic recall, use `client.snapshot()`/`client.restore()` instead — see the [Node SDK reference](/sdk-reference/node-sdk).
</Note>