← All packages

AI · Convex component

convex-supermemory

Give your Convex app long-term, semantically searchable memory with Supermemory. Reactive local memory and document state, direct REST integration.

npm GitHub Convex directory Ask about it
npm install convex-supermemory
18downloads last week
685downloads last 12 months
v0.0.5latest, Sep 18, 2026
5releases since Sep 13, 2026

Downloads

Download history

Loading download history…

Build this

Build with convex-supermemory

The install and setup steps from the package documentation.

  1. 1

    Install

    bash
    npm install convex-supermemory

    Requirements: Convex v1.33.1 or later, Node.js 18+, a API key

  2. 2

    Quick Start

    Three steps to add memory to your Convex app.

    1. Add the component

    In convex/convex.config.ts:

    ts
    import { defineApp } from "convex/server";
import convexSupermemory from "convex-supermemory/convex.config";

const app = defineApp();
app.use(convexSupermemory);

export default app;

    2. Set environment variables

    bash
    npx convex env set SUPERMEMORY_API_KEY sm_xxxxxxxxxxxx

    3. Initialize the client

    In convex/memory.ts:

    ts
    import { components } from "./_generated/api";
import { Supermemory } from "convex-supermemory";

export const supermemory = new Supermemory(components.convexSupermemory, {
  apiKey: process.env.SUPERMEMORY_API_KEY!,
});

    Import supermemory from this file in any Convex action that needs to read or write memory.

  3. 3

    Usage

    Remember a fact

    ts
    export const remember = action({
  args: { userId: v.string(), fact: v.string() },
  handler: async (ctx, args) => {
    return await supermemory.addMemory(ctx, {
      containerTag: args.userId,
      content: args.fact,
      isStatic: true, // long-term fact, not a fading conversational detail
    });
  },
});
// Returns: { memoryId }

    Recall with semantic search

    ts
    export const recall = action({
  args: { userId: v.string(), query: v.string() },
  handler: async (ctx, args) => {
    return await supermemory.search({
      containerTag: args.userId,
      query: args.query,
      limit: 5,
    });
  },
});
// Returns: { results: [{ documentId, score, summary, chunks, ... }], total }

    Forget a memory

    containerTag is required here too — Supermemory scopes the delete by it, not just by memoryId.

    ts
    export const forget = action({
  args: { userId: v.string(), memoryId: v.string() },
  handler: async (ctx, args) => {
    return await supermemory.forgetMemory(ctx, {
      containerTag: args.userId,
      memoryId: args.memoryId,
    });
  },
});
// Returns: { forgotten: boolean }

    List a user's memories reactively

    ts
    export const getMemories = query({
  args: { userId: v.string() },
  handler: async (ctx, args) => {
    return await supermemory.listMemories(ctx, { containerTag: args.userId });
  },
});