supermemory/apps/docs/integrations/convex.mdx

---
title: "Convex"
sidebarTitle: "Convex"
description: "Add semantic memory and RAG to your Convex apps with reactive queries"
icon: "database"
---

Supermemory integrates with [Convex](https://convex.dev) as a native component, giving you AI-powered semantic memory with reactive real-time queries and full dashboard visibility.

<Card title="@supermemory/convex-component on npm" icon="npm" href="https://www.npmjs.com/package/@supermemory/convex-component">
    Check out the NPM page for more details
</Card>

## Installation

```bash
npm install @supermemory/tools
```

## Quick Start

### 1. Setup Component

Create or update `convex/convex.config.ts`:

```typescript
import { defineApp } from "convex/server";
import supermemory from "@supermemory/convex-component/convex.config";

const app = defineApp();
app.use(supermemory, { name: "supermemory" });

export default app;
```

### 2. Set API Key

Get your API key from [console.supermemory.ai](https://console.supermemory.ai) and set it as a Convex environment variable:

```bash
npx convex env set SUPERMEMORY_API_KEY your-api-key
```

### 3. Use in Your App

<Tabs>
  <Tab title="React Hooks">
    ```tsx
    import { useAddMemory, useSupermemorySearch } from "@supermemory/convex-component/react";

    function ChatApp() {
      const addMemory = useAddMemory();
      const { results, isLoading, search } = useSupermemorySearch({
        q: "user preferences",
        containerTag: "user_123",
        searchMode: "hybrid"
      });

      const handleSendMessage = async (message: string) => {
        await addMemory({
          content: message,
          containerTag: "user_123"
        });

        await search({ q: message, containerTag: "user_123" });
      };

      return (
        <div>
          {isLoading && <div>Searching memories...</div>}
          {results?.results.map(r => (
            <div key={r.id}>{r.memory || r.chunk}</div>
          ))}
        </div>
      );
    }
    ```
  </Tab>
  <Tab title="TypeScript Client">
    ```typescript
    import { ConvexHttpClient } from "convex/browser";
    import { createSupermemoryClient } from "@supermemory/convex-component";

    const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
    const supermemory = createSupermemoryClient(convex);

    // Add a memory
    await supermemory.add({
      content: "User loves TypeScript and prefers tabs over spaces",
      containerTag: "user_123",
      metadata: { category: "preferences" }
    });

    // Search memories
    const results = await supermemory.search({
      q: "coding preferences",
      containerTag: "user_123",
      searchMode: "hybrid",
      limit: 5
    });

    // Get user profile
    const profile = await supermemory.profile({
      containerTag: "user_123"
    });

    console.log("Static facts:", profile.profile.static);
    console.log("Dynamic context:", profile.profile.dynamic);
    ```
  </Tab>
</Tabs>

## React Hooks

### `useAddMemory()`

Hook to add memories to Supermemory through a Convex action.

```tsx
const addMemory = useAddMemory();

await addMemory({
  content: "Meeting notes from Q1 planning",
  containerTag: "user_123",
  customId: "meeting_2024_q1",
  metadata: { type: "meeting" }
});
```

### `useSupermemorySearch(args)`

Hook for reactive semantic search with loading and error states.

```tsx
const { results, isLoading, error, search } = useSupermemorySearch({
  q: "project updates",
  containerTag: "user_123",
  searchMode: "hybrid",
  limit: 10
});

// Trigger search manually
await search({ q: "new query", containerTag: "user_123" });
```

### `useSupermemoryProfile(args)`

Hook to get user profile with static and dynamic facts.

```tsx
const { profile, isLoading, refresh } = useSupermemoryProfile({
  containerTag: "user_123",
  q: "recent preferences"
});

// Refresh profile
await refresh();
```

### `useMemories(args)`

Hook to list memories by container tag and source.

```tsx
const memories = useMemories({
  containerTag: "user_123",
  source: "manual", // "chat" | "document" | "manual"
  limit: 50
});
```

## AI SDK Integration

Use Supermemory with Vercel AI SDK through the Convex backend.

### Middleware (Automatic Context Injection)

```typescript
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { withSupermemory } from "@supermemory/convex-component/ai-sdk";
import { ConvexHttpClient } from "convex/browser";

const convex = new ConvexHttpClient(process.env.CONVEX_URL!);

const modelWithMemory = withSupermemory(
  openai("gpt-4"),
  convex,
  "user_123",
  { mode: "full", addMemory: "always", verbose: true }
);

const result = await generateText({
  model: modelWithMemory,
  messages: [{ role: "user", content: "What do you know about me?" }]
});
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `mode` | string | `"profile"` | `"profile"`, `"query"`, or `"full"` |
| `addMemory` | string | `"never"` | `"never"`, `"always"`, or `"tool"` |
| `promptTemplate` | function | — | Custom memory formatting function |
| `verbose` | boolean | `false` | Enable debug logging |