@co-engram/viewer

Host-agnostic HTTP viewer for Co-Engram team memory.

Inline SPA that lets you browse engrams, synapses, skills, audit log, effectiveness metrics, and the trash bin. Bind to loopback only, optional bearer token auth, automatic EADDRINUSE retry.

Both @co-engram/claude-code and @co-engram/openclaw import this package to start a viewer — no host-specific coupling here.

Usage

import { startViewerServer } from "@co-engram/viewer";

const runtime = await startViewerServer(ctx, {
  port: 18899, // optional, defaults to 18899 (unified across both hosts since 2026-07) with auto-retry
  token: "optional", // optional bearer token
  language: "zh", // 'en' | 'zh'
});

// later
await runtime.stop();

Architecture

• server.ts — HTTP server (11 endpoints under /api/* + SPA root)
• html.ts — SPA shell assembler (inlines vendor bundles, runtime modules)
• styles.ts — all CSS as a string literal
• runtime/{app,tabs,graph}.ts — client-side TS shipped as strings to the browser
• UI (2026-08 redesign) — left sidebar navigation (browse / governance / admin icon row) on a warm light theme; the overview tab shows KPIs with weekly deltas, a 30-day memory pulse, an audit-driven activity feed, and TOP-N ranking cards
• Graph tab (2026-08) — beyond kind/family filters and physics freeze: an importance-threshold slider, a creation-time replay slider (nodes carry createdAtMs, combined with the threshold), Louvain cluster hulls with breathing animation, glow halos on importance ≥ 0.7 nodes, night mode, and click-to-focus with flowing edges and non-neighbor fade-out (Esc resets). Motion effects live in a pointer-transparent SVG overlay driven by CSS animations; positions re-sync on afterDrawing via canvasToDOM, so no per-frame canvas redraws are needed
• vendor/*-source.ts — auto-generated by scripts/build-vendor.mjs, inlining marked / DOMPurify / vis-network UMD bundles so the SPA works offline

Build

pnpm build   # runs build:vendor (inlines UMD bundles) + tsc

Run pnpm build:vendor after upgrading marked / DOMPurify / vis-network to refresh the inlined strings.