Mastra - Maximem Synap

Add persistent, per-user memory to a Mastra agent in TypeScript. The integration ships a MastraMemory subclass for always-on memory and a pair of tools the model can call when it wants explicit control.

@maximem/synap-mastra wraps the JavaScript SDK, which in turn wraps the Python SDK as a subprocess. It requires a Python 3.11+ runtime on the host. Edge Runtime, Cloudflare Workers, Bun, Deno Deploy, and AWS Lambda Node-only runtimes are not supported. See Installation → JavaScript / TypeScript SDK.

Runtime: Node.js 18+ only. The JS SDK wraps the Python SDK as a subprocess, so it needs Python 3.11+ on the host and does NOT run on Edge / Cloudflare Workers / Bun / Deno / Lambda-Node-only. On Next.js, pin the route to runtime = “nodejs”.

Overview

This guide shows how to add Synap to a Mastra application to build agents that:

Recall and persist memory automatically on every generate call
Search and store memories on demand when the model decides it’s relevant
Mix and match: use the memory class alone, the tools alone, or both together

The Synap Mastra integration ships three exports: one memory class and two tool factories.

Export	Mastra interface	Purpose
`SynapMemory`	`MastraMemory` subclass	Always-on memory: auto-recall + auto-store on every `generate`
`synapSearchTool`	Tool factory	Returns a Mastra-compatible tool for explicit memory search
`synapStoreTool`	Tool factory	Returns a Mastra-compatible tool for explicit memory storage

Setup

Install the package alongside Mastra:

npm install @maximem/synap-mastra @maximem/synap-js-sdk @mastra/core zod

Import the integration from its package name directly: import { SynapMemory } from "@maximem/synap-mastra". The core SDK (createClient) comes from the separate @maximem/synap-js-sdk package.

Configure your API key. Generate one from the Synap Dashboard.

.env

SYNAP_API_KEY=synap_your_key_here
OPENAI_API_KEY=your-openai-api-key

Initialize the SDK once at application startup:

import { createClient } from "@maximem/synap-js-sdk";

const sdk = createClient();
await sdk.init();

See SDK Initialization for the full lifecycle and configuration options.

Basic integration

The smallest useful integration plugs SynapMemory into an Agent. Every generate call automatically pulls relevant memories into the prompt and writes the new turn back out:

// npm install @maximem/synap-mastra @maximem/synap-js-sdk @mastra/core zod
import { Agent } from "@mastra/core";
import { openai } from "@ai-sdk/openai";
import { createClient } from "@maximem/synap-js-sdk";
import { SynapMemory } from "@maximem/synap-mastra";

const sdk = createClient();
await sdk.init();

const agent = new Agent({
  name: "MemoryAgent",
  instructions: "You are an agent with persistent memory.",
  model: openai("gpt-4o"),

  memory: new SynapMemory({
    sdk,
    userId: "alice",
    customerId: "acme",   // optional, required for B2B instances
  }),
});

const result = await agent.generate("What do you remember about my project deadlines?");
console.log(result.text);

The scoping triple is bound when SynapMemory is constructed: the model never sees the user identity. Memory reads degrade gracefully (empty context on failure); writes raise so silent data loss is impossible. To let the model decide when to recall or store (rather than running on every turn), use the tools below.

Core concepts

SynapMemory

SynapMemory extends Mastra’s MastraMemory and overrides the storage layer to route through Synap:

import { SynapMemory } from "@maximem/synap-mastra";

const memory = new SynapMemory({
  sdk,
  userId: "alice",
  customerId: "acme",       // optional
  conversationId: crypto.randomUUID(),  // optional, scopes to a single session; must be a valid UUID
  maxResults: 8,
  mode: "fast",             // "fast" | "accurate"
});

The two retrieval modes trade latency against comprehensiveness:

	`fast`	`accurate`
Search	Vector + graph (no LLM subquery decomposition)	Vector + graph + LLM subquery decomposition + reranking
Best for	Real-time chat	Multi-entity queries

fast is lower-latency and suited to the hot path; accurate adds LLM-driven query decomposition and reranking for relationship-aware queries at a higher latency cost. Method behavior:

Method	Behavior
`remember(message)`	Ingests a message into Synap
`recall(query, options)`	Semantic search; returns `MemoryMessage[]`
`getMessages(threadId)`	Retrieves the message thread from Synap

synapSearchTool and synapStoreTool

The tool factories return Mastra-compatible tool objects with Zod schemas. They’re for agents that should decide when to query memory rather than running on every turn:

import { synapSearchTool, synapStoreTool } from "@maximem/synap-mastra";

const agent = new Agent({
  // ...
  tools: {
    synapSearch: synapSearchTool({
      sdk,
      userId: "alice",
      maxResults: 5,
      mode: "accurate",
    }),
    synapStore: synapStoreTool({ sdk, userId: "alice" }),
  },
});

