Supermemory Deep Research: Codebase-Level Analysis (2026-09-07)

> github.com/supermemoryai/supermemory — a memory and context engine for AI. What's actually open source, what's closed, and how much water the benchmarks carry.

Stats: ⭐ 29,246 stars · 🍴 2,556 forks · Created 2024-02-27 · $2.6M seed (2025-10) · Used by Cursor / Cognition / Klarna · Reviewed at main @ 4d8a4ebf (2026-09-02)

Verdict

What's open-sourced is the periphery (MCP server, SDKs, consumer app, docs); what's closed is the engine (memory extraction model + temporal vector-graph database). Engineering quality is very high—especially the MCP server—but the README's "#1 on every major AI memory benchmark" is a vendor self-assessment, and the claim that the local version is open source is inaccurate: the local version only ships precompiled binaries, with no engine source in any git tag.

Three Key Findings

1. The engine is not in the repo. The "custom learning model + temporal vector-graph engine" runs on closed-source Cloudflare Workers; the repo only contains MCP, SDKs, the consumer web app, and docs. 2. Local version = closed-source binary. supermemory local downloads darwin/linux precompiled binaries from GitHub Releases (no Windows build); all server-v0.0.x tags are structurally identical to main, with no engine source. 3. All #1 claims are self-reported. The 95% Recall@15 figure comes from Supermemory's own research page; Mastra/OMEGA/Hindsight simultaneously self-report ~95% SOTA. No neutral leaderboard exists, though the MemoryBench framework is open source and reproducible.

1. Actual Repository Layout

Turbo + Bun monorepo, but CLAUDE.md is outdated—it describes an "API Application (Primary Backend)" (Cloudflare Worker, Hyperdrive, IngestContentWorkflow, 4-hour cron) that isn't in this repo; that's the closed-source backend. Actual contents:

