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 cortexdbai

Quick Start

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

const mastra = new Mastra({
  integrations: [
    cortexdbIntegration({
      endpoint: "https://api.cortexdb.ai",
      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: "https://api.cortexdb.ai",
  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",
});
// { 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., "https://api.cortexdb.ai") | | tenantId | "default" | Tenant identifier for multi-tenant isolation |

Complete Example

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

// Configure CortexDB integration
const cortexdb = cortexdbIntegration({
  endpoint: "https://api.cortexdb.ai",
  tenantId: "support-team",
});

// 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}`
  );
}

Under the Hood

The Mastra integration calls the CortexDB REST API:

# store tool
curl -X POST https://api.cortexdb.ai/v1/remember \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"content": "The user prefers dark mode.", "tenant_id": "my-app"}'

# context tool
curl -X POST https://api.cortexdb.ai/v1/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What do we know about this customer?", "tenant_id": "support-team"}'

# search tool
curl -X POST https://api.cortexdb.ai/v1/search \
  -H "Authorization: Bearer your-api-key" \
  -H "x-tenant-id: my-app" \
  -H "Content-Type: application/json" \
  -d '{"query": "user preferences"}'

# forget tool
curl -X POST https://api.cortexdb.ai/v1/forget \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "user preferences", "reason": "GDPR deletion request", "tenant_id": "my-app"}'