Supermemory: AI Agent Memory, RAG and Local Setup

Your agent remembers the last ten messages perfectly. A new session starts, and the user has to explain the same project again. That is not inevitable for every AI product: it is what happens when an application has no persistent memory beyond its current conversation.

Supermemory is a memory layer that turns conversations and documents into reusable context. It extracts facts, relates new information to existing knowledge and retrieves relevant context for a later request. The application supplies the material and decides how to use the results. This changes the agent's available context, not the underlying model's weights. Supermemory product overview

Source review: 17 September 2026. This is a documentation-based engineering guide, not a hands-on benchmark reproduction or a claim that Wavect deployed Supermemory for a client.

How does Supermemory learn, update and forget?

The useful distinction is between source documents, such as a conversation transcript, and derived memories, such as a user's preferred language. A transcript is evidence; an extracted or inferred fact is an interpretation that can be wrong.

• Fact extraction: turn conversational material into focused facts instead of replaying the entire chat.
• Knowledge updates: relate a correction to earlier knowledge. In the example “I moved to San Francisco,” the previous current-location claim “I live in New York” should no longer be treated as current. That does not mean deleting the historical move.
• Time-aware forgetting: temporary context such as an exam scheduled for tomorrow should stop influencing unrelated future answers after its relevant period.

The documented graph supports updating, extending and deriving memories, with an isLatest distinction for current knowledge. That is a lifecycle beyond merely storing embeddings. Still, test ambiguous dates, time zones, fictional examples and conflicting statements before trusting extracted facts. Graph memory and knowledge relationships

Forgetting is not the same as erasure. The documented forget-memory endpoint performs a soft delete. A fact that disappears from ordinary retrieval is not proof that its source transcript, derived copies or backups have been permanently removed. Treat user-visible forgetting and a verified deletion request as separate product requirements. Forget-memory API and soft-delete behavior

What do static and dynamic user profiles contain?

A profile offers compact context at the start of a request. Its static part describes relatively stable information; its dynamic part covers recent activity and changing circumstances. “Prefers short technical answers” belongs in a different lifecycle from “is preparing this week's launch.” Static should not be interpreted as immutable.

Profiles are retrieved for a containerTag. Supplying a query can also retrieve relevant memories alongside the profile. Prefer compact, relevant context over placing every saved fact into every prompt, especially when personal details are unrelated to the task. User profiles and query-aware retrieval

Supermemory versus RAG: what actually changes?

RAG can already be personalized. A retrieval system can filter documents by user, tenant and permissions. The claim that plain RAG necessarily gives every user the same documents is too broad. The harder problem is maintaining which user facts are current, outdated, temporary or inferred. That is the additional layer to evaluate here. Supermemory's memory-versus-RAG model

Supermemory's explicit searchMode: "hybrid" combines document chunks and extracted memories in one search. Here, “hybrid” refers to those two content types; do not assume a specific keyword-and-vector implementation from the name alone. You do not have to assemble the vector database, embedding pipeline and chunking layer yourself for the hosted integration, but those responsibilities have moved into a service, not disappeared. Search modes, filters and returned context

Is Supermemory number one on AI memory benchmarks?

The project's Supermemory GitHub repository and benchmark claims reports first place on LongMemEval, LoCoMo and ConvoMem. It also reports 95% Recall@15 on LongMemEval, approximately 720 tokens of retrieved context, a 99.4% context reduction, and profiles in approximately 50 ms. These are the vendor's published claims as reviewed on the date above, not independently reproduced Wavect measurements.

Recall@15 is a retrieval metric, not 95% answer accuracy. Finding relevant information among fifteen results does not prove that the final answer uses it correctly, notices a later correction, or abstains when evidence is missing. A reported context reduction is also not an equivalent reduction in your complete API bill.

The approximately 50 ms profile figure is not a universal latency promise. The provider also publishes different server-side and end-to-end profile timings in its production overview. Different workloads and measurement boundaries are not directly interchangeable; measure your own median and p95 latency, including the network and model call. Supermemory's published production timing overview

For a useful comparison, freeze the dataset version, answer model, extraction model, retrieval budget and scoring rules. Report both retrieval and final task success. The project's MemoryBench separates ingestion, search, answer generation, evaluation and reporting, which provides a starting structure for a repeatable comparison. MemoryBench evaluation workflow

