Supermemory Deep Research (Codebase-Level)
Repository: github.com/supermemoryai/supermemory — a memory and context engine for AI. 29,246 stars, 2,556 forks, created 2024-02-27, $2.6M seed round (Oct 2025). Used by Cursor, Cognition, and Klarna. Reviewed at main @ 4d8a4ebf (2026-09-02).
One-line verdict: What is open-sourced is the *periphery* (MCP server, SDKs, consumer app, docs); what is closed is the *engine* (memory extraction model + temporal vector-graph database). Engineering quality is very high — the MCP server in particular is unusually rigorous — but the README's "#1 on every major AI memory benchmark" is a vendor self-assessment, and the "local version is open source" claim doesn't match reality: the local build ships only precompiled binaries with no engine source in any tag.
Key points
- The engine is not in the repo. The "custom learning model + temporal vector-graph engine" runs on a closed-source Cloudflare Worker backend. The repo contains only the MCP server, SDKs, the consumer web app, and docs.
CLAUDE.mdis stale — it describes a backend that isn't in this repository. - Local version = closed-source binary.
supermemory localdownloads precompiled darwin/linux binaries from GitHub Releases (server-v0.0.8, no Windows build). Allserver-v0.0.xtags are structurally identical tomainwith no engine source. Docs claim "it's open source," which is inaccurate. - #1 rankings are all self-reported. The 95% Recall@15 figure comes from the vendor's own research page. Mastra (94.87%), OMEGA (95.4%), Hindsight/Vectorize (94.6%), and Exabase M-1 all simultaneously self-report ~95% SOTA. No neutral third-party leaderboard exists (LongMemEval's official academic site doesn't host commercial rankings). The MIT-licensed MemoryBench framework is at least reproducible.
- Graph edge types:
updates(new fact replaces old,isLatestflag, audit history),extends(adds detail, both valid),derives(inferred facts the user never stated). - Memory types: Facts (persist until updated), Preferences (reinforced by repetition), Episodes (decay unless significant).
- Forgetting: temporal expiry ("exam is tomorrow" auto-invalidates) + contradiction resolution + noise filtering; explicit soft-delete and
forget-matchingsemantic batch forgetting with dryRun. - Inference review: derived facts are flagged
isInferenceand down-weighted in retrieval until confirmed; the review queue sorts byparentCount. - Retrieval:
POST /v4/searchwithsearchMode: memories|documents|hybrid;rerank(cross-encoder, ~+100ms),rewriteQuery(~+400ms),include.relatedMemoriesexposes graph edges; example timing 92ms, platform p50 < 300ms. - Scale claims: 1M documents / 10M memories per container; facts average ~10 tokens, so 50 facts ≈ 500 tokens of context.
- Tier A (model-visible):
search_memory,listDocuments,getDocument,listMemories,listSpaces,whoAmI,add_memory(save/forget combined; forget falls back to 0.85-threshold similarity deletion on exact-match 404). - Tier B (app launchers ×4):
select-space,memory-graph,guided-save,upload-file— single-file HTML widgets with behavioral guardrails in descriptions. - Tier C (app-only ×4): hidden from the model via
_meta.ui.visibility: ["app"]. - MCP engineering discipline: zod at every boundary, rollback DO keeping one version, correct 503/401 error taxonomy
- Diff-based billing + idempotent
customIdingestion - SSRF protection down to CGNAT ranges, IPv6 literals, 2MB bounded reads
- "Open source" marketing doesn't match facts: closed engine, binary-only local, no engine source in tags, self-reported #1 rankings
- Stale
CLAUDE.mddescribing a nonexistent backend - Garbled doc passages (likely a batch-edit accident); v3/v4 dual APIs coexist
- Local and cloud "proprietary model" are not the same thing, papered over with a local-vs-enterprise comparison page
- Code: supermemory repo (main @ 4d8a4ebf), GitHub API release assets for server-v0.0.8 (captured 2026-09-07)
- TechCrunch: $2.6M seed
- Supermemory funding announcement
- Supermemory LongMemEval self-report · LongMemEval official (academic, no commercial leaderboard)
- Competitor self-reports: Mastra 94.87% · OMEGA 95.4% · Hindsight 94.6% · Exabase M-1
Repository layout
| Path | Size | What it is |
|---|---|---|
| apps/docs | 71MB | Mintlify docs (the only public source on engine architecture) |
| apps/web | ~73k lines TS | Consumer app app.supermemory.ai (Next.js 16 + React 19) |
| apps/mcp | ~7.2k lines TS | MCP server (Hono + Cloudflare Workers) |
| packages/tools | 508KB | @supermemory/tools, 7 tools × multi-framework integrations |
| packages/memory-graph | ~9.6k lines | Canvas 2D force-directed memory graph visualization |
| Python packages + extensions | ~7MB | OpenAI / Agent Framework / Pipecat / Cartesia integrations, Raycast and browser extensions |
Memory engine mechanics
Each document yields three artifacts: Chunks (raw grounding for RAG), Memories (atomic facts on a graph), and Profile (static + dynamic user summaries, always in context).
Ingestion is two-phase: queued → extracting (OCR/transcription) → chunking → embedding/indexing (this = done), then a second phase called "dreaming" — memory extraction, grouping, and graph building that continues after done. In dynamic mode related documents are grouped and distilled together.
API surface (v3 ingest + v4 memory, coexisting)
Ingestion: POST /v3/documents (millisecond queued response), /v3/documents/file (≤50MB), POST /v4/conversations (turn-aware; duplicate submissions with the same customId are diff-billed — repeated syncs are free). Memory v4 supports direct writes (1–100 per call), versioned PATCH, soft delete, and semantic forget-matching. Scoping via containerTag hard isolation plus container-level scoped keys (default 500 req/60s). Connectors (Drive, Gmail, Notion, OneDrive, GitHub, Granola, Web Crawler) are cloud-only.
MCP server (apps/mcp) — an engineering benchmark
Streamable HTTP, stateless (new McpServer per request). Dual auth: sm_ API keys (validation cached per-isolate, 60s/1000 entries) or OAuth JWT (JWKS). When the upstream auth backend is down it returns 503 + Retry-After instead of 401 — preventing clients from discarding valid credentials.
15 tools in three tiers (the model only sees 7):
Highlights: two-phase upload (Durable Object stores only the SHA-256 of the upload token, 2-min alarm TTL, atomic consumption), PostHog instrumentation via zero-intrusion decorators, discriminated-union server↔widget contracts (adding a view is a compile error).
SDKs and integrations
Seven tools defined once, reused across AI SDK / OpenAI / Mastra / VoltAgent / Python. withSupermemory (Vercel AI SDK) proxies doGenerate/doStream, fetches the profile via POST /v4/profile (5s timeout, LRU-100 cache), deduplicates (static > dynamic > retrieved), injects an XML context block into the system prompt, and stores the exchange back — silently skipping on failure. A Claude Memory Tool adapter implements all six commands. Python packages cover OpenAI (sync/async monkey-patch), Pipecat (voice), and Cartesia.
Consumer web app
The Nova agent is closed-source (UI shell only; chat goes through api.supermemory.ai/chat). Tool surface inferred from stream widgets: searchMemories, recallContext, discoverSpaces, updateMemory, forgetMemory, forgetDocument + dynamic web search. Agent memories from Claude Code / Codex / OpenCode / Cursor are folded into per-project "Agents" spaces.
Business model
Free $0 → Pro $19 → Scale $399 → Enterprise. Metering: text tokens $5/1M, rich $10/1M, superrag mode at 50% (skips memory extraction, RAG only), search $5/1M, operations $0.1 each. SOC 2 Type II, GDPR, HIPAA BAA (Scale+); customer content is never used for training on any plan. Migration guides exist for mem0 and zep.
Pros and cons
Good:
Questionable:
Lessons worth borrowing
1. Three-tier MCP tool visibility (model-visible / app-launcher / app-hidden) is a ready-made pattern against tool-count attention pollution.
2. Profile as a retrieval bypass: facts a query can't hit must come from an always-on summary — every memory system needs this asymmetric channel.
3. Inference memories down-weighted by default + human review (sorted by parentCount) is a pragmatic guard against memory hallucination.
4. Diff billing + idempotent ingestion generalizes to any connector product.
5. Silent degradation on memory-fetch failure (only-add, never-block) is a safe pattern for LLM sidecar dependencies.
6. The temporal graph (updates/extends/derives + isLatest + forgetAfter) is more expressive than flat fact lists, but complexity shifts to temporal filtering on the search side.