synapSearchTool schema:

z.object({
  query: z.string().describe("What to search for in memory"),
  maxResults: z.number().optional().default(5),
})

synapStoreTool schema:

z.object({
  content: z.string().describe("The information to remember"),
  memoryType: z.string().optional().default("fact"),
})

Memory vs. tools

	`SynapMemory`	Tools
Context injection	Automatic on every `generate`	On-demand when model calls the tool
Memory storage	Automatic after every response	On-demand when model calls the tool
Best for	Always-on memory for every interaction	Agents that decide when memory matters

Use both for maximum coverage: SynapMemory handles the always-on path and synapStoreTool lets the model bookmark new information explicitly when it sees something worth remembering.

Complete example: agent with memory + tools

The pattern below assembles all three exports. The agent has always-on memory via SynapMemory AND can call the search/store tools when it decides to:

import { Agent } from "@mastra/core";
import { openai } from "@ai-sdk/openai";
import {
  SynapMemory,
  synapSearchTool,
  synapStoreTool,
} from "@maximem/synap-mastra";

function buildAgent(sdk, userId: string, customerId?: string) {
  return new Agent({
    name: "PersonalAssistant",
    instructions: `You are a personal assistant with long-term memory.
Use synapSearch when you need older context not already in the prompt.
Use synapStore when the user shares a new fact, preference, or decision.`,
    model: openai("gpt-4o"),

    memory: new SynapMemory({
      sdk,
      userId,
      customerId,
      maxResults: 6,
      mode: "fast",
    }),

    tools: {
      synapSearch: synapSearchTool({ sdk, userId, customerId, maxResults: 5 }),
      synapStore: synapStoreTool({ sdk, userId, customerId }),
    },
  });
}


// Usage
const agent = buildAgent(sdk, "alice", "acme");

await agent.generate("I just upgraded to the Pro plan.");
// SynapMemory.remember persists the turn; the model may also call synapStore.

const reply = await agent.generate("What plan am I on?");
// SynapMemory.recall surfaces "Pro plan" automatically.
console.log(reply.text);  // → "You're on the Pro plan."

Three things to notice in this pattern:

Memory and tools are complementary, not redundant. SynapMemory handles the always-on baseline; tools handle the explicit “I should look this up” path.
Scope is per-agent. buildAgent(...) constructs a fresh agent per user, so each invocation has its scope baked in.
The instructions are the policy. Telling the model when to use synapSearch and synapStore is what produces the explicit-memory behavior.

Advanced patterns

Multi-tenant scoping

All three exports accept the standard scoping triple: userId (required), optional customerId, optional conversationId. customerId is required on B2B Synap instances and ignored on single-tenant ones. See Memory Scopes.

const memory = new SynapMemory({
  sdk,
  userId: "alice",
  customerId: "acme",
});

For multi-tenant services, build agents per request rather than caching them; each agent should have its scope baked in.

Choosing between memory, tools, or both

SynapMemory only: always-on agents where every turn benefits from recall and ingestion.
Tools only: agents that should be selective about memory (e.g. research agents that should only remember important findings).
Both: production agents where automatic recall sets the baseline and tools let the model dig deeper or bookmark explicitly.

Failure semantics

The integration follows the Synap-wide contract:

SynapMemory.recall degrades gracefully: returns [] and logs on failure.
SynapMemory.remember surfaces failures: raises SynapIntegrationError.
synapSearchTool degrades gracefully: returns [] and logs on failure.
synapStoreTool surfaces failures: raises SynapIntegrationError.

This is by design: read failures shouldn’t break a user-facing turn, but silent write failures would let the memory drift away from reality.

Going further

Patterns overview: reusable memory patterns across frameworks.
Cookbook overview: end-to-end worked examples.

Next steps

Vercel AI SDK

Model middleware for the Vercel AI SDK.

Claude Agent SDK

Hooks and MCP server for the Claude Agent SDK.

Context Fetch

The retrieval API behind SynapMemory and synapSearchTool.

Memory Scopes

How userId, customerId, and conversationId interact across reads.

​Overview

​Setup

​Basic integration

​Core concepts

​SynapMemory

​synapSearchTool and synapStoreTool

​Memory vs. tools

​Complete example: agent with memory + tools

​Advanced patterns

​Multi-tenant scoping

​Choosing between memory, tools, or both

​Failure semantics

​Going further

​Next steps

Vercel AI SDK

Claude Agent SDK

Context Fetch

Memory Scopes

Overview

Setup

Basic integration

Core concepts

SynapMemory

synapSearchTool and synapStoreTool

Memory vs. tools

Complete example: agent with memory + tools

Advanced patterns

Multi-tenant scoping

Choosing between memory, tools, or both

Failure semantics

Going further

Next steps