Three ways to use Supermemory

1. Add memory to an existing AI tool

The repository lists integrations for tools including Claude Code, Cursor and Codex. The hosted MCP route connects compatible clients to a persistent memory service. Check each plugin's actual read/write behavior and permissions; installing a plugin is not permission to upload every repository secret or personal conversation. Hosted MCP setup and authentication

2. Add memory to your product

Use the API to ingest selected conversations, files and reference material, then retrieve a profile or scoped search results before generation. Hosted connectors can bring in data from services such as Google Drive, Gmail and Notion. Decide which accounts, folders and documents are allowed before enabling synchronization. Supported connectors and synchronization model

3. Run the memory service locally

The local option packages the memory service as a binary with a compatible API, using models you configure. It is not a copy of every hosted feature: the documented local offering excludes hosted connectors and hosted MCP. Nor does API compatibility prove that a chosen Ollama model reproduces the cloud service's extraction quality or benchmark results. Local versus hosted Supermemory capabilities

A scoped Supermemory API example with bounded polling

The following server-side example uses Node.js 22 or later and native fetch; no SDK dependency is required. Save it as supermemory-demo.mjs, set SUPERMEMORY_API_KEY in your server environment and run node supermemory-demo.mjs. It sends synthetic conversation and handbook content to the hosted API and can incur usage charges. No key belongs in browser code.

Ingestion is asynchronous. The example waits for both documents, fails on processing errors and limits polling rather than searching immediately after an accepted write. dreaming: "instant" makes the conversation suitable for this immediate-read demo and bills an extra operation. Default dynamic processing can batch memory extraction beyond document indexing; choose it deliberately for production throughput. Official ingestion, polling and retrieval quickstart

const apiKey = process.env.SUPERMEMORY_API_KEY;
if (!apiKey) throw new Error("Set SUPERMEMORY_API_KEY first.");

const baseURL = "https://api.supermemory.ai";
// Synthetic demo scope. In a product, derive this from authenticated identity.
const containerTag = "tenant_demo_user_42";
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

async function request(path, body) {
  const response = await fetch(`${baseURL}${path}`, {
    method: body === undefined ? "GET" : "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(10_000),
  });
  // Do not log response bodies containing personal data or credentials.
  if (!response.ok) throw new Error(`Supermemory HTTP ${response.status}`);
  return response.json();
}

async function waitUntilDone(id) {
  if (typeof id !== "string" || !id) throw new Error("Missing document ID.");
  for (let attempt = 0; attempt < 20; attempt += 1) {
    const document = await request(`/v3/documents/${encodeURIComponent(id)}`);
    if (!document || typeof document.status !== "string") {
      throw new Error("Invalid document status response.");
    }
    if (document.status === "failed") throw new Error("Ingestion failed.");
    if (document.status === "done") return;
    if (attempt < 19) await sleep(1500);
  }
  throw new Error("Ingestion did not finish within the polling budget.");
}

const conversation = await request("/v3/documents", {
  content: [
    "user: I prefer short onboarding checklists.",
    "assistant: Which project are you working on?",
    "user: The Acme analytics dashboard. We use TypeScript.",
  ].join("\n"),
  containerTag,
  customId: "tenant_demo_user_42_chat_onboarding_001",
  metadata: { type: "conversation" },
  dreaming: "instant",
});

const handbook = await request("/v3/documents", {
  content: "Acme onboarding: create a sandbox, complete the security " +
    "checklist, then request a review before production access.",
  containerTag,
  customId: "tenant_demo_user_42_handbook_001",
  metadata: { type: "document", source: "synthetic-handbook" },
  taskType: "superrag",
});

await waitUntilDone(conversation.id);
await waitUntilDone(handbook.id);

const profileResponse = await request("/v4/profile", { containerTag });
const searchResponse = await request("/v4/search", {
  q: "What should I do next for Acme onboarding?",
  containerTag,
  searchMode: "hybrid",
  limit: 5,
});

