Graph Viewer

SmartMemory ships two ways to inspect your knowledge graph visually:

The viewer is the thin shell. All graph code lives in the package, so you can drop the same explorer into any React app.

Standalone Viewer

The standalone viewer runs on port 5178.

cd smart-memory-viewer
npm install
npm run dev

Open http://localhost:5178. It expects a SmartMemory API on VITE_API_URL (default http://localhost:9001) and an Insights WebSocket on VITE_WS_URL (default ws://localhost:9003/events).

.env:

VITE_API_URL=http://localhost:9001
VITE_WS_URL=ws://localhost:9003/events

What you see

• Nodes — memory items (semantic, episodic, procedural, decision, opinion, observation, code…) and entities (concept, person, organization, location, technology…). Wikidata-grounded entities show as a separate wikidata:Qxxx node connected by a GROUNDED_IN edge.
• Edges — RELATED_TO, MENTIONS, GROUNDED_IN, PART_OF, SUPERSEDES, DERIVED_FROM, plus any custom relation labels promoted into the workspace ontology.
• Color coding — driven by contracts/graph-colors.json. Memory types use warm colors (semantic #f59e0b, episodic #f97316, decision #8b5cf6); entity types use cool colors (concept #3b82f6, person #f472b6, technology #0ea5e9). The same constants are exported as MEMORY_COLORS, ENTITY_COLORS, SPECIAL_COLORS from @smartmemory/graph.
• Type filters — color-coded checkboxes for memory types and entity types
• Search — fuzzy node-label search (Cmd/Ctrl+K)
• Detail panel — click a node to see content, metadata, confidence, timestamps
• Path finder — pick two nodes, find the shortest path
• Entity corrections — rename, retype, ground to Wikipedia
• 5 layout algorithms — force-directed (cose-bilkent), hierarchical (dagre), circle, concentric, grid
• Export — PNG (2x) or SVG via exportPNG / exportSVG

Live-feed mode

When the viewer is connected to a streaming source, it animates ingestion in real time using the Progress Event Bus (PLAT-PROGRESS-1). Events with kinds like graph.node, graph.edge, and pipeline.stage are converted via eventToGraphNode / eventToGraphEdge and dripped onto the canvas with original_ts pacing.

Two transports are supported:

• WebSocket to VITE_WS_URL (Insights bridge — used by the standalone viewer today)
• SSE at GET /memory/progress/stream on the SmartMemory API (workspace-scoped Redis Streams; see Progress Events)

Embedding @smartmemory/graph

The package is consumed locally via a file: dependency. The published name on npm is TBD — until it ships, link to it from a sibling checkout.

package.json:

{
  "dependencies": {
    "@smartmemory/graph": "file:../smart-memory-graph"
  }
}

Minimal example

import { GraphExplorer, createFetchAdapter } from '@smartmemory/graph';
import '@smartmemory/graph/src/graph.css';

const adapter = createFetchAdapter({
  apiUrl: 'http://localhost:9001',
  getToken: () => localStorage.getItem('access_token'),
  getTeamId: () => localStorage.getItem('team_id'),
});

export default function App() {
  return (
    <div style={{ height: '100vh' }}>
      <GraphExplorer
        adapter={adapter}
        wsUrl="ws://localhost:9001/ws/insights"
      />
    </div>
  );
}

Adapters

The package decouples transport from rendering through a 14-method GraphAPIAdapter interface. Two built-in adapters:

• createFetchAdapter({ apiUrl, getToken, getTeamId }) — for standalone apps (used by smart-memory-viewer)
• createSDKAdapter(sdkClient) — for apps that already have a @smartmemory/sdk-js client

To embed the explorer with the JS SDK:

import { SmartMemoryClient } from '@smartmemory/sdk-js';
import { GraphExplorer, createSDKAdapter } from '@smartmemory/graph';

const client = new SmartMemoryClient({ mode: 'apiKey', apiBaseUrl: '...', apiKey: 'sm_live_...' });
const adapter = createSDKAdapter(client);

<GraphExplorer adapter={adapter} />

Exported pieces

If you need to compose the UI yourself instead of using the all-in-one <GraphExplorer>, the package exports the building blocks:

Components — DetailPanel, FilterPanel, SearchBar, Toolbar, OperationsBar, CytoscapeCanvas, NodeTooltip, WikipediaOverlay, ReplayButton, TimeTravelSlider

Hooks — useGraphData, useGraphFilters, useGraphStream, useGraphInteraction, useDripFeed, useUrlState, useConnectionStatus, useEntityCorrections

Core utilities — getNodeColor, getNodeSize, MEMORY_COLORS, ENTITY_COLORS, LAYOUT_OPTIONS, normalizeAPIResponse, coalesceGraphData, classifyEvent, eventToGraphNode, eventToGraphEdge, exportPNG, exportSVG

Controlled vs uncontrolled

• Uncontrolled (default) — pass adapter, the explorer fetches data itself and manages selection/filter state.
• Controlled — pass a data prop with { nodes, edges }; the explorer renders without fetching. Useful for replays and snapshots.

<GraphExplorer data={{ nodes: [...], edges: [...] }} />

Related

• Progress Events API — live-feed event contract
• System Overview
• Source: smart-memory-graph/README.md, smart-memory-viewer/README.md
• Colors contract: contracts/graph-colors.json