supermemory/apps/docs/integrations/memory-graph.mdx

---
title: 'Memory Graph'
sidebarTitle: "Memory Graph"
description: 'Interactive visualization for documents, memories and connections'
icon: "/icons/hugeicons/hierarchy-square-01.svg"
---

Memory Graph is a React component that visualizes your Supermemory documents and memories as an interactive network. Documents appear as rectangular nodes, memories as hexagonal nodes, and connections between them show relationships and similarity.

<Card title="@supermemory/memory-graph on npm" icon="/icons/hugeicons/package.svg" href="https://www.npmjs.com/package/@supermemory/memory-graph">
    Check out the NPM page for more details
</Card>

## Installation

```bash
npm install @supermemory/memory-graph
```

**Requirements:** React 18.0.0 or higher

## Quick start

```tsx
'use client'; // For Next.js App Router

import { MemoryGraph } from '@supermemory/memory-graph';
import type { GraphApiDocument } from '@supermemory/memory-graph';
import { useEffect, useState } from 'react';

export default function GraphPage() {
  const [documents, setDocuments] = useState<GraphApiDocument[]>([]);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    fetch('/api/graph')
      .then(res => res.json())
      .then(data => {
        setDocuments(data.documents);
        setIsLoading(false);
      })
      .catch(err => {
        setError(err);
        setIsLoading(false);
      });
  }, []);

  return (
    <div style={{ height: '100vh' }}>
      <MemoryGraph
        documents={documents}
        isLoading={isLoading}
        error={error}
        variant="console"
      />
    </div>
  );
}
```

## Optional rendering and document navigation

Existing icon-based document nodes and connection styling remain the defaults. Opt in to stacked squares and stronger semantic connections with `appearance`:

```tsx
<MemoryGraph
  documents={documents}
  appearance={{ documentNodes: 'stacked', connections: 'emphasized' }}
  openDocumentOnEnter
  onOpenDocument={openPersistedDocument}
/>
```

`documentNodes` accepts `'icons'` or `'stacked'`; `connections` accepts `'default'` or `'emphasized'`. Both fields are optional and also work on `GraphCanvas`. Stacks stay inside existing node bounds and simplify at low zoom. Use `colors.edgeDocument` to configure document-source ink; older custom `GraphCanvas` palettes without that field use `textSecondary` in emphasized mode.

`openDocumentOnEnter` is off by default. With an `onOpenDocument` callback, `MemoryGraph` exposes a focused Enter action for the selected persisted document or one confirmed memory source. Typing, modifier shortcuts, repeats, composition and keys outside the graph do not open documents. Your callback retains responsibility for routing and access control; consumers without a callback receive no new opening behavior.

