From 1b9b3012e37284d67d9061c6a13dd53cfeb7463f Mon Sep 17 00:00:00 2001
From: nexxeln <95541290+nexxeln@users.noreply.github.com>
Date: Thu, 4 Dec 2025 18:56:40 +0000
Subject: add docs for graph package (#603)
---
apps/docs/memory-graph/api-reference.mdx | 334 +++++++++++++++++++++++++++++++
1 file changed, 334 insertions(+)
create mode 100644 apps/docs/memory-graph/api-reference.mdx
(limited to 'apps/docs/memory-graph/api-reference.mdx')
diff --git a/apps/docs/memory-graph/api-reference.mdx b/apps/docs/memory-graph/api-reference.mdx
new file mode 100644
index 00000000..92641a74
--- /dev/null
+++ b/apps/docs/memory-graph/api-reference.mdx
@@ -0,0 +1,334 @@
+---
+title: 'API Reference'
+description: 'Complete reference for Memory Graph props and types'
+---
+
+## Component Props
+
+### MemoryGraph
+
+The main graph component.
+
+#### Core Props
+
+
+ Array of documents to display in the graph. Each document must include its memory entries.
+
+
+
+ Shows a loading indicator when true.
+
+
+
+ Error object to display. Shows an error message overlay when set.
+
+
+
+ Visual variant:
+ - `console`: Full-featured dashboard view (0.8x zoom, space selector visible)
+ - `consumer`: Embedded widget view (0.5x zoom, space selector hidden)
+
+
+
+ Content to render when no documents exist. Useful for empty states.
+
+
+#### Pagination Props
+
+
+ Shows a subtle indicator when loading additional documents.
+
+
+
+ Whether more documents are available to load.
+
+
+
+ Total number of documents currently loaded. Shown in loading indicator.
+
+
+
+ Callback to load more documents. Called automatically when viewport shows most documents.
+
+
+
+ Automatically load more documents when 80% are visible in viewport.
+
+
+#### Display Props
+
+
+ Show or hide the space filter dropdown. Defaults to `true` for console variant, `false` for consumer.
+
+
+
+ Array of document IDs to highlight with a pulsing outline. Accepts both `customId` and internal `id`.
+
+
+
+ Controls whether highlights are shown. Useful for toggling highlights without changing the array.
+
+
+
+ Pixels occluded on the right side (e.g., by a sidebar). Graph auto-fits accounting for this space.
+
+
+
+ Custom ID for the legend component. Useful for testing or styling.
+
+
+#### Controlled State Props
+
+
+ Currently selected space. When provided, makes space selection controlled. Use `"all"` for all spaces.
+
+
+
+ Callback when space selection changes. Required when using `selectedSpace`.
+
+
+
+ Maximum memories to show per document when a specific space is selected. Only applies when `selectedSpace !== "all"`.
+
+
+
+ Enable experimental features. Currently unused but reserved for future features.
+
+
+## Data Types
+
+### DocumentWithMemories
+
+```typescript
+interface DocumentWithMemories {
+ id: string;
+ customId?: string | null;
+ contentHash: string | null;
+ orgId: string;
+ userId: string;
+ connectionId?: string | null;
+ title?: string | null;
+ content?: string | null;
+ summary?: string | null;
+ url?: string | null;
+ source?: string | null;
+ type?: string | null;
+ status: 'pending' | 'processing' | 'done' | 'failed';
+ metadata?: Record | null;
+ processingMetadata?: Record | null;
+ raw?: string | null;
+ tokenCount?: number | null;
+ wordCount?: number | null;
+ chunkCount?: number | null;
+ averageChunkSize?: number | null;
+ summaryEmbedding?: number[] | null;
+ summaryEmbeddingModel?: string | null;
+ createdAt: string | Date;
+ updatedAt: string | Date;
+ memoryEntries: MemoryEntry[];
+}
+```
+
+### MemoryEntry
+
+```typescript
+interface MemoryEntry {
+ id: string;
+ customId?: string | null;
+ documentId: string;
+ content: string | null;
+ summary?: string | null;
+ title?: string | null;
+ url?: string | null;
+ type?: string | null;
+ metadata?: Record | null;
+ embedding?: number[] | null;
+ embeddingModel?: string | null;
+ tokenCount?: number | null;
+ createdAt: string | Date;
+ updatedAt: string | Date;
+
+ // Fields from join relationship
+ sourceAddedAt?: Date | null;
+ sourceRelevanceScore?: number | null;
+ sourceMetadata?: Record | null;
+ spaceContainerTag?: string | null;
+
+ // Version chain fields
+ updatesMemoryId?: string | null;
+ nextVersionId?: string | null;
+ relation?: 'updates' | 'extends' | 'derives' | null;
+
+ // Memory status fields
+ isForgotten?: boolean;
+ forgetAfter?: Date | string | null;
+ isLatest?: boolean;
+
+ // Space/container fields
+ spaceId?: string | null;
+
+ // Legacy fields (for backwards compatibility)
+ memory?: string | null;
+ memoryRelations?: Array<{
+ relationType: 'updates' | 'extends' | 'derives';
+ targetMemoryId: string;
+ }> | null;
+ parentMemoryId?: string | null;
+}
+```
+
+### GraphNode
+
+Internal type for rendered nodes:
+
+```typescript
+interface GraphNode {
+ id: string;
+ type: 'document' | 'memory';
+ x: number;
+ y: number;
+ data: DocumentWithMemories | MemoryEntry;
+ size: number;
+ color: string;
+ isHovered: boolean;
+ isDragging: boolean;
+}
+```
+
+### GraphEdge
+
+Internal type for connections:
+
+```typescript
+interface GraphEdge {
+ id: string;
+ source: string;
+ target: string;
+ similarity: number;
+ edgeType: 'doc-memory' | 'doc-doc' | 'version';
+ relationType?: 'updates' | 'extends' | 'derives';
+ color: string;
+ visualProps: {
+ opacity: number;
+ thickness: number;
+ glow: number;
+ pulseDuration: number;
+ };
+}
+```
+
+## Exported Components
+
+Besides `MemoryGraph`, the package exports individual components for advanced use cases:
+
+### GraphCanvas
+
+Low-level canvas renderer. Not recommended for direct use.
+
+```typescript
+import { GraphCanvas } from '@supermemory/memory-graph';
+```
+
+### Legend
+
+Graph legend showing node types and counts.
+
+```typescript
+import { Legend } from '@supermemory/memory-graph';
+```
+
+### LoadingIndicator
+
+Loading state indicator with progress counter.
+
+```typescript
+import { LoadingIndicator } from '@supermemory/memory-graph';
+```
+
+### NodeDetailPanel
+
+Side panel showing node details when clicked.
+
+```typescript
+import { NodeDetailPanel } from '@supermemory/memory-graph';
+```
+
+### SpacesDropdown
+
+Space filter dropdown.
+
+```typescript
+import { SpacesDropdown } from '@supermemory/memory-graph';
+```
+
+## Exported Hooks
+
+### useGraphData
+
+Processes documents into graph nodes and edges.
+
+```typescript
+import { useGraphData } from '@supermemory/memory-graph';
+
+const { nodes, edges } = useGraphData(
+ data,
+ selectedSpace,
+ nodePositions,
+ draggingNodeId,
+ memoryLimit
+);
+```
+
+### useGraphInteractions
+
+Handles pan, zoom, and node interactions.
+
+```typescript
+import { useGraphInteractions } from '@supermemory/memory-graph';
+
+const {
+ panX,
+ panY,
+ zoom,
+ selectedNode,
+ handlePanStart,
+ handleWheel,
+ // ... more interaction handlers
+} = useGraphInteractions('console');
+```
+
+## Constants
+
+### colors
+
+Color palette used throughout the graph:
+
+```typescript
+import { colors } from '@supermemory/memory-graph';
+
+colors.document.primary; // Document fill color
+colors.memory.primary; // Memory fill color
+colors.connection.strong; // Strong edge color
+```
+
+### GRAPH_SETTINGS
+
+Initial zoom and pan settings for variants:
+
+```typescript
+import { GRAPH_SETTINGS } from '@supermemory/memory-graph';
+
+GRAPH_SETTINGS.console.initialZoom; // 0.8
+GRAPH_SETTINGS.consumer.initialZoom; // 0.5
+```
+
+### LAYOUT_CONSTANTS
+
+Spatial layout configuration:
+
+```typescript
+import { LAYOUT_CONSTANTS } from '@supermemory/memory-graph';
+
+LAYOUT_CONSTANTS.clusterRadius; // Memory orbit radius
+LAYOUT_CONSTANTS.documentSpacing; // Distance between documents
+```
--
cgit v1.2.3