supermemory

Supermemory is the memory and context layer for AI that solves the fundamental problem of AI forgetting between conversations. It automatically extracts facts from interactions, resolves contradictions, tracks temporal changes, and delivers the right context at the right time — combining full RAG, connectors, and file processing into a single unified system.

Built as a TypeScript monorepo deployed on Cloudflare Workers and Next.js, Supermemory offers three modes of use: a consumer app with a built-in AI agent called Nova, a developer API with SDKs for TypeScript and Python, and a self-hosted local binary that runs fully offline with Ollama. It integrates with Vercel AI SDK, LangChain, LangGraph, OpenAI Agents SDK, Mastra, and Agno via drop-in wrappers.

The project is ranked #1 on LongMemEval, LoCoMo, and ConvoMem — the three major AI memory benchmarks — and supports real-time data sync from Google Drive, Gmail, Notion, OneDrive, and GitHub. Plugins for Claude Code, Cursor, Windsurf, VS Code, and OpenCode enable persistent memory in AI coding tools with a single install command.

What You Get

• Memory Engine - Extracts structured facts from conversations, resolves contradictions automatically, tracks temporal changes, and forgets expired information — no manual curation needed.
• User Profiles - Auto-maintains per-user context with static (long-term preferences) and dynamic (recent activity) facts, returned in a single ~50ms API call ready to inject into system prompts.
• Hybrid Search - Combines RAG document retrieval and personalized user memory in a single query, returning both external knowledge base content and individual user context ranked by relevance.
• Connectors with Real-Time Sync - Auto-syncs from Google Drive, Gmail, Notion, OneDrive, and GitHub via real-time webhooks — documents are automatically chunked, indexed, and kept current.
• Multi-modal File Processing - Processes PDFs, images (OCR), videos (transcription), and code (AST-aware chunking) by upload, making all content types searchable without configuration.
• MCP Server and AI Tool Plugins - Ships an open-source MCP server and plugins for Claude Code, Cursor, Windsurf, VS Code, and OpenCode that add persistent memory to any compatible AI assistant with one install command.
• Local Binary for Full Offline Use - A single supermemory-server binary runs the complete Memory API locally at localhost:6767, using embedded local embeddings and supporting any OpenAI-compatible model including Ollama.
• Framework SDK Wrappers - Drop-in middleware for Vercel AI SDK, LangChain, LangGraph, OpenAI Agents SDK, Mastra, Agno, and n8n that transparently adds memory to existing AI workflows without code changes.

Common Use Cases

• Building personalized AI assistants - A developer wraps their customer support bot with Supermemory’s SDK to give each user persistent memory of past issues, preferences, and project history across every session.
• Running a self-hosted AI knowledge base - A team syncs their Notion workspace and Google Drive into Supermemory’s local binary, enabling RAG with user-specific context for internal tools without sending data to external servers.
• Giving AI coding assistants persistent memory - A software engineer installs the Claude Code or Cursor plugin to have their AI assistant remember coding style, preferred libraries, past debugging patterns, and project-specific context across sessions.
• Scaling AI agents with per-user profiles - A startup uses Supermemory’s profile API with containerTag scoping to maintain individual user context for 10,000+ users, injecting personalized summaries into system prompts automatically.
• Integrating memory into existing AI pipelines - An AI team adds the Vercel AI SDK wrapper to their existing LLM calls to transparently persist and retrieve conversation context without restructuring their codebase.
• Creating a personal second brain - A knowledge worker uses the Supermemory web app to save URLs, documents, and notes from the browser extension, then chats with their accumulated memories through the Nova agent.

Under The Hood

Architecture Supermemory is organized as a Turbo-powered monorepo with cleanly separated apps (web consumer app, MCP server, browser extension, Raycast extension, docs) and shared packages (memory-graph visualization, AI framework tools, Python SDKs, validation). The MCP server uses Cloudflare Durable Objects via the McpAgent base class, giving each user session a stateful, isolated execution context with TTL-based caching of container tags. The web consumer app is a Next.js application deployed on Cloudflare via open-next, while the API backend uses Hono with Zod-OpenAPI for type-safe route definitions and auto-generated documentation. The memory graph visualization is an independent React package using D3 force simulation with a custom canvas renderer, spatial indexing for hit testing, and a version chain index — all fully decoupled from the API layer. Data flows from ingestion through a single unified memory ontology that handles documents, memory entries, and their relationships consistently across all input types.