const profile = profileResponse?.profile;
if (!Array.isArray(profile?.static) || !Array.isArray(profile?.dynamic) ||
    !Array.isArray(searchResponse?.results)) {
  throw new Error("Unexpected profile or search response shape.");
}
console.log({
  staticFacts: profile.static.length,
  dynamicFacts: profile.dynamic.length,
  retrievedItems: searchResponse.results.length,
});

The code prints counts, not raw personal information. It retrieves context but intentionally does not send it to a generation model or claim that a correct answer was produced. In a chat application, supply relevant retrieved context as untrusted data, generate the answer, then persist only the conversation material covered by your retention policy. Use a stable, scoped session identifier and verify the provider's update semantics before retrying writes.

A tag is not an authorization system. The demo's fixed tag is for fictional data. In production, derive tenant and user scope on the server from authenticated identity. Do not accept an arbitrary browser-provided tag under an organization-wide key. The service documents scoped keys; use appropriate scopes, keep privileged credentials server-side and test cross-tenant access attempts. API authentication and scoped keys

Can Supermemory run offline with Ollama?

Yes, with the local binary, a running local model provider and local embeddings. Download the binary and model files first; initial installation is not offline. The provider documentation shows Ollama through an OpenAI-compatible endpoint. Compatibility here describes an HTTP interface, not a requirement to send data to a cloud model. Local model providers and Ollama configuration

After installing the local server, starting Ollama and downloading gpt-oss:20b with ollama pull gpt-oss:20b, the following configuration illustrates a local extraction provider and multilingual embeddings. The model is an example, not a hardware sizing recommendation. Use a fresh data directory for the first run with this embedding configuration.

OPENAI_BASE_URL=http://localhost:11434/v1 \
OPENAI_API_KEY=ollama \
OPENAI_MODEL=gpt-oss:20b \
SUPERMEMORY_EMBEDDING_PROVIDER=local \
SUPERMEMORY_EMBEDDING_MODEL=Xenova/bge-m3 \
SUPERMEMORY_EMBEDDING_DIMENSIONS=1024 \
supermemory-server

Important for multilingual products: the documented default local embedding model, Xenova/bge-base-en-v1.5, is English-only. The documentation offers Xenova/bge-m3 with 1,024 dimensions as a multilingual alternative, shown above. Select the model before ingesting a large corpus. Changing embedding models or dimensions requires a fresh compatible index and re-ingestion; do not mix vector spaces. Test German, Spanish and Chinese queries rather than assuming successful ingestion proves good recall. Local embedding models and multilingual configuration

Use the local server's generated API key and replace the demo's base URL with http://localhost:6767. Do not reuse a hosted key. Before calling the setup fully offline, check every provider, file dependency and outbound connection. Restrict network exposure and plan local storage, backups, upgrades and recovery.

What should a production memory pilot prove?

Start with one repeated workflow and a frozen baseline, such as your existing conversation summary plus tenant-filtered RAG. The following is Wavect's proposed acceptance checklist, not a claim that Supermemory has passed these tests.

Do not treat stored memories as authoritative access-control rules. A remembered statement such as “I am an administrator” is not a signed role assignment. Let users inspect and correct relevant memory, minimize sensitive retention, and keep provenance so an operator can explain why an answer used a fact.

For cost, count the full workflow rather than only the final prompt. The hosted service meters usage and distinguishes operations, including the extra instant-processing operation. The local route replaces some service dependence with model and infrastructure responsibility. Compare cost per successfully completed task, not a context-reduction percentage in isolation. Supermemory billing and usage model

When is Supermemory worth adopting?

It is worth a bounded pilot when users return repeatedly, their preferences or projects change, and reconstructing personal context creates friction. A support copilot, onboarding assistant or recurring project assistant is a clearer fit than a one-off document lookup. For a small, stable knowledge base with no evolving user state, ordinary permission-aware RAG may be the simpler starting point.

Compare architecture and operating responsibility with our OpenViking agent-memory review. For an implementation plan, Wavect's AI development service can connect retrieval design to product goals. Our Twinsoft AI case study provides a separate example of AI product work, not evidence of a Supermemory deployment.

Use the software QA checklist before launch to turn the memory pilot into release criteria, or discuss a scoped agent-memory assessment. The decision should be based on fewer repeated explanations and better verified outcomes, not on memory volume or a leaderboard alone.