| Path | Size | What it is | |---|---|---| | apps/docs | 71MB | Mintlify docs site (sole 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 (npm package) | | Python packages + extensions + playground | ~7MB | OpenAI / Agent Framework / Pipecat / Cartesia integrations, Raycast and browser extensions |

2. Memory Engine Mechanism (from docs + API shape)

Each document yields three artifacts: Chunks (raw grounding for RAG), Memories (atomic facts on the graph), Profile (static + dynamic user summary, always in context).

Two-phase ingestion: index first, then "dreaming"

queued → extracting (OCR/transcription/crawl) → chunking (type-aware) → embedding → indexing (= done) → dreaming (memory extraction, grouping/synthesis, graph building)

• done only means chunk indexing is complete; memory extraction is the second "dreaming" phase—in dynamic mode related documents are grouped then synthesized together ("memories come from coherent units, not isolated one-at-a-time writes"), and memories keep forming after done.
• Three relationship types: updates (new fact supersedes old, isLatest flag, history retained for audit), extends (adds detail, both valid), derives (cross-memory inference of facts the user never stated).
• Three memory types: Facts (persist until updated), Preferences (reinforced by repetition), Episodes (decay unless salient).
• Forgetting: time expiry ("exam tomorrow" auto-invalidates) + contradiction adjudication + noise filtering; explicit soft-delete and forget-matching semantic batch forget (with dryRun).
• Inferred memories get human review: derived facts flagged isInference, retrieval down-weighted until confirmed; review queue sorted by parentCount.
• Retrieval: POST /v4/search, searchMode: memories|documents|hybrid; rerank (cross-encoder, +~100ms), rewriteQuery (+~400ms), include.relatedMemories exposes graph edges; sample timing 92ms, platform p50 < 300ms.
• Scale claims: 1M documents / 10M memories per container; ~10 tokens per fact, 50 facts ≈ 500 context tokens.

3. API Surface (v3 ingestion + v4 memory, coexisting)

Ingestion via POST /v3/documents (millisecond ack returning queued), /v3/documents/file (≤50MB), POST /v4/conversations (turn-aware; duplicate customId submissions billed as max(0, total - already-seen) diff billing—repeated syncs are free, a clever and honest design).

Memory v4: direct writes (1-100 per call), versioned PATCH (old version gets isLatest=false), soft-delete forget, semantic batch forget-matching. Scoping via hard containerTag isolation + container-level scoped keys (default 500 req/60s). Connectors (Drive / Gmail / Notion / OneDrive / GitHub / Granola / Web Crawler) are cloud-only.

4. Supermemory local: Precompiled Binary, "Open Source" in Doubt

curl -fsSL https://supermemory.ai/install | bash installs a precompiled darwin/linux binary (no Windows) from GitHub Releases (server-v0.0.8), port 6767, all data in ./.supermemory/, zero telemetry. Built-in local embeddings Xenova/bge-base-en-v1.5 (768d, ONNX via WASM, swappable to OpenAI / Gemini / Ollama; dimension mismatch refuses to start); 1GB default memory governor, ingestion concurrency 2.

> ⚠ Discrepancy: Docs say "it's open source (git.new/memory)" but neither main nor any server-v0.0.x tag contains engine source. Local extraction uses your own models (OpenAI defaults to gpt-5.1, Anthropic pinned to claude-haiku-4-5) while cloud uses a "proprietary long-horizon model"—the local version is a freemium funnel, not an open-source engine. v0.0.5 had an embedding read/write inconsistency silently breaking exact Japanese search; fixed in v0.0.7.

5. MCP Server (apps/mcp, Engineering Benchmark)

Streamable HTTP, stateless (new McpServer per request). Dual auth: sm_ API key (validation cached per-isolate 60s/1000 entries) or OAuth JWT (JWKS verification). When the auth backend is down, returns 503 + Retry-After instead of 401—preventing clients from discarding valid credentials, a rare detail.

15 tools in three tiers (model sees only the first 7)

• 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 after exact-match 404)
• Tier B (app launchers ×4): select-space, memory-graph, guided-save, upload-file—launch embedded single-file HTML widgets, with behavior clamps in descriptions
• Tier C (app-only ×4): set-active-tag, save-memory, prepare-file-upload, fetch-graph-data—hidden from the model via _meta.ui.visibility:["app"]

Highlights: two-phase upload (Durable Object stores only the SHA-256 of the uploadToken, 2-min alarm TTL, atomic consumption, multipart passthrough—widget never sees the real token); zero-intrusion PostHog instrumentation via decorators around registerTool; server↔widget contract as discriminated unions (adding a view is a compile error).

6. SDK / Integration Layer

7 tools defined once, reused across five targets (AI SDK / OpenAI / Mastra / VoltAgent / Python).

• withSupermemory (Vercel AI SDK): Proxy intercepts doGenerate/doStream → takes last user message → POST /v4/profile (5s timeout, LRU 100 cache) → dedupe (normalized, static > dynamic > retrieval, order preserved) → injects as <supermemory context="user-memories" readonly> XML block into system prompt → saves back to /v4/conversations; memory fetch failures silently skip by default.
• Claude Memory Tool adapter implements all six commands (view / create / str_replace / insert / delete / rename).
• Python packages: openai-sdk most complete (sync/async monkey-patch + 7 tools); pipecat for voice; cartesia intercepts UserTurnEnded.

7. Consumer Web (apps/web, ~73k lines TS)

Nova agent is closed-source: chat goes through api.supermemory.ai/chat; the repo has only the UI shell. Model menu: grok-4.5 / gpt-5.6-terra / claude-sonnet-5 / gemini-3.1-pro-preview. Tool surface inferred from stream widgets: searchMemories / recallContext / discoverSpaces / updateMemory / forgetMemory / forgetDocument + dynamic web search.