<Note>
  `documents` must be `GraphApiDocument[]`, the shape the API route below returns, with `documentType` and `memories` fields (not the raw API's `type` and `memoryEntries`).
</Note>

## Backend API route

Create an API route to fetch documents from Supermemory. The `/v3/documents/documents` response uses `type` and `memoryEntries`; `<MemoryGraph>` expects `documentType` and `memories`, so the route normalizes the shape before returning it:

<CodeGroup>

```typescript Next.js App Router
// app/api/graph/route.ts
import { NextResponse } from 'next/server';
import type { GraphApiDocument, GraphApiMemory } from '@supermemory/memory-graph';

interface RawMemoryEntry {
  id: string;
  memory?: string | null;
  content?: string | null;
  spaceId?: string | null;
  isStatic?: boolean;
  isLatest?: boolean;
  isForgotten?: boolean;
  forgetAfter?: string | null;
  forgetReason?: string | null;
  version?: number;
  parentMemoryId?: string | null;
  rootMemoryId?: string | null;
  createdAt: string;
  updatedAt: string;
  relation?: 'updates' | 'extends' | 'derives' | null;
  updatesMemoryId?: string | null;
  nextVersionId?: string | null;
  memoryRelations?: Record<string, 'updates' | 'extends' | 'derives'> | null;
  spaceContainerTag?: string | null;
}

interface RawDocument {
  id: string;
  title: string | null;
  summary?: string | null;
  type: string;
  createdAt: string;
  updatedAt: string;
  memoryEntries: RawMemoryEntry[];
}

interface RawDocumentsResponse {
  documents: RawDocument[];
  pagination: {
    currentPage: number;
    limit: number;
    totalItems: number;
    totalPages: number;
  };
}

// Maps the raw API document (`type` / `memoryEntries`) onto the shape
// <MemoryGraph> expects (`documentType` / `memories`), filling in the
// defaults for fields the API may omit.
function toGraphDocument(doc: RawDocument): GraphApiDocument {
  return {
    id: doc.id,
    title: doc.title,
    summary: doc.summary ?? null,
    documentType: doc.type,
    createdAt: doc.createdAt,
    updatedAt: doc.updatedAt,
    memories: doc.memoryEntries.map((mem): GraphApiMemory => ({
      id: mem.id,
      memory: mem.memory ?? mem.content ?? '',
      content: mem.content ?? null,
      isStatic: mem.isStatic ?? false,
      spaceId: mem.spaceId ?? '',
      isLatest: mem.isLatest ?? true,
      isForgotten: mem.isForgotten ?? false,
      forgetAfter: mem.forgetAfter ?? null,
      forgetReason: mem.forgetReason ?? null,
      version: mem.version ?? 1,
      parentMemoryId: mem.parentMemoryId ?? null,
      rootMemoryId: mem.rootMemoryId ?? null,
      createdAt: mem.createdAt,
      updatedAt: mem.updatedAt,
      relation: mem.relation ?? null,
      updatesMemoryId: mem.updatesMemoryId ?? null,
      nextVersionId: mem.nextVersionId ?? null,
      memoryRelations: mem.memoryRelations ?? null,
      spaceContainerTag: mem.spaceContainerTag ?? null,
    })),
  };
}

export async function GET() {
  const response = await fetch('https://api.supermemory.ai/v3/documents/documents', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    },
    body: JSON.stringify({
      page: 1,
      limit: 500,
      sort: 'createdAt',
      order: 'desc',
    }),
  });

  const data: RawDocumentsResponse = await response.json();
  return NextResponse.json({
    documents: data.documents.map(toGraphDocument),
    pagination: data.pagination,
  });
}
```

```typescript Next.js Pages Router
// pages/api/graph.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import type { GraphApiDocument, GraphApiMemory } from '@supermemory/memory-graph';

interface RawMemoryEntry {
  id: string;
  memory?: string | null;
  content?: string | null;
  spaceId?: string | null;
  isStatic?: boolean;
  isLatest?: boolean;
  isForgotten?: boolean;
  forgetAfter?: string | null;
  forgetReason?: string | null;
  version?: number;
  parentMemoryId?: string | null;
  rootMemoryId?: string | null;
  createdAt: string;
  updatedAt: string;
  relation?: 'updates' | 'extends' | 'derives' | null;
  updatesMemoryId?: string | null;
  nextVersionId?: string | null;
  memoryRelations?: Record<string, 'updates' | 'extends' | 'derives'> | null;
  spaceContainerTag?: string | null;
}

interface RawDocument {
  id: string;
  title: string | null;
  summary?: string | null;
  type: string;
  createdAt: string;
  updatedAt: string;
  memoryEntries: RawMemoryEntry[];
}

interface RawDocumentsResponse {
  documents: RawDocument[];
  pagination: {
    currentPage: number;
    limit: number;
    totalItems: number;
    totalPages: number;
  };
}

// Maps the raw API document (`type` / `memoryEntries`) onto the shape
// <MemoryGraph> expects (`documentType` / `memories`), filling in the
// defaults for fields the API may omit.
function toGraphDocument(doc: RawDocument): GraphApiDocument {
  return {
    id: doc.id,
    title: doc.title,
    summary: doc.summary ?? null,
    documentType: doc.type,
    createdAt: doc.createdAt,
    updatedAt: doc.updatedAt,
    memories: doc.memoryEntries.map((mem): GraphApiMemory => ({
      id: mem.id,
      memory: mem.memory ?? mem.content ?? '',
      content: mem.content ?? null,
      isStatic: mem.isStatic ?? false,
      spaceId: mem.spaceId ?? '',
      isLatest: mem.isLatest ?? true,
      isForgotten: mem.isForgotten ?? false,
      forgetAfter: mem.forgetAfter ?? null,
      forgetReason: mem.forgetReason ?? null,
      version: mem.version ?? 1,
      parentMemoryId: mem.parentMemoryId ?? null,
      rootMemoryId: mem.rootMemoryId ?? null,
      createdAt: mem.createdAt,
      updatedAt: mem.updatedAt,
      relation: mem.relation ?? null,
      updatesMemoryId: mem.updatesMemoryId ?? null,
      nextVersionId: mem.nextVersionId ?? null,
      memoryRelations: mem.memoryRelations ?? null,
      spaceContainerTag: mem.spaceContainerTag ?? null,
    })),
  };
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const response = await fetch('https://api.supermemory.ai/v3/documents/documents', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    },
    body: JSON.stringify({ page: 1, limit: 500, sort: 'createdAt', order: 'desc' }),
  });

  const data: RawDocumentsResponse = await response.json();
  res.json({
    documents: data.documents.map(toGraphDocument),
    pagination: data.pagination,
  });
}
```

```javascript Express
app.get('/api/graph', async (req, res) => {
  const response = await fetch('https://api.supermemory.ai/v3/documents/documents', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    },
    body: JSON.stringify({ page: 1, limit: 500, sort: 'createdAt', order: 'desc' }),
  });

  const data = await response.json();

  // Map the raw API document (`type` / `memoryEntries`) onto the shape
  // <MemoryGraph> expects (`documentType` / `memories`), filling in the
  // defaults for fields the API may omit.
  const documents = data.documents.map((doc) => ({
    id: doc.id,
    title: doc.title,
    summary: doc.summary ?? null,
    documentType: doc.type,
    createdAt: doc.createdAt,
    updatedAt: doc.updatedAt,
    memories: doc.memoryEntries.map((mem) => ({
      id: mem.id,
      memory: mem.memory ?? mem.content ?? '',
      content: mem.content ?? null,
      isStatic: mem.isStatic ?? false,
      spaceId: mem.spaceId ?? '',
      isLatest: mem.isLatest ?? true,
      isForgotten: mem.isForgotten ?? false,
      forgetAfter: mem.forgetAfter ?? null,
      forgetReason: mem.forgetReason ?? null,
      version: mem.version ?? 1,
      parentMemoryId: mem.parentMemoryId ?? null,
      rootMemoryId: mem.rootMemoryId ?? null,
      createdAt: mem.createdAt,
      updatedAt: mem.updatedAt,
      relation: mem.relation ?? null,
      updatesMemoryId: mem.updatesMemoryId ?? null,
      nextVersionId: mem.nextVersionId ?? null,
      memoryRelations: mem.memoryRelations ?? null,
      spaceContainerTag: mem.spaceContainerTag ?? null,
    })),
  }));

  res.json({ documents, pagination: data.pagination });
});
```

</CodeGroup>

<Warning>
  Never expose your Supermemory API key to the client. Always fetch data through your backend.
</Warning>

---

## Variants

**Console Variant** - Full-featured dashboard view (0.8x initial zoom):

```tsx
<MemoryGraph documents={documents} variant="console" />
```

**Consumer Variant** - Embedded widget view (0.5x initial zoom):

```tsx
<MemoryGraph documents={documents} variant="consumer" />
```

---

## Examples

### With pagination

```tsx
'use client';

import { MemoryGraph } from '@supermemory/memory-graph';
import type { GraphApiDocument } from '@supermemory/memory-graph';
import { useCallback, useEffect, useState } from 'react';

export default function PaginatedGraph() {
  const [documents, setDocuments] = useState<GraphApiDocument[]>([]);
  const [page, setPage] = useState(1);
  const [hasMore, setHasMore] = useState(true);
  const [isLoading, setIsLoading] = useState(true);
  const [isLoadingMore, setIsLoadingMore] = useState(false);

  useEffect(() => { fetchPage(1, false); }, []);

  const fetchPage = async (pageNum, append) => {
    pageNum === 1 ? setIsLoading(true) : setIsLoadingMore(true);

    const res = await fetch(`/api/graph?page=${pageNum}&limit=100`);
    const data = await res.json();

    append ? setDocuments(prev => [...prev, ...data.documents]) : setDocuments(data.documents);
    setHasMore(data.pagination.currentPage < data.pagination.totalPages);
    setIsLoading(false);
    setIsLoadingMore(false);
  };

  const loadMore = useCallback(async () => {
    if (!isLoadingMore && hasMore) {
      const nextPage = page + 1;
      setPage(nextPage);
      await fetchPage(nextPage, true);
    }
  }, [page, hasMore, isLoadingMore]);

  return (
    <MemoryGraph
      documents={documents}
      isLoading={isLoading}
      isLoadingMore={isLoadingMore}
      hasMore={hasMore}
      totalCount={documents.length}
      onLoadMore={loadMore}
    />
  );
}
```

### Highlighting search results

```tsx
<MemoryGraph
  documents={documents}
  highlightDocumentIds={searchResults}
  highlightsVisible={searchResults.length > 0}
/>
```

### Custom empty state

```tsx
<MemoryGraph documents={documents} isLoading={isLoading}>
  <div style={{ textAlign: 'center', padding: '2rem' }}>
    <h2>No memories yet</h2>
    <p>Add content to see your knowledge graph</p>
  </div>
</MemoryGraph>
```

---

## Props reference

### Core props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `documents` | `GraphApiDocument[]` | `[]` | Documents to display - pass this for direct data mode |
| `isLoading` | `boolean` | `false` | Whether data is loading |
| `error` | `Error \| null` | `null` | Error from data fetching |
| `variant` | `"console" \| "consumer"` | `"console"` | Visual variant |
| `children` | `ReactNode` | - | Rendered when there are no documents |

### Pagination props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isLoadingMore` | `boolean` | `false` | Whether more data is being loaded |
| `hasMore` | `boolean` | `false` | Whether there are more documents to load |
| `onLoadMore` | `() => void` | - | Callback to load more documents |
| `totalCount` | `number` | - | Total count, used by the loading indicator |

### Display props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `highlightDocumentIds` | `string[]` | `[]` | Document IDs to highlight |
| `highlightsVisible` | `boolean` | `true` | Whether highlights are visible |
| `showFps` | `boolean` | `false` | Show FPS counter overlay |
| `canvasRef` | `RefObject<HTMLCanvasElement \| null>` | - | External ref to the canvas (e.g. for screenshot export) |
| `colors` | `Partial<GraphThemeColors>` | - | Custom theme colors, merged with CSS-variable/default values |
| `labels` | `MemoryGraphLabels` | - | Custom user-facing labels, merged with defaults |
| `layering` | `MemoryGraphLayering` | - | Overlay layering controls (e.g. hover popover z-index) |
| `appearance` | `GraphAppearance` | - | Opt-in `documentNodes: 'stacked'` and `connections: 'emphasized'` rendering |

### Filtering props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `maxNodes` | `number` | - | Caps the total document plus memory node count |

`containerTags`, `documentIds` and `legendId` are in `MemoryGraphProps` but `MemoryGraph` does not use them. Filter `documents` before you pass them in.

### Slideshow props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isSlideshowActive` | `boolean` | - | Whether slideshow mode is active |
| `onSlideshowNodeChange` | `(nodeId: string \| null) => void` | - | Called as the slideshow moves between nodes |
| `onSlideshowStop` | `() => void` | - | Called when the slideshow ends |

### Other

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onOpenDocument` | `(documentId: string) => void` | - | Called when the user wants to view a document's full content |
| `openDocumentOnEnter` | `boolean` | `false` | Let Enter call `onOpenDocument` for the selected document |

---

## Data types

### GraphApiDocument / GraphApiMemory

This is the shape `documents` actually takes: `documentType` and `memories`, matching what the API route in [Backend API Route](#backend-api-route) normalizes into:

```typescript
interface GraphApiDocument {
  id: string;
  title: string | null;
  summary: string | null;
  documentType: string;
  createdAt: string;
  updatedAt: string;
  memories: GraphApiMemory[];
}

interface GraphApiMemory {
  id: string;
  memory: string;
  content?: string | null;
  isStatic: boolean;
  spaceId: string;
  isLatest: boolean;
  isForgotten: boolean;
  forgetAfter: string | null;
  forgetReason: string | null;
  version: number;
  parentMemoryId: string | null;
  rootMemoryId: string | null;
  createdAt: string;
  updatedAt: string;
  relation?: 'updates' | 'extends' | 'derives' | null;
  updatesMemoryId?: string | null;
  nextVersionId?: string | null;
  memoryRelations?: Record<string, 'updates' | 'extends' | 'derives'> | null;
  spaceContainerTag?: string | null;
}
```

### DocumentWithMemories / MemoryEntry

Also exported for backward compatibility with older API response shapes. Not what `documents` takes today, but still useful for typing a raw fetch response before mapping it to `GraphApiDocument`:

```typescript
interface DocumentWithMemories {
  id: string;
  title: string | null;
  url: string | null;
  documentType: string;
  createdAt: string;
  updatedAt: string;
  summary?: string | null;
  memories: MemoryEntry[];
}

interface MemoryEntry {
  id: string;
  memory: string;
  content?: string | null;
  createdAt: string;
  updatedAt: string;
  spaceId?: string | null;
  isStatic?: boolean;
  isForgotten?: boolean;
  forgetAfter?: string | null;
  forgetReason?: string | null;
  version?: number;
  parentMemoryId?: string | null;
  rootMemoryId?: string | null;
  isLatest?: boolean;
  relation?: 'updates' | 'extends' | 'derives' | null;
  spaceContainerTag?: string | null;
}
```

---

## Exports

### Components

```typescript
import { MemoryGraph, GraphCanvas } from '@supermemory/memory-graph';
```

### Hooks

```typescript
import { useGraphData, useGraphTheme } from '@supermemory/memory-graph';
```

### Engine classes

For advanced usage: driving the force simulation, viewport, or hit-testing directly:

```typescript
import {
  ForceSimulation,
  ViewportState,
  SpatialIndex,
  VersionChainIndex,
} from '@supermemory/memory-graph';
```

### Constants

```typescript
import {
  DEFAULT_COLORS,
  DEFAULT_HOVER_POPOVER_Z_INDEX,
  DEFAULT_LABELS,
  FORCE_CONFIG,
  GRAPH_SETTINGS,
} from '@supermemory/memory-graph';
```

### Mock data

`@supermemory/memory-graph/mock-data` generates fake `GraphApiDocument[]` data for local development and stress testing, without a live API key:

```typescript
import { generateMockGraphData } from '@supermemory/memory-graph/mock-data';

const { documents } = generateMockGraphData({
  documentCount: 100,
  memoriesPerDoc: [2, 5],
  seed: 12345,
});
```

---

## Performance

The graph handles hundreds of nodes efficiently through:
- Canvas-based rendering (not DOM elements)
- Viewport culling (only draws visible nodes)
- Level-of-detail optimization (simplifies when zoomed out)
- Change-based rendering (only redraws when state changes)

For very large datasets (1000+ documents), use pagination to load data in chunks.

## Browser support

Works in all modern browsers supporting Canvas 2D API, ES2020, and CSS custom properties. Tested on Chrome, Firefox, Safari, and Edge.