Mastra Integration

CortexDB integrates with Mastra as a set of tools that give your agents persistent long-term memory. Mastra is a TypeScript framework for building AI applications — CortexDB adds store, search, forget, and context retrieval capabilities.

Installation

npm install cortexdb-mastra

Quick Start

import { cortexdbIntegration } from "cortexdb-mastra";
import { Mastra } from "@mastra/core";

const mastra = new Mastra({
  integrations: [
    cortexdbIntegration({
      endpoint: "http://localhost:3141",
      tenantId: "my-app",
    }),
  ],
});

Available Tools

The integration provides four tools that agents can call:

store

Persist information into CortexDB's long-term memory.

const integration = cortexdbIntegration({
  endpoint: "http://localhost:3141",
  tenantId: "my-app",
});

const result = await integration.tools.store.handler({
  content: "The user prefers dark mode and weekly email digests.",
});
// { status: "success", id: "mem-abc", message: "Memory stored successfully in CortexDB." }

search

Semantic search over stored memories.

const result = await integration.tools.search.handler({
  query: "user preferences",
  topK: 5,
});
// { status: "success", results: [{ index: 1, content: "...", score: 0.95 }] }

forget

Remove memories for privacy compliance or data hygiene.

const result = await integration.tools.forget.handler({
  query: "user preferences",
  reason: "GDPR deletion request",
});
// { status: "success", deleted: 2, message: "Memories matching 'user preferences' have been forgotten." }

context

Retrieve relevant context for injection into an agent's prompt.

const result = await integration.tools.context.handler({
  query: "What do we know about this customer?",
  maxTokens: 4096,
});
// { status: "success", context: "The customer signed up in January..." }

Configuration

| Parameter | Default | Description | |---|---|---| | endpoint | Required | CortexDB server endpoint (e.g., "http://localhost:3141") | | tenantId | "default" | Tenant identifier for multi-tenant isolation | | namespace | undefined | Optional namespace for organizing memories | | topK | 5 | Default maximum results for search operations |

Complete Example

import { Mastra, Agent } from "@mastra/core";
import { cortexdbIntegration } from "cortexdb-mastra";

// Configure CortexDB integration
const cortexdb = cortexdbIntegration({
  endpoint: "http://localhost:3141",
  tenantId: "support-team",
  namespace: "tickets",
  topK: 10,
});

// Create a Mastra instance with CortexDB
const mastra = new Mastra({
  integrations: [cortexdb],
});

// Define an agent that uses CortexDB memory
const supportAgent = new Agent({
  name: "Support Agent",
  instructions: `You are a customer support agent. Use the cortexdb_store tool
    to remember important customer information. Use cortexdb_search to look up
    past interactions. Use cortexdb_context to get relevant background before
    responding.`,
  tools: [
    cortexdb.tools.store,
    cortexdb.tools.search,
    cortexdb.tools.forget,
    cortexdb.tools.context,
  ],
});

// The agent can now persist and retrieve memories across sessions
async function handleTicket(customerId: string, message: string) {
  // Get prior context about the customer
  const priorContext = await cortexdb.tools.context.handler({
    query: `customer ${customerId} history`,
    maxTokens: 4096,
  });

  // Store the new interaction
  await cortexdb.tools.store.handler({
    content: `Customer ${customerId}: ${message}`,
  });

  // Agent responds with full context awareness
  return supportAgent.generate(
    `Customer ${customerId} says: "${message}"\n\nPrior context:\n${priorContext.context}`
  );
}