nlm-memory 0.4.0

package/src/ui/pages/Recall.tsx

@@ -0,0 +1,190 @@
+/**
+ * Recall — adoption + coverage telemetry for the memory system.
+ *
+ * Two surfaces, two audiences:
+ *   - Session recall  → what the orchestrator pulls answering questions
+ *                       about past work (the human-operator surface).
+ *   - Fact recall     → structured facts agents pull mid-task.
+ *
+ * Hit rate answers "did recall return something," not "did the agent use
+ * it." By-source answers "is anything calling this at all." Read together
+ * they distinguish an adoption problem from a corpus-coverage problem.
+ */
+
+import { useState } from "react";
+import { usePolledEndpoint } from "../lib/api.js";
+
+interface BaseStats {
+  days: number;
+  total: number;
+  with_results: number;
+  hit_rate: number;
+  by_source: Record<string, number>;
+  log_present: boolean;
+}
+
+interface SessionStats extends BaseStats {
+  top_queries: { query: string; count: number }[];
+}
+
+interface FactStats extends BaseStats {
+  top_subjects: { subject: string; count: number }[];
+  top_predicates: { predicate: string; count: number }[];
+}
+
+const EMPTY_SESSION: SessionStats = {
+  days: 7, total: 0, with_results: 0, hit_rate: 0, by_source: {}, top_queries: [], log_present: false,
+};
+const EMPTY_FACT: FactStats = {
+  days: 7, total: 0, with_results: 0, hit_rate: 0, by_source: {}, top_subjects: [], top_predicates: [], log_present: false,
+};
+
+const WINDOWS = [7, 30, 90] as const;
+
+interface BarRow {
+  label: string;
+  count: number;
+}
+
+export function RecallPage() {
+  const [days, setDays] = useState<number>(7);
+  const session = usePolledEndpoint<SessionStats>(`/api/recall/stats?days=${days}`, 30_000, EMPTY_SESSION);
+  const facts = usePolledEndpoint<FactStats>(`/api/recall/facts/stats?days=${days}`, 30_000, EMPTY_FACT);
+
+  return (
+    <div className="page-pad">
+      <div className="recall-head">
+        <p className="muted small recall-note">
+          Hit rate measures whether recall returned something — not whether the agent used it.
+          Watch <strong>by source</strong> for adoption and <strong>hit rate</strong> for
+          whether the corpus covers what's being asked.
+        </p>
+        <div className="filter-group" role="group" aria-label="Time window">
+          {WINDOWS.map((w) => (
+            <button
+              key={w}
+              type="button"
+              className={`chip${days === w ? " active" : ""}`}
+              onClick={() => setDays(w)}
+            >{w}d</button>
+          ))}
+        </div>
+      </div>
+
+      <StatsBlock
+        title="Session recall"
+        subtitle="What the orchestrator pulls when answering questions about past work — the human-operator surface."
+        stats={session.data}
+        error={session.error}
+        topLabel="Top queries"
+        topRows={session.data.top_queries.map((q) => ({ label: q.query, count: q.count }))}
+      />
+
+      <StatsBlock
+        title="Fact recall"
+        subtitle="Structured facts agents pull mid-task — the orchestrator surface."
+        stats={facts.data}
+        error={facts.error}
+        topLabel="Top subjects"
+        topRows={facts.data.top_subjects.map((s) => ({ label: s.subject, count: s.count }))}
+        extraLabel="Top predicates"
+        extraRows={facts.data.top_predicates.map((p) => ({ label: p.predicate, count: p.count }))}
+      />
+    </div>
+  );
+}
+
+interface StatsBlockProps {
+  title: string;
+  subtitle: string;
+  stats: BaseStats;
+  error: string | null;
+  topLabel: string;
+  topRows: BarRow[];
+  extraLabel?: string;
+  extraRows?: BarRow[];
+}
+
+function StatsBlock({ title, subtitle, stats, error, topLabel, topRows, extraLabel, extraRows }: StatsBlockProps) {
+  const zeroResult = stats.total - stats.with_results;
+  const sourceRows: BarRow[] = Object.entries(stats.by_source)
+    .map(([label, count]) => ({ label, count }))
+    .sort((a, b) => b.count - a.count);
+
+  return (
+    <section className="recall-block">
+      <header className="recall-block-head">
+        <h2 className="page-title">{title}</h2>
+        <p className="muted small">{subtitle}</p>
+      </header>
+
+      {error && <div className="muted error small">{error}</div>}
+
+      {!stats.log_present ? (
+        <div className="card recall-empty muted">
+          No query log on disk yet — nothing has called this recall surface.
+        </div>
+      ) : stats.total === 0 ? (
+        <div className="card recall-empty muted">
+          No queries in the last {stats.days} days. The log exists but this window is empty.
+        </div>
+      ) : (
+        <>
+          <div className="kpi-row">
+            <Kpi label="Queries" value={stats.total} hint={`last ${stats.days}d`} />
+            <Kpi
+              label="Hit rate"
+              value={`${Math.round(stats.hit_rate * 100)}%`}
+              hint={`${stats.with_results.toLocaleString()} returned ≥1`}
+            />
+            <Kpi
+              label="Zero-result"
+              value={zeroResult}
+              hint={zeroResult > 0 ? "corpus gaps" : "full coverage"}
+            />
+            <Kpi label="Sources" value={sourceRows.length} hint="distinct callers" />
+          </div>
+
+          <div className="recall-cards">
+            <BarCard title="By source" rows={sourceRows} emptyText="No sources recorded." />
+            <BarCard title={topLabel} rows={topRows} emptyText="None recorded." />
+            {extraLabel && extraRows && (
+              <BarCard title={extraLabel} rows={extraRows} emptyText="None recorded." />
+            )}
+          </div>
+        </>
+      )}
+    </section>
+  );
+}
+
+function Kpi({ label, value, hint }: { label: string; value: number | string; hint?: string }) {
+  return (
+    <div className="kpi">
+      <span className="kpi-label">{label}</span>
+      <span className="kpi-value">{typeof value === "number" ? value.toLocaleString() : value}</span>
+      {hint && <span className="kpi-hint">{hint}</span>}
+    </div>
+  );
+}
+
+function BarCard({ title, rows, emptyText }: { title: string; rows: BarRow[]; emptyText: string }) {
+  const max = Math.max(1, ...rows.map((r) => r.count));
+  return (
+    <section className="card">
+      <header className="card-head"><h3>{title}</h3></header>
+      <div className="bar-stack recall-bars">
+        {rows.length === 0 && <div className="muted small recall-bars-empty">{emptyText}</div>}
+        {rows.map((r) => (
+          <div key={r.label} className="bar-item">
+            <span className="bar-label recall-bar-label" title={r.label}>{r.label}</span>
+            <div className="bar-track">
+              <div className="bar-fill tone-active" style={{ width: `${(r.count / max) * 100}%` }} />
+            </div>
+            <span className="bar-value mono">{r.count.toLocaleString()}</span>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}

package/src/ui/pages/River.tsx

@@ -0,0 +1,308 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { useDataset, relativeAge } from "../lib/dataset.js";
+import type { DatasetSession } from "../lib/dataset.js";
+import { SessionDrawer } from "../components/SessionDrawer.js";
+import { readViewSettings } from "../lib/view-settings.js";
+
+type Span = "7d" | "30d" | "90d" | "all";
+const SPAN_DAYS: Record<Span, number | null> = { "7d": 7, "30d": 30, "90d": 90, all: null };
+
+interface HoverState {
+  entity: string;
+  date: string;
+  count: number;
+  x: number;
+  y: number;
+}
+
+interface DragState {
+  startX: number;
+  rect: DOMRect;
+}
+
+interface CellDrawerState {
+  entity: string;
+  date: string;
+  sessions: DatasetSession[];
+}
+
+export function RiverPage() {
+  const { data, loading, error } = useDataset();
+  const [span, setSpan] = useState<Span>("30d");
+  const [hover, setHover] = useState<HoverState | null>(null);
+  const [cellDrawer, setCellDrawer] = useState<CellDrawerState | null>(null);
+  const [sessionId, setSessionId] = useState<string | null>(null);
+  const navigate = useNavigate();
+  const [density] = useState(() => readViewSettings().riverDensity);
+  const gridRef = useRef<HTMLDivElement | null>(null);
+  const dragRef = useRef<DragState | null>(null);
+  const [dragRange, setDragRange] = useState<{ from: number; to: number } | null>(null);
+
+  const view = useMemo(() => {
+    if (!data) return null;
+    const days = SPAN_DAYS[span];
+    const sessions = data.sessions.filter((s) => s.started_at !== null);
+    const now = Date.now();
+    const filtered = days
+      ? sessions.filter((s) => (now - Date.parse(s.started_at!)) / 86_400_000 <= days)
+      : sessions;
+    const lanes = new Map<string, Map<string, number>>();
+    const dateSet = new Set<string>();
+    for (const s of filtered) {
+      const d = (s.started_at ?? "").slice(0, 10);
+      if (!d) continue;
+      dateSet.add(d);
+      for (const e of s.entities) {
+        const inner = lanes.get(e) ?? new Map<string, number>();
+        inner.set(d, (inner.get(d) ?? 0) + 1);
+        lanes.set(e, inner);
+      }
+    }
+    const dates = [...dateSet].sort();
+    const laneRows = [...lanes.entries()]
+      .map(([entity, perDate]) => ({
+        entity,
+        total: [...perDate.values()].reduce((a, b) => a + b, 0),
+        perDate,
+      }))
+      .sort((a, b) => b.total - a.total)
+      .slice(0, 24);
+    return { dates, laneRows, total: filtered.length };
+  }, [data, span]);
+
+  const onCellClick = (entity: string, date: string) => {
+    if (!data) return;
+    const matches = data.sessions
+      .filter((s) => (s.started_at ?? "").slice(0, 10) === date && s.entities.includes(entity))
+      .sort((a, b) => (b.started_at ?? "").localeCompare(a.started_at ?? ""));
+    if (matches.length === 0) return;
+    if (matches.length === 1) {
+      setSessionId(matches[0]!.id);
+      return;
+    }
+    setCellDrawer({ entity, date, sessions: matches });
+  };
+
+  const onMouseDown = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (!gridRef.current) return;
+    const rect = gridRef.current.getBoundingClientRect();
+    dragRef.current = { startX: e.clientX, rect };
+  };
+
+  const onMouseMove = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (!dragRef.current) return;
+    const { startX, rect } = dragRef.current;
+    const from = Math.min(startX, e.clientX) - rect.left;
+    const to = Math.max(startX, e.clientX) - rect.left;
+    if (to - from < 6) {
+      setDragRange(null);
+      return;
+    }
+    setDragRange({ from, to });
+  };
+
+  const onMouseUp = () => {
+    if (!dragRef.current || !dragRange || !view) {
+      dragRef.current = null;
+      setDragRange(null);
+      return;
+    }
+    // Cells live in a CSS grid with repeat(N, 1fr); compute the cell-area
+    // width by measuring the rendered grid minus the fixed label column.
+    const grid = gridRef.current;
+    const labelEl = grid?.querySelector(".river-lane-label") as HTMLElement | null;
+    const labelWidth = labelEl?.offsetWidth ?? 0;
+    const gridWidth = grid?.offsetWidth ?? 0;
+    const cellArea = Math.max(1, gridWidth - labelWidth);
+    const cellSize = cellArea / view.dates.length;
+    const labelOffset = labelWidth + 12; // grid padding + gap
+
+    const startIdx = Math.max(0, Math.floor((dragRange.from - labelOffset) / cellSize));
+    const endIdx = Math.min(view.dates.length - 1, Math.floor((dragRange.to - labelOffset) / cellSize));
+    if (endIdx <= startIdx) {
+      dragRef.current = null;
+      setDragRange(null);
+      return;
+    }
+    const startDate = view.dates[startIdx];
+    const endDate = view.dates[endIdx];
+    if (startDate && endDate) {
+      const days = Math.max(1, Math.ceil((Date.parse(endDate) - Date.parse(startDate)) / 86_400_000));
+      setSpan(days <= 7 ? "7d" : days <= 30 ? "30d" : days <= 90 ? "90d" : "all");
+    }
+    dragRef.current = null;
+    setDragRange(null);
+  };
+
+  if (loading && !data) return <div className="page-pad"><div className="muted">Loading dataset…</div></div>;
+  if (error && !data) return <div className="page-pad"><div className="muted error">{error}</div></div>;
+  if (!data || !view) return null;
+
+  return (
+    <div className="page-pad">
+      <div className="river-toolbar">
+        <span className="page-title">River</span>
+        <span className="muted small">{view.total} sessions · {view.laneRows.length} lanes · {view.dates.length} days</span>
+        <span className="header-spacer" />
+        {(Object.keys(SPAN_DAYS) as Span[]).map((s) => (
+          <button
+            key={s}
+            type="button"
+            className={`ctrl-btn${s === span ? " active" : ""}`}
+            onClick={() => setSpan(s)}
+          >{s}</button>
+        ))}
+      </div>
+
+      <div
+        className={`river-grid card river-density-${density}`}
+        ref={gridRef}
+        onMouseDown={onMouseDown}
+        onMouseMove={onMouseMove}
+        onMouseUp={onMouseUp}
+        onMouseLeave={() => { dragRef.current = null; setDragRange(null); setHover(null); }}
+        style={{ ["--cells" as string]: view.dates.length }}
+      >
+        {dragRange && (
+          <div
+            className="river-drag-rect"
+            style={{ left: `${dragRange.from}px`, width: `${dragRange.to - dragRange.from}px` }}
+          />
+        )}
+        <div className="river-row river-row-dates">
+          <div className="river-lane-label river-lane-label--header" aria-hidden="true" />
+          <div className="river-cells">
+            {view.dates.map((d) => (
+              <div key={d} className="river-date-cell" title={d}>{d.slice(5)}</div>
+            ))}
+          </div>
+        </div>
+        {view.laneRows.map(({ entity, perDate, total }) => (
+          <div key={entity} className="river-row">
+            <button
+              type="button"
+              className="river-lane-label"
+              onClick={() => navigate(`/thread?entity=${encodeURIComponent(entity)}`)}
+            >
+              <span className="dot" style={{ background: data.entity_colors[entity] ?? "#666" }} />
+              <span className="river-lane-name">{entity}</span>
+              <span className="muted small">{total}</span>
+            </button>
+            <div className="river-cells">
+              {view.dates.map((d) => {
+                const v = perDate.get(d) ?? 0;
+                return (
+                  <div
+                    key={d}
+                    className={`river-cell tier-${tier(v)}`}
+                    onMouseEnter={(e) => setHover({ entity, date: d, count: v, x: e.clientX, y: e.clientY })}
+                    onMouseMove={(e) => setHover({ entity, date: d, count: v, x: e.clientX, y: e.clientY })}
+                    onMouseLeave={() => setHover(null)}
+                    onClick={() => v > 0 && onCellClick(entity, d)}
+                    style={v > 0 ? { cursor: "pointer" } : {}}
+                  />
+                );
+              })}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {view.laneRows.length === 0 && <div className="muted">No entities in this window.</div>}
+
+      {hover && hover.count > 0 && (
+        <div className="river-hover" style={{ left: hover.x + 12, top: hover.y + 12 }}>
+          <span className="dot" style={{ background: data.entity_colors[hover.entity] ?? "#666" }} />
+          <span className="river-hover-name">{hover.entity}</span>
+          <span className="muted small">{hover.date} · {hover.count} session{hover.count === 1 ? "" : "s"}</span>
+        </div>
+      )}
+
+      {cellDrawer && (
+        <CellPicker
+          state={cellDrawer}
+          entityColor={data.entity_colors[cellDrawer.entity] ?? "#666"}
+          onClose={() => setCellDrawer(null)}
+          onPick={(sid) => { setCellDrawer(null); setSessionId(sid); }}
+          onOpenThread={() => navigate(`/thread?entity=${encodeURIComponent(cellDrawer.entity)}`)}
+        />
+      )}
+
+      {sessionId && (
+        <SessionDrawer
+          sessionId={sessionId}
+          onClose={() => setSessionId(null)}
+          entityColor={(() => {
+            const s = data.sessions.find((x) => x.id === sessionId);
+            const e = s?.entities[0];
+            return e ? data.entity_colors[e] : undefined;
+          })()}
+        />
+      )}
+    </div>
+  );
+}
+
+interface CellPickerProps {
+  state: CellDrawerState;
+  entityColor: string;
+  onClose: () => void;
+  onPick: (sessionId: string) => void;
+  onOpenThread: () => void;
+}
+
+function CellPicker({ state, entityColor, onClose, onPick, onOpenThread }: CellPickerProps) {
+  useEffect(() => {
+    const onEsc = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); };
+    window.addEventListener("keydown", onEsc);
+    return () => window.removeEventListener("keydown", onEsc);
+  }, [onClose]);
+
+  return (
+    <>
+      <div className="drawer-backdrop" onClick={onClose} />
+      <aside className="session-drawer" role="dialog" aria-modal="true" aria-label={`Sessions on ${state.date}`}>
+        <header className="drawer-head">
+          <span className="dot lg" style={{ background: entityColor }} />
+          <h3 className="drawer-title">{state.entity}</h3>
+          <span className="muted small">{state.date}</span>
+          <button type="button" className="drawer-close" onClick={onClose} aria-label="Close">×</button>
+        </header>
+        <div className="drawer-body">
+          <p className="muted small">{state.sessions.length} sessions on this day. Pick one to inspect.</p>
+          <div className="drawer-actions">
+            <button type="button" className="btn btn-accent" onClick={onOpenThread}>Open thread</button>
+          </div>
+          <ul className="session-list">
+            {state.sessions.map((s) => (
+              <li
+                key={s.id}
+                className="session-row session-row-detail clickable"
+                onClick={() => onPick(s.id)}
+                role="button"
+                tabIndex={0}
+                onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onPick(s.id); } }}
+              >
+                <span className={`chip-inline status-${s.status}`}>{s.status}</span>
+                <div className="session-row-main">
+                  <span className="session-label">{s.label}</span>
+                  <span className="session-meta">{s.summary}</span>
+                </div>
+                <span className="muted small mono">{relativeAge(s.started_at)}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      </aside>
+    </>
+  );
+}
+
+function tier(v: number): 0 | 1 | 2 | 3 | 4 {
+  if (v === 0) return 0;
+  if (v === 1) return 1;
+  if (v <= 3) return 2;
+  if (v <= 6) return 3;
+  return 4;
+}

package/src/ui/pages/Search.tsx

@@ -0,0 +1,93 @@
+import { useMemo, useState } from "react";
+import { Link, useSearchParams } from "react-router-dom";
+import { useDataset, relativeAge } from "../lib/dataset.js";
+
+export function SearchPage() {
+  const { data, loading, error } = useDataset();
+  const [params, setParams] = useSearchParams();
+  const q = params.get("q") ?? "";
+  const entity = params.get("entity") ?? "";
+
+  const [input, setInput] = useState(q);
+
+  const tokens = useMemo(() => {
+    const norm = q.toLowerCase().split(/\s+/).filter(Boolean);
+    return norm;
+  }, [q]);
+
+  const results = useMemo(() => {
+    if (!data) return [];
+    const sessions = entity
+      ? data.sessions.filter((s) => s.entities.includes(entity))
+      : data.sessions;
+    if (tokens.length === 0) return sessions.slice(-50).reverse();
+    const scored = sessions
+      .map((s) => ({ session: s, score: score(s, tokens) }))
+      .filter((x) => x.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 100);
+    return scored.map((x) => x.session);
+  }, [data, tokens, entity]);
+
+  const onSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    const next = new URLSearchParams(params);
+    if (input) next.set("q", input);
+    else next.delete("q");
+    setParams(next);
+  };
+
+  return (
+    <div className="page-pad">
+      <form onSubmit={onSubmit} className="search-bar">
+        <input
+          className="search-input search-big"
+          placeholder="search sessions, decisions, open questions…"
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          autoFocus
+        />
+        {entity && (
+          <span className="chip-inline">
+            entity: {entity}
+            <button type="button" className="chip-x" onClick={() => { const n = new URLSearchParams(params); n.delete("entity"); setParams(n); }}>×</button>
+          </span>
+        )}
+      </form>
+
+      {loading && !data && <div className="muted">Loading…</div>}
+      {error && <div className="muted error">{error}</div>}
+
+      <div className="muted small search-meta">
+        {results.length} result{results.length === 1 ? "" : "s"}
+      </div>
+
+      <ul className="session-list compact">
+        {results.map((s) => (
+          <li key={s.id} className="session-row">
+            <span className={`chip-inline status-${s.status}`}>{s.status}</span>
+            <Link to={`/thread?entity=${encodeURIComponent(s.entities[0] ?? "")}`} className="session-label">
+              {s.label}
+            </Link>
+            <span className="session-meta">{relativeAge(s.started_at)} · {s.entities.slice(0, 4).join(", ")}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+function score(s: { label: string; summary: string; decisions: string[]; open: string[]; entities: string[] }, tokens: string[]): number {
+  let total = 0;
+  const label = s.label.toLowerCase();
+  const summary = s.summary.toLowerCase();
+  const decisions = s.decisions.join(" ").toLowerCase();
+  const open = s.open.join(" ").toLowerCase();
+  for (const t of tokens) {
+    if (label.includes(t)) total += 3;
+    if (decisions.includes(t)) total += 2;
+    if (open.includes(t)) total += 2;
+    if (summary.includes(t)) total += 1;
+  }
+  return total;
+}

package/src/ui/pages/Stub.tsx

@@ -0,0 +1,9 @@
+export function StubPage({ page }: { page: string }) {
+  return (
+    <div className="stub-shell">
+      <span className="stub-name">/{page}</span>
+      <p>not yet ported from the Astro UI.</p>
+      <p className="stub-hint">Tracked in NocoDB #95 (Vite + React SPA port).</p>
+    </div>
+  );
+}