Agent-space merging: regex taxonomy folds memories written by Claude Code / Codex / OpenCode / Cursor into one "Agents" space per project—coding-agent memories are first-class citizens. Next.js 16 deployed to Workers via @opennextjs/cloudflare.

8. Business Model

Free $0 (with $5 monthly credits) → Pro $19 → Scale $399 → Enterprise. Metering: text tokens $5/1M, rich $10/1M, superrag mode 50% off (skips memory extraction, RAG only), search $5/1M queries, operations $0.1 each. SOC 2 Type II, GDPR, HIPAA BAA (Scale+); "customer content never used for training—on all plans." Direct from-mem0 / from-zep migration guides.

9. Benchmark Claims Verified (Important)

README claims #1 on three benchmarks (LongMemEval / LoCoMo / ConvoMem), 95% Recall@15 @ ~720 tokens (99.4% context compression). Verification:

> Conclusion: All figures come from the company's own research page; the docs site itself gives no numbers; no neutral third-party leaderboard exists (LongMemEval's official academic site does not host commercial vendor rankings).

At least four competitors self-report ~95% SOTA in the same period, mutually contradictory:

| Vendor | Self-reported score | Notes | |---|---|---| | Supermemory | 95% Recall@15 | Own research page, +~720 tokens | | Mastra Observational Memory | 94.87% | "highest score ever recorded" (gpt-5-mini) | | OMEGA | 95.4% | Claims 50ms retrieval | | Hindsight / Vectorize | 94.6% | Claims "independent verification" | | Exabase M-1 | ~SOTA | Research on model scale vs long-term memory |

The credible part: the MemoryBench framework itself is open source (MIT, unified provider interface), so anyone can re-run supermemory / mem0 / zep + filesystem / rag baselines—turning self-assessment into something verifiable is good faith, though the default leaderboard is still vendor-maintained.

10. Engineering Quality: Pros and Cons

👍 Good

• MCP engineering discipline: zod at every boundary, rollback DOs retaining one version, 503/401 error classification
• Diff billing + customId idempotent ingestion—clever and honest
• SSRF protection down to CGNAT ranges, IPv6 literals, 2MB bounded reads
• Load-bearing comments about AI SDK v6 widget defects in the web app

👎 Questionable / Bad

• "Open source" marketing misleads: engine closed, local binary-only, no source in tags, all #1 claims self-reported
• CLAUDE.md describes a nonexistent backend, misleading agent developers
• Batches of garbled text in docs (likely a bulk-edit accident)
• v3/v4 dual APIs coexist; SDK contains workaround traces ("pinned SDK lacks forget, so raw DELETE")
• Self-host vs cloud "proprietary model" are different things; docs smooth over this with a full local-vs-enterprise page

11. Transferable Lessons

1. Three-tier MCP tool hierarchy (model-visible / app launchers / app-hidden) is a ready-made pattern for "too many tools polluting attention." 2. Profile as a retrieval bypass: facts queries can't hit must come from an always-on summary—every memory system needs this asymmetric channel. 3. Inferred memories default down-weighted + human review (sorted by parentCount) is a pragmatic guard against LLM memory-hallucination contamination. 4. Diff billing + customId idempotent ingestion: making "repeated syncs free" a billing primitive generalizes to connector products. 5. withSupermemory's "silently degrade on memory-fetch failure, additive only, never blocking" is the safe pattern for adding sidecar dependencies to LLMs. 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.

Sources

1. Code: local clone of supermemoryai/supermemory (main @ 4d8a4ebf) 2. TechCrunch: 19-year-old founder backed by Google execs ($2.6M) 3. Supermemory official funding announcement ($3M self-reported) 4. Supermemory LongMemEval self-assessment page · LongMemEval official (academic, no commercial leaderboard) 5. Competitor self-reports: Mastra 94.87% · OMEGA 95.4% · Hindsight 94.6% · Exabase M-1 6. GitHub API: repo stats and server-v0.0.8 release asset manifest (fetched 2026-09-07)