---
name: bijection-convex-supermemory
description: "Evaluate and integrate the Convex Supermemory component with Bijection."
---

# Convex Supermemory

Give your Convex app long-term, searchable memory with Supermemory. Reactive local state, backed by direct REST calls.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-supermemory
- Source: https://github.com/sholajegede/convex-supermemory
- npm: https://www.npmjs.com/package/convex-supermemory
- Directory: https://bijection.com/components/convex-supermemory

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-supermemory. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex Supermemory. Follow the installation and configuration steps exactly.

# Convex Supermemory

## Instructions

convex-supermemory integrates Supermemory's memory API into Convex applications, providing semantic search over stored facts and documents without running a separate vector database. It mirrors everything written to Supermemory into local Convex tables, so memory state is reactively queryable via standard Convex queries. The component handles both short discrete facts via `addMemory()` and larger content via `addDocument()`, which goes through Supermemory's async chunking and embedding pipeline.

### Installation

```bash
npm install convex-supermemory
```

Current npm version: `convex-supermemory@0.0.5`

## Use cases

- Adding per-user long-term memory to an AI agent so it recalls preferences, history, or facts across separate sessions
- Scoping memory to individual users or workspaces using `containerTag` and running semantic search against only that container
- Ingesting large documents (transcripts, notes, documentation) and querying them later with hybrid RAG search without managing embeddings
- Building a reactive UI that displays a user's stored memories and documents using Convex queries without extra API calls
- Implementing a forgetting mechanism to remove specific memories or documents from both Supermemory and local Convex state in sync

## How it works

Setup requires three steps: adding `convexSupermemory` to `convex.config.ts` via `app.use()`, setting `SUPERMEMORY_API_KEY` as a Convex environment variable, and instantiating `new Supermemory(components.convexSupermemory, { apiKey })` in a Convex module. The instance is then imported into any Convex action that needs to read or write memory.

The component exposes two write paths. `addMemory()` stores a single fact immediately with no processing delay and accepts options like `isStatic`, `forgetAfter`, and arbitrary `metadata`. `addDocument()` sends larger content through Supermemory's extraction and chunking pipeline asynchronously; status progresses through `queued`, `extracting`, `chunking`, `embedding`, `indexing`, and `done`. Callers must poll status manually using `refreshDocument()`, for example from a Convex scheduled function or cron.

Every memory and document written is mirrored into Convex tables (`memories` and `documents`), making them available through reactive query methods: `listMemories()`, `listDocuments()`, `getMemory()`, `getDocument()`, and `getStats()`. Semantic search via `search()` calls Supermemory live and is not cached locally, since results are a ranked view over the underlying data rather than durable records.

Deletion is handled by `forgetMemory()` and `deleteDocument()`, both of which update local Convex state to match what Supermemory removes. `deleteDocument()` throws on a `409` if the document is still processing, so callers should wait for a terminal status before attempting deletion.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex Supermemory is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-supermemory)
- [GitHub repository](https://github.com/sholajegede/convex-supermemory)
- [Live demo](https://convex-supermemory.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/convex-supermemory)
- [Convex documentation](https://docs.convex.dev)