Add long-term, semantically searchable memory to Convex apps via Supermemory REST integration, with reactive local state mirrored into Convex tables.
npm install convex-supermemoryconvex-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.
convex-supermemory lets you call addMemory() from any Convex action to store a fact keyed to a containerTag, typically one per user or agent. Later calls to search() run hybrid semantic search against that same containerTag and return ranked results with scores and matching chunks. No vector database setup is required.
The search() method in convex-supermemory proxies Supermemory's hybrid RAG plus memory search live against a specified containerTag. You pass a natural language query and an optional limit, and receive ranked results with document summaries, chunk-level content, and relevance scores. Results are not cached locally since they are a ranked view rather than durable records.
addDocument() sends content through Supermemory's extraction and chunking pipeline and mirrors the document record into a Convex table. Because processing is asynchronous, you call refreshDocument() to poll status through stages from queued to done. deleteDocument() removes the document from both Supermemory and the local Convex table.
convex-supermemory mirrors every memory and document into Convex tables, so listMemories() and listDocuments() are standard Convex queries that return results newest-first without any additional API call. This makes it straightforward to drive reactive UI from memory state using useQuery on the client.
addMemory() is for short, discrete facts that are immediately available for search with no processing delay. addDocument() is for longer content that needs chunking and embedding; processing is asynchronous and moves through stages (queued, extracting, chunking, embedding, indexing, done). Use addMemory() for conversational facts and addDocument() for transcripts, documentation pages, or other multi-paragraph content.
No. The search() method in convex-supermemory always calls the Supermemory API live and does not mirror results into Convex tables. Memories and documents are mirrored locally, but search results are a ranked view over that data and are intentionally not persisted.
Every write, search, and profile operation in convex-supermemory is scoped to a containerTag string you provide. Container tags are exact-match scopes, not fuzzy. A common convention is one containerTag per user ID or one per agent workspace. Search only looks within the containerTag you pass, so tags must be consistent between writes and reads.
forgetMemory() asks Supermemory to remove the memory scoped by both containerTag and memoryId, then updates the local Convex record's forgotten field to match the response. deleteDocument() removes the document from Supermemory and from the local Convex table, but will throw if Supermemory returns a 409 because the document is still processing. You should wait until refreshDocument() reports a terminal status before deleting.
convex-supermemory requires Convex v1.33.1 or later and Node.js 18 or later. You also need a Supermemory API key starting with sm_, which you set as the SUPERMEMORY_API_KEY environment variable in your Convex deployment.