Tech Stack The stack is built on TypeScript throughout, using Bun as the package manager and runtime baseline (Node.js 20+ also supported), with Turbo orchestrating incremental builds across the monorepo. The web app is Next.js 15 with React 19, deployed on Cloudflare Pages via open-next with Wrangler for configuration and deployment. The API layer uses Hono with hono-openapi for automatic OpenAPI spec generation and Scalar for API reference UI. Drizzle ORM handles database access with PostgreSQL, and Drizzle-Zod bridges schema definitions to runtime validation. AI integration spans multiple providers — @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google, and @anthropic-ai/sdk — enabling provider-agnostic memory operations. Better-Auth handles authentication, Biome provides linting and formatting across all packages, Sentry handles observability, and PostHog powers analytics and feature tracking.

Code Quality The codebase has comprehensive test coverage with Vitest powering unit tests across packages — the tools package alone has dedicated test files for each framework integration (Mastra, Vercel AI SDK, Claude memory tool, OpenAI tools) with both unit and integration test variants, plus e2e tests for the MCP server covering auth flows, OAuth, memory operations, and graph data. The memory-graph package has its own Vitest setup with happy-dom. Error handling uses neverthrow for typed Result patterns alongside conventional try-catch with structured error messages — the MCP server in particular wraps every tool handler in explicit error boundaries that return structured isError: true responses rather than throwing. TypeScript is configured in strict mode across all packages with @total-typescript/tsconfig as the base. Biome enforces consistent formatting and linting monorepo-wide. The claude-memory tool demonstrates thorough path security validation and edge case handling with view_range support and multi-line content operations.

What Makes It Unique Supermemory is the only AI memory system that has been rigorously benchmarked and ranks #1 on LongMemEval, LoCoMo, and ConvoMem simultaneously — the three standard evaluation benchmarks for long-term conversational memory. The dual-profile architecture (stable facts + recent dynamic activity in a single ~50ms call) eliminates the need to guess what to retrieve: the system proactively surfaces what an AI assistant needs to know about a user without requiring a search query. The Claude Memory Tool in the tools package implements a filesystem-like abstraction layer over memory storage with view, create, str_replace, insert, delete, and rename commands, enabling Claude’s built-in memory tool to transparently use Supermemory as its backend. The memory-graph package ships a purpose-built canvas renderer with D3 force simulation, spatial indexing, and version chain tracking — not a generic graph library, but a domain-specific visualization engine for navigating memory relationships interactively.

Self-Hosting

Supermemory is released under the MIT License, which is one of the most permissive open-source licenses available. You can use it commercially, modify the source, distribute it, and incorporate it into proprietary products without any copyleft obligations. The only requirement is retaining the copyright notice. There are no restrictions on the number of users, API calls, or deployment environments — self-hosted installations are fully unrestricted.

Running Supermemory yourself requires choosing your deployment path. The local binary (supermemory-server) is the easiest entry point: a single command installs and starts a full-featured server at localhost:6767 with embedded embeddings and an interactive first-boot wizard for model selection. For production self-hosting, the full monorepo deploys to Cloudflare Workers and Pages using Wrangler, with PostgreSQL as the database backend and Drizzle Kit handling migrations. You are responsible for provisioning the database, managing Cloudflare deployments, handling uptime and scaling, keeping dependencies current, and configuring LLM provider API keys. The codebase uses Turbo for monorepo orchestration, so build dependencies are well-defined, but operational management of a multi-service Cloudflare deployment requires familiarity with Workers, Pages, KV, and Durable Objects.

The hosted platform at supermemory.ai provides a fully managed alternative with a console dashboard, OAuth-based MCP server authentication, and zero infrastructure management. Compared to self-hosting, the managed tier handles uptime, database backups, automatic updates, and support through Discord. The MCP server on the managed platform uses Cloudflare Durable Objects for stateful per-session memory with built-in TTL caching — replicating this on a self-hosted deployment requires manual Cloudflare account setup and Durable Object configuration. Teams evaluating self-hosting should weigh the operational complexity of a multi-app Cloudflare monorepo against the simplicity of the hosted API, especially for production workloads with reliability requirements.