Loading components
supermemory component
Add long-term memory to Convex apps via Supermemory: queue text or URLs from mutations, track ingestion status reactively, and search memories from actions.
Installation
npm install @waynesutton/convex-supermemoryAbout supermemory component
The supermemory component integrates Supermemory's AI memory service into a Convex app, letting you persist and retrieve text or URLs as long-term memories scoped to a namespace. Writes happen in mutations so they commit atomically with your transaction, while the actual HTTP call to Supermemory runs in a scheduled background action. The component tracks each document through a processing lifecycle (pending, queued, extracting, embedding, done, failed) in its own tables, with automatic retries on transient failures and reactive status available via useQuery.
Benefits
- Write memory additions from mutations so they commit atomically with your transaction before background ingestion begins
- Track each document through pending, queued, extracting, embedding, done, or failed states with reactive useQuery updates
- Retry failed ingestion and deletions automatically with backoff, with safe deduplication checks before resending
- Search stored memories and fetch user profiles from any Convex action using Supermemory hybrid search
Use cases
how to give a Convex AI agent persistent memory between sessions
The supermemory component lets you call supermemory.add() inside a Convex mutation to persist text or URLs scoped to a user namespace. On subsequent sessions, call supermemory.search() from an action to retrieve relevant memories by semantic query. Each memory is stored in Supermemory and tracked locally so you can list or delete it at any time.
how to store and search user memories in Convex without blocking mutations
supermemory.add() is a Convex mutation that returns immediately and schedules a background action to send the content to Supermemory. This means the write commits with your transaction and the HTTP call happens asynchronously. Status updates move through a component table so your UI can subscribe reactively via useQuery.
how to delete all memories for a user in Convex
Call supermemory.deleteNamespace() from a mutation to delete every document locally and schedule the remote namespace deletion in Supermemory with automatic retries. You can check deletion progress with supermemory.deletionStatus() and retry any failures with retryFailedDeletions().
how to retrieve a user profile summary from Supermemory in Convex
Call supermemory.profile() from a Convex action, passing the user namespace. It returns static, dynamic, and bucketed memories that Supermemory maintains for that namespace. Rate-limiting this call in your app is recommended since it goes directly to the Supermemory API.
Frequently asked questions
What version of Convex is required to use the supermemory component?
The @waynesutton/convex-supermemory component requires convex 1.49 or later. This version introduced support for component env vars, which is how the SUPERMEMORY_API_KEY is scoped to the component without appearing in function arguments or scheduled job records.
How does the supermemory component handle retries when Supermemory is unavailable?
The supermemory component retries ingest on timeouts, 408, 429, and 5xx responses up to 3 times with backoff. Attempts after the first check whether the document already landed before resending, since Supermemory appends to an existing document ID. Remote deletes retry up to 8 times and remain listed in pendingRemoteDeletes until resolved.
Is namespace isolation enforced by the supermemory component?
Every read, search, and delete in the supermemory component is scoped to the namespace you provide. The component trusts the namespace value you pass, so you must derive it from the authenticated user on the server side. Namespaces must be 1 to 128 characters consisting of letters, digits, underscores, or hyphens.
Can I use the supermemory component with convex-test for unit testing?
Yes. The supermemory component exports a test helper from @waynesutton/convex-supermemory/test. You register it with your convexTest instance using supermemoryTest.register(t, 'supermemory') and then stub fetch to simulate Supermemory API responses. The repo includes a working example in src/testing/fakeSupermemory.ts.
What are the content and query size limits for the supermemory component?
The supermemory component caps document content at 50,000 characters per document and limits list() results to 100 documents per namespace. Search queries are also length-limited. The exported constants MAX_CONTENT_LENGTH, MAX_QUERY_LENGTH, and NAMESPACE_PATTERN can be used in your own validators to enforce these limits before calling the component.
Links
Components
Open-source building blocks for your Convex app
Browse components in this category.