1 files changed, 405 insertions, 0 deletions
diff --git a/apps/docs/memory-graph/api-reference.mdx b/apps/docs/memory-graph/api-reference.mdx
new file mode 100644
index 00000000..f6dc00c2
--- /dev/null
+++ b/apps/docs/memory-graph/api-reference.mdx
@@ -0,0 +1,405 @@
+---
+title: "API Reference"
+description: "Complete reference for props, types, and configuration options"
+sidebarTitle: "API Reference"
+---
+
+## Component Props
+
+### Core Props
+
+<ParamField path="documents" type="DocumentWithMemories[]" required>
+  Array of documents with their associated memories to display in the graph. This is the primary data source for the visualization.
+
+  ```tsx
+  <MemoryGraph
+    documents={[
+      {
+        id: "doc-1",
+        title: "Meeting Notes",
+        memoryEntries: [
+          {
+            id: "mem-1",
+            documentId: "doc-1",
+            content: "Discussed project roadmap",
+            // ... other memory fields
+          }
+        ]
+      }
+    ]}
+  />
+  ```
+</ParamField>
+
+<ParamField path="isLoading" type="boolean" default="false">
+  Indicates whether the initial data is currently loading. Shows a loading indicator overlay.
+
+  ```tsx
+  <MemoryGraph
+    documents={documents}
+    isLoading={true}
+  />
+  ```
+</ParamField>
+
+<ParamField path="error" type="Error | null" default="null">
+  Error object to display if data fetching fails. Shows an error state with the error message.
+
+  ```tsx
+  <MemoryGraph
+    documents={documents}
+    error={new Error('Failed to load graph data')}
+  />
+  ```
+</ParamField>
+
+<ParamField path="children" type="ReactNode">
+  Content to display when no documents are available. Useful for custom empty states.
+
+  ```tsx
+  <MemoryGraph documents={[]}>
+    <div>
+      <h2>No memories yet</h2>
+      <button>Add Memory</button>
+    </div>
+  </MemoryGraph>
+  ```
+</ParamField>
+
+### Display Props
+
+<ParamField path="variant" type="'console' | 'consumer'" default="'console'">
+  Visual variant that determines the default zoom level and UI layout.
+
+  - **console**: Full dashboard view (zoom: 0.8, spaces selector shown, legend bottom-right)
+  - **consumer**: Embedded widget view (zoom: 0.5, spaces selector hidden, legend top-right)
+
+  ```tsx
+  {/* Full dashboard */}
+  <MemoryGraph documents={documents} variant="console" />
+
+  {/* Embedded widget */}
+  <MemoryGraph documents={documents} variant="consumer" />
+  ```
+</ParamField>
+
+<ParamField path="showSpacesSelector" type="boolean" default="Based on variant">
+  Controls visibility of the spaces/container filter dropdown. Defaults to `true` for console variant, `false` for consumer variant.
+
+  ```tsx
+  {/* Force show on consumer variant */}
+  <MemoryGraph
+    documents={documents}
+    variant="consumer"
+    showSpacesSelector={true}
+  />
+  ```
+</ParamField>
+
+<ParamField path="legendId" type="string">
+  Custom ID for the legend element. Useful for DOM targeting or testing.
+
+  ```tsx
+  <MemoryGraph
+    documents={documents}
+    legendId="my-custom-legend"
+  />
+  ```
+</ParamField>
+
+### Highlighting Props
+
+<ParamField path="highlightDocumentIds" type="string[]" default="[]">
+  Array of document IDs to highlight in the graph. Supports both internal IDs and custom IDs. Perfect for showing search results or filtered content.
+
+  ```tsx
+  <MemoryGraph
+    documents={documents}
+    highlightDocumentIds={['doc-123', 'custom-id-456']}
+  />
+  ```
+</ParamField>
+
+<ParamField path="highlightsVisible" type="boolean" default="true">
+  Controls whether highlights are currently visible. Useful for toggling highlights on/off.
+
+  ```tsx
+  const [showHighlights, setShowHighlights] = useState(true)
+
+  <MemoryGraph
+    documents={documents}
+    highlightDocumentIds={searchResults}
+    highlightsVisible={showHighlights}
+  />
+  ```
+</ParamField>
+
+### Pagination Props
+
+For large datasets, implement pagination to load documents incrementally:
+
+<ParamField path="isLoadingMore" type="boolean" default="false">
+  Indicates whether additional data is being loaded. Shows a loading indicator without blocking interactions.
+
+  ```tsx
+  <MemoryGraph
+    documents={documents}
+    isLoadingMore={true}
+  />
+  ```
+</ParamField>
+
+<ParamField path="hasMore" type="boolean" default="false">
+  Indicates whether more documents are available to load.
+
+  ```tsx
+  <MemoryGraph
+    documents={documents}
+    hasMore={page < totalPages}
+  />
+  ```
+</ParamField>
+
+<ParamField path="totalLoaded" type="number" default="documents.length">
+  Total number of documents currently loaded. Displayed in the loading indicator.
+
+  ```tsx
+  <MemoryGraph
+    documents={documents}
+    totalLoaded={documents.length}
+  />
+  ```
+</ParamField>
+
+<ParamField path="loadMoreDocuments" type="() => Promise<void>">
+  Async callback function to load more documents. Called automatically when user scrolls near the viewport edge.
+
+  ```tsx
+  const loadMore = async () => {
+    const nextPage = await fetchNextPage()
+    setDocuments(prev => [...prev, ...nextPage])
+  }
+
+  <MemoryGraph
+    documents={documents}
+    hasMore={true}
+    loadMoreDocuments={loadMore}
+  />
+  ```
+</ParamField>
+
+### Advanced Props
+
+<ParamField path="occludedRightPx" type="number" default="0">
+  Number of pixels occluded on the right side (e.g., by a chat panel). Used to adjust auto-fit calculations.
+
+  ```tsx
+  {/* Account for 400px chat panel on the right */}
+  <MemoryGraph
+    documents={documents}
+    occludedRightPx={400}
+  />
+  ```
+</ParamField>
+
+<ParamField path="autoLoadOnViewport" type="boolean" default="true">
+  Enable automatic loading when 80% of documents are visible in viewport. Set to `false` for manual pagination control.
+
+  ```tsx
+  <MemoryGraph
+    documents={documents}
+    hasMore={true}
+    loadMoreDocuments={loadMore}
+    autoLoadOnViewport={false}
+  />
+  ```
+</ParamField>
+
+<ParamField path="themeClassName" type="string">
+  Custom theme class name for styling overrides. Use with Vanilla Extract theme system.
+
+  ```tsx
+  import { customTheme } from './my-theme.css'
+
+  <MemoryGraph
+    documents={documents}
+    themeClassName={customTheme}
+  />
+  ```
+</ParamField>
+
+## TypeScript Types
+
+### Core Data Types
+
+```typescript
+interface DocumentWithMemories {
+  id: string
+  customId?: string | null
+  title?: string
+  content?: string
+  summary?: string
+  url?: string
+  summaryEmbedding?: number[]  // For similarity calculations
+  memoryEntries: MemoryEntry[]
+  createdAt: string
+  updatedAt: string
+  userId?: string
+  spaceId?: string
+  spaceContainerTag?: string
+}
+
+interface MemoryEntry {
+  id: string
+  documentId: string
+  content: string | null
+  embedding?: number[]
+  spaceContainerTag?: string
+  spaceId?: string
+  updatesMemoryId?: string | null
+  relation?: 'updates' | 'extends' | 'derives' | null
+  isForgotten?: boolean
+  isLatest?: boolean
+  forgetAfter?: string | null
+  createdAt: string
+  updatedAt: string
+}
+```
+
+### Graph Types
+
+```typescript
+interface GraphNode {
+  id: string
+  type: 'document' | 'memory'
+  x: number
+  y: number
+  data: DocumentWithMemories | MemoryEntry
+  size: number
+  color: string
+  isHovered: boolean
+  isDragging: boolean
+}
+
+interface GraphEdge {
+  id: string
+  source: string
+  target: string
+  similarity: number  // 0-1 for semantic similarity
+  visualProps: {
+    opacity: number
+    thickness: number
+    glow: number
+    pulseDuration: number
+  }
+  color: string
+  edgeType: 'doc-memory' | 'doc-doc' | 'version'
+  relationType?: 'updates' | 'extends' | 'derives'
+}
+```
+
+### Component Props Type
+
+```typescript
+interface MemoryGraphProps {
+  // Core
+  documents: DocumentWithMemories[]
+  isLoading?: boolean
+  error?: Error | null
+  children?: ReactNode
+
+  // Display
+  variant?: 'console' | 'consumer'
+  showSpacesSelector?: boolean
+  legendId?: string
+
+  // Highlighting
+  highlightDocumentIds?: string[]
+  highlightsVisible?: boolean
+
+  // Pagination
+  isLoadingMore?: boolean
+  hasMore?: boolean
+  totalLoaded?: number
+  loadMoreDocuments?: () => Promise<void>
+
+  // Advanced
+  occludedRightPx?: number
+  autoLoadOnViewport?: boolean
+  themeClassName?: string
+}
+```
+
+## Variants Comparison
+
+| Feature | Console | Consumer |
+|---------|---------|----------|
+| **Initial Zoom** | 0.8 (closer view) | 0.5 (wider view) |
+| **Spaces Selector** | Shown by default | Hidden by default |
+| **Legend Position** | Bottom-right | Top-right |
+| **Best For** | Full-page dashboards | Embedded widgets |
+| **Use Cases** | Admin panels, analytics | Sidebars, chat integration |
+
+### Console Variant
+
+```tsx
+<MemoryGraph
+  documents={documents}
+  variant="console"
+  // Spaces selector shown
+  // Legend in bottom-right
+  // Closer initial view
+/>
+```
+
+{/* TODO: Add console variant screenshot */}
+
+### Consumer Variant
+
+```tsx
+<MemoryGraph
+  documents={documents}
+  variant="consumer"
+  // Spaces selector hidden
+  // Legend in top-right
+  // Wider initial view
+/>
+```
+
+{/* TODO: Add consumer variant screenshot */}
+
+## Type Imports
+
+Import all types you need for TypeScript:
+
+```typescript
+import type {
+  // Data types
+  DocumentWithMemories,
+  MemoryEntry,
+  DocumentsResponse,
+
+  // Graph types
+  GraphNode,
+  GraphEdge,
+  MemoryRelation,
+
+  // Component types
+  MemoryGraphProps,
+
+  // Theme types (if customizing)
+  Sprinkles,
+} from '@supermemory/memory-graph'
+```
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Examples" icon="code" href="/memory-graph/examples">
+    See real-world implementation patterns
+  </Card>
+
+  <Card title="Troubleshooting" icon="wrench" href="/memory-graph/troubleshooting">
+    Solve common issues
+  </Card>
+</CardGroup>