Graph memory

How understanding is stored and stays true over time. Supermemory builds a living knowledge graph of facts on top of other facts — not a static folder of embeddings, and not classic entity–relation–entity triples you maintain by hand. The pipeline that turns a chat or file into memories is How it works. This page is the model: what a memory is, how edges form, and why agents utilize supermemory’s graph

Try it

Get a key from the developer console — API Keys → Create API Key — then add a memory and pull it back with related edges:

import Supermemory from "supermemory";

const client = new Supermemory({ apiKey: "sm_..." }); // from console.supermemory.ai → API Keys

await client.add({
  content: "Alex mentioned he just started at Stripe",
  containerTag: "user_123",
});

const results = await client.search({
  q: "where does Alex work?",
  containerTag: "user_123",
  include: { relatedMemories: true },
});

Full walkthrough with a live example: Quickstart.

Documents vs memories

	Documents	Memories
What	Raw input you send	Facts Supermemory extracts
Examples	PDF, chat log, Drive file, URL	“Alex is a PM at Stripe”
Role	Source of truth for RAG / SuperRAG	Personal and entity state over time
Lifecycle	You add / update / delete	Graph updates, extends, derives, forgets

Think of documents as books you hand the system. Memories are the insights it keeps — connected to each other as new content arrives.

Uploading a long PDF does more than store bytes: Supermemory derives many memories and links them to what it already knows about that entity or user. Chunks of the document remain available for SuperRAG grounding.

Properties and rules of memories

Memories are atomic - Each memory has enough information and context about one particular topic
They always build on top of each other - with updates, the model knows the history, a memory extends from other memories, and new facts are derived (derives relation) from existing knowledg.e

Memory relationships

When content is processed, new facts connect to existing ones through three relationship types.

Updates — information changes

New fact replaces what was true before for search purposes; history can remain for audit.

Memory 1: "Alex works at Google as a software engineer"
Memory 2: "Alex just started at Stripe as a PM"
         → Memory 2 UPDATES Memory 1

isLatest (and related graph fields) keep retrieval on the current fact without erasing the past.

Extends — information enriches

New fact adds detail without invalidating the old one.

Memory 1: "Alex works at Stripe as a PM"
Memory 2: "Alex focuses on payments and leads a team of 5"
         → Memory 2 EXTENDS Memory 1

Both stay valid; context gets richer.

Derives — information infers

Supermemory infers a fact you never stated in one place, from patterns across memories.

Memory 1: "Alex is a PM at Stripe"
Memory 2: "Alex frequently discusses payment APIs and fraud detection"
         → Derived: "Alex likely works on Stripe's core payments product"

That is the same class of “entity chain” you see in the quickstart (gift → VP of Product → Sarah → Tokyo offsite). Search can expose edges via include.relatedMemories — see Search API.

Automatic extraction (one input → many facts)

Input:

Had a great call with Alex. He’s enjoying the new PM role at Stripe, though the payments work is intense. He moved to Seattle for the job—Capitol Hill. Wants dinner next time I’m in town.

Example extracted memories:

Alex works at Stripe as a PM
Alex works on payments infrastructure (extends role)
Alex lives in Seattle, Capitol Hill
Alex wants to meet for dinner (episodic)

You do not define schema or draw edges. You add content; the graph updates.

Dreaming keeps the graph alive

Ingest is not a one-shot snapshot. After (and alongside) indexing, dreaming continues building the graph: extracting facts, linking related memories, resolving updates, and producing derives you never stated in one place. By default Supermemory uses dreaming: "dynamic" — related documents are grouped so memories form from coherent units (e.g. a real multi-turn session), not each isolated write in isolation. That is why production quality is higher when you keep a stable customId on conversations and let dynamic dreaming do its job. Use dreaming: "instant" when this document must hit the graph immediately (demos, “search right after add”). That path processes the document alone and costs an extra operation. How to set the flag, statuses, and when done means what: How it works → Dreaming and Processing modes.

Memory types

Type	Example	Behavior
Facts	“Alex is a PM at Stripe”	Persists until updated
Preferences	“Alex prefers morning meetings”	Strengthens with repetition
Episodes	“Met Alex for coffee Tuesday”	Decays unless significant

Automatic forgetting

Time-based — temporary facts drop after they expire (“exam tomorrow”, “meeting at 3pm today”).
Contradiction — updates win for “what’s true now.”
Noise filtering — casual, non-meaningful chatter is less likely to become durable memory.

For explicit product controls (forget, review low-confidence derives), see Forget & update and Memory review.

What you don’t do

You do not hand-maintain the graph. You:

Ingest under a container tag
Wait for the pipeline when needed
Search or load a profile

await client.add({
  content: "Alex mentioned he just started at Stripe",
  containerTag: "user_123",
});

const results = await client.search({
  q: "where does Alex work?",
  containerTag: "user_123",
  include: { relatedMemories: true },
});
// Prefer latest work fact (Stripe); history remains in the graph

If you need…	Go to
Pipeline statuses, dreaming, documents in	How it works
Memory vs document retrieval	Memory vs RAG · SuperRAG
Always-on summary of a user	Profiles
Isolation / tenants	Multi-tenancy
API: add / search / forget	Ingestion · Search · Forget & update

How it works

Ingest pipeline, statuses, and outputs.

Memory vs RAG

When to use memory vs document retrieval.

Profiles

Static + dynamic context built from the graph.

Quickstart

See entity chains in a full conversation + document flow.

Getting Started

Concepts

Using supermemory

Deployment

Other resources

Migration Guides

Try it

Documents vs memories

Properties and rules of memories

Memory relationships

Updates — information changes

Extends — information enriches

Derives — information infers

Automatic extraction (one input → many facts)

Dreaming keeps the graph alive

Memory types

Automatic forgetting

What you don’t do

How it works

Memory vs RAG

Profiles

Quickstart

​Try it

​Documents vs memories

​Properties and rules of memories

​Memory relationships

​Updates — information changes

​Extends — information enriches

​Derives — information infers

​Automatic extraction (one input → many facts)

​Dreaming keeps the graph alive

​Memory types

​Automatic forgetting

​What you don’t do

​Related in the docs

How it works

Memory vs RAG

Profiles

Quickstart

Try it

Documents vs memories

Properties and rules of memories

Memory relationships

Updates — information changes

Extends — information enriches

Derives — information infers

Automatic extraction (one input → many facts)

Dreaming keeps the graph alive

Memory types

Automatic forgetting

What you don’t do

Related in the docs