# supermemory
Context infrastructure for AI agents. Use it with the API, your tools, your team, or run it yourself.
No memories yet
Add content to see your knowledge graph
vs Rolling your own (vector DB + embeddings + glue)
**What this path is:** Pinecone/Weaviate/pgvector + an embedding model + chunking scripts + a prompt that says “here is relevant context.” and running it through a text model, extracting facts. **When it is enough** * Static knowledge base, low update rate * You already run retrieval infra and only need nearest-neighbor chunks * Latency, ops, and embedding quality are already solved problems for your team **Where it breaks for agent memory** * No temporal truth (“loved Adidas” then “switched to Puma”, both stay equally “relevant”) * You have to use 6+ vendors for all the different stuff * No entity identity or profile, just similar text * Multimodal extraction, connectors, forgetting, and multi-tenant isolation become a second product * You spend lots of time on just figuring out the right plumbing and combinations of vendors * Not very scalable for memory. New facts need knowledge of all previous facts **Supermemory instead:** one engine that derives **memories** using our custom model, a **temporal vector-graph engine**, and **profiles**, with hybrid retrieval and isolation primitives built in. You keep the option to [self-host](/docs/self-hosting/overview) when you want the stack on your metal.vs “Memory layers” that are thin wrappers
**What this path is:** an API that stores chat turns or summaries in a vector store, sometimes with a light extract-facts prompt. Marketed as memory; architected as RAG with better branding. **When it is enough** * Demo chatbots and hackathon agents * You only need “remember the last few sessions” as blobs of text * Quality bar is “sometimes recalls a preference” **Where it breaks in production** * Facts do not **update** cleanly when users change their mind * Some of them have no real graph of people, projects, and relations across separately ingested events * There's no concept of Profiles since they don't have the same underlying learning model and store engine * You still have to build the entire thing around it, on their abstraction. Low configurability and doesn't support many use cases (Extractors, retrieval, etc.) **Supermemory instead:** memory is a first-class data model (documents → derived memories → graph → profiles), not a convenience wrapper. Same store from API, MCP, and plugins, all primitives built in for you to compose for your use case. See [How it works](/docs/concepts/how-it-works) and [Graph memory](/docs/concepts/graph-memory).vs Pure RAG / document search products
**What this path is:** excellent document ingestion and semantic search over a corpus, wikis, PDFs, tickets. No (or weak) per-user long-horizon memory. **When it is enough** * Internal knowledge base Q\&A only, no change in text * “Chat with these PDFs” with a fixed corpus * Content is universal, not personal. The files are structured and short * Content does not update enough over long horizons **Where it breaks** * Personalized agents that must know *this user* over months * Mixing “what is in the policy doc” with “what did this customer decide last quarter” * You still have to build in the contextualization and bear the cost of it. Also need to sign up for many vendors for the same. * Treating user state as another document collection **Supermemory instead:** **both** layers in one engine, SuperRAG for corpus grounding, memory + profiles for people and entities. They share container tags so isolation stays coherent. Deep dive: [Memory vs RAG](/docs/concepts/memory-vs-rag).vs Building a full context engine in-house
**What this path is:** custom extraction models, graph store, profile assembly, hybrid search, connector fleet, multi-tenant keys, compliance pack. **When it is justified** * Memory *is* the product and differentiation lives in proprietary models/data * You have a dedicated platform team and years of runway * Regulatory constraints force a greenfield design with no external dependency (even then, [self-host](/docs/self-hosting/overview) is often enough) **What you are actually signing up for** * Extraction quality and eval harnesses * Temporal updates, conflict resolution, forgetting * Multimodal pipelines and connector maintenance * Authz (scoped keys, container boundaries), billing metering, SOC 2 / GDPR / HIPAA paths * Sub-300ms retrieval under agent-loop load, deployability, maintaining it forever as the industry changes **Supermemory instead:** that platform as a product, managed cloud or self-hosted binary, so your team ships agents and apps, not a second infrastructure company. Benchmarks and research: [supermemory.ai/research](https://supermemory.ai/research).Decision cheat sheet
| If your job is… | Prefer | | -------------------------------------------------------- | ----------------------------------------------------------------- | | Q\&A over a mostly static doc set | RAG product or SuperRAG-only usage | | Remember users across sessions with updates over time | Supermemory memory + profiles | | Both personalization *and* company docs | Supermemory (memory + SuperRAG, same containers) | | Full control, data never leaves your network | Supermemory [self-host](/docs/self-hosting/overview) / Enterprise | | Maximum control of every model weight and storage engine | Build in-house (or fork open pieces and accept the ops) |Prove it yourself
We would rather you verify than trust a comparison page: 1. Run the [quickstart](/docs/quickstart), scatter facts across “sessions,” ask a question that requires linking them 2. Reproduce long-horizon results with [MemoryBench](https://supermemory.ai/research) / the MemoryBench docs when you care about evals 3. If you already store memories elsewhere, use a [migration guide](/docs/migration/from-mem0)Supermemory is never overkill
In most cases, supermemory will be the *lighter* choice (not heavier), and it is cheaper too! Because supermemory involves all the blocks while being fully composable, but we also build the infrastructure ourselves (a post-trained model, etc.), it's perfect for everything from internal tools, side projects, and hobby projects to production-grade infrastructure that millions of people rely on. Building your own, however, will mean that you have to sign up for 20 different vendors to do your database, hosting, embedding, graph, vector store, learning model, ingestion pipeline, etc. Why is it cheaper? Because we (the team) come from an infrastructure background, we built some of the best base for memory out there. Owning the database and the model layer gives us a lot of advantages! And if data ownership is a concern, it shouldn't be :) You can always [self-host](/docs/self-hosting/overview) supermemory which ensures that nothing leaves your servers and you have full control and access. Concerned about lock-in? You can always export your data, delete it, or switch to running your own instance of supermemory. **Supermemory is an architecture** to build with, not an *opinionated service*. It comes with the right defaults and some easy ways to use it, but you can go as deep as you want to make it perfect for your case. Finally, we truly believe every use case can make advantage of supermemory, or a base of it's components. Most AI applications should use supermemory.(SMFS mount)"] end Mount -->|sync| SM["Supermemory"] ``` ### Agent outside the container The agent runs in a Cloudflare Worker and sends commands to the container over HTTP. The container exposes a simple exec endpoint. ```mermaid theme={null} graph LR Agent["Worker
(agent logic)"] -->|"containerFetch('/exec')"| Container subgraph Container ["Cloudflare Container"] Mount["/memory
(SMFS mount)"] end Mount -->|sync| SM["Supermemory"] ``` ## Prerequisites * A [Supermemory API key](https://supermemory.ai) * An [Anthropic API key](https://console.anthropic.com) * A [Cloudflare account](https://dash.cloudflare.com) with Containers enabled (Workers Paid plan) * [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) * The [`@cloudflare/containers`](https://www.npmjs.com/package/@cloudflare/containers) package: `npm install @cloudflare/containers`
(SMFS mount)"] end Mount -->|sync| SM["Supermemory"] ``` ### Agent outside the sandbox The agent runs in your orchestrating code and executes commands inside the sandbox remotely. ```mermaid theme={null} graph LR Agent["Claude Agent
(your server)"] -->|"sandbox.process.exec()"| Sandbox subgraph Sandbox ["Daytona Sandbox"] Mount["/home/daytona/memory
(SMFS mount)"] end Mount -->|sync| SM["Supermemory"] ``` ## Prerequisites * A [Supermemory API key](https://supermemory.ai) * A [Daytona API key](https://app.daytona.io) — go to **API Keys** in the sidebar * An [Anthropic API key](https://console.anthropic.com) *** ## Install SMFS in a Daytona sandbox Both patterns below run the same setup snippet inside the sandbox before mounting. Daytona can't reach `smfs.ai`, so we download the binary directly from GitHub Releases and add `~/.local/bin` to PATH.
(SMFS mount)"] end Mount -->|sync| SM["Supermemory"] ``` ### Agent outside the sandbox The agent runs in your orchestrating code and executes commands inside the sandbox remotely. Useful when you want to keep the agent loop in your own infra. ```mermaid theme={null} graph LR Agent["Claude Agent
(your server)"] -->|"sbx.commands.run()"| Sandbox subgraph Sandbox ["E2B Sandbox"] Mount["/home/user/memory
(SMFS mount)"] end Mount -->|sync| SM["Supermemory"] ``` ## Prerequisites * A [Supermemory API key](https://supermemory.ai) * An [E2B API key](https://e2b.dev) * An [Anthropic API key](https://console.anthropic.com) ## 1. Create a custom template Bake SMFS and the Claude Agent SDK into a template so sandboxes start ready: ```dockerfile e2b.Dockerfile theme={null} FROM e2b/code-interpreter:latest RUN apt-get update && apt-get install -y fuse3 && rm -rf /var/lib/apt/lists/* RUN echo 'user_allow_other' >> /etc/fuse.conf RUN curl -fsSL https://smfs.ai/install | bash -s -- 0.0.1-rc2 ENV PATH="/root/.local/bin:$PATH" RUN pip install claude-agent-sdk ``` ```bash theme={null} e2b template build -d e2b.Dockerfile ``` *** ## Pattern A: Agent inside the sandbox The agent runs inside the sandbox as a Python script. Your orchestrating code just sets up the mount and starts it. ### Agent code ```python agent.py theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions MEMORY = "/home/user/memory" async def main(): async for message in query( prompt=f"You have a persistent memory filesystem at {MEMORY}. " "Read profile.md to learn about the user, then create " "session_notes.md summarizing what you found.", options=ClaudeAgentOptions( allowed_tools=["Bash", "Read", "Write"], cwd=MEMORY, ), ): print(message) asyncio.run(main()) ``` ### Orchestration
(SMFS mount)"] end Mount -->|sync| SM["Supermemory"] ``` ### Vercel Functions / serverless (Bash Tool) The agent runs inside `generateText` and accesses memory through `@supermemory/bash`, which proxies bash commands to your Supermemory container over HTTP. No mount, no FUSE, no long-lived process required. ```mermaid theme={null} graph LR subgraph Vercel Function AI["generateText()"] -->|"bash tool"| Bash["@supermemory/bash"] end Bash -->|HTTPS| SM["Supermemory"] ``` ## Prerequisites * A [Supermemory API key](https://supermemory.ai) * An [Anthropic API key](https://console.anthropic.com) * For Pattern A only: SMFS installed on your server (`curl -fsSL https://smfs.ai/install | bash`) *** ## Pattern A: Claude Agent SDK on self-hosted Node Use this when the Vercel AI SDK is just the orchestrator and your real workload is a Claude agent running on a long-lived server you control. Start the mount once when your server boots — not per-request: ```bash theme={null} smfs login --key $SUPERMEMORY_API_KEY smfs mount my_agent --path ./memory ```