supermemory/packages/memory-graph/README.md

@supermemory/memory-graph

Interactive graph visualization for documents and their memory connections.

Installation

npm install @supermemory/memory-graph
# or
bun add @supermemory/memory-graph
# or
pnpm add @supermemory/memory-graph

Quick Start

import { MemoryGraph } from '@supermemory/memory-graph';
import type { DocumentWithMemories } from '@supermemory/memory-graph';

function App() {
  const [documents, setDocuments] = useState<DocumentWithMemories[]>([]);
  const [isLoading, setIsLoading] = useState(true);

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

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

Features

• Interactive canvas visualization - Pan, zoom, and drag nodes using Canvas 2D rendering
• Document and memory nodes - Documents as rectangles, memories as hexagons
• Relationship visualization - Edges show document similarity and memory version chains
• Space filtering - Filter by workspace or view all memories
• Two variants - Full-featured console mode or embedded consumer mode
• Pagination support - Keep the initial graph fitted as pages arrive; manual pan, zoom, or selection takes control of the view
• TypeScript support - Full type definitions included

Essential Props

Prop	Type	Description
documents	DocumentWithMemories[]	Array of documents with their memory entries
isLoading	boolean	Show loading state
variant	"console" | "consumer"	Display mode (default: "console")
error	Error | null	Error to display
loadMoreDocuments	() => Promise<void>	Function to load more data
highlightDocumentIds	string[]	IDs of documents to highlight

Console mode uses the supplied theme colors for its surface, 16px dot grid, document icons, and node fills and strokes. Consumer mode keeps its transparent surface and cluster colors.

Set colors.dotColor or the --graph-dot CSS variable to style the dot grid independently of text. When neither is set, the grid uses textMuted.

For paginated initial loading, pass hasMore and isLoadingMore alongside documents. In both variants, new batches gradually warm the force layout from the existing node positions. Initial and appended nodes relax until their movement stays low, then cool automatically; a tick limit bounds settling for layouts that keep drifting. The initial view smoothly follows the changing bounds until loading and settling finish. Manual interaction immediately cancels automatic camera movement. Clicking a node selects it without restarting the forces; dragging warms the layout until release, including release outside the canvas. Changing the document selection starts a new fit; the Fit control remains available at any time. The existing static layout safeguard for more than 6,000 nodes remains in place.

Documentation

Full documentation available at docs.supermemory.ai:

• Overview - What it is and when to use it
• Installation - Setup and requirements
• Quick Start - Get running in 2 minutes
• API Reference - Complete API documentation
• Examples - Common use cases
• Troubleshooting - Common issues

Requirements

• React 18+
• Modern browser

License

MIT

Links

• GitHub
• Issues
• Supermemory