Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

feat(memory-graph): SVG memory-graph panel + model/layout helpers

Chaitanya Giri7ea347b86290
diff --git a/src/renderer/src/components/MemoryGraphPanel.tsx b/src/renderer/src/components/MemoryGraphPanel.tsx
new file mode 100644
index 00000000..65b2d837
--- /dev/null
+++ b/src/renderer/src/components/MemoryGraphPanel.tsx
@@ -0,0 +1,535 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useStore } from '@/store/store';
+import { PixelBadge } from './PixelBadge';
+import { Icon } from './Icon';
+import type { MessageAct } from '@/scene/office/MessageEnvelope';
+import {
+ buildGraph,
+ type GraphData,
+ type GraphNode,
+ type GraphEdge,
+ type MessageLogEntry
+} from './memoryGraph/buildGraph';
+import { forceLayout, type Positions } from './memoryGraph/forceLayout';
+
+/** The memory-graph tab: hive agents as nodes, messages as edges, an optional
+ * topic layer from each agent's memory file. SVG-rendered (DESIGN.md neo-pixel:
+ * square nodes, hard offset shadows, VT323/Pixelify). See MEMORY_GRAPH_SPEC.md.
+ *
+ * All data comes from the existing preload bridge: store.agents + hiveLog +
+ * hiveMemory. No new IPC. Click an agent to jump to its memory; hover to peek. */
+export function MemoryGraphPanel({
+ godId,
+ onJumpToMemory
+}: {
+ godId: string;
+ onJumpToMemory: (agentId: string) => void;
+}) {
+ const agents = useStore((s) => s.agents);
+
+ const [log, setLog] = useState<MessageLogEntry[]>([]);
+ const [showTopics, setShowTopics] = useState(false);
+ const [memories, setMemories] = useState<Record<string, string>>({});
+ const [loadingTopics, setLoadingTopics] = useState(false);
+
+ // ── poll the message log (same cadence as the Activity tab) ──────────────────
+ const refresh = useCallback(async () => {
+ try { setLog((await window.cth.hiveLog(200)) as MessageLogEntry[]); } catch { /* noop */ }
+ }, []);
+ useEffect(() => {
+ refresh();
+ const t = setInterval(refresh, 5000);
+ return () => clearInterval(t);
+ }, [refresh]);
+
+ // ── lazy memory loads: one on hover, all when the topic layer turns on ───────
+ const fetchMemory = useCallback(async (id: string) => {
+ try {
+ const text = await window.cth.hiveMemory(id);
+ setMemories((m) => ({ ...m, [id]: text ?? '' }));
+ } catch { setMemories((m) => ({ ...m, [id]: '' })); }
+ }, []);
+
+ useEffect(() => {
+ if (!showTopics) return;
+ const missing = agents.map((a) => a.id).filter((id) => !(id in memories));
+ if (missing.length === 0) return;
+ setLoadingTopics(true);
+ Promise.all(missing.map((id) => window.cth.hiveMemory(id).then(
+ (t) => [id, t ?? ''] as const,
+ () => [id, ''] as const
+ ))).then((pairs) => {
+ setMemories((m) => ({ ...m, ...Object.fromEntries(pairs) }));
+ setLoadingTopics(false);
+ });
+ }, [showTopics, agents, memories]);
+
+ // ── graph model ──────────────────────────────────────────────────────────────
+ const graph: GraphData = useMemo(
+ () => buildGraph(agents, log, { showTopics, memories }),
+ [agents, log, showTopics, memories]
+ );
+
+ // ── canvas sizing ─────────────────────────────────────────────────────────────
+ const wrapRef = useRef<HTMLDivElement | null>(null);
+ const [dims, setDims] = useState({ w: 640, h: 440 });
+ useEffect(() => {
+ const el = wrapRef.current;
+ if (!el) return;
+ const ro = new ResizeObserver((entries) => {
+ const r = entries[0]?.contentRect;
+ if (r && r.width > 0 && r.height > 0) setDims({ w: Math.round(r.width), h: Math.round(r.height) });
+ });
+ ro.observe(el);
+ return () => ro.disconnect();
+ }, []);
+
+ // ── pinned (dragged) node positions ──────────────────────────────────────────
+ const [pinned, setPinned] = useState<Record<string, { x: number; y: number }>>({});
+
+ // recompute layout only when structure / size / pins change (not on every poll)
+ const structKey = useMemo(
+ () => graph.nodes.map((n) => n.id).join(',') + '|' + graph.edges.map((e) => e.id).join(','),
+ [graph]
+ );
+ const pinnedKey = useMemo(() => JSON.stringify(pinned), [pinned]);
+ const layout: Positions = useMemo(() => {
+ const lnodes = graph.nodes.map((n) => ({
+ id: n.id,
+ gravityBias: n.kind === 'topic' ? 0.6 : n.kind === 'pseudo' ? 1.4 : n.id === godId ? 2.4 : 1
+ }));
+ const ledges = graph.edges.map((e) => ({
+ source: e.source,
+ target: e.target,
+ strength: e.kind === 'topic' ? 0.35 : 0.7 + Math.min(e.weight, 5) * 0.06
+ }));
+ return forceLayout(lnodes, ledges, { width: dims.w, height: dims.h, pinned });
+ // structKey/pinnedKey capture the relevant graph identity; intentional.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [structKey, pinnedKey, dims.w, dims.h, godId]);
+
+ // ── drag ──────────────────────────────────────────────────────────────────────
+ const [live, setLive] = useState<{ id: string; x: number; y: number } | null>(null);
+ const dragOffset = useRef({ x: 0, y: 0 });
+ const moved = useRef(false);
+
+ const toSvg = useCallback((clientX: number, clientY: number) => {
+ const r = wrapRef.current?.getBoundingClientRect();
+ return { x: clientX - (r?.left ?? 0), y: clientY - (r?.top ?? 0) };
+ }, []);
+
+ const posOf = useCallback(
+ (id: string) => (live && live.id === id ? { x: live.x, y: live.y } : layout.get(id)),
+ [live, layout]
+ );
+
+ const startDrag = useCallback((e: React.MouseEvent, id: string) => {
+ e.preventDefault();
+ const p = posOf(id);
+ if (!p) return;
+ const s = toSvg(e.clientX, e.clientY);
+ dragOffset.current = { x: s.x - p.x, y: s.y - p.y };
+ moved.current = false;
+ setLive({ id, x: p.x, y: p.y });
+ }, [posOf, toSvg]);
+
+ useEffect(() => {
+ if (!live) return;
+ const onMove = (ev: MouseEvent) => {
+ const s = toSvg(ev.clientX, ev.clientY);
+ const x = Math.max(8, Math.min(dims.w - 8, s.x - dragOffset.current.x));
+ const y = Math.max(8, Math.min(dims.h - 8, s.y - dragOffset.current.y));
+ moved.current = true;
+ setLive((l) => (l ? { ...l, x, y } : l));
+ };
+ const onUp = () => {
+ setLive((l) => {
+ if (l && moved.current) setPinned((p) => ({ ...p, [l.id]: { x: l.x, y: l.y } }));
+ return null;
+ });
+ };
+ window.addEventListener('mousemove', onMove);
+ window.addEventListener('mouseup', onUp);
+ return () => {
+ window.removeEventListener('mousemove', onMove);
+ window.removeEventListener('mouseup', onUp);
+ };
+ }, [live, toSvg, dims.w, dims.h]);
+
+ // ── hover / tooltip ─────────────────────────────────────────────────────────
+ const [hover, setHover] = useState<
+ | { kind: 'node'; node: GraphNode }
+ | { kind: 'edge'; edge: GraphEdge }
+ | null
+ >(null);
+ const [cursor, setCursor] = useState({ x: 0, y: 0 });
+
+ const onCanvasMove = useCallback((e: React.MouseEvent) => {
+ const s = toSvg(e.clientX, e.clientY);
+ setCursor(s);
+ }, [toSvg]);
+
+ const hoverNode = useCallback((node: GraphNode) => {
+ setHover({ kind: 'node', node });
+ if (node.kind === 'agent' && !(node.id in memories)) fetchMemory(node.id);
+ }, [memories, fetchMemory]);
+
+ const hoverNodeId = hover?.kind === 'node' ? hover.node.id : null;
+ const nodeById = useMemo(() => new Map(graph.nodes.map((n) => [n.id, n])), [graph]);
+
+ const messageEdgeCount = graph.edges.filter((e) => e.kind === 'message').length;
+
+ return (
+ <div style={{ flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column', background: 'var(--cth-paper-200)' }}>
+ {/* toolbar */}
+ <div style={{
+ display: 'flex', alignItems: 'center', gap: 8, padding: '6px 8px', flexShrink: 0,
+ borderBottom: '1px solid var(--cth-ink-300)', background: 'var(--cth-cream-100)', flexWrap: 'wrap'
+ }}>
+ <Toggle on={showTopics} onClick={() => setShowTopics((v) => !v)} label="topics" />
+ <button onClick={refresh} title="Refresh" style={iconBtn}>
+ <Icon name="gear" /> refresh
+ </button>
+ <div style={{ flex: 1 }} />
+ {showTopics && (
+ <span style={{ fontSize: 11, color: 'var(--cth-ink-500)' }}>
+ {loadingTopics ? 'reading memory…' : `showing ${graph.topicShown} of ${graph.topicTotal} topics`}
+ </span>
+ )}
+ </div>
+
+ {/* canvas */}
+ <div ref={wrapRef} style={{ position: 'relative', flex: 1, minHeight: 0, overflow: 'hidden' }}>
+ <svg
+ width={dims.w}
+ height={dims.h}
+ onMouseMove={onCanvasMove}
+ style={{ display: 'block', userSelect: 'none' }}
+ >
+ <defs>
+ <pattern id="mg-grid" width={32} height={32} patternUnits="userSpaceOnUse">
+ <circle cx={1} cy={1} r={1} fill="var(--cth-ink-100)" />
+ </pattern>
+ {MARKER_ACTS.map((act) => (
+ <marker
+ key={act}
+ id={`mg-arrow-${act}`}
+ viewBox="0 0 8 8" refX={7} refY={4}
+ markerWidth={7} markerHeight={7}
+ markerUnits="userSpaceOnUse"
+ orient="auto-start-reverse"
+ >
+ <path d="M0,0 L8,4 L0,8 Z" fill={actColor(act)} />
+ </marker>
+ ))}
+ </defs>
+
+ <rect x={0} y={0} width={dims.w} height={dims.h} fill="var(--cth-paper-100)" />
+ <rect x={0} y={0} width={dims.w} height={dims.h} fill="url(#mg-grid)" />
+
+ {/* edges */}
+ <g>
+ {graph.edges.map((e) => {
+ const sp = posOf(e.source);
+ const tp = posOf(e.target);
+ const sn = nodeById.get(e.source);
+ const tn = nodeById.get(e.target);
+ if (!sp || !tp || !sn || !tn) return null;
+ const isTopic = e.kind === 'topic';
+ const touches = !hoverNodeId || e.source === hoverNodeId || e.target === hoverNodeId;
+ const dx = tp.x - sp.x;
+ const dy = tp.y - sp.y;
+ const dist = Math.hypot(dx, dy) || 1;
+ const ux = dx / dist;
+ const uy = dy / dist;
+ const startArrow = !isTopic && (e.dir === 'bwd' || e.dir === 'both');
+ const endArrow = !isTopic && (e.dir === 'fwd' || e.dir === 'both');
+ const sr = nodeRadius(sn) + (startArrow ? 7 : 2);
+ const tr = nodeRadius(tn) + (endArrow ? 7 : 2);
+ const x1 = sp.x + ux * sr;
+ const y1 = sp.y + uy * sr;
+ const x2 = tp.x - ux * tr;
+ const y2 = tp.y - uy * tr;
+ const stroke = isTopic ? 'var(--cth-ink-300)' : actColor(e.lastAct);
+ const w = isTopic ? 1 : 1 + Math.min(e.weight, 4) * 0.6;
+ return (
+ <line
+ key={e.id}
+ x1={x1} y1={y1} x2={x2} y2={y2}
+ stroke={stroke}
+ strokeWidth={w}
+ strokeDasharray={isTopic ? '3 3' : undefined}
+ opacity={touches ? (isTopic ? 0.55 : 0.9) : 0.12}
+ markerStart={startArrow ? `url(#mg-arrow-${e.lastAct ?? 'inform'})` : undefined}
+ markerEnd={endArrow ? `url(#mg-arrow-${e.lastAct ?? 'inform'})` : undefined}
+ onMouseEnter={() => setHover({ kind: 'edge', edge: e })}
+ onMouseLeave={() => setHover(null)}
+ style={{ cursor: 'default' }}
+ />
+ );
+ })}
+ </g>
+
+ {/* nodes */}
+ <g>
+ {graph.nodes.map((n) => {
+ const p = posOf(n.id);
+ if (!p) return null;
+ const s = nodeSize(n);
+ const half = s / 2;
+ const dim = hoverNodeId && hoverNodeId !== n.id && !isNeighbor(graph, hoverNodeId, n.id);
+ const navigable = n.kind === 'agent';
+ return (
+ <g
+ key={n.id}
+ transform={`translate(${p.x},${p.y})`}
+ opacity={dim ? 0.3 : 1}
+ onMouseEnter={() => hoverNode(n)}
+ onMouseLeave={() => setHover(null)}
+ onMouseDown={(e) => startDrag(e, n.id)}
+ onClick={() => { if (navigable && !moved.current) onJumpToMemory(n.id); }}
+ style={{ cursor: navigable ? 'pointer' : 'grab' }}
+ >
+ {/* hard offset shadow */}
+ <rect x={-half + 2} y={-half + 2} width={s} height={s} fill="var(--cth-ink-900)" />
+ {/* body */}
+ <rect
+ x={-half} y={-half} width={s} height={s}
+ fill={nodeFill(n)}
+ stroke="var(--cth-ink-900)"
+ strokeWidth={n.kind === 'agent' && n.isGod ? 2 : 1.5}
+ />
+ {/* double border for god + human */}
+ {((n.kind === 'agent' && n.isGod) || (n.kind === 'pseudo' && n.id === 'human')) && (
+ <rect x={-half + 3} y={-half + 3} width={s - 6} height={s - 6}
+ fill="none" stroke="var(--cth-ink-900)" strokeWidth={1} />
+ )}
+ {/* status ring for agents */}
+ {n.kind === 'agent' && (
+ <rect x={-half - 2} y={-half - 2} width={s + 4} height={s + 4}
+ fill="none" stroke={`var(--cth-status-${n.status})`} strokeWidth={1.5} />
+ )}
+ </g>
+ );
+ })}
+ </g>
+
+ {/* labels */}
+ <g pointerEvents="none">
+ {graph.nodes.map((n) => {
+ const p = posOf(n.id);
+ if (!p) return null;
+ const dim = hoverNodeId && hoverNodeId !== n.id && !isNeighbor(graph, hoverNodeId, n.id);
+ const below = nodeSize(n) / 2 + 12;
+ const isTopic = n.kind === 'topic';
+ return (
+ <text
+ key={n.id}
+ x={p.x} y={p.y + below}
+ textAnchor="middle"
+ opacity={dim ? 0.25 : 1}
+ style={{
+ fontFamily: isTopic ? 'var(--cth-font-mono)' : 'var(--cth-font-ui)',
+ fontSize: isTopic ? 12 : 11,
+ fill: isTopic ? 'var(--cth-ink-700)' : 'var(--cth-ink-900)'
+ }}
+ >{truncate(n.label, isTopic ? 20 : 16)}</text>
+ );
+ })}
+ </g>
+ </svg>
+
+ {/* empty hint */}
+ {messageEdgeCount === 0 && !showTopics && (
+ <div style={{
+ position: 'absolute', top: 10, left: 0, right: 0, textAlign: 'center',
+ fontSize: 12, color: 'var(--cth-ink-500)', pointerEvents: 'none'
+ }}>No messages logged yet — the hive is quiet. Agents shown as roster.</div>
+ )}
+
+ {/* tooltip */}
+ {hover && (
+ <Tooltip x={cursor.x} y={cursor.y} wrap={dims}>
+ {hover.kind === 'node'
+ ? <NodeTip node={hover.node} memories={memories} />
+ : <EdgeTip edge={hover.edge} nodeById={nodeById} />}
+ </Tooltip>
+ )}
+
+ {/* legend */}
+ <Legend />
+ </div>
+ </div>
+ );
+}
+
+// ─── tooltip bodies ──────────────────────────────────────────────────────────
+
+function NodeTip({ node, memories }: { node: GraphNode; memories: Record<string, string> }) {
+ if (node.kind === 'agent') {
+ const mem = memories[node.id];
+ const snippet = mem === undefined ? 'loading memory…' : memorySnippet(mem);
+ return (
+ <>
+ <div style={tipTitle}>{node.label}</div>
+ <div style={{ display: 'flex', alignItems: 'center', gap: 6, margin: '2px 0 4px' }}>
+ <PixelBadge status={node.status} />
+ <span style={{ fontSize: 11, color: 'var(--cth-ink-500)' }}>{node.degree} message link{node.degree === 1 ? '' : 's'}</span>
+ </div>
+ <div style={tipBody}>{snippet}</div>
+ </>
+ );
+ }
+ if (node.kind === 'topic') {
+ return (
+ <>
+ <div style={tipTitle}>{node.label}</div>
+ <div style={tipBody}>shared by {node.weight} agents</div>
+ </>
+ );
+ }
+ return (
+ <>
+ <div style={tipTitle}>{node.label}</div>
+ <div style={tipBody}>{node.id === 'human' ? 'escalations to the human' : 'broadcast to everyone'}</div>
+ </>
+ );
+}
+
+function EdgeTip({ edge, nodeById }: { edge: GraphEdge; nodeById: Map<string, GraphNode> }) {
+ const a = nodeById.get(edge.source)?.label ?? edge.source;
+ const b = nodeById.get(edge.target)?.label ?? edge.target;
+ if (edge.kind === 'topic') {
+ return <div style={tipBody}>{a} knows about “{b}”</div>;
+ }
+ const arrow = edge.dir === 'both' ? '↔' : edge.dir === 'bwd' ? '←' : '→';
+ return (
+ <>
+ <div style={tipTitle}>{a} {arrow} {b}</div>
+ <div style={{ fontSize: 11, color: 'var(--cth-ink-500)', margin: '2px 0' }}>
+ {edge.weight} message{edge.weight === 1 ? '' : 's'} · last: {edge.lastAct ?? '—'}
+ </div>
+ {edge.lastSubject && <div style={tipBody}>{truncate(edge.lastSubject, 80)}</div>}
+ </>
+ );
+}
+
+function Legend() {
+ const items: { c: string; label: string }[] = [
+ { c: actColor('request'), label: 'request' },
+ { c: actColor('query'), label: 'query' },
+ { c: actColor('propose'), label: 'propose' },
+ { c: actColor('agree'), label: 'agree/done' },
+ { c: actColor('refuse'), label: 'refuse' },
+ { c: 'var(--cth-ink-300)', label: 'inform/topic' }
+ ];
+ return (
+ <div style={{
+ position: 'absolute', bottom: 8, left: 8, padding: '5px 7px',
+ background: 'var(--cth-cream-100)', boxShadow: 'inset 0 0 0 1px var(--cth-ink-700)',
+ display: 'flex', flexWrap: 'wrap', gap: '2px 10px', maxWidth: 280, pointerEvents: 'none'
+ }}>
+ {items.map((it) => (
+ <span key={it.label} style={{ display: 'inline-flex', alignItems: 'center', gap: 4, fontSize: 10, color: 'var(--cth-ink-700)' }}>
+ <span style={{ width: 9, height: 3, background: it.c, display: 'inline-block' }} /> {it.label}
+ </span>
+ ))}
+ </div>
+ );
+}
+
+function Tooltip({ x, y, wrap, children }: { x: number; y: number; wrap: { w: number; h: number }; children: React.ReactNode }) {
+ const W = 240;
+ const left = Math.min(x + 14, wrap.w - W - 6);
+ const flipUp = y > wrap.h - 120;
+ return (
+ <div style={{
+ position: 'absolute', left: Math.max(6, left), top: flipUp ? undefined : y + 14,
+ bottom: flipUp ? wrap.h - y + 14 : undefined,
+ width: W, padding: 8, pointerEvents: 'none', zIndex: 5,
+ background: 'var(--cth-cream-50)', boxShadow: '2px 2px 0 var(--cth-ink-900), inset 0 0 0 1px var(--cth-ink-900)'
+ }}>{children}</div>
+ );
+}
+
+function Toggle({ on, onClick, label }: { on: boolean; onClick: () => void; label: string }) {
+ return (
+ <button
+ onClick={onClick}
+ style={{
+ display: 'inline-flex', alignItems: 'center', gap: 4, padding: '3px 9px 2px', border: 'none', cursor: 'pointer',
+ background: on ? 'var(--cth-lilac)' : 'var(--cth-cream-200)',
+ boxShadow: on ? 'inset 0 0 0 1px var(--cth-ink-900)' : 'inset 0 0 0 1px var(--cth-ink-700)',
+ fontFamily: 'var(--cth-font-ui)', fontSize: 12, color: 'var(--cth-ink-900)'
+ }}
+ >
+ <Icon name={on ? 'check' : 'plus'} /> {label}
+ </button>
+ );
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+const MARKER_ACTS: MessageAct[] = ['request', 'inform', 'propose', 'query', 'agree', 'refuse', 'done'];
+
+/** Speech-act → colour. Mirrors ACT_COLOR in MessageEnvelope.ts so the graph
+ * speaks the same visual language as the floor's flying envelopes. */
+function actColor(act?: MessageAct): string {
+ switch (act) {
+ case 'request': return 'var(--cth-sky)';
+ case 'query': return 'var(--cth-lilac)';
+ case 'propose': return 'var(--cth-lemon)';
+ case 'agree': return 'var(--cth-mint)';
+ case 'done': return 'var(--cth-mint)';
+ case 'refuse': return 'var(--cth-coral)';
+ case 'inform':
+ default: return 'var(--cth-ink-300)';
+ }
+}
+
+function nodeSize(n: GraphNode): number {
+ if (n.kind === 'agent') return (n.isGod ? 30 : 22) + Math.min(n.degree, 10) * 1.0;
+ if (n.kind === 'topic') return 12 + Math.min(n.weight, 6) * 1.4;
+ return 17; // pseudo
+}
+function nodeRadius(n: GraphNode): number { return nodeSize(n) / 2; }
+
+function nodeFill(n: GraphNode): string {
+ if (n.kind === 'agent') return `var(--cth-${n.accent})`;
+ if (n.kind === 'topic') return 'var(--cth-cream-200)';
+ return n.id === 'human' ? 'var(--cth-lemon-light)' : 'var(--cth-ink-300)';
+}
+
+function isNeighbor(graph: GraphData, a: string, b: string): boolean {
+ for (const e of graph.edges) {
+ if ((e.source === a && e.target === b) || (e.source === b && e.target === a)) return true;
+ }
+ return false;
+}
+
+function truncate(s: string, n: number): string {
+ return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+/** First meaningful line(s) of a memory file, for the hover preview. */
+function memorySnippet(text: string): string {
+ if (!text.trim()) return 'No memory recorded yet.';
+ const lines = text
+ .split('\n')
+ .map((l) => l.replace(/^[#>\-*\s]+/, '').trim())
+ .filter((l) => l && !/^_.*_$/.test(l) && !/^memory —/i.test(l));
+ return truncate(lines.slice(0, 3).join(' '), 200) || 'No memory recorded yet.';
+}
+
+const iconBtn: React.CSSProperties = {
+ display: 'inline-flex', alignItems: 'center', gap: 4, padding: '3px 9px 2px', border: 'none', cursor: 'pointer',
+ background: 'var(--cth-cream-200)', boxShadow: 'inset 0 0 0 1px var(--cth-ink-700)',
+ fontFamily: 'var(--cth-font-ui)', fontSize: 12, color: 'var(--cth-ink-900)'
+};
+
+const tipTitle: React.CSSProperties = {
+ fontFamily: 'var(--cth-font-ui)', fontSize: 13, color: 'var(--cth-ink-900)', lineHeight: '16px'
+};
+const tipBody: React.CSSProperties = {
+ fontSize: 11, lineHeight: '15px', color: 'var(--cth-ink-700)'
+};
diff --git a/src/renderer/src/components/memoryGraph/buildGraph.ts b/src/renderer/src/components/memoryGraph/buildGraph.ts
new file mode 100644
index 00000000..6fdf2481
Binary files /dev/null and b/src/renderer/src/components/memoryGraph/buildGraph.ts differ
diff --git a/src/renderer/src/components/memoryGraph/extractTopics.ts b/src/renderer/src/components/memoryGraph/extractTopics.ts
new file mode 100644
index 00000000..757787a9
--- /dev/null
+++ b/src/renderer/src/components/memoryGraph/extractTopics.ts
@@ -0,0 +1,103 @@
+// Topic extraction for the memory graph — pure, dependency-free, client-side.
+//
+// Agent memory.md files are structured markdown: dated `## <date> — <title>`
+// section headers, `**bold**` key terms, bullet lists. We pull candidate topic
+// phrases from headings + bold spans, normalise them, and keep only the ones
+// mentioned by >= 2 distinct agents (shared knowledge is the interesting signal;
+// an agent's solo notes aren't a hive-wide "topic"). See MEMORY_GRAPH_SPEC.md §5.
+//
+// This is deliberately heuristic, not semantic — MemPalace (searchMemory) owns
+// the semantic side and returns ranked snippets per query, not an enumerable set.
+
+export interface Topic {
+ /** stable node id, e.g. "topic:landing page redesign" */
+ id: string;
+ /** human-facing label (first-seen original casing) */
+ label: string;
+ /** ids of agents whose memory mentions this topic */
+ agentIds: string[];
+ /** = agentIds.length; how many agents share it */
+ weight: number;
+}
+
+export interface TopicResult {
+ /** topics sorted by weight desc, then label — already capped to `max` */
+ topics: Topic[];
+ /** total number of qualifying topics (weight >= 2) before the cap */
+ total: number;
+}
+
+// Generic words/phrases that show up as headings or bold but aren't real topics.
+const STOP = new Set([
+ 'update', 'updates', 'done', 'note', 'notes', 'next', 'open', 'todo', 'todos',
+ 'fixed', 'resolved', 'wip', 'status', 'context', 'memory', 'summary', 'decision',
+ 'decisions', 'plan', 'plans', 'task', 'tasks', 'phase 1', 'phase 2', 'phase',
+ 'why', 'how', 'what', 'gap', 'gaps', 'needed', 'open / next', 'important', 'fact', 'facts'
+]);
+
+/** Strip a leading `YYYY-MM-DD —`/`-`/`:` date prefix from a heading tail. */
+function stripDatePrefix(s: string): string {
+ return s.replace(/^\s*\d{4}-\d{2}-\d{2}\s*[—\-:·]*\s*/, '');
+}
+
+/** Lowercase, collapse whitespace, drop surrounding markup/punctuation. */
+function normalise(raw: string): string {
+ return raw
+ .replace(/[`*_~]/g, '') // strip inline md markup
+ .replace(/\(.*?\)/g, '') // drop parentheticals
+ .replace(/[#:.,;!?]+$/g, '') // trailing punctuation
+ .replace(/\s+/g, ' ')
+ .trim()
+ .toLowerCase();
+}
+
+/** Pull raw candidate phrases out of one memory file's markdown. */
+function candidatesFrom(markdown: string): string[] {
+ const out: string[] = [];
+ for (const line of markdown.split('\n')) {
+ const heading = line.match(/^#{2,4}\s+(.+?)\s*$/);
+ if (heading) out.push(stripDatePrefix(heading[1]));
+ for (const m of line.matchAll(/\*\*(.+?)\*\*/g)) out.push(stripDatePrefix(m[1]));
+ }
+ return out;
+}
+
+function isUsable(norm: string): boolean {
+ if (norm.length < 3 || norm.length > 40) return false;
+ if (STOP.has(norm)) return false;
+ if (/^[\d\s\-—.]+$/.test(norm)) return false; // pure numbers/dates
+ if (!/[a-z]/.test(norm)) return false; // must contain letters
+ return true;
+}
+
+/**
+ * Build the shared-topic set across all agents' memory files.
+ * @param memories agentId -> raw memory.md text
+ * @param max cap on returned topics (default 24, per spec)
+ */
+export function extractTopics(memories: Record<string, string>, max = 24): TopicResult {
+ // normalised topic -> { display label, set of agent ids }
+ const acc = new Map<string, { label: string; agents: Set<string> }>();
+
+ for (const [agentId, text] of Object.entries(memories)) {
+ if (!text) continue;
+ const seenThisAgent = new Set<string>();
+ for (const cand of candidatesFrom(text)) {
+ const norm = normalise(cand);
+ if (!isUsable(norm) || seenThisAgent.has(norm)) continue;
+ seenThisAgent.add(norm);
+ const entry = acc.get(norm);
+ if (entry) entry.agents.add(agentId);
+ else acc.set(norm, { label: cand.replace(/[`*_]/g, '').trim(), agents: new Set([agentId]) });
+ }
+ }
+
+ const all: Topic[] = [];
+ for (const [norm, { label, agents }] of acc) {
+ if (agents.size < 2) continue;
+ all.push({ id: `topic:${norm}`, label, agentIds: [...agents], weight: agents.size });
+ }
+ all.sort((a, b) => b.weight - a.weight || a.label.localeCompare(b.label));
+
+ return { topics: all.slice(0, max), total: all.length };
+}
diff --git a/src/renderer/src/components/memoryGraph/forceLayout.ts b/src/renderer/src/components/memoryGraph/forceLayout.ts
new file mode 100644
index 00000000..7c946a1b
--- /dev/null
+++ b/src/renderer/src/components/memoryGraph/forceLayout.ts
@@ -0,0 +1,144 @@
+// Tiny deterministic force-directed layout — Fruchterman–Reingold with mild
+// centre gravity. No dependency (d3-force isn't in node_modules and the project
+// keeps deps lean); for < 100 nodes a fixed-iteration integrator is plenty.
+// See MEMORY_GRAPH_SPEC.md §6.
+//
+// Deterministic: nodes are seeded on a phyllotaxis spiral by index (no Math.random),
+// so the graph doesn't reshuffle between polls. Pinned nodes (dragged) stay fixed
+// and the rest relax around them.
+
+export interface LayoutNode {
+ id: string;
+ /** extra centre-pull multiplier (god reads as the hub) */
+ gravityBias?: number;
+}
+export interface LayoutEdge {
+ source: string;
+ target: string;
+ /** spring strength multiplier (topic edges pull weaker) */
+ strength?: number;
+}
+export interface LayoutOpts {
+ width: number;
+ height: number;
+ /** fixed positions for dragged/pinned nodes */
+ pinned?: Record<string, { x: number; y: number }>;
+ iterations?: number;
+ padding?: number;
+}
+
+export type Positions = Map<string, { x: number; y: number }>;
+
+const GOLDEN_ANGLE = 2.399963229728653; // radians
+
+/** Deterministic seed: phyllotaxis spiral centred in the frame. */
+function seed(ids: string[], cx: number, cy: number, radius: number): Positions {
+ const pos: Positions = new Map();
+ const n = Math.max(1, ids.length);
+ ids.forEach((id, i) => {
+ const r = radius * Math.sqrt((i + 0.5) / n);
+ const a = i * GOLDEN_ANGLE;
+ pos.set(id, { x: cx + Math.cos(a) * r, y: cy + Math.sin(a) * r });
+ });
+ return pos;
+}
+
+export function forceLayout(
+ nodes: LayoutNode[],
+ edges: LayoutEdge[],
+ opts: LayoutOpts
+): Positions {
+ const { width, height } = opts;
+ const padding = opts.padding ?? 28;
+ const iterations = opts.iterations ?? 320;
+ const pinned = opts.pinned ?? {};
+
+ const ids = nodes.map((n) => n.id);
+ const cx = width / 2;
+ const cy = height / 2;
+ const usableR = Math.max(40, Math.min(width, height) / 2 - padding);
+ const pos = seed(ids, cx, cy, usableR);
+
+ // honour pins from the start
+ for (const id of ids) if (pinned[id]) pos.set(id, { ...pinned[id] });
+
+ if (ids.length <= 1) return pos;
+
+ // Fruchterman–Reingold ideal edge length, scaled down so labels have room.
+ const area = width * height;
+ const k = Math.sqrt(area / ids.length) * 0.55;
+ const k2 = k * k;
+ const gravity = 0.045;
+
+ const biasById = new Map(nodes.map((n) => [n.id, n.gravityBias ?? 1]));
+ const disp = new Map<string, { x: number; y: number }>(ids.map((id) => [id, { x: 0, y: 0 }]));
+
+ let temp = Math.min(width, height) * 0.12;
+ const cool = Math.pow(0.02, 1 / iterations); // temp → ~2% of start by the end
+
+ for (let it = 0; it < iterations; it++) {
+ for (const id of ids) { const d = disp.get(id)!; d.x = 0; d.y = 0; }
+
+ // repulsion — every pair pushes apart (O(n²), fine at this scale)
+ for (let i = 0; i < ids.length; i++) {
+ const pi = pos.get(ids[i])!;
+ const di = disp.get(ids[i])!;
+ for (let j = i + 1; j < ids.length; j++) {
+ const pj = pos.get(ids[j])!;
+ let dx = pi.x - pj.x;
+ let dy = pi.y - pj.y;
+ let dist = Math.hypot(dx, dy);
+ if (dist < 0.01) { dx = (i - j) * 0.01 + 0.01; dy = 0.01; dist = Math.hypot(dx, dy); }
+ const force = k2 / dist;
+ const ux = dx / dist;
+ const uy = dy / dist;
+ di.x += ux * force; di.y += uy * force;
+ const dj = disp.get(ids[j])!;
+ dj.x -= ux * force; dj.y -= uy * force;
+ }
+ }
+
+ // attraction — edges pull their endpoints together
+ for (const e of edges) {
+ const ps = pos.get(e.source);
+ const pt = pos.get(e.target);
+ if (!ps || !pt) continue;
+ const dx = ps.x - pt.x;
+ const dy = ps.y - pt.y;
+ const dist = Math.hypot(dx, dy) || 0.01;
+ const force = (dist * dist) / k * (e.strength ?? 1);
+ const ux = dx / dist;
+ const uy = dy / dist;
+ const ds = disp.get(e.source)!;
+ const dt = disp.get(e.target)!;
+ ds.x -= ux * force; ds.y -= uy * force;
+ dt.x += ux * force; dt.y += uy * force;
+ }
+
+ // mild gravity toward centre keeps disconnected nodes on-screen
+ for (const id of ids) {
+ const p = pos.get(id)!;
+ const d = disp.get(id)!;
+ const g = gravity * (biasById.get(id) ?? 1);
+ d.x += (cx - p.x) * g;
+ d.y += (cy - p.y) * g;
+ }
+
+ // integrate (skip pinned), clamp step by temperature, keep in frame
+ for (const id of ids) {
+ if (pinned[id]) { pos.set(id, { ...pinned[id] }); continue; }
+ const p = pos.get(id)!;
+ const d = disp.get(id)!;
+ const len = Math.hypot(d.x, d.y) || 0.01;
+ const step = Math.min(len, temp);
+ p.x += (d.x / len) * step;
+ p.y += (d.y / len) * step;
+ p.x = Math.max(padding, Math.min(width - padding, p.x));
+ p.y = Math.max(padding, Math.min(height - padding, p.y));
+ }
+
+ temp *= cool;
+ }
+
+ return pos;
+}