Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Agent Memory Graph — the living knowledge graph rendered in the agent's Diary.
// =============================================================================
// Two layers, intentionally split so the math is testable without a DOM:
//
// 1. PURE functions (rankByMentions, layoutGraph, shapeDigestEntities,
// digestCounts, entityHref) — deterministic, no canvas, no randomness.
// These shape the real memory graph (api/memory/graph) and the day's
// memories into the digest the API returns and the renderer draws. Unit
// tested in tests/agent-memory-graph.test.js.
//
// 2. AgentMemoryGraph — a small 2D canvas renderer that lays those nodes out
// radially (brightest = most-mentioned, centred), draws co-occurrence
// edges, and exposes light(nodeId) so the Diary can pulse a node as its
// name is spoken. Instantiated only in the browser; importing this module
// in Node (tests, the API endpoint) never touches the canvas.
//
// Nothing here invents data: every node/edge originates from the agent's real
// mined entity graph; the layout only positions what it is given.
// Entity kinds the memory miner emits (api/_lib/memory-entities.js).
export const ENTITY_KINDS = ['mint', 'ticker', 'wallet', 'person', 'strategy', 'topic'];
// Colour per entity kind — coins/mints glow $THREE-gold, people cyan, the rest
// cool neutrals so the graph reads at a glance.
export const KIND_COLORS = {
mint: [255, 196, 0],
ticker: [255, 196, 0],
person: [56, 224, 201],
wallet: [149, 168, 255],
strategy: [196, 149, 255],
topic: [148, 163, 184],
agent: [56, 224, 201],
};
function clamp(n, lo, hi) {
if (!Number.isFinite(n)) return lo;
return Math.max(lo, Math.min(hi, n));
}
// ── Ranking ──────────────────────────────────────────────────────────────────
/**
* Rank entity nodes by how often the agent's memories mention them (mentions
* desc, then salience, then a stable label tiebreak so the order is
* deterministic across renders and test runs).
*/
export function rankByMentions(nodes = []) {
return [...(nodes || [])]
.filter((n) => n && n.id)
.sort((a, b) => {
const dm = (b.mentions || 0) - (a.mentions || 0);
if (dm) return dm;
const ds = (b.salience || 0) - (a.salience || 0);
if (ds) return ds;
return String(a.label || '').localeCompare(String(b.label || ''));
});
}
// ── Link mapping ───────────────────────────────────────────────────────────
/**
* Map one entity node to a navigable href, or null when it isn't addressable.
* • mint → /launches/<address> (the coin's addressable profile)
* • person/agent → /agent-screen?agentId= (when resolved to a real agent)
* `agentIndex` is an optional Map of lowercased agent name → agentId, built by
* the API from real agent_identities rows; without a match a person is just a
* chip. Never fabricates a destination.
*/
export function entityHref(node, agentIndex = null) {
if (!node) return null;
const kind = node.kind;
if (kind === 'mint') {
// The mint address is the normalized form; fall back to label.
const mint = String(node.normalized || node.label || '').trim();
if (mint) return `/launches/${encodeURIComponent(mint)}`;
return null;
}
if ((kind === 'person' || kind === 'agent') && agentIndex) {
const key = String(node.label || '').trim().toLowerCase();
const agentId = key && agentIndex.get ? agentIndex.get(key) : (agentIndex[key] || null);
if (agentId) return `/agent-screen?agentId=${encodeURIComponent(agentId)}`;
}
return null;
}
/**
* Shape the raw graph nodes into the top-N entity chips the Diary renders:
* ranked by mentions, deduped by id, capped, each carrying a resolved href when
* one exists. Pure — `agentIndex` supplies the only external knowledge.
*/
export function shapeDigestEntities(nodes = [], { topN = 12, agentIndex = null } = {}) {
const ranked = rankByMentions(nodes);
const seen = new Set();
const out = [];
for (const n of ranked) {
if (seen.has(n.id)) continue;
seen.add(n.id);
out.push({
id: n.id,
kind: ENTITY_KINDS.includes(n.kind) ? n.kind : (n.kind || 'topic'),
label: String(n.label || '').slice(0, 80),
mentions: n.mentions || 0,
salience: n.salience ?? null,
href: entityHref(n, agentIndex),
});
if (out.length >= topN) break;
}
return out;
}
/**
* Derive the day's headline counts strictly from the real memory rows:
* • learned — memories formed in the window
* • decided — memories tagged a decision (tag "decision" or context.kind)
* • interacted — distinct people/agents the memories mention
* Honest by construction: a count is 0 when the rows don't support it.
*/
export function digestCounts(memories = [], entities = []) {
const mem = Array.isArray(memories) ? memories : [];
const ents = Array.isArray(entities) ? entities : [];
const decided = mem.filter((m) => {
const tags = Array.isArray(m.tags) ? m.tags.map((t) => String(t).toLowerCase()) : [];
if (tags.includes('decision') || tags.includes('decided')) return true;
const ctxKind = m.context && typeof m.context === 'object' ? String(m.context.kind || '').toLowerCase() : '';
return ctxKind === 'decision';
}).length;
const interacted = ents.filter((e) => e.kind === 'person' || e.kind === 'agent').length;
return { learned: mem.length, decided, interacted };
}
// ── Layout (radial, deterministic) ───────────────────────────────────────────
/**
* Lay out ranked nodes radially: the most-mentioned node anchors the centre,
* the rest fan out on concentric rings (closer + larger + brighter = more
* mentions). Deterministic — angle derives from the node's index, never random
* — so the same graph always renders the same way (and the tests can assert it).
*
* @returns {Array<{id,label,kind,mentions,x,y,r,brightness}>}
*/
export function layoutGraph(nodes = [], edges = [], { width = 320, height = 220, maxNodes = 40, padding = 24 } = {}) {
const ranked = rankByMentions(nodes).slice(0, maxNodes);
if (!ranked.length) return [];
const cx = width / 2;
const cy = height / 2;
const maxR = Math.max(8, Math.min(width, height) / 2 - padding);
const maxMentions = Math.max(1, ranked[0].mentions || 1);
// Ring assignment: node 0 → centre; then 5 per ring expanding outward.
const PER_RING = 6;
return ranked.map((n, i) => {
const mentions = n.mentions || 0;
// Node radius (visual size) scales with mention share, 4–13px.
const share = mentions / maxMentions;
const r = 4 + share * 9;
// Brightness 0.35–1: brightest = most-mentioned.
const brightness = clamp(0.35 + share * 0.65, 0.35, 1);
let x = cx;
let y = cy;
if (i > 0) {
const ring = Math.ceil(i / PER_RING);
const ringRadius = (maxR * ring) / (Math.ceil((ranked.length - 1) / PER_RING) || 1);
const idxInRing = (i - 1) % PER_RING;
const countInRing = Math.min(PER_RING, ranked.length - 1 - (ring - 1) * PER_RING);
// Offset alternate rings by half a slot so nodes don't line up radially.
const angle = (idxInRing / Math.max(1, countInRing)) * Math.PI * 2 + (ring % 2 ? 0 : Math.PI / PER_RING);
x = cx + Math.cos(angle) * ringRadius;
y = cy + Math.sin(angle) * ringRadius;
}
return {
id: n.id,
label: String(n.label || ''),
kind: n.kind || 'topic',
mentions,
x: clamp(x, padding, width - padding),
y: clamp(y, padding, height - padding),
r,
brightness,
};
});
}
// ── Canvas renderer ───────────────────────────────────────────────────────────
/**
* AgentMemoryGraph — draws a laid-out memory graph into a <canvas> and pulses
* nodes on demand. All visual state is recomputed from setData() + the layout
* helper above; no data is invented here.
*/
export class AgentMemoryGraph {
/**
* @param {HTMLCanvasElement} canvas
* @param {{ onNodeClick?:(node:object)=>void }} [opts]
*/
constructor(canvas, { onNodeClick = null } = {}) {
this.canvas = canvas;
this.ctx = canvas.getContext('2d');
this.onNodeClick = onNodeClick;
this._nodes = [];
this._edges = [];
this._positions = [];
this._byId = new Map();
this._pulses = new Map(); // id → pulse phase 0..1 (1 = just lit)
this._raf = null;
this._dpr = Math.min(globalThis.devicePixelRatio || 1, 2);
this._w = 0;
this._h = 0;
this._onClick = (e) => this._handleClick(e);
this._onMove = (e) => this._handleMove(e);
canvas.addEventListener('click', this._onClick);
canvas.addEventListener('pointermove', this._onMove);
}
/** Match the backing store to the element's CSS box. */
resize() {
const rect = this.canvas.getBoundingClientRect();
const w = Math.max(1, Math.round(rect.width));
const h = Math.max(1, Math.round(rect.height));
this._dpr = Math.min(globalThis.devicePixelRatio || 1, 2);
this.canvas.width = Math.round(w * this._dpr);
this.canvas.height = Math.round(h * this._dpr);
this._w = w;
this._h = h;
this._relayout();
}
/** Replace the graph data and recompute the layout. */
setData({ nodes = [], edges = [] } = {}) {
this._nodes = nodes || [];
this._edges = edges || [];
this._relayout();
}
_relayout() {
if (!this._w || !this._h) {
const rect = this.canvas.getBoundingClientRect();
this._w = Math.max(1, Math.round(rect.width));
this._h = Math.max(1, Math.round(rect.height));
}
this._positions = layoutGraph(this._nodes, this._edges, { width: this._w, height: this._h });
this._byId = new Map(this._positions.map((p) => [p.id, p]));
}
/** Pulse a node by id (brighten + ring), e.g. as its name is spoken. */
light(nodeId) {
if (this._byId.has(nodeId)) this._pulses.set(nodeId, 1);
}
/** Pulse the highest-mention node matching a label fragment (speech sync). */
lightByLabel(fragment) {
const f = String(fragment || '').trim().toLowerCase();
if (!f) return;
for (const p of this._positions) {
if (p.label && f.includes(p.label.toLowerCase())) { this.light(p.id); return; }
}
}
start() {
if (this._raf != null) return;
const tick = () => {
this._raf = requestAnimationFrame(tick);
this._draw();
};
this._raf = requestAnimationFrame(tick);
}
stop() {
if (this._raf != null) { cancelAnimationFrame(this._raf); this._raf = null; }
}
dispose() {
this.stop();
this.canvas.removeEventListener('click', this._onClick);
this.canvas.removeEventListener('pointermove', this._onMove);
this._pulses.clear();
this._byId.clear();
}
_nodeAt(clientX, clientY) {
const rect = this.canvas.getBoundingClientRect();
const x = clientX - rect.left;
const y = clientY - rect.top;
let best = null;
let bestD = Infinity;
for (const p of this._positions) {
const d = Math.hypot(p.x - x, p.y - y);
if (d <= Math.max(10, p.r + 6) && d < bestD) { best = p; bestD = d; }
}
return best;
}
_handleClick(e) {
const node = this._nodeAt(e.clientX, e.clientY);
if (node && this.onNodeClick) this.onNodeClick(node);
}
_handleMove(e) {
const node = this._nodeAt(e.clientX, e.clientY);
this.canvas.style.cursor = node ? 'pointer' : 'default';
}
_draw() {
const ctx = this.ctx;
if (!ctx) return;
const dpr = this._dpr;
ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
ctx.clearRect(0, 0, this._w, this._h);
if (!this._positions.length) return;
// Edges first (under nodes).
ctx.lineWidth = 1;
for (const e of this._edges) {
const a = this._byId.get(e.source);
const b = this._byId.get(e.target);
if (!a || !b) continue;
const w = clamp((e.weight || 1) / 4, 0.06, 0.5);
ctx.strokeStyle = `rgba(148,163,184,${w})`;
ctx.beginPath();
ctx.moveTo(a.x, a.y);
ctx.lineTo(b.x, b.y);
ctx.stroke();
}
// Nodes.
for (const p of this._positions) {
let pulse = this._pulses.get(p.id) || 0;
if (pulse > 0) {
pulse = Math.max(0, pulse - 0.02);
if (pulse === 0) this._pulses.delete(p.id);
else this._pulses.set(p.id, pulse);
}
const [r, g, b] = KIND_COLORS[p.kind] || KIND_COLORS.topic;
const baseAlpha = p.brightness;
const alpha = clamp(baseAlpha + pulse * 0.4, 0, 1);
const radius = p.r + pulse * 6;
// Glow halo (stronger while pulsing).
const glow = ctx.createRadialGradient(p.x, p.y, 0, p.x, p.y, radius * 3.2);
glow.addColorStop(0, `rgba(${r},${g},${b},${0.32 * alpha})`);
glow.addColorStop(1, `rgba(${r},${g},${b},0)`);
ctx.fillStyle = glow;
ctx.beginPath();
ctx.arc(p.x, p.y, radius * 3.2, 0, Math.PI * 2);
ctx.fill();
// Core dot.
ctx.fillStyle = `rgba(${r},${g},${b},${alpha})`;
ctx.beginPath();
ctx.arc(p.x, p.y, radius, 0, Math.PI * 2);
ctx.fill();
// Pulse ring.
if (pulse > 0) {
ctx.strokeStyle = `rgba(${r},${g},${b},${pulse * 0.6})`;
ctx.lineWidth = 1.5;
ctx.beginPath();
ctx.arc(p.x, p.y, radius + (1 - pulse) * 12, 0, Math.PI * 2);
ctx.stroke();
}
// Label for the brightest handful only (avoid clutter).
if (p.brightness > 0.62 && p.label) {
ctx.font = '10px ui-monospace, monospace';
ctx.fillStyle = `rgba(228,228,231,${clamp(alpha + 0.15, 0, 0.92)})`;
ctx.textAlign = 'center';
ctx.fillText(truncateLabel(p.label, 16), p.x, p.y - radius - 5);
}
}
}
}
function truncateLabel(s, n) {
const str = String(s || '');
return str.length > n ? str.slice(0, n - 1) + '…' : str;
}